Metadata-Version: 2.4
Name: arythmatic-connect-mcp
Version: 0.2.0
Summary: MCP server for Arythmatic Connect — let your AI agent post, comment, read channels, file support tickets, and chat from inside Claude / Cursor / any MCP-compatible client.
Author-email: Arythmatic <engineering@arythmatic.cloud>
License: MIT
Project-URL: Homepage, https://connect.arythmatic.cloud
Project-URL: Documentation, https://github.com/askmeidentitycorp/Arythmatic-community-backend/tree/develop/mcp
Project-URL: Source, https://github.com/askmeidentitycorp/Arythmatic-community-backend
Keywords: mcp,claude,arythmatic,connect,agents
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.0
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: respx>=0.21; extra == "dev"

# Arythmatic Connect — MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io/) server that lets your AI agent post, comment, read channels, run polls + quizzes, file support tickets, and chat inside an Arythmatic Connect workspace.

Compatible with any MCP-capable host — Claude Desktop, Claude Code, Cursor, opencode, Continue, GitHub Copilot, OpenAI Codex, and more.

## Install

```bash
pip install arythmatic-connect-mcp
```

or run from source:

```bash
cd mcp/
pip install -e .
```

Verify the console shim is on `PATH`:

```bash
arythmatic-connect-mcp --help   # should sit on stdio waiting for MCP traffic; Ctrl+C to exit
```

If the command isn't found, you likely installed into a Python install whose `Scripts/` (Windows) or `bin/` (macOS/Linux) directory isn't on `PATH`. Either fix `PATH`, install via `pipx install arythmatic-connect-mcp`, or use the absolute path in your agent config (see Troubleshooting).

## Get a tenant API key

The MCP server authenticates as the **tenant API key** owner — every action the agent takes is performed as if that user did it (matching their permission scopes in the community UI).

1. Sign in to your community as a workspace admin.
2. Go to `https://<your-tenant>.connect.arythmatic.cloud/w/<slug>/admin/api-keys`.
3. Create a key — copy the `arc_live_<prefix>_<secret>` value immediately (only shown once).

## Required environment variables

The MCP server reads two env vars at startup:

| Var | Value |
|---|---|
| `ARYTHMATIC_API_BASE_URL` | `https://api.connect.arythmatic.cloud/api/v1` (the `/api/v1` suffix is REQUIRED) |
| `ARYTHMATIC_API_KEY` | The `arc_live_...` key from above |

For a self-hosted / dev environment, swap the host accordingly (e.g. `https://api.connect-dev.arythmatic.cloud/api/v1`).

---

# Wire into your agent

Each MCP host has a different config file shape — pick yours.

## Claude Desktop

> ⚠️ Note: as of mid-2026 Anthropic has been migrating users from the Desktop app toward Claude Code (the CLI). The Desktop app still works but if you find it slow, Claude Code below is a lighter alternative.

Edit `claude_desktop_config.json`:

| OS | Path |
|---|---|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |

```json
{
  "mcpServers": {
    "arythmatic-connect": {
      "command": "arythmatic-connect-mcp",
      "env": {
        "ARYTHMATIC_API_BASE_URL": "https://api.connect.arythmatic.cloud/api/v1",
        "ARYTHMATIC_API_KEY": "arc_live_xxxxxxxx_yyyyyyyyyyyy"
      }
    }
  }
}
```

Restart Claude Desktop. The Connect tools appear in the tools picker (look for the hammer icon in the chat input).

## Claude Code (terminal)

Claude Code is Anthropic's official CLI — works on Windows / macOS / Linux. Register the MCP server with one command:

```bash
claude mcp add arythmatic-connect arythmatic-connect-mcp \
  -e ARYTHMATIC_API_BASE_URL=https://api.connect.arythmatic.cloud/api/v1 \
  -e ARYTHMATIC_API_KEY=arc_live_xxxxxxxx_yyyyyyyyyyyy
```

