affine-mcp-server 2.1.0 → 2.3.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.1.0-blue)](https://github.com/dawncr0w/affine-mcp-server/releases)
+[![Version](https://img.shields.io/badge/version-2.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)
@@ -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 85 canonical MCP tools backed by AFFiNE GraphQL and WebSocket APIs
+- Exposes 94 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.1.0: Added exact-title document lookup, folder placement for `create_doc`, and trusted npm publishing.
+> New in v2.3.0: Added document and folder sidebar icon tools, plus richer hierarchy detection for inline LinkedPage references and synced-doc embeds.
 
 ## Choose Your Path
 | Goal | Start here |
@@ -170,7 +170,7 @@ Domains:
 
 - Workspace: create, inspect, update, delete, and traverse workspaces
 - Organization: collections, collection-rule sync, workspace blueprints, and experimental organize or folder helpers
-- Documents: search, read, create, publish, move, tag, import/export, semantic composition, template inspection and native instantiation, capability and fidelity reporting, and block-level mutation
+- Documents: search, read, create, publish, move, tag, custom properties, import/export, semantic composition, template inspection and native instantiation, capability and fidelity reporting, and block-level mutation
 - Databases: create columns, add rows, update rows, inspect schema, and compose database structures from intent
 - Comments: list, create, update, delete, and resolve
 - History: version history listing

package/dist/index.js

@@ -14,6 +14,8 @@ import { registerNotificationTools } from "./tools/notifications.js";
 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";
@@ -165,6 +167,8 @@ async function buildServer() {
     registerCommentTools(server, gql, { workspaceId: config.defaultWorkspaceId });
     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

@@ -10,9 +10,11 @@ const ALL_TOOLS = [
     "append_markdown",
     "append_semantic_section",
     "cleanup_blobs",
+    "clear_doc_property",
     "compose_database_from_intent",
     "create_collection",
     "create_comment",
+    "create_custom_property",
     "create_doc",
     "create_doc_from_markdown",
     "create_folder",
@@ -25,6 +27,7 @@ const ALL_TOOLS = [
     "delete_block",
     "delete_collection",
     "delete_comment",
+    "delete_custom_property",
     "delete_database_row",
     "delete_doc",
     "delete_folder",
@@ -38,7 +41,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",
@@ -47,6 +52,7 @@ const ALL_TOOLS = [
     "list_children",
     "list_collections",
     "list_comments",
+    "list_doc_properties",
     "list_docs",
     "list_docs_by_tag",
     "list_histories",
@@ -71,13 +77,16 @@ const ALL_TOOLS = [
     "revoke_access_token",
     "revoke_doc",
     "search_docs",
+    "set_doc_property",
     "sign_in",
     "update_collection",
     "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",
@@ -97,9 +106,11 @@ const TOOL_GROUPS = {
     append_markdown: ["docs", "docs.markdown", "docs.write", "write"],
     append_semantic_section: ["docs", "docs.semantic", "docs.write", "write"],
     cleanup_blobs: ["blobs", "blobs.write", "cleanup", "destructive", "write"],
+    clear_doc_property: ["docs", "docs.properties", "docs.write", "write"],
     compose_database_from_intent: ["docs", "docs.database", "docs.intent", "docs.write", "write"],
     create_collection: ["organize", "organize.collections", "organize.write", "write"],
     create_comment: ["comments", "comments.write", "write"],
+    create_custom_property: ["docs", "docs.properties", "docs.write", "write"],
     create_doc: ["docs", "docs.write", "write"],
     create_doc_from_markdown: ["docs", "docs.markdown", "docs.write", "write"],
     create_folder: ["organize", "organize.folders", "organize.write", "experimental", "write"],
@@ -112,6 +123,7 @@ const TOOL_GROUPS = {
     delete_block: ["docs", "docs.edgeless", "docs.write", "destructive", "write"],
     delete_collection: ["organize", "organize.collections", "organize.write", "destructive", "write"],
     delete_comment: ["comments", "comments.write", "destructive", "write"],
+    delete_custom_property: ["docs", "docs.properties", "docs.write", "destructive", "write"],
     delete_database_row: ["docs", "docs.database", "docs.write", "destructive", "write"],
     delete_doc: ["docs", "docs.write", "destructive", "write"],
     delete_folder: ["organize", "organize.folders", "organize.write", "destructive", "experimental", "write"],
@@ -125,7 +137,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"],
@@ -134,6 +148,7 @@ const TOOL_GROUPS = {
     list_children: ["docs", "docs.tree", "docs.read", "read"],
     list_collections: ["organize", "organize.collections", "organize.read", "read"],
     list_comments: ["comments", "comments.read", "read"],
+    list_doc_properties: ["docs", "docs.properties", "docs.read", "read"],
     list_docs: ["docs", "docs.read", "read"],
     list_docs_by_tag: ["docs", "docs.tags", "docs.read", "read"],
     list_histories: ["history", "history.read", "read"],
@@ -158,13 +173,16 @@ const TOOL_GROUPS = {
     revoke_access_token: ["access_tokens", "access_tokens.write", "admin", "destructive", "write"],
     revoke_doc: ["docs", "docs.share", "docs.write", "destructive", "write"],
     search_docs: ["docs", "docs.read", "read"],
+    set_doc_property: ["docs", "docs.properties", "docs.write", "write"],
     sign_in: ["users", "users.auth", "auth", "write"],
     update_collection: ["organize", "organize.collections", "organize.write", "write"],
     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"],
@@ -181,7 +199,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",
@@ -189,6 +209,7 @@ const READ_ONLY_TOOLS = new Set([
     "list_children",
     "list_collections",
     "list_comments",
+    "list_doc_properties",
     "list_docs",
     "list_docs_by_tag",
     "list_histories",
@@ -217,6 +238,7 @@ const CORE_TOOLS = new Set([
     "find_doc_by_title",
     "get_capabilities",
     "get_doc",
+    "get_doc_icon",
     "get_workspace",
     "list_children",
     "list_docs",
@@ -231,6 +253,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

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { generateKeyBetween } from "fractional-indexing";
+import { generateKeyBetween, generateNKeysBetween } from "fractional-indexing";
 import { receipt, text } from "../util/mcp.js";
 import { wsUrlFromGraphQLEndpoint, connectWorkspaceSocket, joinWorkspace, loadDoc, pushDocUpdate, deleteDoc as wsDeleteDoc } from "../ws.js";
 import * as Y from "yjs";
@@ -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");
@@ -166,22 +213,30 @@ export function registerDocTools(server, gql, defaults) {
         return makeText(delta);
     }
     /**
-     * Extract a linked-doc page ID from a database row block's prop:text,
-     * if it contains a LinkedPage reference delta.  Returns null otherwise.
+     * Extract inline LinkedPage reference IDs from a Y.Text value. AFFiNE stores
+     * @-mentions as zero-width text deltas whose page id lives in attributes.
      */
-    function readLinkedDocId(rowBlock) {
-        const propText = rowBlock.get("prop:text");
+    function extractLinkedPageRefs(propText) {
         if (!(propText instanceof Y.Text))
-            return null;
+            return [];
         const delta = propText.toDelta();
         if (!Array.isArray(delta))
-            return null;
+            return [];
+        const refs = [];
         for (const d of delta) {
-            if (d.attributes?.reference?.type === "LinkedPage" && d.attributes.reference.pageId) {
-                return d.attributes.reference.pageId;
+            const reference = d.attributes?.reference;
+            if (reference?.type === "LinkedPage" && typeof reference.pageId === "string" && reference.pageId.length > 0) {
+                refs.push(reference.pageId);
             }
         }
-        return null;
+        return refs;
+    }
+    /**
+     * Extract a linked-doc page ID from a database row block's prop:text,
+     * if it contains a LinkedPage reference delta. Returns null otherwise.
+     */
+    function readLinkedDocId(rowBlock) {
+        return extractLinkedPageRefs(rowBlock.get("prop:text"))[0] ?? null;
     }
     function asText(value) {
         if (value instanceof Y.Text)
@@ -1340,16 +1395,23 @@ export function registerDocTools(server, gql, defaults) {
                 const rowIds = [];
                 const columnIds = [];
                 const tableData = normalized.tableData ?? [];
+                // Row/column `order` must be valid fractional-indexing keys. AFFiNE's
+                // editor computes the next order with generateKeyBetween(prevOrder, ...)
+                // when inserting a row/column; plain strings like "r0000" render but make
+                // that call throw "invalid order key", so rows/columns cannot be added in
+                // the UI. Use real keys (a0, a1, ...) so insertion works.
+                const rowOrders = generateNKeysBetween(null, null, normalized.rows);
+                const columnOrders = generateNKeysBetween(null, null, normalized.columns);
                 for (let i = 0; i < normalized.rows; i++) {
                     const rowId = generateId();
                     block.set(`prop:rows.${rowId}.rowId`, rowId);
-                    block.set(`prop:rows.${rowId}.order`, `r${String(i).padStart(4, "0")}`);
+                    block.set(`prop:rows.${rowId}.order`, rowOrders[i]);
                     rowIds.push(rowId);
                 }
                 for (let i = 0; i < normalized.columns; i++) {
                     const columnId = generateId();
                     block.set(`prop:columns.${columnId}.columnId`, columnId);
-                    block.set(`prop:columns.${columnId}.order`, `c${String(i).padStart(4, "0")}`);
+                    block.set(`prop:columns.${columnId}.order`, columnOrders[i]);
                     columnIds.push(columnId);
                 }
                 for (let rowIndex = 0; rowIndex < rowIds.length; rowIndex += 1) {
@@ -2074,6 +2136,13 @@ export function registerDocTools(server, gql, defaults) {
         return [];
     }
     function extractTableData(block) {
+        const compareOrder = (left, right) => {
+            if (left < right)
+                return -1;
+            if (left > right)
+                return 1;
+            return 0;
+        };
         const rowsValue = block.get("prop:rows");
         const columnsValue = block.get("prop:columns");
         const cellsValue = block.get("prop:cells");
@@ -2084,7 +2153,7 @@ export function registerDocTools(server, gql, defaults) {
                 ? payload.order
                 : rowId,
         }))
-            .sort((a, b) => a.order.localeCompare(b.order));
+            .sort((a, b) => compareOrder(a.order, b.order));
         let columnEntries = mapEntries(columnsValue)
             .map(([columnId, payload]) => ({
             columnId,
@@ -2092,7 +2161,7 @@ export function registerDocTools(server, gql, defaults) {
                 ? payload.order
                 : columnId,
         }))
-            .sort((a, b) => a.order.localeCompare(b.order));
+            .sort((a, b) => compareOrder(a.order, b.order));
         let cells = new Map();
         if (rowEntries.length === 0 || columnEntries.length === 0) {
             // Fallback: AFFiNE self-hosted stores table props as flat dot-notation keys
@@ -2122,10 +2191,10 @@ export function registerDocTools(server, gql, defaults) {
             if (flatRows.size > 0 && flatColumns.size > 0) {
                 rowEntries = Array.from(flatRows.entries())
                     .map(([rowId, order]) => ({ rowId, order }))
-                    .sort((a, b) => a.order.localeCompare(b.order));
+                    .sort((a, b) => compareOrder(a.order, b.order));
                 columnEntries = Array.from(flatColumns.entries())
                     .map(([columnId, order]) => ({ columnId, order }))
-                    .sort((a, b) => a.order.localeCompare(b.order));
+                    .sort((a, b) => compareOrder(a.order, b.order));
                 cells = flatCells;
             }
         }
@@ -3788,7 +3857,9 @@ export function registerDocTools(server, gql, defaults) {
                 const flavour = raw.get("sys:flavour");
                 const parentId = raw.get("sys:parent");
                 const type = raw.get("prop:type");
-                const textValue = asText(raw.get("prop:text"));
+                const propText = raw.get("prop:text");
+                const textValue = asText(propText);
+                const linkedDocIds = extractLinkedPageRefs(propText);
                 const language = raw.get("prop:language");
                 const checked = raw.get("prop:checked");
                 const childIds = childIdsFrom(raw.get("sys:children"));
@@ -3804,6 +3875,7 @@ export function registerDocTools(server, gql, defaults) {
                     flavour: typeof flavour === "string" ? flavour : null,
                     type: typeof type === "string" ? type : null,
                     text: textValue.length > 0 ? textValue : null,
+                    linkedDocIds,
                     checked: typeof checked === "boolean" ? checked : null,
                     language: typeof language === "string" ? language : null,
                     childIds,
@@ -4758,13 +4830,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);
                     }
@@ -4818,14 +4885,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(/\/$/, "");
@@ -4844,7 +4905,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).",
         inputSchema: { workspaceId: z.string().optional() },
     }, getOrphanDocsHandler);
     const listChildrenHandler = async (parsed) => {
@@ -4857,11 +4918,15 @@ export function registerDocTools(server, gql, defaults) {
         try {
             await joinWorkspace(socket, workspaceId);
             const titleById = 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);
                     if (page.title)
                         titleById.set(page.id, page.title);
                 }
@@ -4873,16 +4938,15 @@ 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}` });
             }
             return text({ docId: parsed.docId, count: children.length, children });
         }
@@ -4892,7 +4956,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, and URL 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/tools/properties.js

@@ -0,0 +1,426 @@
+import { z } from "zod";
+import { generateKeyBetween } from "fractional-indexing";
+import * as Y from "yjs";
+import { text } from "../util/mcp.js";
+import { wsUrlFromGraphQLEndpoint, connectWorkspaceSocket, joinWorkspace, loadDoc, pushDocUpdate, } from "../ws.js";
+/**
+ * Doc custom properties live in dedicated Yjs sub-docs synced by guid, NOT in
+ * the page doc or the workspace root meta. AFFiNE's WorkspaceDB (an ORM on top
+ * of Yjs) maps one table to one sub-doc whose guid is `db$<tableName>`:
+ *
+ *  - `db$docCustomPropertyInfo`: the workspace-wide property *definitions*
+ *     (schema). Top-level YMap keyed by propertyId -> { id, name, type, index,
+ *     icon, show, isDeleted }.
+ *  - `db$docProperties`: the per-doc property *values*. Top-level YMap keyed by
+ *     docId -> { id, ...builtins, "custom:<propertyId>": <value> }.
+ *
+ * A custom property must have a definition in `db$docCustomPropertyInfo` to be
+ * rendered/editable in the AFFiNE UI. Writing a value without a matching
+ * definition stores orphan data that the UI ignores.
+ *
+ * Values are stored as strings, encoded per type:
+ *  - text:     raw string
+ *  - number:   stringified number
+ *  - checkbox: "true" | "false"
+ *  - date:     "YYYY-MM-DD"
+ *
+ * References (AFFiNE repo):
+ *  - modules/db/services/db.ts  -> guid `db$${tableName}`
+ *  - orm/core/adapters/yjs/table.ts -> record = top-level YMap keyed by primary key
+ *  - modules/doc/entities/record.ts -> value key is `custom:<propertyId>`
+ */
+const DOC_PROPERTIES_GUID = "db$docProperties";
+const CUSTOM_PROPERTY_INFO_GUID = "db$docCustomPropertyInfo";
+const DELETED_FLAG = "$$DELETED";
+const CUSTOM_PREFIX = "custom:";
+const SUPPORTED_TYPES = ["text", "number", "checkbox", "date"];
+const WorkspaceId = z.string().min(1, "workspaceId required");
+const DocId = z.string().min(1, "docId required");
+const NANOID_ALPHABET = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_";
+/** Generate a 21-char nanoid-style id, matching AFFiNE's property id format. */
+function generatePropertyId() {
+    let id = "";
+    for (let i = 0; i < 21; i++) {
+        id += NANOID_ALPHABET.charAt(Math.floor(Math.random() * NANOID_ALPHABET.length));
+    }
+    return id;
+}
+/**
+ * Read all live custom-property definitions from the `db$docCustomPropertyInfo`
+ * sub-doc, skipping soft-deleted and empty records.
+ */
+function readPropertyDefinitions(doc) {
+    const defs = [];
+    // Records are top-level (root) Yjs types keyed by id. After applyUpdate, root
+    // types are generic AbstractType until doc.getMap(key) casts them, so an
+    // `instanceof Y.Map` check would skip every record. Mirror AFFiNE's ORM
+    // adapter and materialize each record via getMap.
+    for (const key of doc.share.keys()) {
+        const data = doc.getMap(key).toJSON();
+        if (data[DELETED_FLAG] === true || data.isDeleted === true)
+            continue;
+        if (Object.keys(data).length === 0)
+            continue;
+        const type = typeof data.type === "string" ? data.type : "unknown";
+        defs.push({
+            id: typeof data.id === "string" ? data.id : key,
+            name: typeof data.name === "string" ? data.name : null,
+            type,
+            index: typeof data.index === "string" ? data.index : null,
+            icon: typeof data.icon === "string" ? data.icon : null,
+            show: typeof data.show === "string" ? data.show : null,
+        });
+    }
+    defs.sort((a, b) => (a.index || "").localeCompare(b.index || ""));
+    return defs;
+}
+/**
+ * Resolve a definition by exact id, then by unique case-insensitive name.
+ * Throws if a name matches more than one definition.
+ */
+function resolveDefinition(defs, property) {
+    const byId = defs.find((d) => d.id === property);
+    if (byId)
+        return byId;
+    const lowered = property.trim().toLowerCase();
+    const byName = defs.filter((d) => (d.name || "").trim().toLowerCase() === lowered);
+    if (byName.length === 1)
+        return byName[0];
+    if (byName.length > 1) {
+        throw new Error(`Property name "${property}" is ambiguous (${byName.length} matches). Use the property id instead.`);
+    }
+    return null;
+}
+/** Compute the next fractional index, appending after the current last definition. */
+function nextIndex(defs) {
+    const indexes = defs
+        .map((d) => d.index)
+        .filter((i) => typeof i === "string" && i.length > 0)
+        .sort();
+    const last = indexes.length ? indexes[indexes.length - 1] : null;
+    return generateKeyBetween(last, null);
+}
+/** Encode a JS value into AFFiNE's per-type string representation; throws on invalid input. */
+function encodeValue(type, value) {
+    switch (type) {
+        case "checkbox": {
+            const truthy = value === true ||
+                value === 1 ||
+                (typeof value === "string" && ["true", "1", "yes"].includes(value.trim().toLowerCase()));
+            return truthy ? "true" : "false";
+        }
+        case "number": {
+            const n = typeof value === "number" ? value : Number(String(value).trim());
+            if (!Number.isFinite(n)) {
+                throw new Error(`number property requires a numeric value, got ${JSON.stringify(value)}`);
+            }
+            return String(n);
+        }
+        case "date": {
+            const s = String(value).trim();
+            if (!/^\d{4}-\d{2}-\d{2}$/.test(s)) {
+                throw new Error(`date property requires "YYYY-MM-DD", got ${JSON.stringify(value)}`);
+            }
+            const parsed = new Date(`${s}T00:00:00.000Z`);
+            if (!Number.isFinite(parsed.getTime()) || parsed.toISOString().slice(0, 10) !== s) {
+                throw new Error(`date property requires a valid "YYYY-MM-DD" date, got ${JSON.stringify(value)}`);
+            }
+            return s;
+        }
+        case "text":
+        default:
+            return String(value);
+    }
+}
+/** Decode a stored string back into a typed JS value for output. */
+function decodeValue(type, raw) {
+    if (raw === undefined || raw === null)
+        return null;
+    switch (type) {
+        case "checkbox":
+            return raw === "true" || raw === true;
+        case "number": {
+            const n = Number(raw);
+            return Number.isFinite(n) ? n : raw;
+        }
+        default:
+            return raw;
+    }
+}
+/** Register the five document custom-property tools on the MCP server. */
+export function registerPropertyTools(server, gql, defaults) {
+    /** Snapshot the current GraphQL endpoint and auth material for WebSocket use. */
+    function getCookieAndEndpoint() {
+        return { endpoint: gql.endpoint, cookie: gql.cookie, bearer: gql.bearer };
+    }
+    /** Resolve the workspace id from the argument or the configured default; throws if absent. */
+    function requireWorkspaceId(workspaceId) {
+        const id = workspaceId || defaults.workspaceId;
+        if (!id) {
+            throw new Error("workspaceId is required. Provide it as a parameter or set AFFINE_WORKSPACE_ID in environment.");
+        }
+        return id;
+    }
+    /** Load a WorkspaceDB sub-doc by guid and return it with its pre-mutation state vector. */
+    async function loadSubdoc(socket, workspaceId, guid) {
+        const snapshot = await loadDoc(socket, workspaceId, guid);
+        const doc = new Y.Doc();
+        let existed = false;
+        if (snapshot.missing) {
+            Y.applyUpdate(doc, Buffer.from(snapshot.missing, "base64"));
+            existed = true;
+        }
+        return { doc, prevSV: Y.encodeStateVector(doc), existed };
+    }
+    /** Push only the delta accumulated since `prevSV` back to the sync gateway. */
+    async function pushSubdoc(socket, workspaceId, guid, doc, prevSV) {
+        const delta = Y.encodeStateAsUpdate(doc, prevSV);
+        await pushDocUpdate(socket, workspaceId, guid, Buffer.from(delta).toString("base64"));
+    }
+    /** Throw if the workspace root or the docId is not found in workspace metadata. */
+    async function assertDocExists(socket, workspaceId, docId) {
+        const snapshot = await loadDoc(socket, workspaceId, workspaceId);
+        if (!snapshot.missing) {
+            throw new Error(`Workspace root document not found for workspace ${workspaceId}`);
+        }
+        const wsDoc = new Y.Doc();
+        Y.applyUpdate(wsDoc, Buffer.from(snapshot.missing, "base64"));
+        const pages = wsDoc.getMap("meta").get("pages");
+        const exists = pages instanceof Y.Array &&
+            pages.toArray().some((p) => p instanceof Y.Map && p.get("id") === docId);
+        if (!exists) {
+            throw new Error(`docId ${docId} is not present in workspace ${workspaceId}`);
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // list_doc_properties
+    // ---------------------------------------------------------------------------
+    /** Handle `list_doc_properties`: definitions, decoded per-doc values, and orphan values. */
+    const listDocPropertiesHandler = async (parsed) => {
+        const workspaceId = requireWorkspaceId(parsed.workspaceId);
+        const { endpoint, cookie, bearer } = getCookieAndEndpoint();
+        const socket = await connectWorkspaceSocket(wsUrlFromGraphQLEndpoint(endpoint), cookie, bearer);
+        try {
+            await joinWorkspace(socket, workspaceId);
+            const { doc: infoDoc } = await loadSubdoc(socket, workspaceId, CUSTOM_PROPERTY_INFO_GUID);
+            const defs = readPropertyDefinitions(infoDoc);
+            const { doc: propsDoc } = await loadSubdoc(socket, workspaceId, DOC_PROPERTIES_GUID);
+            const record = propsDoc.share.has(parsed.docId)
+                ? propsDoc.getMap(parsed.docId).toJSON()
+                : {};
+            const byId = new Map(defs.map((d) => [d.id, d]));
+            const properties = defs.map((def) => {
+                const raw = record[CUSTOM_PREFIX + def.id];
+                return {
+                    propertyId: def.id,
+                    name: def.name,
+                    type: def.type,
+                    value: decodeValue(def.type, raw),
+                    set: raw !== undefined && raw !== null,
+                };
+            });
+            // Surface custom values that have no matching (live) definition.
+            const orphans = Object.keys(record)
+                .filter((k) => k.startsWith(CUSTOM_PREFIX))
+                .map((k) => k.slice(CUSTOM_PREFIX.length))
+                .filter((id) => !byId.has(id))
+                .map((id) => ({ propertyId: id, value: record[CUSTOM_PREFIX + id] }));
+            return text({
+                workspaceId,
+                docId: parsed.docId,
+                definitions: defs,
+                properties,
+                orphanValues: orphans,
+            });
+        }
+        finally {
+            socket.disconnect();
+        }
+    };
+    server.registerTool("list_doc_properties", {
+        title: "List Document Properties",
+        description: "List the workspace custom-property definitions and a document's current values for them.",
+        inputSchema: {
+            workspaceId: WorkspaceId.optional(),
+            docId: DocId,
+        },
+    }, listDocPropertiesHandler);
+    // ---------------------------------------------------------------------------
+    // create_custom_property
+    // ---------------------------------------------------------------------------
+    /** Handle `create_custom_property`: append a new workspace-wide definition. */
+    const createCustomPropertyHandler = async (parsed) => {
+        const workspaceId = requireWorkspaceId(parsed.workspaceId);
+        const name = parsed.name.trim();
+        if (!name)
+            throw new Error("name is required");
+        const { endpoint, cookie, bearer } = getCookieAndEndpoint();
+        const socket = await connectWorkspaceSocket(wsUrlFromGraphQLEndpoint(endpoint), cookie, bearer);
+        try {
+            await joinWorkspace(socket, workspaceId);
+            const { doc, prevSV } = await loadSubdoc(socket, workspaceId, CUSTOM_PROPERTY_INFO_GUID);
+            const defs = readPropertyDefinitions(doc);
+            const id = generatePropertyId();
+            const index = nextIndex(defs);
+            const record = doc.getMap(id);
+            record.set("id", id);
+            record.set("name", name);
+            record.set("type", parsed.type);
+            record.set("index", index);
+            if (parsed.icon)
+                record.set("icon", parsed.icon);
+            await pushSubdoc(socket, workspaceId, CUSTOM_PROPERTY_INFO_GUID, doc, prevSV);
+            return text({
+                workspaceId,
+                propertyId: id,
+                name,
+                type: parsed.type,
+                index,
+                created: true,
+            });
+        }
+        finally {
+            socket.disconnect();
+        }
+    };
+    server.registerTool("create_custom_property", {
+        title: "Create Custom Property",
+        description: "Create a workspace-wide custom property definition (text, number, checkbox, or date). Returns its propertyId.",
+        inputSchema: {
+            workspaceId: WorkspaceId.optional(),
+            name: z.string().min(1).describe("Display name of the property"),
+            type: z.enum(SUPPORTED_TYPES).describe("Property value type"),
+            icon: z.string().optional().describe("Optional icon name"),
+        },
+    }, createCustomPropertyHandler);
+    // ---------------------------------------------------------------------------
+    // delete_custom_property
+    // ---------------------------------------------------------------------------
+    /** Handle `delete_custom_property`: soft-delete a definition by id or name. */
+    const deleteCustomPropertyHandler = async (parsed) => {
+        const workspaceId = requireWorkspaceId(parsed.workspaceId);
+        const { endpoint, cookie, bearer } = getCookieAndEndpoint();
+        const socket = await connectWorkspaceSocket(wsUrlFromGraphQLEndpoint(endpoint), cookie, bearer);
+        try {
+            await joinWorkspace(socket, workspaceId);
+            const { doc, prevSV } = await loadSubdoc(socket, workspaceId, CUSTOM_PROPERTY_INFO_GUID);
+            const defs = readPropertyDefinitions(doc);
+            const def = resolveDefinition(defs, parsed.property);
+            if (!def) {
+                throw new Error(`No custom property matches "${parsed.property}" in workspace ${workspaceId}`);
+            }
+            // Mirror AFFiNE: keep the record for legacy override, flag it deleted.
+            const record = doc.getMap(def.id);
+            record.set("isDeleted", true);
+            await pushSubdoc(socket, workspaceId, CUSTOM_PROPERTY_INFO_GUID, doc, prevSV);
+            return text({ workspaceId, propertyId: def.id, name: def.name, deleted: true });
+        }
+        finally {
+            socket.disconnect();
+        }
+    };
+    server.registerTool("delete_custom_property", {
+        title: "Delete Custom Property",
+        description: "Soft-delete a workspace custom property definition (by propertyId or name). Existing values are hidden.",
+        inputSchema: {
+            workspaceId: WorkspaceId.optional(),
+            property: z.string().min(1).describe("Property id or name"),
+        },
+    }, deleteCustomPropertyHandler);
+    // ---------------------------------------------------------------------------
+    // set_doc_property
+    // ---------------------------------------------------------------------------
+    /** Handle `set_doc_property`: validate, encode, and upsert a doc's property value. */
+    const setDocPropertyHandler = async (parsed) => {
+        const workspaceId = requireWorkspaceId(parsed.workspaceId);
+        const { endpoint, cookie, bearer } = getCookieAndEndpoint();
+        const socket = await connectWorkspaceSocket(wsUrlFromGraphQLEndpoint(endpoint), cookie, bearer);
+        try {
+            await joinWorkspace(socket, workspaceId);
+            await assertDocExists(socket, workspaceId, parsed.docId);
+            const { doc: infoDoc } = await loadSubdoc(socket, workspaceId, CUSTOM_PROPERTY_INFO_GUID);
+            const defs = readPropertyDefinitions(infoDoc);
+            const def = resolveDefinition(defs, parsed.property);
+            if (!def) {
+                throw new Error(`No custom property matches "${parsed.property}". Create it first with create_custom_property.`);
+            }
+            if (!SUPPORTED_TYPES.includes(def.type)) {
+                throw new Error(`Property "${def.name || def.id}" has type "${def.type}", which set_doc_property cannot edit. Supported: ${SUPPORTED_TYPES.join(", ")}.`);
+            }
+            const encoded = encodeValue(def.type, parsed.value);
+            const { doc, prevSV } = await loadSubdoc(socket, workspaceId, DOC_PROPERTIES_GUID);
+            const record = doc.getMap(parsed.docId);
+            record.set("id", parsed.docId); // ORM keyField, required by find/observe
+            record.set(CUSTOM_PREFIX + def.id, encoded);
+            await pushSubdoc(socket, workspaceId, DOC_PROPERTIES_GUID, doc, prevSV);
+            return text({
+                workspaceId,
+                docId: parsed.docId,
+                propertyId: def.id,
+                name: def.name,
+                type: def.type,
+                value: decodeValue(def.type, encoded),
+                stored: encoded,
+                updated: true,
+            });
+        }
+        finally {
+            socket.disconnect();
+        }
+    };
+    server.registerTool("set_doc_property", {
+        title: "Set Document Property",
+        description: "Set a document's custom property value (property by id or name). Value is validated against the property type (text/number/checkbox/date).",
+        inputSchema: {
+            workspaceId: WorkspaceId.optional(),
+            docId: DocId,
+            property: z.string().min(1).describe("Property id or name"),
+            value: z
+                .union([z.string(), z.number(), z.boolean()])
+                .describe("Value; coerced per property type (checkbox->bool, number, date YYYY-MM-DD, text)"),
+        },
+    }, setDocPropertyHandler);
+    // ---------------------------------------------------------------------------
+    // clear_doc_property
+    // ---------------------------------------------------------------------------
+    /** Handle `clear_doc_property`: remove a doc's value for a property (by id or name). */
+    const clearDocPropertyHandler = async (parsed) => {
+        const workspaceId = requireWorkspaceId(parsed.workspaceId);
+        const { endpoint, cookie, bearer } = getCookieAndEndpoint();
+        const socket = await connectWorkspaceSocket(wsUrlFromGraphQLEndpoint(endpoint), cookie, bearer);
+        try {
+            await joinWorkspace(socket, workspaceId);
+            const { doc: infoDoc } = await loadSubdoc(socket, workspaceId, CUSTOM_PROPERTY_INFO_GUID);
+            const defs = readPropertyDefinitions(infoDoc);
+            const def = resolveDefinition(defs, parsed.property);
+            // Allow clearing by raw id even if the definition was already deleted.
+            const propertyId = def?.id ?? parsed.property;
+            const { doc, prevSV } = await loadSubdoc(socket, workspaceId, DOC_PROPERTIES_GUID);
+            let cleared = false;
+            if (doc.share.has(parsed.docId)) {
+                const record = doc.getMap(parsed.docId);
+                const key = CUSTOM_PREFIX + propertyId;
+                if (record.has(key)) {
+                    record.delete(key);
+                    cleared = true;
+                }
+            }
+            if (cleared) {
+                await pushSubdoc(socket, workspaceId, DOC_PROPERTIES_GUID, doc, prevSV);
+            }
+            return text({ workspaceId, docId: parsed.docId, propertyId, cleared });
+        }
+        finally {
+            socket.disconnect();
+        }
+    };
+    server.registerTool("clear_doc_property", {
+        title: "Clear Document Property",
+        description: "Remove a custom property value from a document (property by id or name).",
+        inputSchema: {
+            workspaceId: WorkspaceId.optional(),
+            docId: DocId,
+            property: z.string().min(1).describe("Property id or name"),
+        },
+    }, clearDocPropertyHandler);
+}

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 |
@@ -55,7 +57,7 @@ Use this document as a grouped catalog. For exact schemas, your MCP client shoul
 | `search_docs` | Search titles with substring, prefix, or exact matching | Supports tag filter and updatedAt sorting |
 | `list_docs_by_tag` | List documents with a specific tag | |
 | `get_doc` | Read document metadata | |
-| `read_doc` | Read block content and plain text snapshot | WebSocket-backed |
+| `read_doc` | Read block content and plain text snapshot | WebSocket-backed; block rows include `linkedDocIds` for inline LinkedPage references |
 | `get_capabilities` | Inspect the server's high-level authoring and fidelity capabilities | Useful for adaptive clients |
 | `analyze_doc_fidelity` | Analyze how a document maps to Markdown and which native AFFiNE structures are lossy | Good before export or migration |
 | `list_children` | List direct child docs linked from a document | |
@@ -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 |
@@ -97,6 +101,16 @@ Use this document as a grouped catalog. For exact schemas, your MCP client shoul
 | `add_tag_to_doc` | Attach a tag to a document | |
 | `remove_tag_from_doc` | Detach a tag from a document | |
 
+### Custom properties
+
+| Tool | Purpose | Notes |
+| --- | --- | --- |
+| `list_doc_properties` | List workspace custom-property definitions and a document's current values | WebSocket-backed; reads the `db$docProperties` / `db$docCustomPropertyInfo` sub-docs |
+| `create_custom_property` | Create a workspace-wide custom property definition | Types: `text`, `number`, `checkbox`, `date`. Returns the `propertyId` |
+| `delete_custom_property` | Soft-delete a custom property definition by id or name | Destructive; existing values are hidden |
+| `set_doc_property` | Set a document's custom property value by property id or name | Value validated per type (`checkbox` boolean, `number`, `date` `YYYY-MM-DD`, `text`) |
+| `clear_doc_property` | Remove a custom property value from a document | |
+
 ### Markdown export
 
 | Tool | Purpose | Notes |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "affine-mcp-server",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "private": false,
   "type": "module",
   "description": "Model Context Protocol server for AFFiNE - enables AI assistants to interact with AFFiNE workspaces, documents, and collaboration features.",
@@ -43,10 +43,14 @@
     "test:e2e": "bash tests/run-e2e.sh",
     "test:db-create": "node tests/test-database-creation.mjs",
     "test:db-cells": "node tests/test-database-cells.mjs",
+    "test:db-linked-doc": "node tests/test-database-linked-doc.mjs",
     "test:db-ui-rows": "node tests/test-database-ui-rows.mjs",
     "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: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",
     "test:surface-elements": "node tests/test-surface-elements.mjs",

package/tool-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.1.0",
+  "version": "2.3.0",
   "tools": [
     "add_database_column",
     "add_database_row",
@@ -12,9 +12,11 @@
     "append_markdown",
     "append_semantic_section",
     "cleanup_blobs",
+    "clear_doc_property",
     "compose_database_from_intent",
     "create_collection",
     "create_comment",
+    "create_custom_property",
     "create_doc",
     "create_doc_from_markdown",
     "create_folder",
@@ -27,6 +29,7 @@
     "delete_block",
     "delete_collection",
     "delete_comment",
+    "delete_custom_property",
     "delete_database_row",
     "delete_doc",
     "delete_folder",
@@ -40,7 +43,9 @@
     "get_capabilities",
     "get_collection",
     "get_doc",
+    "get_doc_icon",
     "get_edgeless_canvas",
+    "get_folder_icon",
     "get_orphan_docs",
     "get_workspace",
     "inspect_template_structure",
@@ -49,6 +54,7 @@
     "list_children",
     "list_collections",
     "list_comments",
+    "list_doc_properties",
     "list_docs",
     "list_docs_by_tag",
     "list_histories",
@@ -73,13 +79,16 @@
     "revoke_access_token",
     "revoke_doc",
     "search_docs",
+    "set_doc_property",
     "sign_in",
     "update_collection",
     "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",