affine-mcp-server 1.3.0 → 1.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 A Model Context Protocol (MCP) server that integrates with AFFiNE (self‑hosted or cloud). It exposes AFFiNE workspaces and documents to AI assistants over stdio.
 
-[![Version](https://img.shields.io/badge/version-1.3.0-blue)](https://github.com/dawncr0w/affine-mcp-server/releases)
+[![Version](https://img.shields.io/badge/version-1.4.0-blue)](https://github.com/dawncr0w/affine-mcp-server/releases)
 [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-1.17.2-green)](https://github.com/modelcontextprotocol/typescript-sdk)
 [![CI](https://github.com/dawncr0w/affine-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/dawncr0w/affine-mcp-server/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-MIT-yellow)](LICENSE)
@@ -16,15 +16,15 @@ A Model Context Protocol (MCP) server that integrates with AFFiNE (self‑hosted
 - Purpose: Manage AFFiNE workspaces and documents through MCP
 - Transport: stdio only (Claude Desktop / Codex compatible)
 - Auth: Token, Cookie, or Email/Password (priority order)
-- Tools: 31 focused tools with WebSocket-based document editing
+- Tools: 32 focused tools with WebSocket-based document editing
 - Status: Active
  
-> New in v1.3.0: Added `append_block` for slash-command style blocks (heading/list/todo/code/divider/quote), removed duplicated aliases/non-core tools, and added CI + manifest quality gates.
+> New in v1.4.0: Added `read_doc` for document content snapshots (blocks + plain text), plus Cursor setup/troubleshooting guidance.
 
 ## Features
 
 - Workspace: create (with initial doc), read, update, delete
-- Documents: list/get/publish/revoke + create/append paragraph/delete (WebSocket‑based)
+- Documents: list/get/read/publish/revoke + create/append paragraph/delete (WebSocket‑based)
 - Comments: full CRUD and resolve
 - Version History: list
 - Users & Tokens: current user, sign in, profile/settings, and personal access tokens
@@ -112,6 +112,43 @@ Notes
 - Command: `affine-mcp`
 - Environment: `AFFINE_BASE_URL` + one auth method (`AFFINE_API_TOKEN` | `AFFINE_COOKIE` | `AFFINE_EMAIL`/`AFFINE_PASSWORD`)
 
+### Cursor
+
+Cursor also supports MCP over stdio with `mcp.json`.
+
+Project-local (`.cursor/mcp.json`) example:
+
+```json
+{
+  "mcpServers": {
+    "affine": {
+      "command": "affine-mcp",
+      "env": {
+        "AFFINE_BASE_URL": "https://your-affine-instance.com",
+        "AFFINE_API_TOKEN": "apt_xxx"
+      }
+    }
+  }
+}
+```
+
+If you prefer `npx`:
+
+```json
+{
+  "mcpServers": {
+    "affine": {
+      "command": "npx",
+      "args": ["-y", "-p", "affine-mcp-server", "affine-mcp"],
+      "env": {
+        "AFFINE_BASE_URL": "https://your-affine-instance.com",
+        "AFFINE_API_TOKEN": "apt_xxx"
+      }
+    }
+  }
+}
+```
+
 ## Available Tools
 
 ### Workspace
@@ -124,6 +161,7 @@ Notes
 ### Documents
 - `list_docs` – list documents with pagination
 - `get_doc` – get document metadata
+- `read_doc` – read document block content and plain text snapshot (WebSocket)
 - `publish_doc` – make document public
 - `revoke_doc` – revoke public access
 - `create_doc` – create a new document (WebSocket)
@@ -186,6 +224,15 @@ Connection
 - GraphQL endpoint default is `/graphql`
 - Check firewall/proxy rules; verify CORS if self‑hosted
 
+Method not found
+- MCP tool names (for example `list_workspaces`) are not JSON-RPC top-level method names.
+- Use an MCP client (`tools/list`, `tools/call`) instead of sending direct JSON-RPC calls like `{\"method\":\"list_workspaces\"}`.
+- From v1.3.0, only canonical tool names are exposed (legacy `affine_*` aliases were removed).
+
+Workspace visibility
+- This MCP server can access server-backed workspaces only (AFFiNE cloud/self-hosted).
+- Browser local-storage workspaces are client-side data, so they are not visible via server GraphQL/WebSocket APIs.
+
 ## Security Considerations
 
 - Never commit `.env` with secrets
@@ -196,6 +243,11 @@ Connection
 
 ## Version History
 
+### 1.4.0 (2026‑02‑13)
+- Added `read_doc` for reading document block snapshot + plain text
+- Added Cursor setup examples and troubleshooting notes for JSON-RPC method usage
+- Added explicit local-storage workspace limitation notes
+
 ### 1.3.0 (2026‑02‑13)
 - Added `append_block` for slash-command style editing (`heading/list/todo/code/divider/quote`)
 - Tool surface simplified to 31 canonical tools (duplicate aliases removed)

package/dist/index.js

@@ -15,7 +15,7 @@ import { loginWithPassword } from "./auth.js";
 import { registerAuthTools } from "./tools/auth.js";
 const config = loadConfig();
 async function buildServer() {
-    const server = new McpServer({ name: "affine-mcp", version: "1.2.2" });
+    const server = new McpServer({ name: "affine-mcp", version: "1.4.0" });
     // Initialize GraphQL client with authentication
     const gql = new GraphQLClient({
         endpoint: `${config.baseUrl}${config.graphqlPath}`,

package/dist/tools/docs.js

@@ -49,6 +49,32 @@ export function registerDocTools(server, gql, defaults) {
         }
         return yText;
     }
+    function asText(value) {
+        if (value instanceof Y.Text)
+            return value.toString();
+        if (typeof value === "string")
+            return value;
+        return "";
+    }
+    function childIdsFrom(value) {
+        if (!(value instanceof Y.Array))
+            return [];
+        const childIds = [];
+        value.forEach((entry) => {
+            if (typeof entry === "string") {
+                childIds.push(entry);
+                return;
+            }
+            if (Array.isArray(entry)) {
+                for (const child of entry) {
+                    if (typeof child === "string") {
+                        childIds.push(child);
+                    }
+                }
+            }
+        });
+        return childIds;
+    }
     function setSysFields(block, blockId, flavour) {
         block.set("sys:id", blockId);
         block.set("sys:flavour", flavour);
@@ -228,6 +254,103 @@ export function registerDocTools(server, gql, defaults) {
             docId: DocId
         }
     }, getDocHandler);
+    const readDocHandler = async (parsed) => {
+        const workspaceId = parsed.workspaceId || defaults.workspaceId;
+        if (!workspaceId) {
+            throw new Error("workspaceId is required. Provide it as a parameter or set AFFINE_WORKSPACE_ID in environment.");
+        }
+        const { endpoint, cookie } = await getCookieAndEndpoint();
+        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
+        const socket = await connectWorkspaceSocket(wsUrl, cookie);
+        try {
+            await joinWorkspace(socket, workspaceId);
+            const snapshot = await loadDoc(socket, workspaceId, parsed.docId);
+            if (!snapshot.missing) {
+                return text({
+                    docId: parsed.docId,
+                    title: null,
+                    exists: false,
+                    blockCount: 0,
+                    blocks: [],
+                    plainText: "",
+                });
+            }
+            const doc = new Y.Doc();
+            Y.applyUpdate(doc, Buffer.from(snapshot.missing, "base64"));
+            const blocks = doc.getMap("blocks");
+            const pageId = findBlockIdByFlavour(blocks, "affine:page");
+            const noteId = findBlockIdByFlavour(blocks, "affine:note");
+            const visited = new Set();
+            const blockRows = [];
+            const plainTextLines = [];
+            let title = "";
+            const visit = (blockId) => {
+                if (visited.has(blockId))
+                    return;
+                visited.add(blockId);
+                const raw = blocks.get(blockId);
+                if (!(raw instanceof Y.Map))
+                    return;
+                const flavour = raw.get("sys:flavour");
+                const parentId = raw.get("sys:parent");
+                const type = raw.get("prop:type");
+                const textValue = asText(raw.get("prop:text"));
+                const language = raw.get("prop:language");
+                const checked = raw.get("prop:checked");
+                const childIds = childIdsFrom(raw.get("sys:children"));
+                if (flavour === "affine:page") {
+                    title = asText(raw.get("prop:title")) || title;
+                }
+                if (textValue.length > 0) {
+                    plainTextLines.push(textValue);
+                }
+                blockRows.push({
+                    id: blockId,
+                    parentId: typeof parentId === "string" ? parentId : null,
+                    flavour: typeof flavour === "string" ? flavour : null,
+                    type: typeof type === "string" ? type : null,
+                    text: textValue.length > 0 ? textValue : null,
+                    checked: typeof checked === "boolean" ? checked : null,
+                    language: typeof language === "string" ? language : null,
+                    childIds,
+                });
+                for (const childId of childIds) {
+                    visit(childId);
+                }
+            };
+            if (pageId) {
+                visit(pageId);
+            }
+            else if (noteId) {
+                visit(noteId);
+            }
+            for (const [id] of blocks) {
+                const blockId = String(id);
+                if (!visited.has(blockId)) {
+                    visit(blockId);
+                }
+            }
+            return text({
+                docId: parsed.docId,
+                title: title || null,
+                exists: true,
+                blockCount: blockRows.length,
+                blocks: blockRows,
+                plainText: plainTextLines.join("\n"),
+            });
+        }
+        finally {
+            socket.disconnect();
+        }
+    };
+    server.registerTool("read_doc", {
+        title: "Read Document Content",
+        description: "Read document block content via WebSocket snapshot (blocks + plain text).",
+        inputSchema: {
+            workspaceId: WorkspaceId.optional(),
+            docId: DocId,
+        },
+    }, readDocHandler);
     const publishDocHandler = async (parsed) => {
         const workspaceId = parsed.workspaceId || defaults.workspaceId;
         if (!workspaceId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "affine-mcp-server",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "private": false,
   "type": "module",
   "description": "Model Context Protocol server for AFFiNE - enables AI assistants to interact with AFFiNE workspaces, documents, and collaboration features.",
@@ -55,12 +55,12 @@
     "form-data": "^4.0.4",
     "node-fetch": "^3.3.2",
     "socket.io-client": "^4.8.1",
-    "undici": "^6.19.8",
+    "undici": "^7.21.0",
     "yjs": "^13.6.27",
     "zod": "^3.23.8"
   },
   "devDependencies": {
-    "@types/node": "^20.14.11",
+    "@types/node": "^25.2.3",
     "tsx": "^4.16.2",
     "typescript": "^5.5.4"
   }