affine-mcp-server 1.2.2 → 1.4.0

package/README.md

@@ -2,28 +2,34 @@
 
 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.2.2-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)
 
+<a href="https://glama.ai/mcp/servers/@DAWNCR0W/affine-mcp-server">
+  <img width="380" height="200" src="https://glama.ai/mcp/servers/@DAWNCR0W/affine-mcp-server/badge" alt="AFFiNE Server MCP server" />
+</a>
+
 ## Overview
 
 - Purpose: Manage AFFiNE workspaces and documents through MCP
 - Transport: stdio only (Claude Desktop / Codex compatible)
 - Auth: Token, Cookie, or Email/Password (priority order)
-- Tools: 30+ tools plus WebSocket-based document editing
-- Status: Production Ready (v1.2.1)
+- Tools: 32 focused tools with WebSocket-based document editing
+- Status: Active
  
-> New in v1.2.2: Fixed CLI binary to always run via Node (no shell mis-execution). Startup remains non-blocking for email/password login by default; set `AFFINE_LOGIN_AT_START=sync` to block at startup.
+> 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/search/publish/revoke + create/append paragraph/delete (WebSocket‑based) — added in v1.2.0
+- Documents: list/get/read/publish/revoke + create/append paragraph/delete (WebSocket‑based)
 - Comments: full CRUD and resolve
-- Version History: list and recover
-- Users & Tokens: profile/settings and personal access tokens
+- Version History: list
+- Users & Tokens: current user, sign in, profile/settings, and personal access tokens
 - Notifications: list and mark as read
+- Blob storage: upload/delete/cleanup
 
 ## Requirements
 
@@ -43,7 +49,7 @@ npx -y -p affine-mcp-server affine-mcp -- --version
 
 The package installs a CLI named `affine-mcp` that runs the MCP server over stdio.
 
-Note: From v1.2.2 the CLI wrapper (`bin/affine-mcp`) ensures Node runs the ESM entrypoint, preventing shell from misinterpreting JS.
+Note: From v1.2.2+ the CLI wrapper (`bin/affine-mcp`) ensures Node runs the ESM entrypoint, preventing shell from misinterpreting JS.
 
 ## Configuration
 
@@ -106,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
@@ -118,33 +161,30 @@ Notes
 ### Documents
 - `list_docs` – list documents with pagination
 - `get_doc` – get document metadata
-- `search_docs` – search documents by keyword
-- `recent_docs` – list recently updated documents
+- `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)
 - `append_paragraph` – append a paragraph block (WebSocket)
+- `append_block` – append slash-command style blocks (`heading/list/todo/code/divider/quote`)
 - `delete_doc` – delete a document (WebSocket)
 
 ### Comments
 - `list_comments`, `create_comment`, `update_comment`, `delete_comment`, `resolve_comment`
 
 ### Version History
-- `list_histories`, `recover_doc`
+- `list_histories`
 
 ### Users & Tokens
 - `current_user`, `sign_in`, `update_profile`, `update_settings`
 - `list_access_tokens`, `generate_access_token`, `revoke_access_token`
 
 ### Notifications
-- `list_notifications`, `read_notification`, `read_all_notifications`
+- `list_notifications`, `read_all_notifications`
 
 ### Blob Storage
 - `upload_blob`, `delete_blob`, `cleanup_blobs`
 
-### Advanced
-- `apply_doc_updates` – apply CRDT updates to documents
-
 ## Use Locally (clone)
 
 ```bash
