affine-mcp-server 1.11.1 → 1.12.0

package/README.md

@@ -2,7 +2,7 @@
 
 A Model Context Protocol (MCP) server that integrates with AFFiNE (self‑hosted or cloud). It exposes AFFiNE workspaces and documents to AI assistants over stdio (default) or HTTP (`/mcp`).
 
-[![Version](https://img.shields.io/badge/version-1.11.1-blue)](https://github.com/dawncr0w/affine-mcp-server/releases)
+[![Version](https://img.shields.io/badge/version-1.12.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)
@@ -19,7 +19,7 @@ A Model Context Protocol (MCP) server that integrates with AFFiNE (self‑hosted
 - Tools: 76 focused tools with WebSocket-based document editing
 - Status: Active
  
-> New in v1.11.1: Corrected stale `list_docs` count and cursor metadata after `delete_doc` removes a document.
+> New in v1.12.0: Added linked documents on database rows, restored MCP CRUD for rows created in the AFFiNE UI, fixed self-hosted table exports, and documented GHCR Docker releases.
 
 ## Features
 
@@ -251,6 +251,42 @@ If you prefer `npx`:
 }
 ```
 
+### Docker
+
+Pre-built multi-arch images (`linux/amd64`, `linux/arm64`) are published to the GitHub Container Registry on every release tag:
+
+```
+ghcr.io/dawncr0w/affine-mcp-server:latest      # latest release
+ghcr.io/dawncr0w/affine-mcp-server:1.12.0      # specific version
+```
+
+Quick start:
+
+```bash
+docker run -d \
+  -p 3000:3000 \
+  -e AFFINE_BASE_URL=https://your-affine-instance.com \
+  -e AFFINE_API_TOKEN=ut_your_token \
+  -e AFFINE_MCP_HTTP_TOKEN=your-strong-secret \
+  ghcr.io/dawncr0w/affine-mcp-server:latest
+```
+
+Then add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "affine": {
+      "type": "http",
+      "url": "http://localhost:3000/mcp",
+      "headers": { "Authorization": "Bearer your-strong-secret" }
+    }
+  }
+}
+```
+
+The container runs as a non-root user and exposes `/healthz` and `/readyz` for liveness/readiness probes.
+
 ### Remote Server
 
 If you want to host the server remotely (e.g., using Render, Railway, Docker, or a VPS) and connect via HTTP MCP (Streamable HTTP on `/mcp`) instead of local `stdio`, run the server in HTTP mode.

package/dist/tools/docs.js

@@ -103,6 +103,35 @@ export function registerDocTools(server, gql, defaults) {
         }
         return yText;
     }
+    /**
+     * Build a Y.Text containing a LinkedPage reference delta.
+     * This is the mechanism AFFiNE uses to associate a database row with a
+     * linked doc that opens in "center peek" when the row title is clicked.
+     */
+    function makeLinkedDocText(docId) {
+        const delta = [{ insert: "\u200B", attributes: { reference: { type: "LinkedPage", pageId: docId } } }];
+        // Cast needed: TextDelta.attributes doesn't declare `reference`, but
+        // makeText spreads all attributes at runtime via `{ ...delta.attributes }`.
+        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.
+     */
+    function readLinkedDocId(rowBlock) {
+        const propText = rowBlock.get("prop:text");
+        if (!(propText instanceof Y.Text))
+            return null;
+        const delta = propText.toDelta();
+        if (!Array.isArray(delta))
+            return null;
+        for (const d of delta) {
+            if (d.attributes?.reference?.type === "LinkedPage" && d.attributes.reference.pageId) {
+                return d.attributes.reference.pageId;
+            }
+        }
+        return null;
+    }
     function asText(value) {
         if (value instanceof Y.Text)
             return value.toString();
@@ -1690,7 +1719,7 @@ export function registerDocTools(server, gql, defaults) {
         const rowsValue = block.get("prop:rows");
         const columnsValue = block.get("prop:columns");
         const cellsValue = block.get("prop:cells");
-        const rowEntries = mapEntries(rowsValue)
+        let rowEntries = mapEntries(rowsValue)
             .map(([rowId, payload]) => ({
             rowId,
             order: payload && typeof payload === "object" && typeof payload.order === "string"
@@ -1698,7 +1727,7 @@ export function registerDocTools(server, gql, defaults) {
                 : rowId,
         }))
             .sort((a, b) => a.order.localeCompare(b.order));
-        const columnEntries = mapEntries(columnsValue)
+        let columnEntries = mapEntries(columnsValue)
             .map(([columnId, payload]) => ({
             columnId,
             order: payload && typeof payload === "object" && typeof payload.order === "string"
@@ -1706,19 +1735,56 @@ export function registerDocTools(server, gql, defaults) {
                 : columnId,
         }))
             .sort((a, b) => a.order.localeCompare(b.order));
+        let cells = new Map();
         if (rowEntries.length === 0 || columnEntries.length === 0) {
-            return null;
-        }
-        const cells = new Map();
-        for (const [cellKey, payload] of mapEntries(cellsValue)) {
-            if (payload instanceof Y.Map) {
-                cells.set(cellKey, richTextValueToString(payload.get("text")));
-                continue;
+            // Fallback: AFFiNE self-hosted stores table props as flat dot-notation keys
+            // directly on the block Y.Map instead of nested Y.Maps:
+            //   prop:rows.{rowId}.order
+            //   prop:columns.{colId}.order
+            //   prop:cells.{rowId}:{colId}.text  (Y.Text)
+            const flatRows = new Map(); // rowId -> order
+            const flatColumns = new Map(); // colId -> order
+            const flatCells = new Map(); // rowId:colId -> text
+            block.forEach((value, key) => {
+                const rowMatch = key.match(/^prop:rows\.([^.]+)\.order$/);
+                if (rowMatch) {
+                    flatRows.set(rowMatch[1], typeof value === "string" ? value : rowMatch[1]);
+                    return;
+                }
+                const colMatch = key.match(/^prop:columns\.([^.]+)\.order$/);
+                if (colMatch) {
+                    flatColumns.set(colMatch[1], typeof value === "string" ? value : colMatch[1]);
+                    return;
+                }
+                const cellMatch = key.match(/^prop:cells\.([^.]+:[^.]+)\.text$/);
+                if (cellMatch) {
+                    flatCells.set(cellMatch[1], richTextValueToString(value));
+                }
+            });
+            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));
+                columnEntries = Array.from(flatColumns.entries())
+                    .map(([columnId, order]) => ({ columnId, order }))
+                    .sort((a, b) => a.order.localeCompare(b.order));
+                cells = flatCells;
             }
-            if (payload && typeof payload === "object" && "text" in payload) {
-                cells.set(cellKey, richTextValueToString(payload.text));
+        }
+        else {
+            for (const [cellKey, payload] of mapEntries(cellsValue)) {
+                if (payload instanceof Y.Map) {
+                    cells.set(cellKey, richTextValueToString(payload.get("text")));
+                    continue;
+                }
+                if (payload && typeof payload === "object" && "text" in payload) {
+                    cells.set(cellKey, richTextValueToString(payload.text));
+                }
             }
         }
+        if (rowEntries.length === 0 || columnEntries.length === 0) {
+            return null;
+        }
         const tableData = [];
         for (const { rowId } of rowEntries) {
             const row = [];
@@ -1986,6 +2052,8 @@ export function registerDocTools(server, gql, defaults) {
         const tagsByDocId = new Map();
         const titlesByDocId = new Map();
         let workspacePageCount = null;
+        let workspacePageIds = null;
+        const deletedDocIds = new Set();
         try {
             const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
             const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
@@ -1999,6 +2067,7 @@ export function registerDocTools(server, gql, defaults) {
                     const meta = wsDoc.getMap("meta");
                     const pages = getWorkspacePageEntries(meta);
                     workspacePageCount = pages.length;
+                    workspacePageIds = new Set(pages.map(page => page.id));
                     const { byId } = getWorkspaceTagOptionMaps(meta);
                     for (const page of pages) {
                         if (page.title) {
@@ -2008,6 +2077,20 @@ export function registerDocTools(server, gql, defaults) {
                         tagsByDocId.set(page.id, resolveTagLabels(tagEntries, byId));
                     }
                 }
+                const graphEdges = Array.isArray(docs?.edges) ? docs.edges : [];
+                if (workspacePageIds && graphEdges.length > workspacePageIds.size) {
+                    for (const edge of graphEdges) {
+                        const nodeId = edge?.node?.id;
+                        if (typeof nodeId !== "string" || workspacePageIds.has(nodeId)) {
+                            continue;
+                        }
+                        const edgeSnapshot = await loadDoc(socket, workspaceId, nodeId);
+                        const edgeExists = Boolean(edgeSnapshot.missing || edgeSnapshot.state || edgeSnapshot.timestamp);
+                        if (!edgeExists) {
+                            deletedDocIds.add(nodeId);
+                        }
+                    }
+                }
             }
             finally {
                 socket.disconnect();
@@ -2032,19 +2115,22 @@ export function registerDocTools(server, gql, defaults) {
                 };
             })
             : [];
-        // The workspace snapshot reflects deletions before GraphQL count metadata catches up.
-        // Clamp downward only so create/index lag does not inflate counts from partial snapshot state.
+        const visibleEdges = deletedDocIds.size > 0
+            ? mergedEdges.filter((edge) => !deletedDocIds.has(edge?.node?.id))
+            : mergedEdges;
         const correctedTotalCount = typeof docs?.totalCount === "number" &&
             typeof workspacePageCount === "number" &&
+            (deletedDocIds.size > 0 ||
+                visibleEdges.length === workspacePageCount) &&
             workspacePageCount < docs.totalCount
             ? workspacePageCount
             : docs?.totalCount;
         const correctedPageInfo = docs?.pageInfo
             ? {
                 ...docs.pageInfo,
-                endCursor: mergedEdges.length > 0 ? mergedEdges[mergedEdges.length - 1]?.cursor ?? null : null,
+                endCursor: visibleEdges.length > 0 ? visibleEdges[visibleEdges.length - 1]?.cursor ?? null : null,
                 hasNextPage: typeof correctedTotalCount === "number" && !parsed.after
-                    ? (parsed.offset ?? 0) + mergedEdges.length < correctedTotalCount
+                    ? (parsed.offset ?? 0) + visibleEdges.length < correctedTotalCount
                     : docs.pageInfo.hasNextPage,
             }
             : docs?.pageInfo;
@@ -2052,7 +2138,7 @@ export function registerDocTools(server, gql, defaults) {
             ...docs,
             totalCount: correctedTotalCount,
             pageInfo: correctedPageInfo,
-            edges: mergedEdges,
+            edges: visibleEdges,
         };
         return text(mergedDocs);
     };
@@ -3957,12 +4043,14 @@ export function registerDocTools(server, gql, defaults) {
         cellsMap.set(rowBlockId, rowCells);
         return rowCells;
     }
-    function getDatabaseRowBlock(blocks, databaseBlockId, rowBlockId) {
+    function getDatabaseRowBlock(blocks, dbBlock, databaseBlockId, rowBlockId) {
         const rowBlock = findBlockById(blocks, rowBlockId);
         if (!rowBlock) {
             throw new Error(`Row block '${rowBlockId}' not found`);
         }
-        if (rowBlock.get("sys:parent") !== databaseBlockId) {
+        const parentId = rowBlock.get("sys:parent");
+        const isDatabaseChild = getDatabaseRowIds(dbBlock).includes(rowBlockId);
+        if (parentId !== databaseBlockId && !isDatabaseChild) {
             throw new Error(`Row block '${rowBlockId}' does not belong to database '${databaseBlockId}'`);
         }
         if (rowBlock.get("sys:flavour") !== "affine:paragraph") {
@@ -4191,8 +4279,13 @@ export function registerDocTools(server, gql, defaults) {
             rowBlock.set("sys:parent", parsed.databaseBlockId);
             rowBlock.set("sys:children", new Y.Array());
             rowBlock.set("prop:type", "text");
-            const titleValue = resolveDatabaseTitleValue(parsed.cells, ctx);
-            rowBlock.set("prop:text", makeText(String(titleValue)));
+            if (parsed.linkedDocId) {
+                rowBlock.set("prop:text", makeLinkedDocText(parsed.linkedDocId));
+            }
+            else {
+                const titleValue = resolveDatabaseTitleValue(parsed.cells, ctx);
+                rowBlock.set("prop:text", makeText(String(titleValue)));
+            }
             ctx.blocks.set(rowBlockId, rowBlock);
             // Add row block to database's children
             const dbChildren = ensureChildrenArray(ctx.dbBlock);
@@ -4216,6 +4309,7 @@ export function registerDocTools(server, gql, defaults) {
                 rowBlockId,
                 databaseBlockId: parsed.databaseBlockId,
                 cellCount: Object.keys(parsed.cells).length,
+                linkedDocId: parsed.linkedDocId || null,
             });
         }
         finally {
@@ -4230,6 +4324,7 @@ export function registerDocTools(server, gql, defaults) {
             docId: DocId.describe("Document ID containing the database"),
             databaseBlockId: z.string().min(1).describe("Block ID of the affine:database block"),
             cells: z.record(z.unknown()).describe("Map of column name (or column ID) to cell value. For select columns, pass the display label (option auto-created if new)."),
+            linkedDocId: z.string().optional().describe("Link this row to an existing doc by ID. The row will open the linked doc in center peek when clicked."),
         },
     }, addDatabaseRowHandler);
     const deleteDatabaseRowHandler = async (parsed) => {
@@ -4238,7 +4333,7 @@ export function registerDocTools(server, gql, defaults) {
             throw new Error("workspaceId is required");
         const ctx = await loadDatabaseDocContext(workspaceId, parsed.docId, parsed.databaseBlockId);
         try {
-            const rowBlock = getDatabaseRowBlock(ctx.blocks, parsed.databaseBlockId, parsed.rowBlockId);
+            const rowBlock = getDatabaseRowBlock(ctx.blocks, ctx.dbBlock, parsed.databaseBlockId, parsed.rowBlockId);
             const descendantBlockIds = collectDescendantBlockIds(ctx.blocks, [parsed.rowBlockId, ...childIdsFrom(rowBlock.get("sys:children"))]);
             const dbChildren = ensureChildrenArray(ctx.dbBlock);
             const rowIndex = indexOfChild(dbChildren, parsed.rowBlockId);
@@ -4292,7 +4387,7 @@ export function registerDocTools(server, gql, defaults) {
                 : ctx.columnDefs;
             const requestedColumnIds = new Set(requestedColumns.map(col => col.id));
             const rows = requestedRows.map(rowBlockId => {
-                const rowBlock = getDatabaseRowBlock(ctx.blocks, parsed.databaseBlockId, rowBlockId);
+                const rowBlock = getDatabaseRowBlock(ctx.blocks, ctx.dbBlock, parsed.databaseBlockId, rowBlockId);
                 const title = readDatabaseRowTitle(rowBlock) || null;
                 const rowCells = ctx.cellsMap.get(rowBlockId);
                 const cells = {};
@@ -4314,6 +4409,7 @@ export function registerDocTools(server, gql, defaults) {
                 return {
                     rowBlockId,
                     title,
+                    linkedDocId: readLinkedDocId(rowBlock),
                     cells,
                 };
             });
@@ -4375,7 +4471,7 @@ export function registerDocTools(server, gql, defaults) {
             throw new Error("workspaceId is required");
         const ctx = await loadDatabaseDocContext(workspaceId, parsed.docId, parsed.databaseBlockId);
         try {
-            const rowBlock = getDatabaseRowBlock(ctx.blocks, parsed.databaseBlockId, parsed.rowBlockId);
+            const rowBlock = getDatabaseRowBlock(ctx.blocks, ctx.dbBlock, parsed.databaseBlockId, parsed.rowBlockId);
             const rowCells = ensureDatabaseRowCells(ctx.cellsMap, parsed.rowBlockId);
             const col = findDatabaseColumn(parsed.column, ctx);
             if (!col) {
@@ -4386,7 +4482,10 @@ export function registerDocTools(server, gql, defaults) {
             else {
                 writeDatabaseCellValue(rowCells, col, parsed.value, parsed.createOption ?? true);
             }
-            if (isTitleAliasKey(parsed.column) || (col && (col.type === "title" || isTitleAliasKey(col.name)))) {
+            if (parsed.linkedDocId) {
+                rowBlock.set("prop:text", makeLinkedDocText(parsed.linkedDocId));
+            }
+            else if (isTitleAliasKey(parsed.column) || (col && (col.type === "title" || isTitleAliasKey(col.name)))) {
                 rowBlock.set("prop:text", makeText(String(parsed.value ?? "")));
             }
             const delta = Y.encodeStateAsUpdate(ctx.doc, ctx.prevSV);
@@ -4413,6 +4512,7 @@ export function registerDocTools(server, gql, defaults) {
             column: z.string().min(1).describe("Column name or ID. Use `title` for the built-in row title."),
             value: z.unknown().describe("New cell value"),
             createOption: z.boolean().optional().describe("For select and multi-select columns, create the option label if it does not exist (default true)"),
+            linkedDocId: z.string().optional().describe("Link this row to an existing doc by ID. Replaces any existing title with a linked doc reference."),
         },
     }, updateDatabaseCellHandler);
     const updateDatabaseRowHandler = async (parsed) => {
@@ -4421,7 +4521,7 @@ export function registerDocTools(server, gql, defaults) {
             throw new Error("workspaceId is required");
         const ctx = await loadDatabaseDocContext(workspaceId, parsed.docId, parsed.databaseBlockId);
         try {
-            const rowBlock = getDatabaseRowBlock(ctx.blocks, parsed.databaseBlockId, parsed.rowBlockId);
+            const rowBlock = getDatabaseRowBlock(ctx.blocks, ctx.dbBlock, parsed.databaseBlockId, parsed.rowBlockId);
             const rowCells = ensureDatabaseRowCells(ctx.cellsMap, parsed.rowBlockId);
             let titleValue = null;
             for (const [key, value] of Object.entries(parsed.cells)) {
@@ -4438,7 +4538,10 @@ export function registerDocTools(server, gql, defaults) {
                     titleValue = String(value ?? "");
                 }
             }
-            if (titleValue !== null) {
+            if (parsed.linkedDocId) {
+                rowBlock.set("prop:text", makeLinkedDocText(parsed.linkedDocId));
+            }
+            else if (titleValue !== null) {
                 rowBlock.set("prop:text", makeText(titleValue));
             }
             const delta = Y.encodeStateAsUpdate(ctx.doc, ctx.prevSV);
@@ -4463,6 +4566,7 @@ export function registerDocTools(server, gql, defaults) {
             rowBlockId: z.string().min(1).describe("Row paragraph block ID"),
             cells: z.record(z.unknown()).describe("Map of column name (or column ID) to new cell value. Use `title` for the built-in row title."),
             createOption: z.boolean().optional().describe("For select and multi-select columns, create the option label if it does not exist (default true)"),
+            linkedDocId: z.string().optional().describe("Link this row to an existing doc by ID. The row will open the linked doc in center peek when clicked."),
         },
     }, updateDatabaseRowHandler);
     // ADD DATABASE COLUMN

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "affine-mcp-server",
-  "version": "1.11.1",
+  "version": "1.12.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,6 +43,7 @@
     "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-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",