Useful flags:

- `-s user` — register globally (available in every project).
- `-s project` — write a `.mcp.json` committed alongside the repo so teammates pick it up too.
- Default scope is `local` (this project / directory only).

Then verify:

```bash
claude mcp list                       # confirms the server is wired and connects
claude mcp get arythmatic-connect     # shows the stored command + env
```

Start a `claude` session and try *"list my workspaces"* — it should invoke `list_workspaces` via MCP.

> Windows tip: if `claude mcp list` says "Failed to connect" because the shim isn't on `PATH`, re-register using the absolute path:
> ```powershell
> claude mcp add arythmatic-connect "C:\Users\<you>\AppData\Local\Programs\Python\Python313\Scripts\arythmatic-connect-mcp.exe" -e ARYTHMATIC_API_BASE_URL=... -e ARYTHMATIC_API_KEY=...
> ```

## Cursor

Cursor uses the same `mcpServers` schema as Claude Desktop. Create `~/.cursor/mcp.json` for global access or `.cursor/mcp.json` in a specific project:

```json
{
  "mcpServers": {
    "arythmatic-connect": {
      "command": "arythmatic-connect-mcp",
      "env": {
        "ARYTHMATIC_API_BASE_URL": "https://api.connect.arythmatic.cloud/api/v1",
        "ARYTHMATIC_API_KEY": "arc_live_xxxxxxxx_yyyyyyyyyyyy"
      }
    }
  }
}
```

Then enable the server in **Settings → MCP**.

## opencode (terminal)

[opencode](https://opencode.ai) is an open-source AI coding agent for the terminal. Edit `~/.config/opencode/opencode.json`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "arythmatic-connect": {
      "type": "local",
      "command": ["arythmatic-connect-mcp"],
      "environment": {
        "ARYTHMATIC_API_BASE_URL": "https://api.connect.arythmatic.cloud/api/v1",
        "ARYTHMATIC_API_KEY": "arc_live_xxxxxxxx_yyyyyyyyyyyy"
      }
    }
  }
}
```

Restart `opencode` — tools appear in the agent's tool list. opencode's MCP schema occasionally evolves; if the keys above no longer match, see <https://opencode.ai/docs/mcp>.

## VS Code — GitHub Copilot

GitHub Copilot supports MCP in Visual Studio Code (Copilot Chat / Agent Mode). Workspace config goes in `.vscode/mcp.json`:

```json
{
  "servers": {
    "arythmatic-connect": {
      "type": "stdio",
      "command": "arythmatic-connect-mcp",
      "env": {
        "ARYTHMATIC_API_BASE_URL": "https://api.connect.arythmatic.cloud/api/v1",
        "ARYTHMATIC_API_KEY": "arc_live_xxxxxxxx_yyyyyyyyyyyy"
      }
    }
  }
}
```

For global config, add the same `servers` block to **Settings → MCP: Server Definitions** (user-level settings). Restart VS Code. Enable Agent Mode in Copilot Chat to see the tools.

## VS Code — Continue

[Continue](https://www.continue.dev/) reads `~/.continue/config.yaml`:

```yaml
mcpServers:
  - name: arythmatic-connect
    command: arythmatic-connect-mcp
    env:
      ARYTHMATIC_API_BASE_URL: https://api.connect.arythmatic.cloud/api/v1
      ARYTHMATIC_API_KEY: arc_live_xxxxxxxx_yyyyyyyyyyyy
```

Restart the Continue extension. Tools appear in the agent's tool registry.

## OpenAI Codex (CLI)

[OpenAI Codex CLI](https://github.com/openai/codex) uses TOML config at `~/.codex/config.toml`:

```toml
[mcp_servers.arythmatic-connect]
command = "arythmatic-connect-mcp"
args = []

