affine-mcp-server 1.7.0 → 1.7.2

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.2-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.2: Fixed tag visibility parity in AFFiNE Web/App for MCP-created tags and hardened Docker E2E startup reliability with retry/diagnostics.
 
 ## Features
 
@@ -409,6 +409,18 @@ Workspace visibility
 
 ## Version History
 
+### 1.7.2 (2026‑03‑04)
+- Fixed MCP tag persistence to use AFFiNE canonical tag option IDs so tags are visible in Web/App UI
+- Added backward-compatible tag normalization for legacy string tag entries
+- Added tag visibility regression coverage (`tests/test-tag-visibility.mjs`, `tests/playwright/verify-tag-visibility.pw.ts`)
+- Hardened E2E credential bootstrap with configurable health retries, retry attempts, and Docker diagnostics on failure
+- Verified CI gates (`validate`, `e2e`) for PR #46 and local `npm run ci`
+
+### 1.7.1 (2026‑03‑03)
+- Fixed MCP-created document structure parity with AFFiNE UI (`sys:parent` handling)
+- Fixed callout text rendering parity in AFFiNE UI for MCP-created blocks
+- Added regression assertions for visibility-sensitive document creation paths
+
 ### 1.7.0 (2026‑02‑27)
 - Added Streamable HTTP MCP support on `/mcp` for remote hosting while keeping legacy SSE compatibility paths (`/sse`, `/messages`)
 - Added HTTP deployment controls: `AFFINE_MCP_HTTP_HOST`, `AFFINE_MCP_HTTP_TOKEN`, `AFFINE_MCP_HTTP_ALLOWED_ORIGINS`, `AFFINE_MCP_HTTP_ALLOW_ALL_ORIGINS`

package/dist/tools/docs.js

@@ -118,6 +118,11 @@ export function registerDocTools(server, gql, defaults) {
         }
         return normalized;
     }
