affine-mcp-server 2.0.0 → 2.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 A Model Context Protocol (MCP) server for AFFiNE. It exposes AFFiNE workspaces and documents to AI assistants over stdio (default) or HTTP (`/mcp`) and supports both AFFiNE Cloud and self-hosted deployments.
 
-[![Version](https://img.shields.io/badge/version-2.0.0-blue)](https://github.com/dawncr0w/affine-mcp-server/releases)
+[![Version](https://img.shields.io/badge/version-2.1.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)
@@ -38,7 +38,7 @@ Highlights:
 - Supports AFFiNE Cloud and self-hosted AFFiNE instances
 - Supports stdio and HTTP transports
 - Supports token, cookie, and email/password authentication
-- Exposes 84 canonical MCP tools backed by AFFiNE GraphQL and WebSocket APIs
+- Exposes 85 canonical MCP tools backed by AFFiNE GraphQL and WebSocket APIs
 - Includes semantic page composition, native template instantiation, database intent composition, capability and fidelity reporting, and workspace blueprint helpers
 - Includes Docker images, health probes, and end-to-end test coverage
 
@@ -48,7 +48,7 @@ Scope boundaries:
 - Browser-local workspaces stored only in local storage are not available through AFFiNE server APIs
 - AFFiNE Cloud requires API-token-based access for MCP usage; programmatic email/password sign-in is blocked by Cloudflare
 
-> New in v2.0.0: Added native edgeless canvas tools and shipped a slimmer 84-tool public surface with least-privilege profiles for read-only, core, and authoring deployments.
+> New in v2.1.0: Added exact-title document lookup, folder placement for `create_doc`, and trusted npm publishing.
 
 ## Choose Your Path
 | Goal | Start here |

package/dist/toolSurface.js

@@ -33,6 +33,7 @@ const ALL_TOOLS = [
     "delete_workspace",
     "export_doc_markdown",
     "export_with_fidelity_report",
+    "find_doc_by_title",
     "generate_access_token",
     "get_capabilities",
     "get_collection",
@@ -119,6 +120,7 @@ const TOOL_GROUPS = {
     delete_workspace: ["workspaces", "workspaces.write", "admin", "destructive", "write"],
     export_doc_markdown: ["docs", "docs.export", "docs.markdown", "docs.read", "read"],
     export_with_fidelity_report: ["docs", "docs.export", "docs.markdown", "docs.read", "read"],
+    find_doc_by_title: ["docs", "docs.read", "read"],
     generate_access_token: ["access_tokens", "access_tokens.write", "admin", "write"],
     get_capabilities: ["docs", "docs.read", "read"],
     get_collection: ["organize", "organize.collections", "organize.read", "read"],
@@ -175,6 +177,7 @@ const READ_ONLY_TOOLS = new Set([
     "current_user",
     "export_doc_markdown",
     "export_with_fidelity_report",
+    "find_doc_by_title",
     "get_capabilities",
     "get_collection",
     "get_doc",
@@ -211,6 +214,7 @@ const CORE_TOOLS = new Set([
     "create_doc_from_markdown",
     "current_user",
     "export_doc_markdown",
+    "find_doc_by_title",
     "get_capabilities",
     "get_doc",
     "get_workspace",

package/dist/tools/docs.js

@@ -5,6 +5,7 @@ import { wsUrlFromGraphQLEndpoint, connectWorkspaceSocket, joinWorkspace, loadDo
 import * as Y from "yjs";
 import { parseMarkdownToOperations } from "../markdown/parse.js";
 import { renderBlocksToMarkdown } from "../markdown/render.js";
+import { addOrganizeLinkToFolder } from "./organize.js";
 import { DEFAULT_NOTE_XYWH, DEFAULT_STACK_GAP_HORIZONTAL, DEFAULT_STACK_GAP_VERTICAL, SIDE_TO_NORMALIZED_POSITION, encloseBounds, estimateConnectorLabelXYWH, estimateNoteHeightForMarkdown, formatXywhString, parseXywhString, pickConnectorSides, pickFurthestInDirection, sortByFractionalIndex, stackRelativeTo, } from "../edgeless/layout.js";
 const WorkspaceId = z.string().min(1, "workspaceId required");
 const DocId = z.string().min(1, "docId required");
@@ -3387,6 +3388,88 @@ export function registerDocTools(server, gql, defaults) {
             sortDirection: z.enum(["asc", "desc"]).optional().describe("Sort direction for updatedAt sorting (default: desc)."),
         },
     }, searchDocsHandler);
+    const findDocByTitleHandler = 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 title = parsed.title;
+        if (!title || title.length === 0) {
+            throw new Error("title is required and must be non-empty.");
+        }
+        const limit = parsed.limit ?? 50;
+        const caseInsensitive = parsed.caseInsensitive ?? false;
+        const target = caseInsensitive ? title.toLocaleLowerCase() : title;
+        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
+        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
+        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
+        try {
+            await joinWorkspace(socket, workspaceId);
+            const snapshot = await loadDoc(socket, workspaceId, workspaceId);
+            if (!snapshot.missing) {
+                return text({
+                    query: title,
+                    caseInsensitive,
+                    matches: [],
+                    workspaceDocCount: 0,
+                    truncated: false,
+                });
+            }
+            const wsDoc = new Y.Doc();
+            Y.applyUpdate(wsDoc, Buffer.from(snapshot.missing, "base64"));
+            const meta = wsDoc.getMap("meta");
+            const pages = getWorkspacePageEntries(meta);
+            const matches = [];
+            let truncated = false;
+            for (const page of pages) {
+                const pageTitle = page.title ?? "";
+                const candidate = caseInsensitive ? pageTitle.toLocaleLowerCase() : pageTitle;
+                if (candidate !== target)
+                    continue;
+                if (matches.length >= limit) {
+                    // We hit `limit` on a previous iteration and now found another match —
+                    // there are genuinely more matches than the cap.
+                    truncated = true;
+                    break;
+                }
+                // A doc that has never been edited after creation has no
+                // `updatedDate` in workspace meta — fall back to `createDate` so
+                // `updatedAt` is always populated, consistent with `search_docs`.
+                const updatedTimestamp = page.updatedDate ?? page.createDate;
+                matches.push({
+                    id: page.id,
+                    title: pageTitle,
+                    createdAt: page.createDate ? new Date(page.createDate).toISOString() : null,
+                    updatedAt: updatedTimestamp ? new Date(updatedTimestamp).toISOString() : null,
+                });
+            }
+            return text({
+                query: title,
+                caseInsensitive,
+                matches,
+                workspaceDocCount: pages.length,
+                truncated,
+            });
+        }
+        finally {
+            socket.disconnect();
+        }
+    };
+    server.registerTool("find_doc_by_title", {
+        title: "Find Doc by Title",
+        description: "Resolve docs by exact title. Returns ALL matches up to `limit` (callers handle ambiguity). " +
+            "Case-sensitive by default; pass `caseInsensitive: true` to fold case. " +
+            "Reads workspace metadata — fast, no per-doc fetch. " +
+            "Unlike `search_docs` (which is always case-insensitive and capped at limit 20), this tool defaults to case-sensitive matching and returns up to `limit` matches (default 50, max 200). " +
+            "Prefer this over `search_docs` when you know the exact title and want every match. " +
+            "Returns: { query, caseInsensitive, matches: [{ id, title, createdAt, updatedAt }], workspaceDocCount, truncated }.",
+        inputSchema: {
+            workspaceId: z.string().optional().describe("Workspace ID (optional if AFFINE_WORKSPACE_ID is set)."),
+            title: z.string().min(1).describe("The exact title to match."),
+            caseInsensitive: z.boolean().optional().describe("If true, fold case for comparison (default: false)."),
+            limit: z.number().int().positive().max(200).optional().describe("Max matches to return (default: 50)."),
+        },
+    }, findDocByTitleHandler);
     server.registerTool("list_tags", {
         title: "List Tags",
         description: "List all tags in a workspace and the number of docs attached to each tag.",
@@ -4033,23 +4116,51 @@ export function registerDocTools(server, gql, defaults) {
             parentDocId: parsed.parentDocId,
             context: "create_doc",
         });
+        const warnings = mergeWarnings(created.warnings ?? [], placement.warnings);
+        let linkedFolderId = null;
+        let folderNodeId = null;
+        if (parsed.folderId) {
+            const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
+            const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
+            const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
+            try {
+                await joinWorkspace(socket, created.workspaceId);
+                const link = await addOrganizeLinkToFolder(socket, created.workspaceId, {
+                    folderId: parsed.folderId,
+                    type: "doc",
+                    targetId: created.docId,
+                });
+                linkedFolderId = link.parentId;
+                folderNodeId = link.id;
+            }
+            catch (err) {
+                warnings.push(`Doc created but could not be placed in folder "${parsed.folderId}": ${err?.message ?? "unknown error"}`);
+            }
+            finally {
+                socket.disconnect();
+            }
+        }
         return receipt("doc.create", {
             workspaceId: created.workspaceId,
             docId: created.docId,
             title: created.title,
             parentDocId: placement.parentDocId,
             linkedToParent: placement.linkedToParent,
-            warnings: mergeWarnings(created.warnings ?? [], placement.warnings),
+            folderId: linkedFolderId,
+            folderLinked: folderNodeId !== null,
+            folderNodeId,
+            warnings,
         });
     };
     server.registerTool('create_doc', {
         title: 'Create Document',
-        description: 'Create a new AFFiNE document with optional content. If parentDocId is provided, the new doc is linked into the sidebar tree immediately.',
+        description: 'Create a new AFFiNE document with optional content. If parentDocId is provided, the new doc is linked into the sidebar tree immediately. If folderId is provided, the doc is placed inside that folder in the sidebar.',
         inputSchema: {
             workspaceId: z.string().optional(),
             title: z.string().optional(),
             content: z.string().optional(),
             parentDocId: z.string().optional().describe("Optional parent doc to link the new doc under in the sidebar."),
+            folderId: z.string().optional().describe("Optional folder ID to place the doc in. Use list_organize_nodes to find folder IDs."),
         },
     }, createDocHandler);
     const semanticSectionSchema = z.object({

package/dist/tools/organize.js

@@ -453,6 +453,43 @@ function nextOrganizeIndex(nodes, parentId) {
     const last = siblings.at(-1);
     return generateFractionalIndexingKeyBetween(last?.index ?? null, null);
 }
+async function loadFoldersDoc(socket, workspaceId) {
+    const docId = specialWorkspaceDbDocId(workspaceId, "folders");
+    const snapshot = await loadDoc(socket, workspaceId, docId);
+    const doc = new Y.Doc();
+    if (snapshot.missing) {
+        Y.applyUpdate(doc, Buffer.from(snapshot.missing, "base64"));
+    }
+    return { docId, doc, snapshot };
+}
+async function saveFoldersDoc(socket, workspaceId, docId, doc) {
+    const update = Y.encodeStateAsUpdate(doc);
+    await pushDocUpdate(socket, workspaceId, docId, Buffer.from(update).toString("base64"));
+}
+export async function addOrganizeLinkToFolder(socket, workspaceId, { folderId, type, targetId, index, }) {
+    const { docId, doc } = await loadFoldersDoc(socket, workspaceId);
+    const nodes = readOrganizeNodes(doc);
+    const nodeMap = organizeNodeMap(nodes);
+    ensureNodeIsFolder(nodeMap, folderId);
+    const linkId = generateId();
+    const nextIndex = index ?? nextOrganizeIndex(nodes, folderId);
+    const record = ensureRecord(doc, linkId);
+    record.set("id", linkId);
+    record.set("type", type);
+    record.set("data", targetId);
+    record.set("parentId", folderId);
+    record.set("index", nextIndex);
+    record.delete("$$DELETED");
+    await saveFoldersDoc(socket, workspaceId, docId, doc);
+    return {
+        id: linkId,
+        parentId: folderId,
+        type,
+        data: targetId,
+        index: nextIndex,
+        storageDocId: docId,
+    };
+}
 export function registerOrganizeTools(server, gql, defaults) {
     async function getSocketContext() {
         const endpoint = gql.endpoint;
@@ -474,19 +511,6 @@ export function registerOrganizeTools(server, gql, defaults) {
         const update = Y.encodeStateAsUpdate(doc);
         await pushDocUpdate(socket, workspaceId, workspaceId, Buffer.from(update).toString("base64"));
     }
-    async function loadFoldersDoc(socket, workspaceId) {
-        const docId = specialWorkspaceDbDocId(workspaceId, "folders");
-        const snapshot = await loadDoc(socket, workspaceId, docId);
-        const doc = new Y.Doc();
-        if (snapshot.missing) {
-            Y.applyUpdate(doc, Buffer.from(snapshot.missing, "base64"));
-        }
-        return { docId, doc, snapshot };
-    }
-    async function saveFoldersDoc(socket, workspaceId, docId, doc) {
-        const update = Y.encodeStateAsUpdate(doc);
-        await pushDocUpdate(socket, workspaceId, docId, Buffer.from(update).toString("base64"));
-    }
     function sleep(ms) {
         return new Promise(resolve => setTimeout(resolve, ms));
     }
@@ -1068,28 +1092,13 @@ export function registerOrganizeTools(server, gql, defaults) {
         const { socket } = await getSocketContext();
         try {
             await joinWorkspace(socket, resolvedWorkspaceId);
-            const { docId, doc } = await loadFoldersDoc(socket, resolvedWorkspaceId);
-            const nodes = readOrganizeNodes(doc);
-            const nodeMap = organizeNodeMap(nodes);
-            ensureNodeIsFolder(nodeMap, folderId);
-            const linkId = generateId();
-            const nextIndex = index ?? nextOrganizeIndex(nodes, folderId);
-            const record = ensureRecord(doc, linkId);
-            record.set("id", linkId);
-            record.set("type", type);
-            record.set("data", targetId);
-            record.set("parentId", folderId);
-            record.set("index", nextIndex);
-            record.delete("$$DELETED");
-            await saveFoldersDoc(socket, resolvedWorkspaceId, docId, doc);
-            return text({
-                id: linkId,
-                parentId: folderId,
+            const link = await addOrganizeLinkToFolder(socket, resolvedWorkspaceId, {
+                folderId,
                 type,
-                data: targetId,
-                index: nextIndex,
-                storageDocId: docId,
+                targetId,
+                index,
             });
+            return text(link);
         }
         finally {
             socket.disconnect();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "affine-mcp-server",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "private": false,
   "type": "module",
   "description": "Model Context Protocol server for AFFiNE - enables AI assistants to interact with AFFiNE workspaces, documents, and collaboration features.",
@@ -8,12 +8,12 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/dawncr0w/affine-mcp-server.git"
+    "url": "git+https://github.com/DAWNCR0W/affine-mcp-server.git"
   },
   "bugs": {
-    "url": "https://github.com/dawncr0w/affine-mcp-server/issues"
+    "url": "https://github.com/DAWNCR0W/affine-mcp-server/issues"
   },
-  "homepage": "https://github.com/dawncr0w/affine-mcp-server#readme",
+  "homepage": "https://github.com/DAWNCR0W/affine-mcp-server#readme",
   "keywords": [
     "mcp",
     "affine",
@@ -47,6 +47,7 @@
     "test:db-schema": "node tests/test-database-schema.mjs",
     "test:data-view": "node tests/test-data-view.mjs",
     "test:doc-discovery": "node tests/test-doc-discovery.mjs",
+    "test:find-doc-by-title": "node tests/test-find-doc-by-title.mjs",
     "test:create-placement": "node tests/test-create-placement.mjs",
     "test:surface-elements": "node tests/test-surface-elements.mjs",
     "test:surface-element-gating": "node scripts/verify-surface-element-gating.mjs",
@@ -60,6 +61,7 @@
     "test:http-bearer": "node tests/test-http-bearer.mjs",
     "test:oauth-http": "node tests/test-oauth-http.mjs",
     "test:organize": "node tests/test-organize-tools.mjs",
+    "test:create-doc-folder-placement": "node tests/test-create-doc-folder-placement.mjs",
     "test:supporting-tools": "node tests/test-supporting-tools.mjs",
     "test:tag-visibility": "node tests/test-tag-visibility.mjs",
     "test:markdown-roundtrip": "node tests/test-markdown-roundtrip.mjs",

package/tool-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.0.0",
+  "version": "2.1.0",
   "tools": [
     "add_database_column",
     "add_database_row",
@@ -35,6 +35,7 @@
     "delete_workspace",
     "export_doc_markdown",
     "export_with_fidelity_report",
+    "find_doc_by_title",
     "generate_access_token",
     "get_capabilities",
     "get_collection",