affine-mcp-server 2.3.0 → 2.4.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.3.0-blue)](https://github.com/dawncr0w/affine-mcp-server/releases)
+[![Version](https://img.shields.io/badge/version-2.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)
@@ -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 94 canonical MCP tools backed by AFFiNE GraphQL and WebSocket APIs
+- Exposes 95 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.3.0: Added document and folder sidebar icon tools, plus richer hierarchy detection for inline LinkedPage references and synced-doc embeds.
+> New in v2.4.0: Added `delete_tag` for workspace tag cleanup and surfaced `inTrash` across document listing and hierarchy tools.
 
 ## Choose Your Path
 | Goal | Start here |

package/dist/toolSurface.js

@@ -33,6 +33,7 @@ const ALL_TOOLS = [
     "delete_folder",
     "delete_organize_link",
     "delete_surface_element",
+    "delete_tag",
     "delete_workspace",
     "export_doc_markdown",
     "export_with_fidelity_report",
@@ -129,6 +130,7 @@ const TOOL_GROUPS = {
     delete_folder: ["organize", "organize.folders", "organize.write", "destructive", "experimental", "write"],
     delete_organize_link: ["organize", "organize.folders", "organize.write", "destructive", "experimental", "write"],
     delete_surface_element: ["docs", "docs.edgeless", "docs.surface", "docs.write", "destructive", "write"],
+    delete_tag: ["docs", "docs.tags", "docs.write", "destructive", "write"],
     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"],

package/dist/tools/docs.js

@@ -463,6 +463,31 @@ export function registerDocTools(server, gql, defaults) {
         optionsArray.push([optionMap]);
         return { option, created: true };
     }
+    /**
+     * Resolve the single tag option targeted for deletion. Matches a tag id
+     * first (ids are unique), then falls back to a case-insensitive name match.
+     * Throws when no tag matches, or when a name is shared by several tags so the
+     * caller can re-run with a specific id rather than deleting the wrong one.
+     */
+    function findTagOptionForDeletion(meta, tag) {
+        const normalized = normalizeTag(tag);
+        const { options, byId } = getWorkspaceTagOptionMaps(meta);
+        const byIdMatch = byId.get(normalized);
+        if (byIdMatch) {
+            return { option: byIdMatch, matchedBy: "id" };
+        }
+        const lower = normalized.toLocaleLowerCase();
+        const valueMatches = options.filter((option) => option.value.toLocaleLowerCase() === lower);
+        if (valueMatches.length === 0) {
+            throw new Error(`Tag "${normalized}" was not found in workspace tag options.`);
+        }
+        if (valueMatches.length > 1) {
+            const candidates = valueMatches.map((option) => `${option.id} ("${option.value}")`).join(", ");
+            throw new Error(`Tag name "${normalized}" is ambiguous; ${valueMatches.length} tags share this name. ` +
+                `Re-run delete_tag with a specific tag id: ${candidates}`);
+        }
+        return { option: valueMatches[0], matchedBy: "value" };
+    }
     function collectMatchingTagIndexes(tags, requestedTag, option, ignoreCase) {
         const normalizedRequested = ignoreCase ? requestedTag.toLocaleLowerCase() : requestedTag;
         const normalizedOptionId = option
@@ -551,12 +576,19 @@ export function registerDocTools(server, gql, defaults) {
             const title = value.get("title");
             const createDate = value.get("createDate");
             const updatedDate = value.get("updatedDate");
+            const inTrashRaw = value.get("inTrash");
+            const trashRaw = value.get("trash");
+            const trashDate = value.get("trashDate");
+            const inTrash = typeof inTrashRaw === "boolean" ? inTrashRaw
+                : typeof trashRaw === "boolean" ? trashRaw
+                    : (typeof trashDate === "number" && trashDate > 0);
             entries.push({
                 index,
                 id,
                 title: typeof title === "string" ? title : null,
                 createDate: typeof createDate === "number" ? createDate : null,
                 updatedDate: typeof updatedDate === "number" ? updatedDate : null,
+                inTrash,
                 entry: value,
                 tagsArray: getTagArray(value),
             });
@@ -3177,6 +3209,7 @@ export function registerDocTools(server, gql, defaults) {
         const docs = data.workspace.docs;
         const tagsByDocId = new Map();
         const titlesByDocId = new Map();
+        const inTrashByDocId = new Map();
         let workspacePageCount = null;
         let workspacePageIds = null;
         const deletedDocIds = new Set();
@@ -3201,6 +3234,7 @@ export function registerDocTools(server, gql, defaults) {
                         }
                         const tagEntries = getStringArray(page.tagsArray);
                         tagsByDocId.set(page.id, resolveTagLabels(tagEntries, byId));
+                        inTrashByDocId.set(page.id, page.inTrash);
                     }
                 }
                 const graphEdges = Array.isArray(docs?.edges) ? docs.edges : [];
@@ -3239,6 +3273,7 @@ export function registerDocTools(server, gql, defaults) {
                         ...node,
                         title: titlesByDocId.get(node.id) || node.title,
                         tags: tagsByDocId.get(node.id) || [],
+                        inTrash: inTrashByDocId.get(node.id) ?? false,
                     },
                 };
             })
@@ -3272,7 +3307,7 @@ export function registerDocTools(server, gql, defaults) {
     };
     server.registerTool("list_docs", {
         title: "List Documents",
-        description: "List documents in a workspace (GraphQL).",
+        description: "List documents in a workspace (GraphQL). Each doc includes an inTrash flag.",
         inputSchema: {
             workspaceId: z.string().describe("Workspace ID (optional if default set).").optional(),
             first: z.number().optional(),
@@ -3401,6 +3436,7 @@ export function registerDocTools(server, gql, defaults) {
                     updatedAt: updatedTimestamp > 0 ? new Date(updatedTimestamp).toISOString() : null,
                     updatedTimestamp,
                     url: `${baseUrl}/workspace/${workspaceId}/${page.id}`,
+                    inTrash: page.inTrash,
                     rank,
                 };
             })
@@ -3429,6 +3465,7 @@ export function registerDocTools(server, gql, defaults) {
                 tags: entry.tags,
                 updatedAt: entry.updatedAt,
                 url: entry.url,
+                inTrash: entry.inTrash,
             }));
             return text({
                 query: parsed.query,
@@ -3446,7 +3483,7 @@ export function registerDocTools(server, gql, defaults) {
     };
     server.registerTool("search_docs", {
         title: "Search Documents by Title",
-        description: "Fast search for documents by title using workspace metadata. Much faster than exporting each doc. Returns docId, title, and direct URL for each match.",
+        description: "Fast search for documents by title using workspace metadata. Much faster than exporting each doc. Returns docId, title, direct URL, and inTrash for each match.",
         inputSchema: {
             workspaceId: z.string().optional().describe("Workspace ID (optional if default set)."),
             query: z.string().describe("Search query — matched case-insensitively against doc titles."),
@@ -3510,6 +3547,7 @@ export function registerDocTools(server, gql, defaults) {
                     title: pageTitle,
                     createdAt: page.createDate ? new Date(page.createDate).toISOString() : null,
                     updatedAt: updatedTimestamp ? new Date(updatedTimestamp).toISOString() : null,
+                    inTrash: page.inTrash,
                 });
             }
             return text({
@@ -3531,7 +3569,7 @@ export function registerDocTools(server, gql, defaults) {
             "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 }.",
+            "Returns: { query, caseInsensitive, matches: [{ id, title, createdAt, updatedAt, inTrash }], 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."),
@@ -3578,6 +3616,7 @@ export function registerDocTools(server, gql, defaults) {
                     updatedDate: page.updatedDate,
                     tags,
                     rawTags,
+                    inTrash: page.inTrash,
                 };
             })
                 .filter((page) => hasTag(page.tags, tag, ignoreCase) || hasTag(page.rawTags, tag, ignoreCase))
@@ -3596,7 +3635,7 @@ export function registerDocTools(server, gql, defaults) {
     };
     server.registerTool("list_docs_by_tag", {
         title: "List Documents By Tag",
-        description: "List documents that contain the requested tag.",
+        description: "List documents that contain the requested tag. Each doc includes an inTrash flag.",
         inputSchema: {
             workspaceId: WorkspaceId.optional(),
             tag: z.string().min(1).describe("Tag name"),
@@ -3790,6 +3829,121 @@ export function registerDocTools(server, gql, defaults) {
             tag: z.string().min(1).describe("Tag name"),
         },
     }, removeTagFromDocHandler);
+    /**
+     * Delete a workspace-level tag and detach it from every document that
+     * references it, mirroring AFFiNE's TagStore.removeTagOption. Resolves the
+     * tag by id or name (ambiguous names are rejected), removes the option from
+     * meta.properties.tags.options, strips the tag id from each page's tag array,
+     * then syncs each affected document's own metadata. All workspace-root edits
+     * are applied to an in-memory Y.Doc and pushed as a single delta, so a failed
+     * push leaves the server unchanged and the operation safely retriable.
+     */
+    const deleteTagHandler = 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 tag = normalizeTag(parsed.tag);
+        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
+        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
+        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
+        try {
+            await joinWorkspace(socket, workspaceId);
+            const wsSnapshot = await loadDoc(socket, workspaceId, workspaceId);
+            if (!wsSnapshot.missing) {
+                throw new Error(`Workspace root document not found for workspace ${workspaceId}`);
+            }
+            const wsDoc = new Y.Doc();
+            Y.applyUpdate(wsDoc, Buffer.from(wsSnapshot.missing, "base64"));
+            const wsPrevSV = Y.encodeStateVector(wsDoc);
+            const wsMeta = wsDoc.getMap("meta");
+            const { option } = findTagOptionForDeletion(wsMeta, tag);
+            // Step 1: drop the tag option itself from the workspace tag registry.
+            const optionsArray = getWorkspaceTagOptionsArray(wsMeta);
+            let optionRemoved = false;
+            if (optionsArray) {
+                const optionIndexes = [];
+                optionsArray.forEach((raw, index) => {
+                    const parsedOption = parseWorkspaceTagOption(raw);
+                    if (parsedOption && parsedOption.id === option.id) {
+                        optionIndexes.push(index);
+                    }
+                });
+                optionRemoved = deleteArrayIndexes(optionsArray, optionIndexes);
+            }
+            // Step 2: strip the tag id from every page entry that still references it.
+            // Match by id only (case-sensitive), mirroring AFFiNE's removeTagOption
+            // (`t !== id`): doc tags are stored as canonical ids, and matching by
+            // value could clobber a same-name sibling tag's references.
+            const affectedDocIds = [];
+            for (const page of getWorkspacePageEntries(wsMeta)) {
+                const pageTags = page.tagsArray;
+                if (!pageTags) {
+                    continue;
+                }
+                const indexes = collectMatchingTagIndexes(pageTags, option.id, null, false);
+                if (deleteArrayIndexes(pageTags, indexes)) {
+                    affectedDocIds.push(page.id);
+                }
+            }
+            if (optionRemoved || affectedDocIds.length > 0) {
+                const wsDelta = Y.encodeStateAsUpdate(wsDoc, wsPrevSV);
+                await pushDocUpdate(socket, workspaceId, workspaceId, Buffer.from(wsDelta).toString("base64"));
+            }
+            // Step 3: mirror the cleanup in each affected document's own metadata.
+            let docMetaSynced = 0;
+            const warnings = [];
+            // The workspace registry is the source of truth and has already been
+            // updated; per-document metadata is a secondary sync. Treat each doc as
+            // best-effort so one failing push degrades to a warning instead of
+            // throwing and leaving a non-retriable partial state.
+            for (const docId of affectedDocIds) {
+                try {
+                    const docSnapshot = await loadDoc(socket, workspaceId, docId);
+                    if (!docSnapshot.missing) {
+                        warnings.push(`Document ${docId} snapshot not found; workspace tag map was updated only.`);
+                        continue;
+                    }
+                    const doc = new Y.Doc();
+                    Y.applyUpdate(doc, Buffer.from(docSnapshot.missing, "base64"));
+                    const docPrevSV = Y.encodeStateVector(doc);
+                    const docTags = getTagArray(doc.getMap("meta"));
+                    if (docTags) {
+                        const docIndexes = collectMatchingTagIndexes(docTags, option.id, null, false);
+                        if (deleteArrayIndexes(docTags, docIndexes)) {
+                            const docDelta = Y.encodeStateAsUpdate(doc, docPrevSV);
+                            await pushDocUpdate(socket, workspaceId, docId, Buffer.from(docDelta).toString("base64"));
+                        }
+                    }
+                    docMetaSynced += 1;
+                }
+                catch (err) {
+                    warnings.push(`Document ${docId} metadata sync failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            return text({
+                workspaceId,
+                tag,
+                tagId: option.id,
+                value: option.value,
+                deleted: optionRemoved,
+                affectedDocs: affectedDocIds.length,
+                docMetaSynced,
+                warnings,
+            });
+        }
+        finally {
+            socket.disconnect();
+        }
+    };
+    server.registerTool("delete_tag", {
+        title: "Delete Tag",
+        description: "Delete a workspace-level tag and remove it from every document that references it. Accepts a tag id or name; an ambiguous name is rejected with the candidate ids.",
+        inputSchema: {
+            workspaceId: WorkspaceId.optional(),
+            tag: z.string().min(1).describe("Tag id or name to delete"),
+        },
+    }, deleteTagHandler);
     const getDocHandler = async (parsed) => {
         const workspaceId = parsed.workspaceId || defaults.workspaceId;
         if (!workspaceId) {
@@ -4820,6 +4974,7 @@ export function registerDocTools(server, gql, defaults) {
             Y.applyUpdate(wsDoc, Buffer.from(wsSnap.missing, "base64"));
             const pages = getWorkspacePageEntries(wsDoc.getMap("meta"));
             const titleById = new Map(pages.map(p => [p.id, p.title ?? "Untitled"]));
+            const trashById = new Map(pages.map(p => [p.id, p.inTrash]));
             const childrenOf = new Map();
             const allChildren = new Set();
             for (const page of pages) {
@@ -4844,6 +4999,7 @@ export function registerDocTools(server, gql, defaults) {
             const buildNode = (id, depth) => ({
                 docId: id, title: titleById.get(id) ?? "Untitled",
                 url: `${baseUrl}/workspace/${workspaceId}/${id}`,
+                inTrash: trashById.get(id) ?? false,
                 children: depth < maxDepth ? (childrenOf.get(id) ?? []).map(cid => buildNode(cid, depth + 1)) : [],
             });
             return text({ workspaceId, totalDocs: pages.length, rootCount: roots.length, tree: roots.map(id => buildNode(id, 0)) });
@@ -4854,7 +5010,7 @@ export function registerDocTools(server, gql, defaults) {
     };
     server.registerTool("list_workspace_tree", {
         title: "List Workspace Tree",
-        description: "Returns the full document hierarchy as a tree (roots → children → grandchildren). Use depth to limit nesting (default: 3). Note: loads all docs — may be slow on large workspaces.",
+        description: "Returns the full document hierarchy as a tree (roots → children → grandchildren). Use depth to limit nesting (default: 3). Note: loads all docs — may be slow on large workspaces. Each node includes an inTrash flag.",
         inputSchema: {
             workspaceId: z.string().optional(),
             depth: z.number().optional().describe("Max nesting depth to return (default: 3)."),
@@ -4896,6 +5052,7 @@ export function registerDocTools(server, gql, defaults) {
                 docId: p.id,
                 title: titleById.get(p.id) ?? "Untitled",
                 url: `${baseUrl}/workspace/${workspaceId}/${p.id}`,
+                inTrash: p.inTrash,
             }));
             return text({ count: orphans.length, orphans });
         }
@@ -4905,7 +5062,7 @@ export function registerDocTools(server, gql, defaults) {
     };
     server.registerTool("get_orphan_docs", {
         title: "Get Orphan Documents",
-        description: "Find all documents that have no parent (not linked from any other doc via embed_linked_doc / embed_synced_doc blocks or inline LinkedPage references). Useful for workspace hygiene. Note: scans all docs — O(n).",
+        description: "Find all documents that have no parent (not linked from any other doc via embed_linked_doc / embed_synced_doc blocks or inline LinkedPage references). Useful for workspace hygiene. Note: scans all docs — O(n). Each doc includes an inTrash flag.",
         inputSchema: { workspaceId: z.string().optional() },
     }, getOrphanDocsHandler);
     const listChildrenHandler = async (parsed) => {
@@ -4918,6 +5075,7 @@ export function registerDocTools(server, gql, defaults) {
         try {
             await joinWorkspace(socket, workspaceId);
             const titleById = new Map();
+            const trashById = new Map();
             const workspacePageIds = new Set();
             let hasWorkspaceMetadata = false;
             const wsSnap = await loadDoc(socket, workspaceId, workspaceId);
@@ -4927,6 +5085,7 @@ export function registerDocTools(server, gql, defaults) {
                 Y.applyUpdate(wsDoc, Buffer.from(wsSnap.missing, "base64"));
                 for (const page of getWorkspacePageEntries(wsDoc.getMap("meta"))) {
                     workspacePageIds.add(page.id);
+                    trashById.set(page.id, page.inTrash);
                     if (page.title)
                         titleById.set(page.id, page.title);
                 }
@@ -4946,7 +5105,8 @@ export function registerDocTools(server, gql, defaults) {
                     continue;
                 seen.add(pageId);
                 children.push({ docId: pageId, title: titleById.get(pageId) ?? null,
-                    url: `${(process.env.AFFINE_BASE_URL || endpoint.replace(/\/graphql\/?$/, '')).replace(/\/$/, '')}/workspace/${workspaceId}/${pageId}` });
+                    url: `${(process.env.AFFINE_BASE_URL || endpoint.replace(/\/graphql\/?$/, '')).replace(/\/$/, '')}/workspace/${workspaceId}/${pageId}`,
+                    inTrash: trashById.get(pageId) ?? false });
             }
             return text({ docId: parsed.docId, count: children.length, children });
         }
@@ -4956,7 +5116,7 @@ export function registerDocTools(server, gql, defaults) {
     };
     server.registerTool("list_children", {
         title: "List Document Children",
-        description: "List the direct children of a document in the sidebar (embed_linked_doc / embed_synced_doc blocks and inline LinkedPage references). Returns docId, title, and URL for each child.",
+        description: "List the direct children of a document in the sidebar (embed_linked_doc / embed_synced_doc blocks and inline LinkedPage references). Returns docId, title, URL, and inTrash for each child.",
         inputSchema: {
             workspaceId: z.string().optional(),
             docId: z.string().describe("The parent doc whose children to list."),

package/docs/tool-reference.md

@@ -100,6 +100,7 @@ Use this document as a grouped catalog. For exact schemas, your MCP client shoul
 | `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 | |
+| `delete_tag` | Delete a workspace tag and detach it from every document | Destructive; accepts a tag id or name, rejects an ambiguous name |
 
 ### Custom properties
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "affine-mcp-server",
-  "version": "2.3.0",
+  "version": "2.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.",
@@ -68,6 +68,7 @@
     "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:tag-deletion": "node tests/test-tag-deletion.mjs",
     "test:markdown-roundtrip": "node tests/test-markdown-roundtrip.mjs",
     "test:markdown-rich-text-import": "node tests/test-markdown-rich-text-import.mjs",
     "test:playwright": "npx playwright test --config tests/playwright/playwright.config.ts",
@@ -99,7 +100,7 @@
     "markdown-it": "^14.1.0",
     "node-fetch": "^3.3.2",
     "socket.io-client": "^4.8.1",
-    "undici": "^8.0.2",
+    "undici": "^6.27.0",
     "yjs": "^13.6.27",
     "zod": "^3.23.8"
   },

package/tool-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.3.0",
+  "version": "2.4.0",
   "tools": [
     "add_database_column",
     "add_database_row",
@@ -35,6 +35,7 @@
     "delete_folder",
     "delete_organize_link",
     "delete_surface_element",
+    "delete_tag",
     "delete_workspace",
     "export_doc_markdown",
     "export_with_fidelity_report",