# Cloud MCP (all existing tools)

Endpoint: `https://adhdos.app/mcp`.
Use Streamable HTTP with `Authorization: Bearer <API key>`. Generate/reset/revoke the shared key in desktop settings → MCP / API → API. Resetting/revoking affects both protocols immediately.

Cloud access requires an active Pro subscription (the existing billing record). Expiry blocks every request with 403 subscription_required without deleting data or revoking the key; renewal restores the same key automatically. Status and revocation remain available while expired. Local MCP stays free.

Cloud MCP exposes all current REST data operations. See the [capability and field contract](./cloud-api.html#对外契约) and [OpenAPI description](./openapi.json). `tools/list` is the machine-readable MCP input contract; REST and MCP have separate version identifiers.

| Cloud tool | REST operation | Notes |
|---|---|---|
| `get_snapshot` | GET /snapshot | Broad read, explicit need required |
| `list_tasks` | GET /tasks | Source, done, partition and pagination filters |
| `search` | GET /search | Task and Board search |
| `list_board_items` | GET /board-items | Includes `tabsOnly` for partition names |
| `get_today_context` | GET /today-context | UTC date |
| `create_task` | POST /tasks | Structured task, including subtasks |
| `import_tasks` | POST /tasks with input | Atomic multiline capture, up to 50 tasks |
| `update_task` | PATCH /tasks/{id} | Text, done, date, partition; append/edit/complete/delete subtasks by ID |
| `complete_task` | POST /tasks/{id}/complete | Does not archive |
| `archive_task` | POST /tasks/{id}/archive | Completed tasks only |
| `delete_task` | PATCH /tasks/{id} with deleted=true | Moves to cancelled tasks |
| `set_archived_task_liked` | PATCH /tasks/{id} with source=archived | Explicit liked boolean |
| `create_board_item` | POST /board-items | Content, tab, optional initial thought |
| `append_board_thought` | POST /board-items/{id}/thoughts | Append without replacing content |
| `delete_board_item` | POST /board-items/{id}/delete | Moves item and thoughts to trash |
| `get_board_image` | GET /board-items/{id}/image | Owned private image URL, expiresAt in Unix milliseconds |

All cloud writes require `requestId`. Updating, completing, archiving, deleting and liking tasks, and deleting Board items require `expectedUpdatedAt` from the last read. Appending a thought uses server-side append semantics and does not require a version. Never submit a snapshot as a write body.
These call the same REST handler and database transaction as Scriptable. See [cloud API](./cloud-api.html) for fields, limits and errors. List source can be active, archived or cancelled. Write tools require an explicit `requestId` (Idempotency-Key); updates, completion and archival also require `expectedUpdatedAt` from the last read. Retrying the same operation keeps the same requestId and arguments. Never silently reread and overwrite a version conflict.

Completion only sets done=true and retains the active task. Archival is separate and fails if the task is not already complete. This behavior now applies to local MCP too; older clients that expected complete_task to archive should call archive_task explicitly after completion.

```json
{"mcpServers":{"adhdos":{"url":"https://adhdos.app/mcp","headers":{"Authorization":"Bearer YOUR_API_KEY"}}}}
```

This is a generic configuration example: client configuration keys may differ. Clients must support custom Authorization headers. OAuth-only connectors are not supported by this API-key endpoint. No credentials belong in the URL. For browser-based clients the server administrator must explicitly allow the exact origin through `MCP_ALLOWED_ORIGINS` (comma-separated); absent Origin is allowed for desktop/server clients. Unknown Origin is rejected.

The remote service uses the official MCP SDK, stateless HTTP, JSON responses and no persistent sessions. GET/SSE and DELETE return 405. Cloud and local modes share pure query functions. The local compatibility table below records argument and availability differences. Cloud snapshots include the same allowed data fields as local exports and expose the last cloud sync/write timestamp; unsynced local data cannot be read remotely. Local mode remains available for offline use. Do not configure both modes with the same server name simultaneously.

---

# ADHDOS MCP Data Source

ADHD OS desktop can expose your local ADHDOS data as an MCP data source with both
read and write tools. It works with Claude Desktop, Cursor, Codex, and other clients
that accept a standard `mcpServers` configuration.

The MCP server only reads this fixed snapshot file:

```text
~/Library/Application Support/adhd-os/adhdos-data-snapshot.json
```

Updating the snapshot overwrites that same file. ADHD OS does not create historical
snapshot files, and the CLI commands do not refresh, copy, or archive snapshots.

## Quick Start

Open ADHD OS desktop first, then open `Desktop Settings -> MCP`.

Use the `ADHDOS MCP 数据源` section to:

- copy one guided setup message for an agent that can configure MCP
- copy the standard `mcpServers` JSON manually
- update the current snapshot
- test the MCP data source

Paste the copied JSON into your MCP client configuration. Claude Desktop, Cursor,
Codex, and similar clients use the same server definition; only the location of
their settings screen differs.

External MCP server management is an advanced section in the same settings page.
It is separate from the built-in ADHDOS MCP data source.

The guided setup message is designed for first-time MCP users. It tells the
agent to preserve the `adhdos` server name, use the desktop bridge for writes, and
test the connection after saving. Once you explicitly ask to use ADHDOS MCP,
access is authorized for that request only. Require “使用 ADHDOS MCP” in each new request; preserve existing agent instructions.

```json
{
  "mcpServers": {
    "adhdos": {
      "command": "node",
      "args": ["/Users/curiosita/dev/ADHDOS/adhd-os/mcp/adhdos-server.mjs"],
      "env": {
        "ADHDOS_SNAPSHOT_PATH": "~/Library/Application Support/adhd-os/adhdos-data-snapshot.json"
      }
    }
  }
}
```

## Read Tools

These tools read data from the current snapshot. The snapshot is updated every 30
seconds while the desktop app is running.

| Tool | Description |
|------|-------------|
| `get_snapshot` | Return the complete current snapshot. |
| `list_tasks` | List tasks with source, done, partition, optional limit/offset and archived/cancelled filters. |
| `search` | Search across tasks and Board items. |
| `list_board_items` | List Board items with filtering by tab, query, and time; tabsOnly returns partition names. |
| `get_today_context` | Return today's tasks, overdue tasks, recent Board items, and cycle context. |

`get_snapshot` returns everything. Prefer focused tools such as
`get_today_context`, `list_board_items`, and `search` unless an agent really
needs broad snapshot access.

`list_board_items` is optimized for natural requests such as "read my recent
Board items". By default it returns the 30 most recently updated Board items and
truncates long content. Agents can request narrower or fuller data with
`limit`, `since`, `tab`, `query`, `sort`, `contentLimit`, and
`includeFullContent`.

## Local write tools and compatibility

Local MCP exposes the same 16 tool names as cloud MCP. The capability table at the top applies to both transports. Local writes go through the authenticated desktop bridge; they do not edit the snapshot file. `tools/list` supplies the exact input schema.

| Difference | Local behavior | Cloud behavior |
|---|---|---|
| Existing five write tools | requestId and expectedUpdatedAt remain optional for older clients; send both for new integrations | Required operation ID; entity updates require version |
| Newly added write tools | requestId required; delete/like operations require version | Same requirements |
| list_tasks without limit | Keeps the existing unbounded local result; limit/offset are optional | Default 100, maximum 500 |
| Returned task fields | Normalized tasks, plus exportedAt, total and nextOffset | Ordinary list returns stored fields; combined list normalizes |
| Image preview | Public/data image URL has expiresAt=null; owned private image signs for 300 seconds using the desktop login | Owned private uploads only, signed for 300 seconds |
| Availability | Desktop must run for writes and image preview; snapshots can be queried offline | Cloud sync and active Pro subscription required |

Local version checks compare the supplied expectedUpdatedAt against current desktop storage, not just the snapshot. Local writes are serialized and commit affected data, deletion markers and retry receipts in one recoverable storage transaction. Receipts survive app restart for seven days. A stale version fails with version_conflict; a concurrent storage edit fails with storage_conflict. Do not silently reread and overwrite either conflict. Older local callers that omit versions or requestId do not receive those protections.

The local bridge binds to `127.0.0.1:17373`. Its random authentication token is stored in `~/Library/Application Support/adhd-os/adhdos-mcp-bridge.json`. Do not expose this port to the internet. The MCP server only accepts known tool names and declared fields; it does not expose arbitrary storage keys or file paths.

### Usage examples

```text
Use ADHD OS MCP to create a task: "Review Q3 budget" due next Friday.
```

```text
Use ADHD OS MCP to mark task 42 as done.
```

```text
Use ADHD OS MCP to add "Research vector databases" to my Board.
```

```text
Use ADHD OS MCP to mark the task "Write design doc" done. Archive it only if I separately ask.
```

## Reference Prompts

Explicitly request “use ADHDOS MCP” in each user request that reads personal data.
Authorization applies to that request only, including the tool calls needed to
finish it; it does not carry over to later messages in the same conversation.
Setup, authentication and tools/list do not authorize reading personal data.
This is an agent usage convention, not a per-request permission check enforced
by the API key. The key grants the technical access described in the API contract.

Setup and connection tests alone do not authorize reading personal data. Reading
authorization does not permit unsolicited writes: creating, updating, or completing
items still requires a user request. Arbitrary file access and other apps or web
search remain outside the scope unless requested.

First request:

```text
Use ADHD OS MCP to read my Board and summarize the themes that keep recurring. Do not use other apps or web search.
```

```text
Use ADHD OS MCP to read today and overdue tasks, then choose the 3 tasks I should do first.
```

```text
Use ADHD OS MCP to search for "review" and organize the related tasks and Board items.
```

中文示例：

```text
使用 ADHDOS MCP，读取我的 Board，帮我提炼最近反复出现的主题。不要使用其他应用或外部搜索。
```

```text
使用 ADHDOS MCP，读取今天和逾期任务，帮我选出最该先做的 3 件事。
```

后续请求仍需明确说“使用 ADHDOS MCP”，例如：

```text
使用 ADHDOS MCP，再看看逾期任务，帮我选出今天最该先做的 3 件事。
```

授权仅限当前请求，不自动延续到后续请求。

## CLI

The CLI is for setup and diagnostics. It does not update or archive snapshots.

```bash
npm run mcp:config
npm run mcp:status
npm run mcp:test
npm run mcp:test -- --data
```

- `mcp:config` prints a standard `mcpServers` JSON block.
- `mcp:status` checks the server file, Node.js command, snapshot JSON, and export time.
- `mcp:test` starts the MCP server and verifies `initialize` plus `tools/list`.
- `mcp:test -- --data` also calls a read-only data tool, so it requires a valid snapshot.

## External MCP Servers

ADHD OS desktop can connect to other local MCP servers over stdio. Configuration
lives in:

```text
~/Library/Application Support/adhd-os/mcp-servers.json
```

You can edit it from `Desktop Settings -> MCP`.

Security note: external MCP servers launch local commands from their
configuration. Only add servers you trust. The built-in ADHD OS MCP data source
is configured separately and does not need to be added in this advanced section.

Use the standard shape:

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "~/Desktop"]
    }
  }
}
```

Each server supports:

- `command`: executable to launch
- `args`: string arguments
- `cwd`: optional working directory
- `env`: optional string environment variables
- `disabled`: set to `true` to keep the server configured but unavailable

## Troubleshooting

- `snapshot_missing`: open ADHD OS desktop and update the current snapshot.
- `snapshot_invalid_json`: update the current snapshot again.
- `server_file_missing`: confirm the repository or packaged app includes `mcp/adhdos-server.mjs`.
- `node_not_found`: in development, install Node.js or set `ADHDOS_MCP_NODE_COMMAND`.
  In the packaged macOS app, ADHD OS uses its own Electron runtime with
  `ELECTRON_RUN_AS_NODE=1`, so a separate shell `node` command is not required.
- `mcp_timeout`: the MCP server started but did not respond in time.
- `invalid_response`: the MCP server wrote malformed JSON-RPC output.
- `permission_denied`: check file and executable permissions.

## Desktop Bridge

The preload bridge exposes these methods to renderer code:

- `window.electronAPI.mcpGetState()`
- `window.electronAPI.mcpSaveConfig({ config })`
- `window.electronAPI.mcpConnect({ name })`
- `window.electronAPI.mcpDisconnect({ name })`
- `window.electronAPI.mcpListTools({ name })`
- `window.electronAPI.mcpCallTool({ name, toolName, arguments })`
- `window.electronAPI.adhdosMcpTest({ language })`
- `window.electronAPI.clipboardWriteText({ text })`
- `window.electronAPI.adhdosApiGetSnapshot()`