affine-mcp-server 2.1.0 → 2.2.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.2.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 90 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.2.0: Added document custom-property tools, `read_doc` LinkedPage reference IDs, and table ordering fixes.
 
 ## 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,7 @@ 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 { runCli } from "./cli.js";
 import { startHttpMcpServer } from "./sse.js";
 import { existsSync } from "fs";
@@ -165,6 +166,7 @@ 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 });
     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",
@@ -47,6 +50,7 @@ const ALL_TOOLS = [
     "list_children",
     "list_collections",
     "list_comments",
+    "list_doc_properties",
     "list_docs",
     "list_docs_by_tag",
     "list_histories",
@@ -71,6 +75,7 @@ const ALL_TOOLS = [
     "revoke_access_token",
     "revoke_doc",
     "search_docs",
+    "set_doc_property",
     "sign_in",
     "update_collection",
     "update_collection_rules",
@@ -97,9 +102,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 +119,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"],
@@ -134,6 +142,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,6 +167,7 @@ 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"],
@@ -189,6 +199,7 @@ const READ_ONLY_TOOLS = new Set([
     "list_children",
     "list_collections",
     "list_comments",
+    "list_doc_properties",
     "list_docs",
     "list_docs_by_tag",
     "list_histories",

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";
@@ -166,22 +166,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 +1348,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 +2089,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 +2106,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 +2114,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 +2144,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 +3810,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 +3828,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,

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/docs/tool-reference.md

@@ -55,7 +55,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 | |
@@ -97,6 +97,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.2.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,13 @@
     "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: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.2.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",
@@ -49,6 +52,7 @@
     "list_children",
     "list_collections",
     "list_comments",
+    "list_doc_properties",
     "list_docs",
     "list_docs_by_tag",
     "list_histories",
@@ -73,6 +77,7 @@
     "revoke_access_token",
     "revoke_doc",
     "search_docs",
+    "set_doc_property",
     "sign_in",
     "update_collection",
     "update_collection_rules",