affine-mcp-server 1.2.1 → 1.3.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.1-blue)](https://github.com/dawncr0w/affine-mcp-server/releases)
+[![Version](https://img.shields.io/badge/version-1.3.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: 31 focused tools with WebSocket-based document editing
+- Status: Active
  
-> New in v1.2.1: Email/Password login no longer blocks MCP startup. The server connects over stdio immediately and performs login asynchronously by default. Use `AFFINE_LOGIN_AT_START=sync` to restore the previous blocking behavior.
+> 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.
 
 ## 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/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,33 +49,15 @@ npx -y -p affine-mcp-server affine-mcp -- --version
 
 The package installs a CLI named `affine-mcp` that runs the MCP server over stdio.
 
-> Available on npm: install in seconds with `npm i -g affine-mcp-server` and use `affine-mcp` anywhere. No manual build or path setup required.
+Note: From v1.2.2+ the CLI wrapper (`bin/affine-mcp`) ensures Node runs the ESM entrypoint, preventing shell from misinterpreting JS.
 
 ## Configuration
 
-Set environment variables (recommended) or create a `.env` file:
-
-```env
-# AFFiNE server URL (required)
-AFFINE_BASE_URL=https://your-affine-instance.com
-
-# Authentication (choose one method):
-# 1) Bearer Token (highest priority)
-AFFINE_API_TOKEN=your_personal_access_token
-# 2) Session Cookie
-AFFINE_COOKIE=affine_session=xxx; affine_csrf=yyy
-# 3) Email/Password (fallback)
-AFFINE_EMAIL=your@email.com
-AFFINE_PASSWORD=your_password
-
-# Optional settings
-AFFINE_GRAPHQL_PATH=/graphql           # Default: /graphql
-AFFINE_WORKSPACE_ID=workspace-uuid     # Default workspace for operations
+Configure via environment variables (shell or app config). `.env` files are no longer recommended.
 
-# Startup auth behavior (optional)
-# AFFINE_LOGIN_AT_START=async           # Default: async (don't block MCP handshake)
-# AFFINE_LOGIN_AT_START=sync            # Block at startup to sign in with email/password
-```
+- Required: `AFFINE_BASE_URL`
+- Auth (choose one): `AFFINE_API_TOKEN` | `AFFINE_COOKIE` | `AFFINE_EMAIL` + `AFFINE_PASSWORD`
+- Optional: `AFFINE_GRAPHQL_PATH` (default `/graphql`), `AFFINE_WORKSPACE_ID`, `AFFINE_LOGIN_AT_START` (`async` default, `sync` to block)
 
 Authentication priority:
 1) `AFFINE_API_TOKEN` → 2) `AFFINE_COOKIE` → 3) `AFFINE_EMAIL` + `AFFINE_PASSWORD`
@@ -136,33 +124,29 @@ 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
 - `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
@@ -178,13 +162,24 @@ 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
-- If using Email/Password and your MCP client shows a startup timeout, ensure `AFFINE_LOGIN_AT_START=async` (default) so login happens after the stdio handshake.
+- 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
@@ -201,6 +196,17 @@ Connection
 
 ## Version History
 
+### 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
+- MCP startup behavior unchanged from 1.2.1 (async login by default)
+
 ### 1.2.1 (2025‑09‑17)
 - Default to asynchronous email/password login after MCP stdio handshake
 - New `AFFINE_LOGIN_AT_START` env (`async` default, `sync` to block at startup)
@@ -208,7 +214,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
 
@@ -225,11 +231,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/bin/affine-mcp

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// Lightweight CLI wrapper to ensure Node runs the ESM entry
+// Resolves to the compiled ESM entrypoint in dist
+import '../dist/index.js';
+

package/dist/config.js

@@ -1,5 +1,3 @@
-import dotenv from "dotenv";
-dotenv.config();
 const defaultEndpoints = {
     listWorkspaces: { method: "GET", path: "/api/workspaces" },
     listDocs: { method: "GET", path: "/api/workspaces/:workspaceId/docs" },

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.1" });
+    const server = new McpServer({ name: "affine-mcp", version: "1.2.2" });
     // 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.",