affine-mcp-server 2.2.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.2.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 90 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.2.0: Added document custom-property tools, `read_doc` LinkedPage reference IDs, and table ordering fixes.
+> 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/index.js

@@ -15,6 +15,7 @@ import { loginWithPassword } from "./auth.js";
 import { registerAuthTools } from "./tools/auth.js";
 import { registerOrganizeTools } from "./tools/organize.js";
 import { registerPropertyTools } from "./tools/properties.js";
+import { registerIconTools } from "./tools/icons.js";
 import { runCli } from "./cli.js";
 import { startHttpMcpServer } from "./sse.js";
 import { existsSync } from "fs";
@@ -167,6 +168,7 @@ async function buildServer() {
     registerHistoryTools(server, gql, { workspaceId: config.defaultWorkspaceId });
     registerOrganizeTools(server, gql, { workspaceId: config.defaultWorkspaceId });
     registerPropertyTools(server, gql, { workspaceId: config.defaultWorkspaceId });
+    registerIconTools(server, gql, { workspaceId: config.defaultWorkspaceId });
     registerUserTools(server, gql);
     registerUserCRUDTools(server, gql);
     if (config.authMode !== "oauth") {

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",
@@ -41,7 +42,9 @@ const ALL_TOOLS = [
     "get_capabilities",
     "get_collection",
     "get_doc",
+    "get_doc_icon",
     "get_edgeless_canvas",
+    "get_folder_icon",
     "get_orphan_docs",
     "get_workspace",
     "inspect_template_structure",
@@ -81,8 +84,10 @@ const ALL_TOOLS = [
     "update_collection_rules",
     "update_comment",
     "update_database_row",
+    "update_doc_icon",
     "update_doc_title",
     "update_edgeless_block",
+    "update_folder_icon",
     "update_frame_children",
     "update_profile",
     "update_settings",
@@ -125,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"],
@@ -133,7 +139,9 @@ const TOOL_GROUPS = {
     get_capabilities: ["docs", "docs.read", "read"],
     get_collection: ["organize", "organize.collections", "organize.read", "read"],
     get_doc: ["docs", "docs.read", "read"],
+    get_doc_icon: ["docs", "docs.read", "read"],
     get_edgeless_canvas: ["docs", "docs.edgeless", "docs.surface", "docs.read", "read"],
+    get_folder_icon: ["organize", "organize.folders", "organize.read", "experimental", "read"],
     get_orphan_docs: ["docs", "docs.tree", "docs.read", "read"],
     get_workspace: ["workspaces", "workspaces.read", "read"],
     inspect_template_structure: ["docs", "docs.template", "docs.read", "read"],
@@ -173,8 +181,10 @@ const TOOL_GROUPS = {
     update_collection_rules: ["organize", "organize.collections", "organize.write", "write"],
     update_comment: ["comments", "comments.write", "write"],
     update_database_row: ["docs", "docs.database", "docs.write", "write"],
+    update_doc_icon: ["docs", "docs.write", "write"],
     update_doc_title: ["docs", "docs.write", "write"],
     update_edgeless_block: ["docs", "docs.edgeless", "docs.write", "write"],
+    update_folder_icon: ["organize", "organize.folders", "organize.write", "experimental", "write"],
     update_frame_children: ["docs", "docs.edgeless", "docs.write", "write"],
     update_profile: ["users", "users.write", "admin", "write"],
     update_settings: ["users", "users.write", "admin", "write"],
@@ -191,7 +201,9 @@ const READ_ONLY_TOOLS = new Set([
     "get_capabilities",
     "get_collection",
     "get_doc",
+    "get_doc_icon",
     "get_edgeless_canvas",
+    "get_folder_icon",
     "get_orphan_docs",
     "get_workspace",
     "inspect_template_structure",
@@ -228,6 +240,7 @@ const CORE_TOOLS = new Set([
     "find_doc_by_title",
     "get_capabilities",
     "get_doc",
+    "get_doc_icon",
     "get_workspace",
     "list_children",
     "list_docs",
@@ -242,6 +255,7 @@ const CORE_TOOLS = new Set([
     "search_docs",
     "sign_in",
     "update_database_row",
+    "update_doc_icon",
     "update_doc_title",
 ]);
 const AUTHORING_EXCLUDED_GROUPS = new Set([

package/dist/tools/docs.js

@@ -7,6 +7,53 @@ 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";
+function collectLinkedChildIds(blocks) {
+    const databaseRowIds = new Set();
+    for (const [, raw] of blocks) {
+        if (!(raw instanceof Y.Map))
+            continue;
+        if (raw.get("sys:flavour") !== "affine:database")
+            continue;
+        const rows = raw.get("sys:children");
+        if (rows instanceof Y.Array) {
+            rows.forEach((entry) => {
+                if (typeof entry === "string")
+                    databaseRowIds.add(entry);
+                else if (Array.isArray(entry)) {
+                    for (const child of entry)
+                        if (typeof child === "string")
+                            databaseRowIds.add(child);
+                }
+            });
+        }
+    }
+    const ids = [];
+    for (const [blockId, raw] of blocks) {
+        if (!(raw instanceof Y.Map))
+            continue;
+        const flavour = raw.get("sys:flavour");
+        if (flavour === "affine:embed-linked-doc" || flavour === "affine:embed-synced-doc") {
+            const pid = raw.get("prop:pageId");
+            if (typeof pid === "string" && pid)
+                ids.push(pid);
+        }
+        if (databaseRowIds.has(String(blockId)))
+            continue;
+        const propText = raw.get("prop:text");
+        if (propText instanceof Y.Text) {
+            const delta = propText.toDelta();
+            if (Array.isArray(delta)) {
+                for (const d of delta) {
+                    const reference = d.attributes?.reference;
+                    if (reference?.type === "LinkedPage" && typeof reference.pageId === "string" && reference.pageId) {
+                        ids.push(reference.pageId);
+                    }
+                }
+            }
+        }
+    }
+    return ids;
+}
 const WorkspaceId = z.string().min(1, "workspaceId required");
 const DocId = z.string().min(1, "docId required");
 const MarkdownContent = z.string().min(1, "markdown required");
@@ -416,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
@@ -504,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),
             });
@@ -3130,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();
@@ -3154,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 : [];
@@ -3192,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,
                     },
                 };
             })
@@ -3225,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(),
@@ -3354,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,
                 };
             })
@@ -3382,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,
@@ -3399,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."),
@@ -3463,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({
@@ -3484,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."),
@@ -3531,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))
@@ -3549,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"),
@@ -3743,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) {
@@ -4773,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) {
@@ -4783,13 +4985,8 @@ export function registerDocTools(server, gql, defaults) {
                 Y.applyUpdate(doc, Buffer.from(snap.missing, "base64"));
                 const blocks = doc.getMap("blocks");
                 const kids = [];
-                for (const [, raw] of blocks) {
-                    if (!(raw instanceof Y.Map))
-                        continue;
-                    if (raw.get("sys:flavour") !== "affine:embed-linked-doc")
-                        continue;
-                    const pid = raw.get("prop:pageId");
-                    if (typeof pid === "string" && pid && titleById.has(pid)) {
+                for (const pid of collectLinkedChildIds(blocks)) {
+                    if (titleById.has(pid) && !kids.includes(pid)) {
                         kids.push(pid);
                         allChildren.add(pid);
                     }
@@ -4802,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)) });
@@ -4812,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)."),
@@ -4843,14 +5041,8 @@ export function registerDocTools(server, gql, defaults) {
                 const doc = new Y.Doc();
                 Y.applyUpdate(doc, Buffer.from(snap.missing, "base64"));
                 const blocks = doc.getMap("blocks");
-                for (const [, raw] of blocks) {
-                    if (!(raw instanceof Y.Map))
-                        continue;
-                    if (raw.get("sys:flavour") !== "affine:embed-linked-doc")
-                        continue;
-                    const pageId = raw.get("prop:pageId");
-                    if (typeof pageId === "string" && pageId)
-                        allChildren.add(pageId);
+                for (const pageId of collectLinkedChildIds(blocks)) {
+                    allChildren.add(pageId);
                 }
             }
             const baseUrl = (process.env.AFFINE_BASE_URL || endpoint.replace(/\/graphql\/?$/, "")).replace(/\/$/, "");
@@ -4860,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 });
         }
