affine-mcp-server 1.7.0 → 1.7.1

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.7.0-blue)](https://github.com/dawncr0w/affine-mcp-server/releases)
+[![Version](https://img.shields.io/badge/version-1.7.1-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: 43 focused tools with WebSocket-based document editing
 - Status: Active
  
-> New in v1.7.0: Added remote HTTP MCP support (`/mcp`) with token/CORS controls, while retaining legacy SSE compatibility (`/sse`, `/messages`) for older clients.
+> New in v1.7.1: Fixed MCP-created document structure parity with AFFiNE UI (`sys:parent` handling) and callout text rendering, plus regression coverage for UI visibility paths.
 
 ## Features
 

package/dist/tools/docs.js

@@ -219,7 +219,7 @@ export function registerDocTools(server, gql, defaults) {
         const noteId = generateId();
         const note = new Y.Map();
         setSysFields(note, noteId, "affine:note");
-        note.set("sys:parent", pageId);
+        note.set("sys:parent", null);
         note.set("sys:children", new Y.Array());
         note.set("prop:xywh", "[0,0,800,95]");
         note.set("prop:index", "a0");
@@ -251,7 +251,7 @@ export function registerDocTools(server, gql, defaults) {
         const surfaceId = generateId();
         const surface = new Y.Map();
         setSysFields(surface, surfaceId, "affine:surface");
-        surface.set("sys:parent", pageId);
+        surface.set("sys:parent", null);
         surface.set("sys:children", new Y.Array());
         const elements = new Y.Map();
         elements.set("type", "$blocksuite:internal:native$");
@@ -601,6 +601,30 @@ export function registerDocTools(server, gql, defaults) {
         });
         return index;
     }
+    function findParentIdByChild(blocks, childId) {
+        for (const [id, value] of blocks) {
+            if (!(value instanceof Y.Map)) {
+                continue;
+            }
+            const childIds = childIdsFrom(value.get("sys:children"));
+            if (childIds.includes(childId)) {
+                return String(id);
+            }
+        }
+        return null;
+    }
+    function resolveBlockParentId(blocks, blockId) {
+        const block = findBlockById(blocks, blockId);
+        if (!block) {
+            return null;
+        }
+        const rawParentId = block.get("sys:parent");
+        if (typeof rawParentId === "string" && rawParentId.trim().length > 0) {
+            return rawParentId;
+        }
+        // AFFiNE UI commonly stores sys:parent as null and derives hierarchy from sys:children.
+        return findParentIdByChild(blocks, blockId);
+    }
     function resolveInsertContext(blocks, normalized) {
         const placement = normalized.placement;
         let parentId;
@@ -612,8 +636,8 @@ export function registerDocTools(server, gql, defaults) {
             const referenceBlock = findBlockById(blocks, referenceBlockId);
             if (!referenceBlock)
                 throw new Error(`placement.afterBlockId '${referenceBlockId}' was not found.`);
-            const refParentId = referenceBlock.get("sys:parent");
-            if (typeof refParentId !== "string" || !refParentId) {
+            const refParentId = resolveBlockParentId(blocks, referenceBlockId);
+            if (!refParentId) {
                 throw new Error(`Block '${referenceBlockId}' has no parent.`);
             }
             parentId = refParentId;
@@ -624,8 +648,8 @@ export function registerDocTools(server, gql, defaults) {
             const referenceBlock = findBlockById(blocks, referenceBlockId);
             if (!referenceBlock)
                 throw new Error(`placement.beforeBlockId '${referenceBlockId}' was not found.`);
-            const refParentId = referenceBlock.get("sys:parent");
-            if (typeof refParentId !== "string" || !refParentId) {
+            const refParentId = resolveBlockParentId(blocks, referenceBlockId);
+            if (!refParentId) {
                 throw new Error(`Block '${referenceBlockId}' has no parent.`);
             }
             parentId = refParentId;
@@ -688,16 +712,17 @@ export function registerDocTools(server, gql, defaults) {
         }
         return { parentId, parentBlock, children, insertIndex };
     }
-    function createBlock(parentId, normalized) {
+    function createBlock(normalized) {
         const blockId = generateId();
         const block = new Y.Map();
         const content = normalized.text;
+        // Keep parity with AFFiNE UI-created docs: sys:parent stays null and hierarchy is represented by sys:children.
         switch (normalized.type) {
             case "paragraph":
             case "heading":
             case "quote": {
                 setSysFields(block, blockId, "affine:paragraph");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 const blockType = normalized.type === "heading"
                     ? `h${normalized.headingLevel}`
@@ -710,7 +735,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "list": {
                 setSysFields(block, blockId, "affine:list");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:type", normalized.listStyle);
                 block.set("prop:checked", normalized.listStyle === "todo" ? normalized.checked : false);
@@ -719,7 +744,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "code": {
                 setSysFields(block, blockId, "affine:code");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:language", normalized.language);
                 if (normalized.caption) {
@@ -730,22 +755,35 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "divider": {
                 setSysFields(block, blockId, "affine:divider");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 return { blockId, block, flavour: "affine:divider" };
             }
             case "callout": {
                 setSysFields(block, blockId, "affine:callout");
-                block.set("sys:parent", parentId);
-                block.set("sys:children", new Y.Array());
+                block.set("sys:parent", null);
+                const calloutChildren = new Y.Array();
+                const textBlockId = generateId();
+                const textBlock = new Y.Map();
+                setSysFields(textBlock, textBlockId, "affine:paragraph");
+                textBlock.set("sys:parent", null);
+                textBlock.set("sys:children", new Y.Array());
+                textBlock.set("prop:type", "text");
+                textBlock.set("prop:text", makeText(content));
+                calloutChildren.push([textBlockId]);
+                block.set("sys:children", calloutChildren);
                 block.set("prop:icon", { type: "emoji", unicode: "💡" });
                 block.set("prop:backgroundColorName", "grey");
-                block.set("prop:text", makeText(content));
-                return { blockId, block, flavour: "affine:callout" };
+                return {
+                    blockId,
+                    block,
+                    flavour: "affine:callout",
+                    extraBlocks: [{ blockId: textBlockId, block: textBlock }],
+                };
             }
             case "latex": {
                 setSysFields(block, blockId, "affine:latex");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:xywh", "[0,0,16,16]");
                 block.set("prop:index", "a0");
@@ -757,7 +795,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "table": {
                 setSysFields(block, blockId, "affine:table");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 const rows = {};
                 const columns = {};
@@ -792,7 +830,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "bookmark": {
                 setSysFields(block, blockId, "affine:bookmark");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:style", normalized.bookmarkStyle);
                 block.set("prop:url", normalized.url);
@@ -810,7 +848,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "image": {
                 setSysFields(block, blockId, "affine:image");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:caption", normalized.caption ?? "");
                 block.set("prop:sourceId", normalized.sourceId);
@@ -825,7 +863,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "attachment": {
                 setSysFields(block, blockId, "affine:attachment");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:name", normalized.name);
                 block.set("prop:size", normalized.size);
@@ -843,7 +881,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "embed_youtube": {
                 setSysFields(block, blockId, "affine:embed-youtube");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:index", "a0");
                 block.set("prop:xywh", "[0,0,0,0]");
@@ -863,7 +901,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "embed_github": {
                 setSysFields(block, blockId, "affine:embed-github");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:index", "a0");
                 block.set("prop:xywh", "[0,0,0,0]");
@@ -887,7 +925,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "embed_figma": {
                 setSysFields(block, blockId, "affine:embed-figma");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:index", "a0");
                 block.set("prop:xywh", "[0,0,0,0]");
@@ -902,7 +940,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "embed_loom": {
                 setSysFields(block, blockId, "affine:embed-loom");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:index", "a0");
                 block.set("prop:xywh", "[0,0,0,0]");
@@ -919,7 +957,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "embed_html": {
                 setSysFields(block, blockId, "affine:embed-html");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:index", "a0");
                 block.set("prop:xywh", "[0,0,0,0]");
@@ -933,7 +971,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "embed_linked_doc": {
                 setSysFields(block, blockId, "affine:embed-linked-doc");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:index", "a0");
                 block.set("prop:xywh", "[0,0,0,0]");
@@ -949,7 +987,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "embed_synced_doc": {
                 setSysFields(block, blockId, "affine:embed-synced-doc");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:index", "a0");
                 block.set("prop:xywh", "[0,0,800,100]");
@@ -966,7 +1004,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "embed_iframe": {
                 setSysFields(block, blockId, "affine:embed-iframe");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:index", "a0");
                 block.set("prop:xywh", "[0,0,0,0]");
@@ -983,7 +1021,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "database": {
                 setSysFields(block, blockId, "affine:database");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 // Create a default table view so AFFiNE UI renders the database
                 const defaultView = new Y.Map();
@@ -1008,7 +1046,7 @@ export function registerDocTools(server, gql, defaults) {
                 // AFFiNE 0.26.x currently crashes on raw affine:data-view render path.
                 // Keep API compatibility for type="data_view" by mapping it to the stable database block.
                 setSysFields(block, blockId, "affine:database");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 const dvDefaultView = new Y.Map();
                 dvDefaultView.set("id", generateId());
@@ -1030,7 +1068,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "surface_ref": {
                 setSysFields(block, blockId, "affine:surface-ref");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:reference", normalized.reference);
                 block.set("prop:caption", normalized.caption ?? "");
@@ -1040,7 +1078,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "frame": {
                 setSysFields(block, blockId, "affine:frame");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:title", makeText(content || "Frame"));
                 block.set("prop:background", normalized.background);
@@ -1053,7 +1091,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "edgeless_text": {
                 setSysFields(block, blockId, "affine:edgeless-text");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:xywh", `[0,0,${normalized.width},${normalized.height}]`);
                 block.set("prop:index", "a0");
@@ -1071,7 +1109,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "note": {
                 setSysFields(block, blockId, "affine:note");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:xywh", `[0,0,${normalized.width},${normalized.height}]`);
                 block.set("prop:background", normalized.background);
@@ -1110,8 +1148,13 @@ export function registerDocTools(server, gql, defaults) {
             const prevSV = Y.encodeStateVector(doc);
             const blocks = doc.getMap("blocks");
             const context = resolveInsertContext(blocks, normalized);
-            const { blockId, block, flavour, blockType } = createBlock(context.parentId, normalized);
+            const { blockId, block, flavour, blockType, extraBlocks } = createBlock(normalized);
             blocks.set(blockId, block);
+            if (Array.isArray(extraBlocks)) {
+                for (const extra of extraBlocks) {
+                    blocks.set(extra.blockId, extra.block);
+                }
+            }
             if (context.insertIndex >= context.children.length) {
                 context.children.push([blockId]);
             }
@@ -1444,8 +1487,13 @@ export function registerDocTools(server, gql, defaults) {
                 try {
                     const normalized = normalizeAppendBlockInput(appendInput);
                     const context = resolveInsertContext(blocks, normalized);
-                    const { blockId, block } = createBlock(context.parentId, normalized);
+                    const { blockId, block, extraBlocks } = createBlock(normalized);
                     blocks.set(blockId, block);
+                    if (Array.isArray(extraBlocks)) {
+                        for (const extra of extraBlocks) {
+                            blocks.set(extra.blockId, extra.block);
+                        }
+                    }
                     if (context.insertIndex >= context.children.length) {
                         context.children.push([blockId]);
                     }
@@ -1499,7 +1547,7 @@ export function registerDocTools(server, gql, defaults) {
             const surfaceId = generateId();
             const surface = new Y.Map();
             setSysFields(surface, surfaceId, "affine:surface");
-            surface.set("sys:parent", pageId);
+            surface.set("sys:parent", null);
             surface.set("sys:children", new Y.Array());
             const elements = new Y.Map();
             elements.set("type", "$blocksuite:internal:native$");
@@ -1510,7 +1558,7 @@ export function registerDocTools(server, gql, defaults) {
             const noteId = generateId();
             const note = new Y.Map();
             setSysFields(note, noteId, "affine:note");
-            note.set("sys:parent", pageId);
+            note.set("sys:parent", null);
             note.set("prop:displayMode", "both");
             note.set("prop:xywh", "[0,0,800,95]");
             note.set("prop:index", "a0");
@@ -1527,7 +1575,7 @@ export function registerDocTools(server, gql, defaults) {
                 const paraId = generateId();
                 const para = new Y.Map();
                 setSysFields(para, paraId, "affine:paragraph");
-                para.set("sys:parent", noteId);
+                para.set("sys:parent", null);
                 para.set("sys:children", new Y.Array());
                 para.set("prop:type", "text");
                 const paragraphText = new Y.Text();

package/dist/tools/workspaces.js

@@ -58,7 +58,7 @@ function createInitialWorkspaceData(workspaceName = 'New Workspace', avatar = ''
     const surfaceBlock = new Y.Map();
     surfaceBlock.set('sys:id', surfaceId);
     surfaceBlock.set('sys:flavour', 'affine:surface');
-    surfaceBlock.set('sys:parent', pageId);
+    surfaceBlock.set('sys:parent', null);
     surfaceBlock.set('sys:children', new Y.Array());
     blocks.set(surfaceId, surfaceBlock);
     pageChildren.push([surfaceId]);
@@ -67,7 +67,7 @@ function createInitialWorkspaceData(workspaceName = 'New Workspace', avatar = ''
     const noteBlock = new Y.Map();
     noteBlock.set('sys:id', noteId);
     noteBlock.set('sys:flavour', 'affine:note');
-    noteBlock.set('sys:parent', pageId);
+    noteBlock.set('sys:parent', null);
     noteBlock.set('prop:displayMode', 'DocAndEdgeless');
     noteBlock.set('prop:xywh', '[0,0,800,600]');
     noteBlock.set('prop:index', 'a0');
@@ -81,7 +81,7 @@ function createInitialWorkspaceData(workspaceName = 'New Workspace', avatar = ''
     const paragraphBlock = new Y.Map();
     paragraphBlock.set('sys:id', paragraphId);
     paragraphBlock.set('sys:flavour', 'affine:paragraph');
-    paragraphBlock.set('sys:parent', noteId);
+    paragraphBlock.set('sys:parent', null);
     paragraphBlock.set('sys:children', new Y.Array());
     paragraphBlock.set('prop:type', 'text');
     const paragraphText = new Y.Text();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "affine-mcp-server",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "private": false,
   "type": "module",
   "description": "Model Context Protocol server for AFFiNE - enables AI assistants to interact with AFFiNE workspaces, documents, and collaboration features.",