@@ -160,19 +200,39 @@ npm link
 # Now use `affine-mcp` like a global binary
 ```
 
+## Quality Gates
+
+```bash
+npm run build
+npm run test:tool-manifest
+npm run pack:check
+```
+
+- `tool-manifest.json` is the source of truth for publicly exposed tool names.
+- CI validates that `registerTool(...)` declarations match the manifest exactly.
+
 ## Troubleshooting
 
 Authentication
 - Email/Password: ensure your instance allows password auth and credentials are valid
 - Cookie: copy cookies (e.g., `affine_session`, `affine_csrf`) from the browser DevTools after login
-- Token: generate a personal access token; verify it hasn’t expired
-- Startup timeouts: v1.2.2 includes a CLI wrapper fix and the default async login to avoid blocking the MCP handshake. Set `AFFINE_LOGIN_AT_START=sync` only if needed.
+- Token: generate a personal access token; verify it hasn't expired
+- Startup timeouts: v1.2.2+ includes a CLI wrapper fix and default async login to avoid blocking the MCP handshake. Set `AFFINE_LOGIN_AT_START=sync` only if needed.
 
 Connection
 - Confirm `AFFINE_BASE_URL` is reachable
 - 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
@@ -183,6 +243,17 @@ 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)
+- Added CI + manifest parity verification (`npm run test:tool-manifest`, `npm run ci`)
+- Added open-source community health docs and issue/PR templates
+
 ### 1.2.2 (2025‑09‑18)
 - CLI wrapper added to ensure Node runs ESM entry (`bin/affine-mcp`), preventing shell mis-execution
 - Docs cleaned: use env vars via shell/app config; `.env` file no longer recommended
@@ -195,7 +266,7 @@ Connection
 
 ### 1.2.0 (2025‑09‑16)
 - WebSocket-based document tools: `create_doc`, `append_paragraph`, `delete_doc` (create/edit/delete now supported)
-- Tool aliases: both `affine_*` and non‑prefixed names
+- Tool aliases introduced at the time (`affine_*` + non-prefixed names). They were removed later to reduce duplication.
 - ESM resolution: NodeNext; improved build stability
 - CLI binary: `affine-mcp` for easy `npm i -g` usage
 
@@ -212,11 +283,16 @@ Connection
 ## Contributing
 
 Contributions are welcome!
-1. Fork the repository
-2. Create a feature branch
-3. Add tests for new features
-4. Ensure all tests pass
-5. Submit a Pull Request
+1. Read `CONTRIBUTING.md`
+2. Run `npm run ci` locally before opening PR
+3. Keep tool changes synced with `tool-manifest.json`
+4. Use issue/PR templates in `.github/`
+
+## Community Health
+
+- Code of Conduct: `CODE_OF_CONDUCT.md`
+- Security policy: `SECURITY.md`
+- Contributing guide: `CONTRIBUTING.md`
 
 ## License
 

package/dist/index.js

@@ -8,7 +8,6 @@ import { registerCommentTools } from "./tools/comments.js";
 import { registerHistoryTools } from "./tools/history.js";
 import { registerUserTools } from "./tools/user.js";
 import { registerUserCRUDTools } from "./tools/userCRUD.js";
-import { registerUpdateTools } from "./tools/updates.js";
 import { registerAccessTokenTools } from "./tools/accessTokens.js";
 import { registerBlobTools } from "./tools/blobStorage.js";
 import { registerNotificationTools } from "./tools/notifications.js";
@@ -16,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}`,
@@ -65,7 +64,6 @@ async function buildServer() {
     registerHistoryTools(server, gql, { workspaceId: config.defaultWorkspaceId });
     registerUserTools(server, gql);
     registerUserCRUDTools(server, gql);
-    registerUpdateTools(server, gql, { workspaceId: config.defaultWorkspaceId });
     registerAccessTokenTools(server, gql);
     registerBlobTools(server, gql);
     registerNotificationTools(server, gql);

package/dist/tools/accessTokens.js

@@ -3,20 +3,15 @@ import { text } from "../util/mcp.js";
 export function registerAccessTokenTools(server, gql) {
     const listAccessTokensHandler = async () => {
         try {
-            const query = `query { accessTokens { id name createdAt expiresAt } }`;
+            const query = `query { currentUser { accessTokens { id name createdAt expiresAt } } }`;
             const data = await gql.request(query);
-            return text(data.accessTokens || []);
+            return text(data.currentUser?.accessTokens || []);
         }
         catch (error) {
             console.error("List access tokens error:", error.message);
-            return text([]);
+            return text({ error: error.message });
         }
     };
-    server.registerTool("affine_list_access_tokens", {
-        title: "List Access Tokens",
-        description: "List personal access tokens (metadata).",
-        inputSchema: {}
-    }, listAccessTokensHandler);
     server.registerTool("list_access_tokens", {
         title: "List Access Tokens",
         description: "List personal access tokens (metadata).",
@@ -27,14 +22,6 @@ export function registerAccessTokenTools(server, gql) {
         const data = await gql.request(mutation, { input: { name: parsed.name, expiresAt: parsed.expiresAt ?? null } });
         return text(data.generateUserAccessToken);
     };
-    server.registerTool("affine_generate_access_token", {
-        title: "Generate Access Token",
-        description: "Generate a personal access token (returns token).",
-        inputSchema: {
-            name: z.string(),
-            expiresAt: z.string().optional()
-        }
-    }, generateAccessTokenHandler);
     server.registerTool("generate_access_token", {
         title: "Generate Access Token",
         description: "Generate a personal access token (returns token).",
@@ -48,13 +35,6 @@ export function registerAccessTokenTools(server, gql) {
         const data = await gql.request(mutation, { id: parsed.id });
         return text({ success: data.revokeUserAccessToken });
     };
-    server.registerTool("affine_revoke_access_token", {
-        title: "Revoke Access Token",
-        description: "Revoke a personal access token by id.",
-        inputSchema: {
-            id: z.string()
-        }
-    }, revokeAccessTokenHandler);
     server.registerTool("revoke_access_token", {
         title: "Revoke Access Token",
         description: "Revoke a personal access token by id.",

package/dist/tools/auth.js

@@ -7,14 +7,6 @@ export function registerAuthTools(server, gql, baseUrl) {
         gql.setCookie(cookieHeader);
         return text({ signedIn: true });
     };
-    server.registerTool("affine_sign_in", {
-        title: "Sign In",
-        description: "Sign in to AFFiNE using email and password; sets session cookies for subsequent calls.",
-        inputSchema: {
-            email: z.string().email(),
-            password: z.string().min(1)
-        }
-    }, signInHandler);
     server.registerTool("sign_in", {
         title: "Sign In",
         description: "Sign in to AFFiNE using email and password; sets session cookies for subsequent calls.",

package/dist/tools/blobStorage.js

@@ -1,36 +1,76 @@
 import { z } from "zod";
 import { text } from "../util/mcp.js";
+import FormData from "form-data";
+import fetch from "node-fetch";
+function decodeBlobContent(content) {
+    const normalized = content.trim().replace(/\s+/g, "");
+    const base64Like = normalized.length > 0 && normalized.length % 4 === 0 && /^[A-Za-z0-9+/=]+$/.test(normalized);
+    if (base64Like) {
+        try {
+            const decoded = Buffer.from(normalized, "base64");
+            if (decoded.length > 0) {
+                return decoded;
+            }
+        }
+        catch {
+            // Fallback to UTF-8 text below.
+        }
+    }
+    return Buffer.from(content, "utf8");
+}
 export function registerBlobTools(server, gql) {
     // UPLOAD BLOB/FILE
     const uploadBlobHandler = async ({ workspaceId, content, filename, contentType }) => {
         try {
-            // Note: Actual file upload requires multipart form data
-            // This is a simplified version that returns structured data
-            const blobId = `blob_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+            const endpoint = gql.endpoint || `${process.env.AFFINE_BASE_URL || "http://localhost:3010"}/graphql`;
+            const headers = gql.headers || {};
+            const cookie = gql.cookie || headers.Cookie || "";
+            const payload = decodeBlobContent(content);
+            const safeFilename = filename || `blob-${Date.now()}.bin`;
+            const mime = contentType || "application/octet-stream";
+            const form = new FormData();
+            form.append("operations", JSON.stringify({
+                query: `mutation SetBlob($workspaceId: String!, $blob: Upload!) {
+          setBlob(workspaceId: $workspaceId, blob: $blob)
+        }`,
+                variables: {
+                    workspaceId,
+                    blob: null
+                }
+            }));
+            form.append("map", JSON.stringify({ "0": ["variables.blob"] }));
+            form.append("0", payload, { filename: safeFilename, contentType: mime });
+            const response = await fetch(endpoint, {
+                method: "POST",
+                headers: {
+                    ...headers,
+                    Cookie: cookie,
+                    ...form.getHeaders(),
+                },
+                body: form,
+            });
+            const result = await response.json();
+            if (result.errors?.length) {
+                throw new Error(result.errors[0].message);
+            }
+            const blobKey = result.data?.setBlob;
+            if (!blobKey) {
+                throw new Error("Upload succeeded but no blob key was returned.");
+            }
             return text({
-                id: blobId,
+                id: blobKey,
+                key: blobKey,
                 workspaceId,
-                filename: filename || "unnamed",
-                contentType: contentType || "application/octet-stream",
-                size: content.length,
-                uploadedAt: new Date().toISOString(),
-                note: "Blob metadata created. Use AFFiNE UI for actual file upload."
+                filename: safeFilename,
+                contentType: mime,
+                size: payload.length,
+                uploadedAt: new Date().toISOString()
             });
         }
         catch (error) {
             return text({ error: error.message });
         }
     };
-    server.registerTool("affine_upload_blob", {
-        title: "Upload Blob",
-        description: "Upload a file or blob to workspace storage.",
-        inputSchema: {
-            workspaceId: z.string().describe("Workspace ID"),
-            content: z.string().describe("Base64 encoded content or text"),
-            filename: z.string().optional().describe("Filename"),
-            contentType: z.string().optional().describe("MIME type")
-        }
-    }, uploadBlobHandler);
     server.registerTool("upload_blob", {
         title: "Upload Blob",
         description: "Upload a file or blob to workspace storage.",
@@ -60,15 +100,6 @@ export function registerBlobTools(server, gql) {
             return text({ error: error.message });
         }
     };
-    server.registerTool("affine_delete_blob", {
-        title: "Delete Blob",
-        description: "Delete a blob/file from workspace storage.",
-        inputSchema: {
-            workspaceId: z.string().describe("Workspace ID"),
-            key: z.string().describe("Blob key/ID to delete"),
-            permanently: z.boolean().optional().describe("Delete permanently")
-        }
-    }, deleteBlobHandler);
     server.registerTool("delete_blob", {
         title: "Delete Blob",
         description: "Delete a blob/file from workspace storage.",
@@ -95,13 +126,6 @@ export function registerBlobTools(server, gql) {
             return text({ error: error.message });
         }
     };
-    server.registerTool("affine_cleanup_blobs", {
-        title: "Cleanup Deleted Blobs",
-        description: "Permanently remove deleted blobs to free up storage.",
-        inputSchema: {
-            workspaceId: z.string().describe("Workspace ID")
-        }
-    }, cleanupBlobsHandler);
     server.registerTool("cleanup_blobs", {
         title: "Cleanup Deleted Blobs",
         description: "Permanently remove deleted blobs to free up storage.",

package/dist/tools/comments.js

@@ -9,17 +9,6 @@ export function registerCommentTools(server, gql, defaults) {
         const data = await gql.request(query, { workspaceId, docId: parsed.docId, first: parsed.first, offset: parsed.offset, after: parsed.after });
         return text(data.workspace.comments);
     };
-    server.registerTool("affine_list_comments", {
-        title: "List Comments",
-        description: "List comments of a doc (with replies).",
-        inputSchema: {
-            workspaceId: z.string().optional(),
-            docId: z.string(),
-            first: z.number().optional(),
-            offset: z.number().optional(),
-            after: z.string().optional()
-        }
-    }, listCommentsHandler);
     server.registerTool("list_comments", {
         title: "List Comments",
         description: "List comments of a doc (with replies).",
@@ -36,22 +25,12 @@ export function registerCommentTools(server, gql, defaults) {
         if (!workspaceId)
             throw new Error("workspaceId required (or set AFFINE_WORKSPACE_ID)");
         const mutation = `mutation CreateComment($input: CommentCreateInput!){ createComment(input:$input){ id content createdAt updatedAt resolved } }`;
-        const input = { content: parsed.content, docId: parsed.docId, workspaceId, docTitle: parsed.docTitle || "", docMode: parsed.docMode || "Page", mentions: parsed.mentions };
+        const normalizedDocMode = (parsed.docMode || 'page').toLowerCase() === 'edgeless' ? 'edgeless' : 'page';
+        const normalizedContent = typeof parsed.content === 'string' ? { text: parsed.content } : parsed.content;
+        const input = { content: normalizedContent, docId: parsed.docId, workspaceId, docTitle: parsed.docTitle || "", docMode: normalizedDocMode, mentions: parsed.mentions };
         const data = await gql.request(mutation, { input });
         return text(data.createComment);
     };
-    server.registerTool("affine_create_comment", {
-        title: "Create Comment",
-        description: "Create a comment on a doc.",
-        inputSchema: {
-            workspaceId: z.string().optional(),
-            docId: z.string(),
-            docTitle: z.string().optional(),
-            docMode: z.enum(["Page", "Edgeless"]).optional(),
-            content: z.any(),
-            mentions: z.array(z.string()).optional()
-        }
-    }, createCommentHandler);
     server.registerTool("create_comment", {
         title: "Create Comment",
         description: "Create a comment on a doc.",
@@ -59,7 +38,7 @@ export function registerCommentTools(server, gql, defaults) {
             workspaceId: z.string().optional(),
             docId: z.string(),
             docTitle: z.string().optional(),
-            docMode: z.enum(["Page", "Edgeless"]).optional(),
+            docMode: z.enum(["Page", "Edgeless", "page", "edgeless"]).optional(),
             content: z.any(),
             mentions: z.array(z.string()).optional()
         }
@@ -69,14 +48,6 @@ export function registerCommentTools(server, gql, defaults) {
         const data = await gql.request(mutation, { input: { id: parsed.id, content: parsed.content } });
         return text({ success: data.updateComment });
     };
-    server.registerTool("affine_update_comment", {
-        title: "Update Comment",
-        description: "Update a comment content.",
-        inputSchema: {
-            id: z.string(),
-            content: z.any()
-        }
-    }, updateCommentHandler);
     server.registerTool("update_comment", {
         title: "Update Comment",
         description: "Update a comment content.",
@@ -90,13 +61,6 @@ export function registerCommentTools(server, gql, defaults) {
         const data = await gql.request(mutation, { id: parsed.id });
         return text({ success: data.deleteComment });
     };
-    server.registerTool("affine_delete_comment", {
-        title: "Delete Comment",
-        description: "Delete a comment by id.",
-        inputSchema: {
-            id: z.string()
-        }
-    }, deleteCommentHandler);
     server.registerTool("delete_comment", {
         title: "Delete Comment",
         description: "Delete a comment by id.",
@@ -109,14 +73,6 @@ export function registerCommentTools(server, gql, defaults) {
         const data = await gql.request(mutation, { input: parsed });
         return text({ success: data.resolveComment });
     };
-    server.registerTool("affine_resolve_comment", {
-        title: "Resolve Comment",
-        description: "Resolve or unresolve a comment.",
-        inputSchema: {
-            id: z.string(),
-            resolved: z.boolean()
-        }
-    }, resolveCommentHandler);
     server.registerTool("resolve_comment", {
         title: "Resolve Comment",
         description: "Resolve or unresolve a comment.",