+    const TAG_OPTION_COLORS = [
+        "var(--affine-tag-blue)", "var(--affine-tag-green)", "var(--affine-tag-red)",
+        "var(--affine-tag-orange)", "var(--affine-tag-purple)", "var(--affine-tag-yellow)",
+        "var(--affine-tag-teal)", "var(--affine-tag-pink)", "var(--affine-tag-gray)",
+    ];
     function getStringArray(value) {
         if (!(value instanceof Y.Array)) {
             return [];
@@ -146,23 +151,235 @@ export function registerDocTools(server, gql, defaults) {
         target.set(key, next);
         return next;
     }
-    function hasTag(tagValues, tag, ignoreCase) {
-        const normalizedTag = ignoreCase ? tag.toLocaleLowerCase() : tag;
-        return tagValues.some((entry) => (ignoreCase ? entry.toLocaleLowerCase() : entry) === normalizedTag);
+    function getYMap(target, key) {
+        const value = target.get(key);
+        if (!(value instanceof Y.Map)) {
+            return null;
+        }
+        return value;
     }
-    function findTagIndex(tags, tag, ignoreCase) {
-        const normalizedTag = ignoreCase ? tag.toLocaleLowerCase() : tag;
-        let index = -1;
-        tags.forEach((entry, i) => {
-            if (index >= 0 || typeof entry !== "string") {
+    function ensureYMap(target, key) {
+        const current = getYMap(target, key);
+        if (current) {
+            return current;
+        }
+        const next = new Y.Map();
+        target.set(key, next);
+        return next;
+    }
+    function getWorkspaceTagOptionsArray(meta) {
+        const properties = getYMap(meta, "properties");
+        if (!properties) {
+            return null;
+        }
+        const tags = getYMap(properties, "tags");
+        if (!tags) {
+            return null;
+        }
+        const options = tags.get("options");
+        if (!(options instanceof Y.Array)) {
+            return null;
+        }
+        return options;
+    }
+    function ensureWorkspaceTagOptionsArray(meta) {
+        const properties = ensureYMap(meta, "properties");
+        const tags = ensureYMap(properties, "tags");
+        const existing = tags.get("options");
+        if (existing instanceof Y.Array) {
+            return existing;
+        }
+        const next = new Y.Array();
+        tags.set("options", next);
+        return next;
+    }
+    function asNumberOrNull(value) {
+        return typeof value === "number" ? value : null;
+    }
+    function parseWorkspaceTagOption(raw) {
+        let id;
+        let value;
+        let color;
+        let createDate;
+        let updateDate;
+        if (raw instanceof Y.Map) {
+            id = raw.get("id");
+            value = raw.get("value");
+            color = raw.get("color");
+            createDate = raw.get("createDate");
+            updateDate = raw.get("updateDate");
+        }
+        else if (raw && typeof raw === "object") {
+            id = raw.id;
+            value = raw.value;
+            color = raw.color;
+            createDate = raw.createDate;
+            updateDate = raw.updateDate;
+        }
+        else {
+            return null;
+        }
+        if (typeof id !== "string" || id.trim().length === 0) {
+            return null;
+        }
+        if (typeof value !== "string" || value.trim().length === 0) {
+            return null;
+        }
+        return {
+            id,
+            value,
+            color: typeof color === "string" && color.trim().length > 0 ? color : TAG_OPTION_COLORS[0],
+            createDate: asNumberOrNull(createDate),
+            updateDate: asNumberOrNull(updateDate),
+        };
+    }
+    function getWorkspaceTagOptions(meta) {
+        const options = getWorkspaceTagOptionsArray(meta);
+        if (!options) {
+            return [];
+        }
+        const parsed = [];
+        options.forEach((raw) => {
+            const option = parseWorkspaceTagOption(raw);
+            if (option) {
+                parsed.push(option);
+            }
+        });
+        return parsed;
+    }
+    function getWorkspaceTagOptionMaps(meta) {
+        const options = getWorkspaceTagOptions(meta);
+        const byId = new Map();
+        const byValueLower = new Map();
+        for (const option of options) {
+            if (!byId.has(option.id)) {
+                byId.set(option.id, option);
+            }
+            const key = option.value.toLocaleLowerCase();
+            if (!byValueLower.has(key)) {
+                byValueLower.set(key, option);
+            }
+        }
+        return { options, byId, byValueLower };
+    }
+    function resolveTagLabels(tagEntries, byId) {
+        const deduped = new Set();
+        const resolved = [];
+        for (const entry of tagEntries) {
+            const raw = entry.trim();
+            if (!raw) {
+                continue;
+            }
+            const option = byId.get(raw);
+            const label = (option ? option.value : raw).trim();
+            if (!label) {
+                continue;
+            }
+            const dedupeKey = label.toLocaleLowerCase();
+            if (deduped.has(dedupeKey)) {
+                continue;
+            }
+            deduped.add(dedupeKey);
+            resolved.push(label);
+        }
+        return resolved;
+    }
+    function ensureWorkspaceTagOption(meta, tag) {
+        const normalizedTag = normalizeTag(tag);
+        const maps = getWorkspaceTagOptionMaps(meta);
+        const existing = maps.byValueLower.get(normalizedTag.toLocaleLowerCase());
+        if (existing) {
+            return { option: existing, created: false };
+        }
+        const optionsArray = ensureWorkspaceTagOptionsArray(meta);
+        const color = TAG_OPTION_COLORS[maps.options.length % TAG_OPTION_COLORS.length];
+        const now = Date.now();
+        const option = {
+            id: generateId(),
+            value: normalizedTag,
+            color,
+            createDate: now,
+            updateDate: now,
+        };
+        const optionMap = new Y.Map();
+        optionMap.set("id", option.id);
+        optionMap.set("value", option.value);
+        optionMap.set("color", option.color);
+        optionMap.set("createDate", now);
+        optionMap.set("updateDate", now);
+        optionsArray.push([optionMap]);
+        return { option, created: true };
+    }
+    function collectMatchingTagIndexes(tags, requestedTag, option, ignoreCase) {
+        const normalizedRequested = ignoreCase ? requestedTag.toLocaleLowerCase() : requestedTag;
+        const normalizedOptionId = option
+            ? (ignoreCase ? option.id.toLocaleLowerCase() : option.id)
+            : null;
+        const normalizedOptionValue = option
+            ? (ignoreCase ? option.value.toLocaleLowerCase() : option.value)
+            : null;
+        const indexes = [];
+        tags.forEach((entry, index) => {
+            if (typeof entry !== "string") {
                 return;
             }
             const current = ignoreCase ? entry.toLocaleLowerCase() : entry;
-            if (current === normalizedTag) {
-                index = i;
+            if (current === normalizedRequested ||
+                (normalizedOptionId && current === normalizedOptionId) ||
+                (normalizedOptionValue && current === normalizedOptionValue)) {
+                indexes.push(index);
             }
         });
-        return index;
+        return indexes;
+    }
+    function deleteArrayIndexes(arr, indexes) {
+        if (indexes.length === 0) {
+            return false;
+        }
+        const sorted = [...indexes].sort((a, b) => b - a);
+        for (const index of sorted) {
+            arr.delete(index, 1);
+        }
+        return true;
+    }
+    function syncTagArrayToOption(tags, requestedTag, option) {
+        const optionId = option.id.toLocaleLowerCase();
+        const optionValue = option.value.toLocaleLowerCase();
+        const requested = requestedTag.toLocaleLowerCase();
+        let existed = false;
+        let hasCanonicalId = false;
+        const removeIndexes = [];
+        tags.forEach((entry, index) => {
+            if (typeof entry !== "string") {
+                return;
+            }
+            const current = entry.toLocaleLowerCase();
+            const matched = current === optionId || current === optionValue || current === requested;
+            if (!matched) {
+                return;
+            }
+            existed = true;
+            if (current === optionId) {
+                if (hasCanonicalId) {
+                    removeIndexes.push(index);
+                }
+                else {
+                    hasCanonicalId = true;
+                }
+                return;
+            }
+            removeIndexes.push(index);
+        });
+        let changed = deleteArrayIndexes(tags, removeIndexes);
+        if (!hasCanonicalId) {
+            tags.push([option.id]);
+            changed = true;
+        }
+        return { existed, changed };
+    }
+    function hasTag(tagValues, tag, ignoreCase) {
+        const normalizedTag = ignoreCase ? tag.toLocaleLowerCase() : tag;
+        return tagValues.some((entry) => (ignoreCase ? entry.toLocaleLowerCase() : entry) === normalizedTag);
     }
     function getWorkspacePageEntries(meta) {
         const pages = meta.get("pages");
@@ -219,7 +436,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 +468,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 +818,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 +853,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 +865,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 +929,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 +952,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 +961,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 +972,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 +1012,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 +1047,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 +1065,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 +1080,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 +1098,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 +1118,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 +1142,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 +1157,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 +1174,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 +1188,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 +1204,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 +1221,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 +1238,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 +1263,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 +1285,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 +1295,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 +1308,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 +1326,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 +1365,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]);
             }
@@ -1330,9 +1590,9 @@ export function registerDocTools(server, gql, defaults) {
         }
         return tableData;
     }
-    function collectDocForMarkdown(doc) {
+    function collectDocForMarkdown(doc, tagOptionsById = new Map()) {
         const meta = doc.getMap("meta");
-        const tags = getStringArray(getTagArray(meta));
+        const tags = resolveTagLabels(getStringArray(getTagArray(meta)), tagOptionsById);
         const blocks = doc.getMap("blocks");
         const pageId = findBlockIdByFlavour(blocks, "affine:page");
         const noteId = findBlockIdByFlavour(blocks, "affine:note");
@@ -1444,8 +1704,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 +1764,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 +1775,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 +1792,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();
@@ -1592,8 +1857,10 @@ export function registerDocTools(server, gql, defaults) {
                     Y.applyUpdate(wsDoc, Buffer.from(snapshot.missing, "base64"));
                     const meta = wsDoc.getMap("meta");
                     const pages = getWorkspacePageEntries(meta);
+                    const { byId } = getWorkspaceTagOptionMaps(meta);
                     for (const page of pages) {
-                        tagsByDocId.set(page.id, getStringArray(page.tagsArray));
+                        const tagEntries = getStringArray(page.tagsArray);
+                        tagsByDocId.set(page.id, resolveTagLabels(tagEntries, byId));
                     }
                 }
             }
@@ -1652,9 +1919,10 @@ export function registerDocTools(server, gql, defaults) {
             Y.applyUpdate(wsDoc, Buffer.from(snapshot.missing, "base64"));
             const meta = wsDoc.getMap("meta");
             const pages = getWorkspacePageEntries(meta);
+            const { options, byId } = getWorkspaceTagOptionMaps(meta);
             const tagCounts = new Map();
-            for (const tag of getStringArray(getTagArray(meta))) {
-                const normalized = tag.trim();
+            for (const option of options) {
+                const normalized = option.value.trim();
                 if (!normalized || tagCounts.has(normalized)) {
                     continue;
                 }
@@ -1662,7 +1930,8 @@ export function registerDocTools(server, gql, defaults) {
             }
             for (const page of pages) {
                 const uniqueTags = new Set();
-                for (const tag of getStringArray(page.tagsArray)) {
+                const resolved = resolveTagLabels(getStringArray(page.tagsArray), byId);
+                for (const tag of resolved) {
                     const normalized = tag.trim();
                     if (!normalized) {
                         continue;
@@ -1713,18 +1982,22 @@ export function registerDocTools(server, gql, defaults) {
             Y.applyUpdate(wsDoc, Buffer.from(snapshot.missing, "base64"));
             const meta = wsDoc.getMap("meta");
             const pages = getWorkspacePageEntries(meta);
+            const { byId } = getWorkspaceTagOptionMaps(meta);
             const docs = pages
                 .map((page) => {
-                const tags = getStringArray(page.tagsArray);
+                const rawTags = getStringArray(page.tagsArray);
+                const tags = resolveTagLabels(rawTags, byId);
                 return {
                     id: page.id,
                     title: page.title,
                     createDate: page.createDate,
                     updatedDate: page.updatedDate,
                     tags,
+                    rawTags,
                 };
             })
-                .filter((page) => hasTag(page.tags, tag, ignoreCase));
+                .filter((page) => hasTag(page.tags, tag, ignoreCase) || hasTag(page.rawTags, tag, ignoreCase))
+                .map(({ rawTags: _rawTags, ...page }) => page);
             return text({
                 workspaceId,
                 tag,
@@ -1765,11 +2038,10 @@ export function registerDocTools(server, gql, defaults) {
             Y.applyUpdate(wsDoc, Buffer.from(snapshot.missing, "base64"));
             const prevSV = Y.encodeStateVector(wsDoc);
             const meta = wsDoc.getMap("meta");
-            const registry = ensureTagArray(meta);
-            if (findTagIndex(registry, tag, true) >= 0) {
+            const { created } = ensureWorkspaceTagOption(meta, tag);
+            if (!created) {
                 return text({ workspaceId, tag, created: false });
             }
-            registry.push([tag]);
             const delta = Y.encodeStateAsUpdate(wsDoc, prevSV);
             await pushDocUpdate(socket, workspaceId, workspaceId, Buffer.from(delta).toString("base64"));
             return text({ workspaceId, tag, created: true });
@@ -1809,17 +2081,11 @@ export function registerDocTools(server, gql, defaults) {
             if (!page) {
                 throw new Error(`docId ${parsed.docId} is not present in workspace ${workspaceId}`);
             }
+            const { option, created: optionCreated } = ensureWorkspaceTagOption(wsMeta, tag);
             const pageTags = ensureTagArray(page.entry);
-            const existedInDoc = findTagIndex(pageTags, tag, true) >= 0;
-            if (!existedInDoc) {
-                pageTags.push([tag]);
-            }
-            const registry = ensureTagArray(wsMeta);
-            const existedInRegistry = findTagIndex(registry, tag, true) >= 0;
-            if (!existedInRegistry) {
-                registry.push([tag]);
-            }
-            if (!existedInDoc || !existedInRegistry) {
+            const pageSync = syncTagArrayToOption(pageTags, tag, option);
+            const wsChanged = optionCreated || pageSync.changed;
+            if (wsChanged) {
                 const wsDelta = Y.encodeStateAsUpdate(wsDoc, wsPrevSV);
                 await pushDocUpdate(socket, workspaceId, workspaceId, Buffer.from(wsDelta).toString("base64"));
             }
@@ -1835,20 +2101,20 @@ export function registerDocTools(server, gql, defaults) {
                 const docPrevSV = Y.encodeStateVector(doc);
                 const docMeta = doc.getMap("meta");
                 const docTags = ensureTagArray(docMeta);
-                const existedInDocMeta = findTagIndex(docTags, tag, true) >= 0;
-                if (!existedInDocMeta) {
-                    docTags.push([tag]);
+                const docSync = syncTagArrayToOption(docTags, tag, option);
+                if (docSync.changed) {
                     const docDelta = Y.encodeStateAsUpdate(doc, docPrevSV);
                     await pushDocUpdate(socket, workspaceId, parsed.docId, Buffer.from(docDelta).toString("base64"));
                 }
                 docMetaSynced = true;
             }
+            const { byId } = getWorkspaceTagOptionMaps(wsMeta);
             return text({
                 workspaceId,
                 docId: parsed.docId,
                 tag,
-                added: !existedInDoc,
-                tags: getStringArray(pageTags),
+                added: !pageSync.existed,
+                tags: resolveTagLabels(getStringArray(pageTags), byId),
                 docMetaSynced,
                 warning,
             });
@@ -1889,10 +2155,11 @@ export function registerDocTools(server, gql, defaults) {
             if (!page) {
                 throw new Error(`docId ${parsed.docId} is not present in workspace ${workspaceId}`);
             }
+            const option = getWorkspaceTagOptionMaps(wsMeta).byValueLower.get(tag.toLocaleLowerCase()) || null;
             const pageTags = ensureTagArray(page.entry);
-            const pageTagIndex = findTagIndex(pageTags, tag, true);
-            if (pageTagIndex >= 0) {
-                pageTags.delete(pageTagIndex, 1);
+            const pageTagIndexes = collectMatchingTagIndexes(pageTags, tag, option, true);
+            const pageRemoved = deleteArrayIndexes(pageTags, pageTagIndexes);
+            if (pageRemoved) {
                 const wsDelta = Y.encodeStateAsUpdate(wsDoc, wsPrevSV);
                 await pushDocUpdate(socket, workspaceId, workspaceId, Buffer.from(wsDelta).toString("base64"));
             }
@@ -1908,20 +2175,20 @@ export function registerDocTools(server, gql, defaults) {
                 const docPrevSV = Y.encodeStateVector(doc);
                 const docMeta = doc.getMap("meta");
                 const docTags = ensureTagArray(docMeta);
-                const docTagIndex = findTagIndex(docTags, tag, true);
-                if (docTagIndex >= 0) {
-                    docTags.delete(docTagIndex, 1);
+                const docTagIndexes = collectMatchingTagIndexes(docTags, tag, option, true);
+                if (deleteArrayIndexes(docTags, docTagIndexes)) {
                     const docDelta = Y.encodeStateAsUpdate(doc, docPrevSV);
                     await pushDocUpdate(socket, workspaceId, parsed.docId, Buffer.from(docDelta).toString("base64"));
                 }
                 docMetaSynced = true;
             }
+            const { byId } = getWorkspaceTagOptionMaps(wsMeta);
             return text({
                 workspaceId,
                 docId: parsed.docId,
                 tag,
-                removed: pageTagIndex >= 0,
-                tags: getStringArray(pageTags),
+                removed: pageRemoved,
+                tags: resolveTagLabels(getStringArray(pageTags), byId),
                 docMetaSynced,
                 warning,
             });
@@ -1966,6 +2233,13 @@ export function registerDocTools(server, gql, defaults) {
         const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
         try {
             await joinWorkspace(socket, workspaceId);
+            let tagOptionsById = new Map();
+            const workspaceSnapshot = await loadDoc(socket, workspaceId, workspaceId);
+            if (workspaceSnapshot.missing) {
+                const workspaceDoc = new Y.Doc();
+                Y.applyUpdate(workspaceDoc, Buffer.from(workspaceSnapshot.missing, "base64"));
+                tagOptionsById = getWorkspaceTagOptionMaps(workspaceDoc.getMap("meta")).byId;
+            }
             const snapshot = await loadDoc(socket, workspaceId, parsed.docId);
             if (!snapshot.missing) {
                 return text({
@@ -1981,7 +2255,7 @@ export function registerDocTools(server, gql, defaults) {
             const doc = new Y.Doc();
             Y.applyUpdate(doc, Buffer.from(snapshot.missing, "base64"));
             const meta = doc.getMap("meta");
-            const tags = getStringArray(getTagArray(meta));
+            const tags = resolveTagLabels(getStringArray(getTagArray(meta)), tagOptionsById);
             const blocks = doc.getMap("blocks");
             const pageId = findBlockIdByFlavour(blocks, "affine:page");
             const noteId = findBlockIdByFlavour(blocks, "affine:note");
@@ -2190,6 +2464,13 @@ export function registerDocTools(server, gql, defaults) {
         const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
         try {
             await joinWorkspace(socket, workspaceId);
+            let tagOptionsById = new Map();
+            const workspaceSnapshot = await loadDoc(socket, workspaceId, workspaceId);
+            if (workspaceSnapshot.missing) {
+                const wsDoc = new Y.Doc();
+                Y.applyUpdate(wsDoc, Buffer.from(workspaceSnapshot.missing, "base64"));
+                tagOptionsById = getWorkspaceTagOptionMaps(wsDoc.getMap("meta")).byId;
+            }
             const snapshot = await loadDoc(socket, workspaceId, parsed.docId);
             if (!snapshot.missing) {
                 return text({
@@ -2208,7 +2489,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             const doc = new Y.Doc();
             Y.applyUpdate(doc, Buffer.from(snapshot.missing, "base64"));
-            const collected = collectDocForMarkdown(doc);
+            const collected = collectDocForMarkdown(doc, tagOptionsById);
             const rendered = renderBlocksToMarkdown({
                 rootBlockIds: collected.rootBlockIds,
                 blocksById: collected.blocksById,

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.2",
   "private": false,
   "type": "module",
   "description": "Model Context Protocol server for AFFiNE - enables AI assistants to interact with AFFiNE workspaces, documents, and collaboration features.",
@@ -38,6 +38,7 @@
     "test:e2e": "bash tests/run-e2e.sh",
     "test:db-create": "node tests/test-database-creation.mjs",
     "test:bearer": "node tests/test-bearer-auth.mjs",
+    "test:tag-visibility": "node tests/test-tag-visibility.mjs",
     "test:playwright": "npx playwright test --config tests/playwright/playwright.config.ts",
     "pack:check": "npm pack --dry-run",
     "ci": "npm run build && npm run test:tool-manifest && npm run pack:check",