[mcp_servers.arythmatic-connect.env]
ARYTHMATIC_API_BASE_URL = "https://api.connect.arythmatic.cloud/api/v1"
ARYTHMATIC_API_KEY = "arc_live_xxxxxxxx_yyyyyyyyyyyy"
```

Restart `codex`. The Connect tools are available to the agent.

## Anything else

Any MCP-spec-compliant host can spawn the server. The contract is:

- **Transport:** stdio
- **Command:** `arythmatic-connect-mcp` (or absolute path to the shim, or `python -m arythmatic_connect_mcp` from inside a venv where the package is installed)
- **Env:** `ARYTHMATIC_API_BASE_URL` + `ARYTHMATIC_API_KEY`

If your host has a different config schema, follow its docs — the command + env are the only universal pieces.

---

# Available tools (v0.2)

47 tools across 9 categories. Every call is a thin pass-through to the Arythmatic Connect REST API authenticated as the API-key owner; the backend enforces permission scopes.

## Discovery
| Tool | Description |
|---|---|
| `get_current_user` | Who the agent is acting as + their permission scopes. |
| `list_workspaces` | Workspaces the caller is a member of. |
| `list_channels` | Channels inside a workspace. |
| `search_content` | Cross-tenant search across posts, articles, questions, channel messages. |

## Channel chat
| Tool | Description |
|---|---|
| `list_channel_messages` | Recent messages in a channel (paginated). |
| `post_channel_message` | Send a message to a channel. |
| `edit_channel_message` | Edit your own channel message. |
| `react_to_channel_message` | Toggle an emoji reaction on a channel message. |

## Feed posts
| Tool | Description |
|---|---|
| `list_feed_posts` | Recent feed posts in a workspace. |
| `create_feed_post` | Create a text feed post (no images in v0.2). |
| `edit_post` | Edit your own feed post. |
| `react_to_post` / `remove_reaction_from_post` | Upsert / clear a named reaction (`like`, `love`, …). |
| `comment_on_post` | Top-level comment on a feed post. |

## Direct messages
| Tool | Description |
|---|---|
| `list_conversations` | DM and group chat conversations the caller is part of. |
| `list_conversation_messages` | Messages in a single conversation. |
| `send_conversation_message` | Reply in a DM or group chat. |
| `edit_conversation_message` | Edit your own message. |
| `react_to_conversation_message` | Toggle an emoji reaction on a DM / group message. |

## Long-form content
| Tool | Description |
|---|---|
| `create_article` | Publish a Markdown article in a workspace. |
| `edit_article` | Edit your own article. |
| `react_to_article` / `remove_reaction_from_article` | Upsert / clear a named reaction. |
| `comment_on_article` | Top-level comment on an article. |
| `create_question` | Open a new Q&A question. |
| `edit_question` | Edit your own question. |
| `comment_on_question` | Top-level comment on a question. |

## Polls
| Tool | Description |
|---|---|
| `create_poll` | Create a poll with 2–20 options. |
| `get_poll` | Read poll detail (needed to find option UUIDs before voting). |
| `vote_on_poll` | Cast a vote (requires option UUID, not index). |
| `close_poll` | Stop the poll from accepting further votes. |

## Quizzes — multi-step draft flow
Quizzes are composed piecewise so the agent can preview the full quiz with the user before publishing. **Drafts live only in MCP-server memory** for the duration of the session — they aren't persisted on the backend until `publish_quiz_draft` is called.

| Tool | Description |
|---|---|
| `create_quiz_draft` | Start an in-memory draft. Returns a local `draft_id`. |
| `add_quiz_question` | Append a question (MCQ / true-false / multi-select / short-answer). |
| `list_quiz_draft_questions` | Show the full draft (for user review before publishing). |
| `discard_quiz_draft` | Throw away an in-progress draft. |
| `publish_quiz_draft` | Commit the draft to the backend in one atomic POST. |

Recommended flow: agent constructs the questions, calls `list_quiz_draft_questions`, shows the user, gets explicit confirmation, then `publish_quiz_draft`. This protects the leaderboard from a buggy "correct answer" pick by the agent.

## Notifications
| Tool | Description |
|---|---|
| `list_notifications` | Caller's inbox (filter `unread_only=true` for what's new). |
| `mark_notifications_read` | Mark specific notifications by UUID. |
| `mark_all_notifications_read` | One-shot "clear my inbox". |

## Support tickets
| Tool | Description |
|---|---|
| `list_my_tickets` | Tickets the caller has filed. |
| `create_ticket` | File a new support ticket (workspace-scoped or tenant-wide). |
| `get_ticket` | Read a ticket's body + status. |
| `list_ticket_comments` | List ticket comments. |
| `comment_on_ticket` | Reply on a ticket (with optional `is_internal` for staff handoff). |

## Admin / moderator
Require the caller's API key to be minted by an admin/moderator. The relevant scope is enforced server-side, same as the web UI.

| Tool | Description |
|---|---|
| `list_all_tickets` | Tenant-wide ticket queue. Requires `tickets:manage`. |
| `update_ticket` | Change a ticket's status / assignee. Requires `tickets:manage`. |
| `list_workspace_members` | Members of a workspace. Requires `members:view`. |

---

# Security model

- **Authentication:** the tenant API key acts as the caller. There's no per-tool gating in the MCP server itself — the Django API enforces scopes on every request, returning 403 when the calling key lacks the right scope. If your agent shouldn't be able to do something, mint a key with narrower scopes via the admin API-keys UI.
- **Audit:** every API call lands in `integrations.APIKeyUsageLog` (90-day retention) just like any other key-driven call, so you can audit the agent's behaviour after the fact.
- **Quiz answers:** `list_quiz_draft_questions` returns the `is_correct` flag on each option. Share that output only with the quiz author for review — never paste it back to people who will take the quiz.

# Troubleshooting

**"Failed to connect" in agent host**
The MCP host can't spawn the server. Usually one of:
1. Package not installed — `pip install arythmatic-connect-mcp` or check `pip show arythmatic-connect-mcp`.
2. Console shim not on `PATH` — use the absolute path to `arythmatic-connect-mcp.exe` (Windows) / `arythmatic-connect-mcp` (macOS / Linux), or install via `pipx`.
3. Wrong Python env — if you've got multiple Python installs, the shim may live in one that isn't first on `PATH`. `which arythmatic-connect-mcp` (macOS / Linux) / `where arythmatic-connect-mcp` (Windows) tells you which one wins.

**Every call returns 404**
`ARYTHMATIC_API_BASE_URL` is missing the `/api/v1` suffix. The full value must be `https://api.connect.arythmatic.cloud/api/v1`, not `…/`.

**Every call returns 401 / 403**
- 401: API key is wrong, revoked, or expired. Mint a fresh one in the admin UI.
- 403: the key's owner lacks the scope the tool needs. E.g. `list_all_tickets` requires `tickets:manage`. Either grant the user the right role or use a key minted by someone with the scope.

**Tools don't show up after editing config**
Most hosts spawn the MCP server lazily on each session. Fully quit + restart the host (close the terminal / app) — reloading a project window often isn't enough.

# Publishing

```bash
cd mcp/
pip install build twine
python -m build
python -m twine upload dist/*
```

Bump `version` in `pyproject.toml`, `src/arythmatic_connect_mcp/__init__.py`, and the User-Agent in `src/arythmatic_connect_mcp/client.py` before building. Tag the release on GitHub matching the version.

# Local development

```bash
cd mcp/
pip install -e ".[dev]"
pytest
```

Run the server manually to sanity-check tool registration:

```bash
ARYTHMATIC_API_BASE_URL=http://localhost:8000/api/v1 \
ARYTHMATIC_API_KEY=arc_test_xxxx \
python -m arythmatic_connect_mcp
```

(Stdio-mode — you can pipe MCP JSON-RPC at it manually if you want, but typically you wire it into an MCP client.)
