@mseep/affine-mcp-server 2.3.0

package/docs/getting-started.md

@@ -0,0 +1,229 @@
+# Getting Started
+
+This guide is the fastest way to get AFFiNE MCP Server working and confirm that your MCP client can reach AFFiNE successfully.
+
+## Choose a setup path
+
+| Scenario | Recommended path |
+| --- | --- |
+| Local MCP client on your machine | Use the saved-config flow with `affine-mcp login` |
+| AFFiNE Cloud | Use an API token |
+| Self-hosted AFFiNE | Use an API token, or email/password if your instance allows it |
+| Temporary usage without a global install | Use `npx` |
+| Run the server in Docker | Use the GHCR image and HTTP transport |
+| Remote MCP deployment | Skip to [configuration and deployment](configuration-and-deployment.md) |
+
+## Path A: Saved config with interactive login
+
+This is the recommended local setup because it keeps client config minimal and avoids repeated environment-variable configuration.
+
+### 1. Install the CLI
+
+```bash
+npm i -g affine-mcp-server
+affine-mcp --version
+```
+
+### 2. Save credentials
+
+```bash
+affine-mcp login
+```
+
+What happens:
+
+- The CLI asks for your AFFiNE base URL
+- For AFFiNE Cloud, it prompts for an API token
+- For self-hosted AFFiNE, it can sign in with email/password and generate a token automatically
+- The effective config is stored at `~/.config/affine-mcp/config`
+
+### 3. Verify the saved config
+
+```bash
+affine-mcp status
+affine-mcp doctor
+```
+
+### 4. Register the server with a client
+
+Minimal stdio config:
+
+```json
+{
+  "mcpServers": {
+    "affine": {
+      "command": "affine-mcp"
+    }
+  }
+}
+```
+
+See [client setup](client-setup.md) for full client-specific snippets.
+
+## Path B: Explicit environment variables
+
+Use this path when you prefer stateless or container-friendly setup instead of a saved config file.
+
+### Required variables
+
+- `AFFINE_BASE_URL`
+- One auth strategy:
+  - `AFFINE_API_TOKEN`
+  - `AFFINE_COOKIE`
+  - `AFFINE_EMAIL` and `AFFINE_PASSWORD`
+
+### Example: AFFiNE Cloud
+
+```bash
+export AFFINE_BASE_URL="https://app.affine.pro"
+export AFFINE_API_TOKEN="ut_xxx"
+affine-mcp status
+```
+
+### Example: self-hosted AFFiNE with email/password
+
+```bash
+export AFFINE_BASE_URL="https://your-affine.example.com"
+export AFFINE_EMAIL="you@example.com"
+export AFFINE_PASSWORD="secret"
+affine-mcp status
+```
+
+For the full environment-variable reference, see [configuration and deployment](configuration-and-deployment.md#environment-variables).
+
+## Path C: Run from the Docker image
+
+Use this when:
+
+- you want a containerized local or remote deployment
+- you prefer an HTTP MCP endpoint over stdio
+- you do not want to install Node.js on the target host
+
+```bash
+docker run -d \
+  -p 3000:3000 \
+  -e MCP_TRANSPORT=http \
+  -e AFFINE_BASE_URL=https://your-affine-instance.com \
+  -e AFFINE_API_TOKEN=ut_your_token \
+  -e AFFINE_MCP_AUTH_MODE=bearer \
+  -e AFFINE_MCP_HTTP_TOKEN=your-strong-secret \
+  ghcr.io/dawncr0w/affine-mcp-server:latest
+```
+
+Quick verification:
+
+```bash
+curl http://localhost:3000/healthz
+curl http://localhost:3000/readyz
+```
+
+Client-side MCP config:
+
+```json
+{
+  "mcpServers": {
+    "affine": {
+      "type": "http",
+      "url": "http://localhost:3000/mcp",
+      "headers": {
+        "Authorization": "Bearer your-strong-secret"
+      }
+    }
+  }
+}
+```
+
+For OAuth mode, origin controls, and deployment hardening, continue with [configuration and deployment](configuration-and-deployment.md#docker).
+
+## Path D: Run from a local clone
+
+Use this when you want to inspect or modify the server locally.
+
+```bash
+git clone https://github.com/dawncr0w/affine-mcp-server.git
+cd affine-mcp-server
+npm install
+npm run build
+node dist/index.js
+```
+
+You can also expose a linked CLI locally:
+
+```bash
+npm link
+affine-mcp --version
+```
+
+## Verify your setup
+
+Use this sequence after any first-run setup:
+
+```bash
+affine-mcp status
+affine-mcp show-config
+affine-mcp doctor
+```
+
+If you are running the Docker image, also verify:
+
+```bash
+curl http://localhost:3000/healthz
+curl http://localhost:3000/readyz
+```
+
+Expected results:
+
+- `status` confirms the active base URL, auth source, and connection result
+- `show-config` prints the effective configuration with secrets redacted
+- `doctor` checks config shape and connectivity and points to the failing layer
+- `healthz` and `readyz` return successful probe responses when the HTTP server is healthy
+
+If you are onboarding another client, these helpers can generate snippets from the current config:
+
+```bash
+affine-mcp snippet claude --env
+affine-mcp snippet codex --env
+affine-mcp snippet all --env
+```
+
+## Common first-run failures
+
+### Cloudflare blocks email/password sign-in
+
+AFFiNE Cloud (`app.affine.pro`) is behind Cloudflare. Programmatic requests to `/api/auth/sign-in` are blocked.
+
+Use:
+
+- `AFFINE_API_TOKEN`
+- or `affine-mcp login`, which guides you toward the supported path
+
+### Saved config exists, but the client cannot connect
+
+Run:
+
+```bash
+affine-mcp status
+affine-mcp doctor
+```
+
+Then verify that the client is invoking `affine-mcp` from the same environment where the config file exists.
+
+### Workspace is missing
+
+This server can access only server-backed AFFiNE workspaces.
+
+It cannot access workspaces that exist only in browser local storage.
+
+### "Method not found" when calling a tool
+
+MCP tools are not JSON-RPC top-level method names. Use an MCP client that calls `tools/list` and `tools/call` instead of sending direct JSON-RPC methods such as `{"method":"list_workspaces"}`.
+
+### Self-hosted email/password does not work
+
+Confirm:
+
+- your instance exposes the standard auth endpoints
+- Cloudflare or another bot-protection layer is not blocking sign-in
+- the credentials are valid
+
+If in doubt, switch to an API token.

package/docs/tool-reference.md

@@ -0,0 +1,200 @@
+# Tool Reference
+
+`tool-manifest.json` is the source of truth for the canonical tool names exposed by this server.
+
+Use this document as a grouped catalog. For exact schemas, your MCP client should inspect `tools/list`.
+
+## Conventions
+
+- Canonical names only: legacy alias names are not part of the public tool surface
+- Document editing relies on AFFiNE WebSocket-backed operations where noted
+- Experimental organize tools are marked explicitly
+- Use `AFFINE_TOOL_PROFILE=read_only`, `core`, or `authoring` in production if you want a reduced surface
+
+## Workspace
+
+| Tool | Purpose | Notes |
+| --- | --- | --- |
+| `list_workspaces` | List all available workspaces | Good first discovery step |
+| `get_workspace` | Read workspace details | Includes settings and metadata |
+| `create_workspace` | Create a workspace with an initial document | Destructive in the sense that it creates new server state |
+| `update_workspace` | Update workspace settings | Use carefully in shared workspaces |
+| `delete_workspace` | Permanently delete a workspace | Destructive |
+| `list_workspace_tree` | Return the workspace document hierarchy as a tree | Useful before moving docs |
+| `get_orphan_docs` | Find documents that are not linked from a parent doc | Useful for cleanup and audits |
+
+## Organization
+
+| Tool | Purpose | Notes |
+| --- | --- | --- |
+| `list_collections` | List workspace collections | |
+| `get_collection` | Read a collection by id | |
+| `create_collection` | Create a collection | |
+| `update_collection` | Rename a collection | |
+| `update_collection_rules` | Replace a collection's rules and rebuild its allow-list from workspace docs | Useful for rule-backed collections |
+| `delete_collection` | Delete a collection | Destructive |
+| `add_doc_to_collection` | Add a document to a collection allow-list | |
+| `remove_doc_from_collection` | Remove a document from a collection allow-list | |
+| `list_organize_nodes` | Dump the organize or folder tree | Experimental |
+| `create_folder` | Create a root or nested folder | Experimental |
+| `create_workspace_blueprint` | Create a simple workspace folder blueprint | Good for structured onboarding setups |
+| `rename_folder` | Rename a folder | Experimental |
+| `update_folder_icon` | Set or clear a folder's sidebar icon (emoji or named icon) | Experimental |
+| `get_folder_icon` | Read a folder's current sidebar icon | Experimental |
+| `delete_folder` | Delete a folder recursively | Experimental and destructive |
+| `move_organize_node` | Move a folder or link node | Experimental |
+| `add_organize_link` | Add a doc, tag, or collection link under a folder | Experimental |
+| `delete_organize_link` | Delete a doc, tag, or collection link | Experimental and destructive |
+
+## Documents
+
+### Discovery and metadata
+
+| Tool | Purpose | Notes |
+| --- | --- | --- |
+| `list_docs` | List documents with pagination | Includes `node.tags` |
+| `list_tags` | List all tags in a workspace | |
+| `search_docs` | Search titles with substring, prefix, or exact matching | Supports tag filter and updatedAt sorting |
+| `list_docs_by_tag` | List documents with a specific tag | |
+| `get_doc` | Read document metadata | |
+| `read_doc` | Read block content and plain text snapshot | WebSocket-backed; block rows include `linkedDocIds` for inline LinkedPage references |
+| `get_capabilities` | Inspect the server's high-level authoring and fidelity capabilities | Useful for adaptive clients |
+| `analyze_doc_fidelity` | Analyze how a document maps to Markdown and which native AFFiNE structures are lossy | Good before export or migration |
+| `list_children` | List direct child docs linked from a document | |
+
+### Publish and visibility
+
+| Tool | Purpose | Notes |
+| --- | --- | --- |
+| `publish_doc` | Make a document public | |
+| `revoke_doc` | Revoke public access | |
+
+### Create, duplicate, and move
+
+| Tool | Purpose | Notes |
+| --- | --- | --- |
+| `create_doc` | Create a new document | WebSocket-backed |
+| `create_doc_from_markdown` | Create a document from Markdown content | |
+| `inspect_template_structure` | Inspect a template's native AFFiNE structure and native-clone support | Helps choose a clone strategy |
+| `instantiate_template_native` | Instantiate a template via native AFFiNE block cloning, with optional Markdown fallback | Higher-fidelity than Markdown-only cloning |
+| `move_doc` | Move a document in the sidebar by relinking it under another parent | |
+| `delete_doc` | Delete a document | WebSocket-backed and destructive |
+
+### Content editing
+
+| Tool | Purpose | Notes |
+| --- | --- | --- |
+| `update_doc_title` | Rename a document in workspace metadata and in the page block | |
+| `update_doc_icon` | Set or clear a document's sidebar icon (emoji or named icon) | |
+| `get_doc_icon` | Read a document's current sidebar icon | |
+| `append_block` | Append canonical block types with validation and placement control | Supports text, media, embeds, database, and edgeless blocks. `frame`/`edgeless_text`/`note` accept `x`/`y`/`width`/`height`. `note` with `text` auto-creates a child paragraph so it renders on the edgeless canvas. |
+| `create_semantic_page` | Create an AFFiNE-native page with an intentional section skeleton and native block composition | High-level authoring helper |
+| `append_semantic_section` | Append a semantic section to an existing page by heading title | High-level authoring helper |
+| `append_markdown` | Append Markdown content to an existing document | |
+| `replace_doc_with_markdown` | Replace the main note content with Markdown | Overwrites main note content |
+
+### Tags
+
+| Tool | Purpose | Notes |
+| --- | --- | --- |
+| `create_tag` | Create a reusable workspace-level tag | |
+| `add_tag_to_doc` | Attach a tag to a document | |
+| `remove_tag_from_doc` | Detach a tag from a document | |
+
+### Custom properties
+
+| Tool | Purpose | Notes |
+| --- | --- | --- |
+| `list_doc_properties` | List workspace custom-property definitions and a document's current values | WebSocket-backed; reads the `db$docProperties` / `db$docCustomPropertyInfo` sub-docs |
+| `create_custom_property` | Create a workspace-wide custom property definition | Types: `text`, `number`, `checkbox`, `date`. Returns the `propertyId` |
+| `delete_custom_property` | Soft-delete a custom property definition by id or name | Destructive; existing values are hidden |
+| `set_doc_property` | Set a document's custom property value by property id or name | Value validated per type (`checkbox` boolean, `number`, `date` `YYYY-MM-DD`, `text`) |
+| `clear_doc_property` | Remove a custom property value from a document | |
+
+### Markdown export
+
+| Tool | Purpose | Notes |
+| --- | --- | --- |
+| `export_doc_markdown` | Export document content as Markdown | Useful for backup and automation |
+| `export_with_fidelity_report` | Export a document with a machine-readable fidelity report | Useful when native AFFiNE structures matter |
+
+## Database blocks
+
+| Tool | Purpose | Notes |
+| --- | --- | --- |
+| `compose_database_from_intent` | Create or enrich a database block from a high-level schema intent | Useful for project boards and structured tables |
+| `add_database_column` | Add a column to a database block | Supports `rich-text`, `select`, `multi-select`, `number`, `checkbox`, `link`, and `date` |
+| `add_database_row` | Add a row to a database block | Can set the built-in title field |
+| `delete_database_row` | Delete a row by row block id | Destructive |
+| `read_database_columns` | Read schema metadata, types, options, and view mappings | Useful before edits |
+| `read_database_cells` | Read row titles and decoded cell values | Supports row and column filters |
+| `update_database_row` | Update multiple cells on a row at once | `createOption` defaults to `true` |
+
+## Edgeless canvas and surface elements
+
+AFFiNE's edgeless doc has two layers: top-level edgeless blocks (`note`, `frame`, `edgeless-text`) with `prop:xywh`, and the surface layer (`affine:surface`) which stores free-floating shapes, connectors, canvas text, and groups in `prop:elements.value` — the native BlockSuite representation.
+
+| Tool | Purpose | Notes |
+| --- | --- | --- |
+| `get_edgeless_canvas` | Read the full canvas: edgeless blocks + surface elements with parsed `{x,y,width,height}`, aggregate `bounds`, per-type `elementCounts` | Deterministic z-order (fractional-index sorted). Note entries carry a structured `children` array of their block descendants (`flavour`, `type`, `text`, `language`, `checked`) so markdown-seeded content round-trips faithfully. |
+| `add_surface_element` | Add a `shape`, `connector`, `text`, or `group` to the surface | Shapes: rect/ellipse/diamond/triangle with fill, stroke, and text. Connectors accept `sourceId`/`targetId` and optional `sourcePosition`/`targetPosition` relative `[x,y]` in `[0,1]`. When both endpoints are bound by id and neither position is supplied, they auto-snap to BlockSuite's four tangent-carrying side-midpoints based on relative bounds. Creates the surface block if the doc doesn't have one. |
+| `list_surface_elements` | List all surface elements (optionally filter by `type` or `elementId`) | Returns raw `xywh` plus parsed `bounds` sorted by fractional `index` ascending; serializes `Y.Text` fields to plain strings. |
+| `update_surface_element` | Partially update an element by id | `x`/`y`/`width`/`height` merge with current `xywh` (move without resizing, or vice versa). `text`/`label`/`title` replace their `Y.Text` wholesale. Fields not applicable to the element's type come back in the response `ignored` list. |
+| `delete_surface_element` | Delete an element by id | `pruneConnectors: true` additionally removes any connectors referencing the deleted element. |
+| `update_frame_children` | Replace a frame block's contents wholesale | Every resolved id (surface element or edgeless block) goes into `prop:childElementIds` and comes back in `ownedIds`; unknown ids in `missing`. Default `resizeToFit: true` recomputes xywh to match new contents + `padding` + title band; pass `resizeToFit: false` to preserve the current box. Pass `[]` to clear ownership (resize skipped). |
+| `update_edgeless_block` | Partially update a note/frame/edgeless-text block | `x`/`y`/`width`/`height` merge with current `prop:xywh`; `background` replaces `prop:background`. Fields not applicable to the flavour come back under `ignored`. Use for repositioning / resizing / recoloring without re-creating the block. |
+| `delete_block` | Delete a block by id | Removes descendants and unlinks from the parent's `sys:children` by default. `deleteChildren: false` keeps descendants orphaned; `pruneConnectors: true` also drops surface connectors referencing any deleted id. Refuses `affine:page`. |
+
+### Layout helpers on `append_block`
+
+When the new block is a frame/note/edgeless_text on the canvas, `append_block` accepts three optional fields that compute coordinates from the current doc state instead of the caller doing arithmetic:
+
+| Field | Applies to | Purpose |
+| --- | --- | --- |
+| `markdown` | `type="note"` | Parse markdown into heading/paragraph/list/code child blocks inside the note. Height auto-estimated from the content when `height` is omitted. |
+| `childElementIds: [id, ...]` | `type="frame"` | The frame's contents. Accepts ids of surface elements (shapes/connectors/groups) AND edgeless blocks (notes/frames/edgeless-text) — every resolved id goes into `prop:childElementIds`, matching what BlockSuite's editor writes when you drag members into a frame. Dragging the frame drags every owned member. Unresolved ids come back under `missing`. If `width`/`height` are omitted, the frame is sized to the union of resolvable bounds + `padding` + a 30px title band. |
+| `stackAfter: { blockId, direction?, gap? }` | any canvas block | Position relative to one or more existing siblings. `blockId` may be an array — picks whichever ref is furthest in the stack direction (useful when stacking below a row of columns) and centers the new block on the union bounds' orthogonal axis (when widths match, same as inheriting the anchor's x). Caller-provided `x` / `y` on the orthogonal axis still wins. Default `gap` is direction-aware: **80px horizontal** (left/right), **40px vertical** (up/down) — mirrors native-flowchart spacing where the flow axis gets more breathing room. |
+| `padding` | used by `childElementIds` auto-sizing and as fallback `gap` for `stackAfter` | Default 40. Explicit `padding` on the block overrides the direction-aware default; explicit `stackAfter.gap` wins over both. |
+
+## Comments
+
+| Tool | Purpose | Notes |
+| --- | --- | --- |
+| `list_comments` | List comments on a document | |
+| `create_comment` | Create a comment on a document | |
+| `update_comment` | Update comment content | |
+| `delete_comment` | Delete a comment | Destructive |
+| `resolve_comment` | Resolve or unresolve a comment | |
+
+## Version History
+
+| Tool | Purpose | Notes |
+| --- | --- | --- |
+| `list_histories` | List document history timestamps | |
+
+## Users and tokens
+
+| Tool | Purpose | Notes |
+| --- | --- | --- |
+| `current_user` | Return the current signed-in user | |
+| `sign_in` | Sign in with email and password | Self-hosted flows only for direct programmatic sign-in |
+| `update_profile` | Update current user profile data | |
+| `update_settings` | Update user notification preferences | |
+| `list_access_tokens` | List personal access tokens | |
+| `generate_access_token` | Create a personal access token | Sensitive operation |
+| `revoke_access_token` | Revoke a personal access token | Destructive |
+
+## Notifications
+
+| Tool | Purpose | Notes |
+| --- | --- | --- |
+| `list_notifications` | List notifications for the current user | |
+| `read_all_notifications` | Mark notifications as read | |
+
+## Blob storage
+
+| Tool | Purpose | Notes |
+| --- | --- | --- |
+| `upload_blob` | Upload a file or blob to workspace storage | |
+| `delete_blob` | Delete a blob from workspace storage | Destructive |
+| `cleanup_blobs` | Permanently remove deleted blobs | Cleanup-oriented |

package/docs/workflow-recipes.md

@@ -0,0 +1,147 @@
+# Workflow Recipes
+
+This guide shows practical tool sequences for common AFFiNE workflows.
+
+The exact JSON schema for each tool is discoverable from MCP `tools/list`. The recipes below focus on tool selection and ordering.
+
+## 1. Discover the right workspace and document
+
+Use when:
+
+- you are connecting to an AFFiNE instance for the first time
+- you need to locate a document before editing it
+
+Typical tool sequence:
+
+1. `list_workspaces`
+2. `list_docs` or `search_docs`
+3. `get_doc` or `read_doc`
+
+Prompt example:
+
+> List my workspaces, find the document titled "Launch Plan", and show me its current structure before editing anything.
+
+## 2. Create a document and place it in the sidebar tree
+
+Use when:
+
+- you need a new document under an existing parent doc
+- you want the new page to be visible in the workspace tree immediately
+
+Typical tool sequence:
+
+1. `search_docs` to find the parent
+2. `create_doc` or `create_doc_from_markdown`
+3. `move_doc` if you created the doc before deciding its final parent
+4. `list_children` to verify placement
+
+Prompt example:
+
+> Create a document called "Q2 Notes" under "Team Wiki", then verify that it appears as a child page.
+
+## 3. Find documents by tag or title and clean up metadata
+
+Use when:
+
+- titles are inconsistent
+- tags exist but you are not sure which document to open
+
+Typical tool sequence:
+
+1. `list_tags`
+2. `list_docs_by_tag` or `search_docs` with `tag`
+3. `update_doc_title`
+4. `add_tag_to_doc` or `remove_tag_from_doc`
+
+Prompt example:
+
+> Show me documents related to onboarding, rename the outdated title, and make sure the page has the `Onboarding` tag.
+
+## 4. Append content or replace the main note
+
+Use when:
+
+- you need to add content incrementally
+- you already have Markdown content to import
+
+Typical tool sequence:
+
+1. `read_doc`
+2. `append_block` or `append_markdown`
+3. `replace_doc_with_markdown` only when you intend to overwrite the main note
+
+Prompt example:
+
+> Read the current document, append a short release checklist section, and leave the existing content intact.
+
+## 5. Work with database blocks
+
+Use when:
+
+- you want to inspect or update an AFFiNE database
+- you need to add rows or change schema
+
+Typical tool sequence:
+
+1. `read_doc` to inspect the page structure
+2. `read_database_columns` to inspect schema
+3. `add_database_column` if needed
+4. `add_database_row`
+5. `update_database_row`
+6. `read_database_cells` to verify
+
+Prompt example:
+
+> Inspect the task database on this page, add a `Due Date` column if it is missing, then add a new task row and verify the final values.
+
+## 6. Review comments and resolve them
+
+Use when:
+
+- you need to triage feedback on a document
+- you want to update or resolve comments after an edit
+
+Typical tool sequence:
+
+1. `list_comments`
+2. `create_comment` or `update_comment`
+3. `resolve_comment`
+
+Prompt example:
+
+> List unresolved comments on the document, summarize them, and resolve the ones that are already addressed in the current draft.
+
+## 7. Publish a document or revoke public access
+
+Use when:
+
+- you are moving a document from draft to public view
+- you need to remove public access after review
+
+Typical tool sequence:
+
+1. `get_doc`
+2. `publish_doc` or `revoke_doc`
+3. `get_doc` again to confirm visibility state
+
+Prompt example:
+
+> Publish the final release notes page and confirm that public access is enabled.
+
+## 8. Export, duplicate, or clean up linked structure
+
+Use when:
+
+- you need a markdown backup
+- you want to recreate a page from Markdown
+- you need to inspect linked child pages
+
+Typical tool sequence:
+
+1. `export_doc_markdown`
+2. `create_doc_from_markdown` if you need a Markdown-based copy
+3. `list_children` if you need structural context
+
+Prompt example:
+
+> Export the template page as Markdown, create a copy under the current parent, and verify the copied page's child links.