@@ -4869,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). 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) => {
@@ -4882,11 +5075,17 @@ 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);
             if (wsSnap.missing) {
+                hasWorkspaceMetadata = true;
                 const wsDoc = new Y.Doc();
                 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);
                 }
@@ -4898,16 +5097,16 @@ export function registerDocTools(server, gql, defaults) {
             Y.applyUpdate(doc, Buffer.from(snap.missing, "base64"));
             const blocks = doc.getMap("blocks");
             const children = [];
-            for (const [, raw] of blocks) {
-                if (!(raw instanceof Y.Map))
+            const seen = new Set();
+            for (const pageId of collectLinkedChildIds(blocks)) {
+                if (hasWorkspaceMetadata && !workspacePageIds.has(pageId))
                     continue;
-                if (raw.get("sys:flavour") !== "affine:embed-linked-doc")
+                if (seen.has(pageId))
                     continue;
-                const pageId = raw.get("prop:pageId");
-                if (typeof pageId === "string" && pageId) {
-                    children.push({ docId: pageId, title: titleById.get(pageId) ?? null,
-                        url: `${(process.env.AFFINE_BASE_URL || endpoint.replace(/\/graphql\/?$/, '')).replace(/\/$/, '')}/workspace/${workspaceId}/${pageId}` });
-                }
+                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}`,
+                    inTrash: trashById.get(pageId) ?? false });
             }
             return text({ docId: parsed.docId, count: children.length, children });
         }
@@ -4917,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 blocks). 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/dist/tools/icons.js

@@ -0,0 +1,125 @@
+import { z } from "zod";
+import { receipt } from "../util/mcp.js";
+import { connectWorkspaceSocket, joinWorkspace, wsUrlFromGraphQLEndpoint, } from "../ws.js";
+import { docIconKey, folderIconKey, getExplorerIcon, normalizeIconInput, setExplorerIcon, } from "../util/explorerIcon.js";
+/**
+ * Zod shape for the `icon` parameter shared by both setters. Accepts an emoji
+ * shorthand string, a full `{type:"emoji",unicode}` / `{type:"icon",name}`
+ * object, or `null` to clear the icon.
+ */
+const iconSchema = z
+    .union([
+    z.string(),
+    z.object({ type: z.literal("emoji"), unicode: z.string() }),
+    z.object({ type: z.literal("icon"), name: z.string() }),
+    z.null(),
+])
+    .describe('Emoji shorthand ("🧪"), a full object ({type:"emoji",unicode:"🧪"} or ' +
+    '{type:"icon",name:"check"}), or null to remove the icon.');
+/**
+ * Registers the explorer-icon tools: set/clear and read the Notion-style
+ * sidebar icon on a document or an organize folder. All four share the
+ * `explorerIcon` sub-doc helper so the storage model lives in one place.
+ */
+export function registerIconTools(server, gql, defaults) {
+    function resolveWorkspaceId(workspaceId) {
+        const resolved = workspaceId || defaults.workspaceId;
+        if (!resolved) {
+            throw new Error("workspaceId is required. Provide it as a parameter or set AFFINE_WORKSPACE_ID.");
+        }
+        return resolved;
+    }
+    async function withSocket(workspaceId, fn) {
+        const wsUrl = wsUrlFromGraphQLEndpoint(gql.endpoint);
+        const socket = await connectWorkspaceSocket(wsUrl, gql.cookie, gql.bearer);
+        try {
+            await joinWorkspace(socket, workspaceId);
+            return await fn(socket);
+        }
+        finally {
+            socket.disconnect();
+        }
+    }
+    // ─── update_doc_icon ────────────────────────────────────────────────────────
+    const updateDocIconHandler = async (parsed) => {
+        const workspaceId = resolveWorkspaceId(parsed.workspaceId);
+        const icon = normalizeIconInput(parsed.icon);
+        const result = await withSocket(workspaceId, (socket) => setExplorerIcon(socket, workspaceId, docIconKey(parsed.docId), icon));
+        return receipt("doc.update_icon", {
+            workspaceId,
+            docId: parsed.docId,
+            icon: result.icon,
+            cleared: result.icon === null,
+        });
+    };
+    server.registerTool("update_doc_icon", {
+        title: "Update Document Icon",
+        description: "Set or clear the sidebar icon (the Notion-style emoji slot) on a document. " +
+            "Pass an emoji string, a full icon object, or null to remove it.",
+        inputSchema: {
+            workspaceId: z.string().optional(),
+            docId: z.string().describe("The document whose icon to update."),
+            icon: iconSchema,
+        },
+    }, updateDocIconHandler);
+    // ─── update_folder_icon ─────────────────────────────────────────────────────
+    const updateFolderIconHandler = async (parsed) => {
+        const workspaceId = resolveWorkspaceId(parsed.workspaceId);
+        const icon = normalizeIconInput(parsed.icon);
+        const result = await withSocket(workspaceId, (socket) => setExplorerIcon(socket, workspaceId, folderIconKey(parsed.folderId), icon));
+        return receipt("folder.update_icon", {
+            workspaceId,
+            folderId: parsed.folderId,
+            icon: result.icon,
+            cleared: result.icon === null,
+        });
+    };
+    server.registerTool("update_folder_icon", {
+        title: "Update Folder Icon",
+        description: "Set or clear the sidebar icon on an organize folder. " +
+            "Pass an emoji string, a full icon object, or null to remove it. Experimental.",
+        inputSchema: {
+            workspaceId: z.string().optional(),
+            folderId: z.string().describe("The organize folder whose icon to update."),
+            icon: iconSchema,
+        },
+    }, updateFolderIconHandler);
+    // ─── get_doc_icon ───────────────────────────────────────────────────────────
+    const getDocIconHandler = async (parsed) => {
+        const workspaceId = resolveWorkspaceId(parsed.workspaceId);
+        const result = await withSocket(workspaceId, (socket) => getExplorerIcon(socket, workspaceId, docIconKey(parsed.docId)));
+        return receipt("doc.get_icon", {
+            workspaceId,
+            docId: parsed.docId,
+            icon: result.icon,
+            hasIcon: result.icon !== null,
+        });
+    };
+    server.registerTool("get_doc_icon", {
+        title: "Get Document Icon",
+        description: "Read the current sidebar icon of a document. Returns null when none is set.",
+        inputSchema: {
+            workspaceId: z.string().optional(),
+            docId: z.string().describe("The document whose icon to read."),
+        },
+    }, getDocIconHandler);
+    // ─── get_folder_icon ────────────────────────────────────────────────────────
+    const getFolderIconHandler = async (parsed) => {
+        const workspaceId = resolveWorkspaceId(parsed.workspaceId);
+        const result = await withSocket(workspaceId, (socket) => getExplorerIcon(socket, workspaceId, folderIconKey(parsed.folderId)));
+        return receipt("folder.get_icon", {
+            workspaceId,
+            folderId: parsed.folderId,
+            icon: result.icon,
+            hasIcon: result.icon !== null,
+        });
+    };
+    server.registerTool("get_folder_icon", {
+        title: "Get Folder Icon",
+        description: "Read the current sidebar icon of an organize folder. Returns null when none is set. Experimental.",
+        inputSchema: {
+            workspaceId: z.string().optional(),
+            folderId: z.string().describe("The organize folder whose icon to read."),
+        },
+    }, getFolderIconHandler);
+}

package/dist/util/explorerIcon.js

@@ -0,0 +1,95 @@
+import * as Y from "yjs";
+import { loadDoc, pushDocUpdate } from "../ws.js";
+/** Build the sub-document guid that holds a workspace's explorer icons. */
+export function explorerIconDocId(workspaceId) {
+    return `db$${workspaceId}$explorerIcon`;
+}
+/** Build the per-entity map key for a document. */
+export function docIconKey(docId) {
+    return `doc:${docId}`;
+}
+/** Build the per-entity map key for an organize folder. */
+export function folderIconKey(folderId) {
+    return `folder:${folderId}`;
+}
+/**
+ * Coerce user input into the stored icon shape (or null to clear).
+ *
+ * - A bare string is treated as an emoji shorthand → `{ type: "emoji", unicode }`.
+ * - A `{ type: "emoji", unicode }` or `{ type: "icon", name }` object is passed
+ *   through after validation. Named-icon `name` values are not validated against
+ *   AFFiNE's fixed icon set — they are written as-is.
+ * - `null` clears the icon.
+ */
+export function normalizeIconInput(input) {
+    if (input === null)
+        return null;
+    if (typeof input === "string") {
+        const unicode = input.trim();
+        if (!unicode)
+            throw new Error("icon emoji string must not be empty.");
+        return { type: "emoji", unicode };
+    }
+    if (input.type === "emoji") {
+        const unicode = input.unicode?.trim();
+        if (!unicode)
+            throw new Error("emoji icon requires a non-empty `unicode`.");
+        return { type: "emoji", unicode };
+    }
+    if (input.type === "icon") {
+        const name = input.name?.trim();
+        if (!name)
+            throw new Error("named icon requires a non-empty `name`.");
+        return { type: "icon", name };
+    }
+    throw new Error(`Unsupported icon type: ${JSON.stringify(input.type)}.`);
+}
+async function loadExplorerIconDoc(socket, workspaceId) {
+    const snap = await loadDoc(socket, workspaceId, explorerIconDocId(workspaceId));
+    const doc = new Y.Doc();
+    if (snap.missing)
+        Y.applyUpdate(doc, Buffer.from(snap.missing, "base64"));
+    return doc;
+}
+function readIcon(doc, key) {
+    const map = doc.share.has(key) ? doc.getMap(key) : null;
+    if (!map || !map.has("icon"))
+        return null;
+    const raw = map.get("icon");
+    if (raw && typeof raw.toJSON === "function") {
+        return raw.toJSON();
+    }
+    return raw ?? null;
+}
+/**
+ * Set or clear the sidebar icon for a single explorer entity.
+ *
+ * Loads the workspace's `explorerIcon` sub-doc, mutates only the target entry,
+ * and pushes the minimal delta. Passing `icon = null` removes the `icon` field
+ * while preserving the entry's `id`.
+ */
+export async function setExplorerIcon(socket, workspaceId, key, icon) {
+    const doc = await loadExplorerIconDoc(socket, workspaceId);
+    const prevSV = Y.encodeStateVector(doc);
+    const map = doc.getMap(key);
+    if (!map.has("id"))
+        map.set("id", key);
+    if (icon === null) {
+        if (map.has("icon"))
+            map.delete("icon");
+    }
+    else {
+        map.set("icon", icon);
+    }
+    const delta = Y.encodeStateAsUpdate(doc, prevSV);
+    await pushDocUpdate(socket, workspaceId, explorerIconDocId(workspaceId), Buffer.from(delta).toString("base64"));
+    return { key, icon };
+}
+/**
+ * Read the current sidebar icon for a single explorer entity.
+ * Returns `null` when no icon is set (or the entry does not exist).
+ */
+export async function getExplorerIcon(socket, workspaceId, key) {
+    const doc = await loadExplorerIconDoc(socket, workspaceId);
+    return { key, icon: readIcon(doc, key) };
+}

package/docs/tool-reference.md

@@ -39,6 +39,8 @@ Use this document as a grouped catalog. For exact schemas, your MCP client shoul
 | `create_folder` | Create a root or nested folder | Experimental |
 | `create_workspace_blueprint` | Create a simple workspace folder blueprint | Good for structured onboarding setups |
 | `rename_folder` | Rename a folder | Experimental |
+| `update_folder_icon` | Set or clear a folder's sidebar icon (emoji or named icon) | Experimental |
+| `get_folder_icon` | Read a folder's current sidebar icon | Experimental |
 | `delete_folder` | Delete a folder recursively | Experimental and destructive |
 | `move_organize_node` | Move a folder or link node | Experimental |
 | `add_organize_link` | Add a doc, tag, or collection link under a folder | Experimental |
@@ -83,6 +85,8 @@ Use this document as a grouped catalog. For exact schemas, your MCP client shoul
 | Tool | Purpose | Notes |
 | --- | --- | --- |
 | `update_doc_title` | Rename a document in workspace metadata and in the page block | |
+| `update_doc_icon` | Set or clear a document's sidebar icon (emoji or named icon) | |
+| `get_doc_icon` | Read a document's current sidebar icon | |
 | `append_block` | Append canonical block types with validation and placement control | Supports text, media, embeds, database, and edgeless blocks. `frame`/`edgeless_text`/`note` accept `x`/`y`/`width`/`height`. `note` with `text` auto-creates a child paragraph so it renders on the edgeless canvas. |
 | `create_semantic_page` | Create an AFFiNE-native page with an intentional section skeleton and native block composition | High-level authoring helper |
 | `append_semantic_section` | Append a semantic section to an existing page by heading title | High-level authoring helper |
@@ -96,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.2.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.",
@@ -49,6 +49,7 @@
     "test:data-view": "node tests/test-data-view.mjs",
     "test:doc-discovery": "node tests/test-doc-discovery.mjs",
     "test:doc-properties": "node tests/test-doc-properties.mjs",
+    "test:icons": "node tests/test-icons.mjs",
     "test:read-doc-linked-refs": "node tests/test-read-doc-linked-refs.mjs",
     "test:find-doc-by-title": "node tests/test-find-doc-by-title.mjs",
     "test:create-placement": "node tests/test-create-placement.mjs",
@@ -67,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",
@@ -98,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.2.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",
@@ -43,7 +44,9 @@
     "get_capabilities",
     "get_collection",
     "get_doc",
+    "get_doc_icon",
     "get_edgeless_canvas",
+    "get_folder_icon",
     "get_orphan_docs",
     "get_workspace",
     "inspect_template_structure",
@@ -83,8 +86,10 @@
     "update_collection_rules",
     "update_comment",
     "update_database_row",
+    "update_doc_icon",
     "update_doc_title",
     "update_edgeless_block",
+    "update_folder_icon",
     "update_frame_children",
     "update_profile",
     "update_settings",