affine-mcp-server 1.4.0 → 1.5.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.
 
-[![Version](https://img.shields.io/badge/version-1.4.0-blue)](https://github.com/dawncr0w/affine-mcp-server/releases)
+[![Version](https://img.shields.io/badge/version-1.5.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: 32 focused tools with WebSocket-based document editing
 - Status: Active
  
-> New in v1.4.0: Added `read_doc` for document content snapshots (blocks + plain text), plus Cursor setup/troubleshooting guidance.
+> New in v1.5.0: `append_block` now supports 30 verified block profiles, including database/edgeless (`frame`, `edgeless_text`, `surface_ref`, `note`) insertion paths. For stability on AFFiNE 0.26.x, `type=\"data_view\"` is currently mapped to a database block.
 
 ## Features
 
@@ -166,7 +166,7 @@ If you prefer `npx`:
 - `revoke_doc` – revoke public access
 - `create_doc` – create a new document (WebSocket)
 - `append_paragraph` – append a paragraph block (WebSocket)
-- `append_block` – append slash-command style blocks (`heading/list/todo/code/divider/quote`)
+- `append_block` – append canonical block types (text/list/code/media/embed/database/edgeless) with strict validation and placement control (`data_view` currently falls back to database)
 - `delete_doc` – delete a document (WebSocket)
 
 ### Comments
@@ -243,6 +243,11 @@ Workspace visibility
 
 ## Version History
 
+### 1.5.0 (2026‑02‑13)
+- Expanded `append_block` from Step1 to Step4 profiles: canonical text/list/code/divider/callout/latex/table/bookmark/media/embed plus `database`, `data_view`, `surface_ref`, `frame`, `edgeless_text`, `note` (`data_view` currently mapped to database for stability)
+- Added strict field validation and canonical parent enforcement for page/note/surface containers
+- Added local integration runner coverage for all 30 append_block cases against a live AFFINE server
+
 ### 1.4.0 (2026‑02‑13)
 - Added `read_doc` for reading document block snapshot + plain text
 - Added Cursor setup examples and troubleshooting notes for JSON-RPC method usage

package/dist/index.js

@@ -15,7 +15,7 @@ import { loginWithPassword } from "./auth.js";
 import { registerAuthTools } from "./tools/auth.js";
 const config = loadConfig();
 async function buildServer() {
-    const server = new McpServer({ name: "affine-mcp", version: "1.4.0" });
+    const server = new McpServer({ name: "affine-mcp", version: "1.5.0" });
     // Initialize GraphQL client with authentication
     const gql = new GraphQLClient({
         endpoint: `${config.baseUrl}${config.graphqlPath}`,

package/dist/tools/docs.js

@@ -4,19 +4,52 @@ import { wsUrlFromGraphQLEndpoint, connectWorkspaceSocket, joinWorkspace, loadDo
 import * as Y from "yjs";
 const WorkspaceId = z.string().min(1, "workspaceId required");
 const DocId = z.string().min(1, "docId required");
-const APPEND_BLOCK_TYPE_VALUES = [
+const APPEND_BLOCK_CANONICAL_TYPE_VALUES = [
     "paragraph",
-    "heading1",
-    "heading2",
-    "heading3",
+    "heading",
     "quote",
-    "bulleted_list",
-    "numbered_list",
-    "todo",
+    "list",
     "code",
     "divider",
+    "callout",
+    "latex",
+    "table",
+    "bookmark",
+    "image",
+    "attachment",
+    "embed_youtube",
+    "embed_github",
+    "embed_figma",
+    "embed_loom",
+    "embed_html",
+    "embed_linked_doc",
+    "embed_synced_doc",
+    "embed_iframe",
+    "database",
+    "data_view",
+    "surface_ref",
+    "frame",
+    "edgeless_text",
+    "note",
 ];
-const AppendBlockType = z.enum(APPEND_BLOCK_TYPE_VALUES);
+const APPEND_BLOCK_LEGACY_ALIAS_MAP = {
+    heading1: "heading",
+    heading2: "heading",
+    heading3: "heading",
+    bulleted_list: "list",
+    numbered_list: "list",
+    todo: "list",
+};
+const APPEND_BLOCK_LIST_STYLE_VALUES = ["bulleted", "numbered", "todo"];
+const AppendBlockListStyle = z.enum(APPEND_BLOCK_LIST_STYLE_VALUES);
+const APPEND_BLOCK_BOOKMARK_STYLE_VALUES = [
+    "vertical",
+    "horizontal",
+    "list",
+    "cube",
+    "citation",
+];
+const AppendBlockBookmarkStyle = z.enum(APPEND_BLOCK_BOOKMARK_STYLE_VALUES);
 function blockVersion(flavour) {
     switch (flavour) {
         case "affine:page":
@@ -121,71 +154,816 @@ export function registerDocTools(server, gql, defaults) {
         pageChildren.push([noteId]);
         return noteId;
     }
-    function createBlock(noteId, parsed) {
+    function ensureSurfaceBlock(blocks) {
+        const existingSurfaceId = findBlockIdByFlavour(blocks, "affine:surface");
+        if (existingSurfaceId) {
+            return existingSurfaceId;
+        }
+        const pageId = findBlockIdByFlavour(blocks, "affine:page");
+        if (!pageId) {
+            throw new Error("Document has no page block; unable to create/find surface.");
+        }
+        const surfaceId = generateId();
+        const surface = new Y.Map();
+        setSysFields(surface, surfaceId, "affine:surface");
+        surface.set("sys:parent", pageId);
+        surface.set("sys:children", new Y.Array());
+        const elements = new Y.Map();
+        elements.set("type", "$blocksuite:internal:native$");
+        elements.set("value", new Y.Map());
+        surface.set("prop:elements", elements);
+        blocks.set(surfaceId, surface);
+        const page = blocks.get(pageId);
+        let pageChildren = page.get("sys:children");
+        if (!(pageChildren instanceof Y.Array)) {
+            pageChildren = new Y.Array();
+            page.set("sys:children", pageChildren);
+        }
+        pageChildren.push([surfaceId]);
+        return surfaceId;
+    }
+    function normalizeBlockTypeInput(typeInput) {
+        const key = typeInput.trim().toLowerCase();
+        if (APPEND_BLOCK_CANONICAL_TYPE_VALUES.includes(key)) {
+            return { type: key };
+        }
+        if (Object.prototype.hasOwnProperty.call(APPEND_BLOCK_LEGACY_ALIAS_MAP, key)) {
+            const legacyType = key;
+            const type = APPEND_BLOCK_LEGACY_ALIAS_MAP[legacyType];
+            const listStyleFromAlias = legacyType === "bulleted_list"
+                ? "bulleted"
+                : legacyType === "numbered_list"
+                    ? "numbered"
+                    : legacyType === "todo"
+                        ? "todo"
+                        : undefined;
+            const headingLevelFromAlias = legacyType === "heading1"
+                ? 1
+                : legacyType === "heading2"
+                    ? 2
+                    : legacyType === "heading3"
+                        ? 3
+                        : undefined;
+            return { type, legacyType, headingLevelFromAlias, listStyleFromAlias };
+        }
+        const supported = [
+            ...APPEND_BLOCK_CANONICAL_TYPE_VALUES,
+            ...Object.keys(APPEND_BLOCK_LEGACY_ALIAS_MAP),
+        ].join(", ");
+        throw new Error(`Unsupported append_block type '${typeInput}'. Supported types: ${supported}`);
+    }
+    function normalizePlacement(placement) {
+        if (!placement)
+            return undefined;
+        const normalized = {};
+        if (placement.parentId?.trim())
+            normalized.parentId = placement.parentId.trim();
+        if (placement.afterBlockId?.trim())
+            normalized.afterBlockId = placement.afterBlockId.trim();
+        if (placement.beforeBlockId?.trim())
+            normalized.beforeBlockId = placement.beforeBlockId.trim();
+        if (placement.index !== undefined)
+            normalized.index = placement.index;
+        const hasAfter = Boolean(normalized.afterBlockId);
+        const hasBefore = Boolean(normalized.beforeBlockId);
+        if (hasAfter && hasBefore) {
+            throw new Error("placement.afterBlockId and placement.beforeBlockId are mutually exclusive.");
+        }
+        if (normalized.index !== undefined) {
+            if (!Number.isInteger(normalized.index) || normalized.index < 0) {
+                throw new Error("placement.index must be an integer greater than or equal to 0.");
+            }
+            if (hasAfter || hasBefore) {
+                throw new Error("placement.index cannot be used with placement.afterBlockId/beforeBlockId.");
+            }
+        }
+        if (!normalized.parentId && !normalized.afterBlockId && !normalized.beforeBlockId && normalized.index === undefined) {
+            return undefined;
+        }
+        return normalized;
+    }
+    function validateNormalizedAppendBlockInput(normalized, raw) {
+        if (normalized.type === "heading") {
+            if (!Number.isInteger(normalized.headingLevel) || normalized.headingLevel < 1 || normalized.headingLevel > 6) {
+                throw new Error("Heading level must be an integer from 1 to 6.");
+            }
+        }
+        else if (raw.level !== undefined && normalized.strict) {
+            throw new Error("The 'level' field can only be used with type='heading'.");
+        }
+        if (normalized.type === "list") {
+            if (!APPEND_BLOCK_LIST_STYLE_VALUES.includes(normalized.listStyle)) {
+                throw new Error(`Invalid list style '${normalized.listStyle}'.`);
+            }
+            if (normalized.listStyle !== "todo" && raw.checked !== undefined && normalized.strict) {
+                throw new Error("The 'checked' field can only be used when list style is 'todo'.");
+            }
+        }
+        else {
+            if (raw.style !== undefined && normalized.strict) {
+                throw new Error("The 'style' field can only be used with type='list'.");
+            }
+            if (raw.checked !== undefined && normalized.strict) {
+                throw new Error("The 'checked' field can only be used with type='list' (style='todo').");
+            }
+        }
+        if (normalized.type !== "code") {
+            if (raw.language !== undefined && normalized.strict) {
+                throw new Error("The 'language' field can only be used with type='code'.");
+            }
+            const allowsCaption = normalized.type === "bookmark" ||
+                normalized.type === "image" ||
+                normalized.type === "attachment" ||
+                normalized.type === "surface_ref" ||
+                normalized.type.startsWith("embed_");
+            if (raw.caption !== undefined && !allowsCaption && normalized.strict) {
+                throw new Error("The 'caption' field is not valid for this block type.");
+            }
+        }
+        else if (normalized.language.length > 64) {
+            throw new Error("Code language is too long (max 64 chars).");
+        }
+        if (normalized.type === "divider" && raw.text && raw.text.length > 0 && normalized.strict) {
+            throw new Error("Divider blocks do not accept text.");
+        }
+        const requiresUrl = [
+            "bookmark",
+            "embed_youtube",
+            "embed_github",
+            "embed_figma",
+            "embed_loom",
+            "embed_iframe",
+        ];
+        const urlAllowedTypes = [...requiresUrl];
+        if (urlAllowedTypes.includes(normalized.type)) {
+            if (!normalized.url) {
+                throw new Error(`${normalized.type} blocks require a non-empty url.`);
+            }
+            try {
+                new URL(normalized.url);
+            }
+            catch {
+                throw new Error(`Invalid url for ${normalized.type} block: '${normalized.url}'.`);
+            }
+        }
+        if (normalized.type === "bookmark") {
+            if (!APPEND_BLOCK_BOOKMARK_STYLE_VALUES.includes(normalized.bookmarkStyle)) {
+                throw new Error(`Invalid bookmark style '${normalized.bookmarkStyle}'.`);
+            }
+        }
+        else {
+            if (raw.bookmarkStyle !== undefined && normalized.strict) {
+                throw new Error("The 'bookmarkStyle' field can only be used with type='bookmark'.");
+            }
+            if (raw.url !== undefined && !urlAllowedTypes.includes(normalized.type) && normalized.strict) {
+                throw new Error("The 'url' field is not valid for this block type.");
+            }
+        }
+        if (normalized.type === "image" || normalized.type === "attachment") {
+            if (!normalized.sourceId) {
+                throw new Error(`${normalized.type} blocks require sourceId (use upload_blob first).`);
+            }
+            if (normalized.type === "attachment" && (!normalized.name || !normalized.mimeType)) {
+                throw new Error("attachment blocks require valid name and mimeType.");
+            }
+        }
+        else if (raw.sourceId !== undefined && normalized.strict) {
+            throw new Error("The 'sourceId' field can only be used with type='image' or type='attachment'.");
+        }
+        else if ((raw.name !== undefined || raw.mimeType !== undefined || raw.embed !== undefined || raw.size !== undefined) &&
+            normalized.strict) {
+            throw new Error("The 'name'/'mimeType'/'embed'/'size' fields are only valid for image/attachment blocks.");
+        }
+        if (normalized.type === "latex") {
+            if (!normalized.latex && normalized.strict) {
+                throw new Error("latex blocks require a non-empty 'latex' value in strict mode.");
+            }
+        }
+        else if (raw.latex !== undefined && normalized.strict) {
+            throw new Error("The 'latex' field can only be used with type='latex'.");
+        }
+        if (normalized.type === "embed_linked_doc" || normalized.type === "embed_synced_doc") {
+            if (!normalized.pageId) {
+                throw new Error(`${normalized.type} blocks require pageId.`);
+            }
+        }
+        else if (raw.pageId !== undefined && normalized.strict) {
+            throw new Error("The 'pageId' field can only be used with linked/synced doc embed types.");
+        }
+        if (normalized.type === "embed_html") {
+            if (!normalized.html && !normalized.design && normalized.strict) {
+                throw new Error("embed_html blocks require html or design.");
+            }
+        }
+        else if ((raw.html !== undefined || raw.design !== undefined) && normalized.strict) {
+            throw new Error("The 'html'/'design' fields can only be used with type='embed_html'.");
+        }
+        if (normalized.type === "embed_iframe") {
+            if (raw.iframeUrl !== undefined && !normalized.iframeUrl && normalized.strict) {
+                throw new Error("embed_iframe iframeUrl cannot be empty when provided.");
+            }
+        }
+        else if (raw.iframeUrl !== undefined && normalized.strict) {
+            throw new Error("The 'iframeUrl' field can only be used with type='embed_iframe'.");
+        }
+        if (normalized.type === "surface_ref") {
+            if (!normalized.reference) {
+                throw new Error("surface_ref blocks require 'reference' (target element/block id).");
+            }
+            if (!normalized.refFlavour) {
+                throw new Error("surface_ref blocks require 'refFlavour' (for example affine:frame).");
+            }
+        }
+        else if ((raw.reference !== undefined || raw.refFlavour !== undefined) && normalized.strict) {
+            throw new Error("The 'reference'/'refFlavour' fields can only be used with type='surface_ref'.");
+        }
+        if (normalized.type === "frame" || normalized.type === "edgeless_text" || normalized.type === "note") {
+            if (!Number.isInteger(normalized.width) || normalized.width < 1 || normalized.width > 10000) {
+                throw new Error(`${normalized.type} width must be an integer between 1 and 10000.`);
+            }
+            if (!Number.isInteger(normalized.height) || normalized.height < 1 || normalized.height > 10000) {
+                throw new Error(`${normalized.type} height must be an integer between 1 and 10000.`);
+            }
+        }
+        else if ((raw.width !== undefined || raw.height !== undefined) && normalized.strict) {
+            throw new Error("The 'width'/'height' fields are only valid for frame/edgeless_text/note.");
+        }
+        if (normalized.type !== "frame" && normalized.type !== "note" && raw.background !== undefined && normalized.strict) {
+            throw new Error("The 'background' field is only valid for frame/note.");
+        }
+        if (normalized.type === "table") {
+            if (!Number.isInteger(normalized.rows) || normalized.rows < 1 || normalized.rows > 20) {
+                throw new Error("table rows must be an integer between 1 and 20.");
+            }
+            if (!Number.isInteger(normalized.columns) || normalized.columns < 1 || normalized.columns > 20) {
+                throw new Error("table columns must be an integer between 1 and 20.");
+            }
+        }
+        else if ((raw.rows !== undefined || raw.columns !== undefined) && normalized.strict) {
+            throw new Error("The 'rows'/'columns' fields can only be used with type='table'.");
+        }
+    }
+    function normalizeAppendBlockInput(parsed) {
+        const strict = parsed.strict !== false;
+        const typeInfo = normalizeBlockTypeInput(parsed.type);
+        const headingLevelCandidate = parsed.level ?? typeInfo.headingLevelFromAlias ?? 1;
+        const headingLevelNumber = Number(headingLevelCandidate);
+        const headingLevel = Math.max(1, Math.min(6, headingLevelNumber));
+        const listStyle = typeInfo.listStyleFromAlias ?? parsed.style ?? "bulleted";
+        const bookmarkStyle = parsed.bookmarkStyle ?? "horizontal";
+        const language = (parsed.language ?? "txt").trim().toLowerCase() || "txt";
+        const placement = normalizePlacement(parsed.placement);
+        const url = (parsed.url ?? "").trim();
+        const pageId = (parsed.pageId ?? "").trim();
+        const iframeUrl = (parsed.iframeUrl ?? "").trim();
+        const html = parsed.html ?? "";
+        const design = parsed.design ?? "";
+        const reference = (parsed.reference ?? "").trim();
+        const refFlavour = (parsed.refFlavour ?? "").trim();
+        const width = Number.isFinite(parsed.width) ? Math.max(1, Math.floor(parsed.width)) : 100;
+        const height = Number.isFinite(parsed.height) ? Math.max(1, Math.floor(parsed.height)) : 100;
+        const background = (parsed.background ?? "transparent").trim() || "transparent";
+        const sourceId = (parsed.sourceId ?? "").trim();
+        const name = (parsed.name ?? "attachment").trim() || "attachment";
+        const mimeType = (parsed.mimeType ?? "application/octet-stream").trim() || "application/octet-stream";
+        const size = Number.isFinite(parsed.size) ? Math.max(0, Math.floor(parsed.size)) : 0;
+        const rows = Number.isInteger(parsed.rows) ? parsed.rows : 3;
+        const columns = Number.isInteger(parsed.columns) ? parsed.columns : 3;
+        const latex = (parsed.latex ?? "").trim();
+        const normalized = {
+            workspaceId: parsed.workspaceId,
+            docId: parsed.docId,
+            type: typeInfo.type,
+            strict,
+            placement,
+            text: parsed.text ?? "",
+            url,
+            pageId,
+            iframeUrl,
+            html,
+            design,
+            reference,
+            refFlavour,
+            width,
+            height,
+            background,
+            sourceId,
+            name,
+            mimeType,
+            size,
+            embed: Boolean(parsed.embed),
+            rows,
+            columns,
+            latex,
+            headingLevel,
+            listStyle,
+            bookmarkStyle,
+            checked: Boolean(parsed.checked),
+            language,
+            caption: parsed.caption,
+            legacyType: typeInfo.legacyType,
+        };
+        validateNormalizedAppendBlockInput(normalized, parsed);
+        return normalized;
+    }
+    function findBlockById(blocks, blockId) {
+        const value = blocks.get(blockId);
+        if (value instanceof Y.Map)
+            return value;
+        return null;
+    }
+    function ensureChildrenArray(block) {
+        const current = block.get("sys:children");
+        if (current instanceof Y.Array)
+            return current;
+        const created = new Y.Array();
+        block.set("sys:children", created);
+        return created;
+    }
+    function indexOfChild(children, blockId) {
+        let index = -1;
+        children.forEach((entry, i) => {
+            if (index >= 0)
+                return;
+            if (typeof entry === "string") {
+                if (entry === blockId)
+                    index = i;
+                return;
+            }
+            if (Array.isArray(entry)) {
+                for (const child of entry) {
+                    if (child === blockId) {
+                        index = i;
+                        return;
+                    }
+                }
+            }
+        });
+        return index;
+    }
+    function resolveInsertContext(blocks, normalized) {
+        const placement = normalized.placement;
+        let parentId;
+        let referenceBlockId;
+        let mode = "append";
+        if (placement?.afterBlockId) {
+            mode = "after";
+            referenceBlockId = placement.afterBlockId;
+            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) {
+                throw new Error(`Block '${referenceBlockId}' has no parent.`);
+            }
+            parentId = refParentId;
+        }
+        else if (placement?.beforeBlockId) {
+            mode = "before";
+            referenceBlockId = placement.beforeBlockId;
+            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) {
+                throw new Error(`Block '${referenceBlockId}' has no parent.`);
+            }
+            parentId = refParentId;
+        }
+        else if (placement?.parentId) {
+            mode = placement.index !== undefined ? "index" : "append";
+            parentId = placement.parentId;
+        }
+        if (!parentId) {
+            if (normalized.type === "frame" || normalized.type === "edgeless_text") {
+                parentId = ensureSurfaceBlock(blocks);
+            }
+            else if (normalized.type === "note") {
+                parentId = findBlockIdByFlavour(blocks, "affine:page") || undefined;
+                if (!parentId) {
+                    throw new Error("Document has no page block; unable to insert note.");
+                }
+            }
+            else {
+                parentId = ensureNoteBlock(blocks);
+            }
+        }
+        const parentBlock = findBlockById(blocks, parentId);
+        if (!parentBlock) {
+            throw new Error(`Target parent block '${parentId}' was not found.`);
+        }
+        const parentFlavour = parentBlock.get("sys:flavour");
+        if (normalized.strict) {
+            if (parentFlavour === "affine:page" && normalized.type !== "note") {
+                throw new Error(`Cannot append '${normalized.type}' directly under 'affine:page'.`);
+            }
+            if (parentFlavour === "affine:surface" &&
+                normalized.type !== "frame" &&
+                normalized.type !== "edgeless_text") {
+                throw new Error(`Cannot append '${normalized.type}' directly under 'affine:surface'.`);
+            }
+            if (normalized.type === "note" && parentFlavour !== "affine:page") {
+                throw new Error("note blocks must be appended under affine:page.");
+            }
+            if ((normalized.type === "frame" || normalized.type === "edgeless_text") &&
+                parentFlavour !== "affine:surface") {
+                throw new Error(`${normalized.type} blocks must be appended under affine:surface.`);
+            }
+        }
+        const children = ensureChildrenArray(parentBlock);
+        let insertIndex = children.length;
+        if (mode === "after" || mode === "before") {
+            const idx = indexOfChild(children, referenceBlockId);
+            if (idx < 0) {
+                throw new Error(`Reference block '${referenceBlockId}' is not a child of parent '${parentId}'.`);
+            }
+            insertIndex = mode === "after" ? idx + 1 : idx;
+        }
+        else if (mode === "index") {
+            const requestedIndex = placement?.index ?? children.length;
+            if (requestedIndex > children.length && normalized.strict) {
+                throw new Error(`placement.index ${requestedIndex} is out of range (max ${children.length}).`);
+            }
+            insertIndex = Math.min(requestedIndex, children.length);
+        }
+        return { parentId, parentBlock, children, insertIndex };
+    }
+    function createBlock(parentId, normalized) {
         const blockId = generateId();
         const block = new Y.Map();
-        const content = parsed.text ?? "";
-        switch (parsed.type) {
+        const content = normalized.text;
+        switch (normalized.type) {
             case "paragraph":
-            case "heading1":
-            case "heading2":
-            case "heading3":
+            case "heading":
             case "quote": {
                 setSysFields(block, blockId, "affine:paragraph");
-                block.set("sys:parent", noteId);
+                block.set("sys:parent", parentId);
                 block.set("sys:children", new Y.Array());
-                const blockType = parsed.type === "heading1"
-                    ? "h1"
-                    : parsed.type === "heading2"
-                        ? "h2"
-                        : parsed.type === "heading3"
-                            ? "h3"
-                            : parsed.type === "quote"
-                                ? "quote"
-                                : "text";
+                const blockType = normalized.type === "heading"
+                    ? `h${normalized.headingLevel}`
+                    : normalized.type === "quote"
+                        ? "quote"
+                        : "text";
                 block.set("prop:type", blockType);
                 block.set("prop:text", makeText(content));
                 return { blockId, block, flavour: "affine:paragraph", blockType };
             }
-            case "bulleted_list":
-            case "numbered_list":
-            case "todo": {
+            case "list": {
                 setSysFields(block, blockId, "affine:list");
-                block.set("sys:parent", noteId);
+                block.set("sys:parent", parentId);
                 block.set("sys:children", new Y.Array());
-                const blockType = parsed.type === "bulleted_list"
-                    ? "bulleted"
-                    : parsed.type === "numbered_list"
-                        ? "numbered"
-                        : "todo";
-                block.set("prop:type", blockType);
-                if (blockType === "todo") {
-                    block.set("prop:checked", Boolean(parsed.checked));
-                }
+                block.set("prop:type", normalized.listStyle);
+                block.set("prop:checked", normalized.listStyle === "todo" ? normalized.checked : false);
                 block.set("prop:text", makeText(content));
-                return { blockId, block, flavour: "affine:list", blockType };
+                return { blockId, block, flavour: "affine:list", blockType: normalized.listStyle };
             }
             case "code": {
                 setSysFields(block, blockId, "affine:code");
-                block.set("sys:parent", noteId);
+                block.set("sys:parent", parentId);
                 block.set("sys:children", new Y.Array());
-                block.set("prop:language", (parsed.language || "txt").toLowerCase());
-                if (parsed.caption) {
-                    block.set("prop:caption", parsed.caption);
+                block.set("prop:language", normalized.language);
+                if (normalized.caption) {
+                    block.set("prop:caption", normalized.caption);
                 }
                 block.set("prop:text", makeText(content));
                 return { blockId, block, flavour: "affine:code" };
             }
             case "divider": {
                 setSysFields(block, blockId, "affine:divider");
-                block.set("sys:parent", noteId);
+                block.set("sys:parent", parentId);
                 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("prop:icon", { type: "emoji", unicode: "💡" });
+                block.set("prop:backgroundColorName", "grey");
+                block.set("prop:text", makeText(content));
+                return { blockId, block, flavour: "affine:callout" };
+            }
+            case "latex": {
+                setSysFields(block, blockId, "affine:latex");
+                block.set("sys:parent", parentId);
+                block.set("sys:children", new Y.Array());
+                block.set("prop:xywh", "[0,0,16,16]");
+                block.set("prop:index", "a0");
+                block.set("prop:lockedBySelf", false);
+                block.set("prop:scale", 1);
+                block.set("prop:rotate", 0);
+                block.set("prop:latex", normalized.latex);
+                return { blockId, block, flavour: "affine:latex" };
+            }
+            case "table": {
+                setSysFields(block, blockId, "affine:table");
+                block.set("sys:parent", parentId);
+                block.set("sys:children", new Y.Array());
+                const rows = {};
+                const columns = {};
+                const cells = {};
+                for (let i = 0; i < normalized.rows; i++) {
+                    const rowId = generateId();
+                    rows[rowId] = { rowId, order: `r${String(i).padStart(4, "0")}` };
+                }
+                for (let i = 0; i < normalized.columns; i++) {
+                    const columnId = generateId();
+                    columns[columnId] = { columnId, order: `c${String(i).padStart(4, "0")}` };
+                }
+                for (const rowId of Object.keys(rows)) {
+                    for (const columnId of Object.keys(columns)) {
+                        cells[`${rowId}:${columnId}`] = { text: makeText("") };
+                    }
+                }
+                block.set("prop:rows", rows);
+                block.set("prop:columns", columns);
+                block.set("prop:cells", cells);
+                block.set("prop:comments", undefined);
+                block.set("prop:textAlign", undefined);
+                return { blockId, block, flavour: "affine:table" };
+            }
+            case "bookmark": {
+                setSysFields(block, blockId, "affine:bookmark");
+                block.set("sys:parent", parentId);
+                block.set("sys:children", new Y.Array());
+                block.set("prop:style", normalized.bookmarkStyle);
+                block.set("prop:url", normalized.url);
+                block.set("prop:caption", normalized.caption ?? null);
+                block.set("prop:description", null);
+                block.set("prop:icon", null);
+                block.set("prop:image", null);
+                block.set("prop:title", null);
+                block.set("prop:xywh", "[0,0,0,0]");
+                block.set("prop:index", "a0");
+                block.set("prop:lockedBySelf", false);
+                block.set("prop:rotate", 0);
+                block.set("prop:footnoteIdentifier", null);
+                return { blockId, block, flavour: "affine:bookmark" };
+            }
+            case "image": {
+                setSysFields(block, blockId, "affine:image");
+                block.set("sys:parent", parentId);
+                block.set("sys:children", new Y.Array());
+                block.set("prop:caption", normalized.caption ?? "");
+                block.set("prop:sourceId", normalized.sourceId);
+                block.set("prop:width", 0);
+                block.set("prop:height", 0);
+                block.set("prop:size", normalized.size || -1);
+                block.set("prop:xywh", "[0,0,0,0]");
+                block.set("prop:index", "a0");
+                block.set("prop:lockedBySelf", false);
+                block.set("prop:rotate", 0);
+                return { blockId, block, flavour: "affine:image" };
+            }
+            case "attachment": {
+                setSysFields(block, blockId, "affine:attachment");
+                block.set("sys:parent", parentId);
+                block.set("sys:children", new Y.Array());
+                block.set("prop:name", normalized.name);
+                block.set("prop:size", normalized.size);
+                block.set("prop:type", normalized.mimeType);
+                block.set("prop:sourceId", normalized.sourceId);
+                block.set("prop:caption", normalized.caption ?? undefined);
+                block.set("prop:embed", normalized.embed);
+                block.set("prop:style", "horizontalThin");
+                block.set("prop:index", "a0");
+                block.set("prop:xywh", "[0,0,0,0]");
+                block.set("prop:lockedBySelf", false);
+                block.set("prop:rotate", 0);
+                block.set("prop:footnoteIdentifier", null);
+                return { blockId, block, flavour: "affine:attachment" };
+            }
+            case "embed_youtube": {
+                setSysFields(block, blockId, "affine:embed-youtube");
+                block.set("sys:parent", parentId);
+                block.set("sys:children", new Y.Array());
+                block.set("prop:index", "a0");
+                block.set("prop:xywh", "[0,0,0,0]");
+                block.set("prop:lockedBySelf", false);
+                block.set("prop:rotate", 0);
+                block.set("prop:style", "video");
+                block.set("prop:url", normalized.url);
+                block.set("prop:caption", normalized.caption ?? null);
+                block.set("prop:image", null);
+                block.set("prop:title", null);
+                block.set("prop:description", null);
+                block.set("prop:creator", null);
+                block.set("prop:creatorUrl", null);
+                block.set("prop:creatorImage", null);
+                block.set("prop:videoId", null);
+                return { blockId, block, flavour: "affine:embed-youtube" };
+            }
+            case "embed_github": {
+                setSysFields(block, blockId, "affine:embed-github");
+                block.set("sys:parent", parentId);
+                block.set("sys:children", new Y.Array());
+                block.set("prop:index", "a0");
+                block.set("prop:xywh", "[0,0,0,0]");
+                block.set("prop:lockedBySelf", false);
+                block.set("prop:rotate", 0);
+                block.set("prop:style", "horizontal");
+                block.set("prop:owner", "");
+                block.set("prop:repo", "");
+                block.set("prop:githubType", "issue");
+                block.set("prop:githubId", "");
+                block.set("prop:url", normalized.url);
+                block.set("prop:caption", normalized.caption ?? null);
+                block.set("prop:image", null);
+                block.set("prop:status", null);
+                block.set("prop:statusReason", null);
+                block.set("prop:title", null);
+                block.set("prop:description", null);
+                block.set("prop:createdAt", null);
+                block.set("prop:assignees", null);
+                return { blockId, block, flavour: "affine:embed-github" };
+            }
+            case "embed_figma": {
+                setSysFields(block, blockId, "affine:embed-figma");
+                block.set("sys:parent", parentId);
+                block.set("sys:children", new Y.Array());
+                block.set("prop:index", "a0");
+                block.set("prop:xywh", "[0,0,0,0]");
+                block.set("prop:lockedBySelf", false);
+                block.set("prop:rotate", 0);
+                block.set("prop:style", "figma");
+                block.set("prop:url", normalized.url);
+                block.set("prop:caption", normalized.caption ?? null);
+                block.set("prop:title", null);
+                block.set("prop:description", null);
+                return { blockId, block, flavour: "affine:embed-figma" };
+            }
+            case "embed_loom": {
+                setSysFields(block, blockId, "affine:embed-loom");
+                block.set("sys:parent", parentId);
+                block.set("sys:children", new Y.Array());
+                block.set("prop:index", "a0");
+                block.set("prop:xywh", "[0,0,0,0]");
+                block.set("prop:lockedBySelf", false);
+                block.set("prop:rotate", 0);
+                block.set("prop:style", "video");
+                block.set("prop:url", normalized.url);
+                block.set("prop:caption", normalized.caption ?? null);
+                block.set("prop:image", null);
+                block.set("prop:title", null);
+                block.set("prop:description", null);
+                block.set("prop:videoId", null);
+                return { blockId, block, flavour: "affine:embed-loom" };
+            }
+            case "embed_html": {
+                setSysFields(block, blockId, "affine:embed-html");
+                block.set("sys:parent", parentId);
+                block.set("sys:children", new Y.Array());
+                block.set("prop:index", "a0");
+                block.set("prop:xywh", "[0,0,0,0]");
+                block.set("prop:lockedBySelf", false);
+                block.set("prop:rotate", 0);
+                block.set("prop:style", "html");
+                block.set("prop:caption", normalized.caption ?? null);
+                block.set("prop:html", normalized.html || undefined);
+                block.set("prop:design", normalized.design || undefined);
+                return { blockId, block, flavour: "affine:embed-html" };
+            }
+            case "embed_linked_doc": {
+                setSysFields(block, blockId, "affine:embed-linked-doc");
+                block.set("sys:parent", parentId);
+                block.set("sys:children", new Y.Array());
+                block.set("prop:index", "a0");
+                block.set("prop:xywh", "[0,0,0,0]");
+                block.set("prop:lockedBySelf", false);
+                block.set("prop:rotate", 0);
+                block.set("prop:style", "horizontal");
+                block.set("prop:caption", normalized.caption ?? null);
+                block.set("prop:pageId", normalized.pageId);
+                block.set("prop:title", undefined);
+                block.set("prop:description", undefined);
+                block.set("prop:footnoteIdentifier", null);
+                return { blockId, block, flavour: "affine:embed-linked-doc" };
+            }
+            case "embed_synced_doc": {
+                setSysFields(block, blockId, "affine:embed-synced-doc");
+                block.set("sys:parent", parentId);
+                block.set("sys:children", new Y.Array());
+                block.set("prop:index", "a0");
+                block.set("prop:xywh", "[0,0,800,100]");
+                block.set("prop:lockedBySelf", false);
+                block.set("prop:rotate", 0);
+                block.set("prop:style", "syncedDoc");
+                block.set("prop:caption", normalized.caption ?? undefined);
+                block.set("prop:pageId", normalized.pageId);
+                block.set("prop:scale", undefined);
+                block.set("prop:preFoldHeight", undefined);
+                block.set("prop:title", undefined);
+                block.set("prop:description", undefined);
+                return { blockId, block, flavour: "affine:embed-synced-doc" };
+            }
+            case "embed_iframe": {
+                setSysFields(block, blockId, "affine:embed-iframe");
+                block.set("sys:parent", parentId);
+                block.set("sys:children", new Y.Array());
+                block.set("prop:index", "a0");
+                block.set("prop:xywh", "[0,0,0,0]");
+                block.set("prop:lockedBySelf", false);
+                block.set("prop:scale", 1);
+                block.set("prop:url", normalized.url);
+                block.set("prop:iframeUrl", normalized.iframeUrl || normalized.url);
+                block.set("prop:width", undefined);
+                block.set("prop:height", undefined);
+                block.set("prop:caption", normalized.caption ?? null);
+                block.set("prop:title", null);
+                block.set("prop:description", null);
+                return { blockId, block, flavour: "affine:embed-iframe" };
+            }
+            case "database": {
+                setSysFields(block, blockId, "affine:database");
+                block.set("sys:parent", parentId);
+                block.set("sys:children", new Y.Array());
+                block.set("prop:views", new Y.Array());
+                block.set("prop:title", makeText(content));
+                block.set("prop:cells", new Y.Map());
+                block.set("prop:columns", new Y.Array());
+                block.set("prop:comments", undefined);
+                return { blockId, block, flavour: "affine:database" };
+            }
+            case "data_view": {
+                // 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:children", new Y.Array());
+                block.set("prop:views", new Y.Array());
+                block.set("prop:title", makeText(content));
+                block.set("prop:cells", new Y.Map());
+                block.set("prop:columns", new Y.Array());
+                block.set("prop:comments", undefined);
+                return { blockId, block, flavour: "affine:database", blockType: "data_view_fallback" };
+            }
+            case "surface_ref": {
+                setSysFields(block, blockId, "affine:surface-ref");
+                block.set("sys:parent", parentId);
+                block.set("sys:children", new Y.Array());
+                block.set("prop:reference", normalized.reference);
+                block.set("prop:caption", normalized.caption ?? "");
+                block.set("prop:refFlavour", normalized.refFlavour);
+                block.set("prop:comments", undefined);
+                return { blockId, block, flavour: "affine:surface-ref" };
+            }
+            case "frame": {
+                setSysFields(block, blockId, "affine:frame");
+                block.set("sys:parent", parentId);
+                block.set("sys:children", new Y.Array());
+                block.set("prop:title", makeText(content || "Frame"));
+                block.set("prop:background", normalized.background);
+                block.set("prop:xywh", `[0,0,${normalized.width},${normalized.height}]`);
+                block.set("prop:index", "a0");
+                block.set("prop:childElementIds", new Y.Map());
+                block.set("prop:presentationIndex", "a0");
+                block.set("prop:lockedBySelf", false);
+                return { blockId, block, flavour: "affine:frame" };
+            }
+            case "edgeless_text": {
+                setSysFields(block, blockId, "affine:edgeless-text");
+                block.set("sys:parent", parentId);
+                block.set("sys:children", new Y.Array());
+                block.set("prop:xywh", `[0,0,${normalized.width},${normalized.height}]`);
+                block.set("prop:index", "a0");
+                block.set("prop:lockedBySelf", false);
+                block.set("prop:scale", 1);
+                block.set("prop:rotate", 0);
+                block.set("prop:hasMaxWidth", false);
+                block.set("prop:comments", undefined);
+                block.set("prop:color", "black");
+                block.set("prop:fontFamily", "Inter");
+                block.set("prop:fontStyle", "normal");
+                block.set("prop:fontWeight", "regular");
+                block.set("prop:textAlign", "left");
+                return { blockId, block, flavour: "affine:edgeless-text" };
+            }
+            case "note": {
+                setSysFields(block, blockId, "affine:note");
+                block.set("sys:parent", parentId);
+                block.set("sys:children", new Y.Array());
+                block.set("prop:xywh", `[0,0,${normalized.width},${normalized.height}]`);
+                block.set("prop:background", normalized.background);
+                block.set("prop:index", "a0");
+                block.set("prop:lockedBySelf", false);
+                block.set("prop:hidden", false);
+                block.set("prop:displayMode", "both");
+                const edgeless = new Y.Map();
+                const style = new Y.Map();
+                style.set("borderRadius", 8);
+                style.set("borderSize", 1);
+                style.set("borderStyle", "solid");
+                style.set("shadowType", "none");
+                edgeless.set("style", style);
+                block.set("prop:edgeless", edgeless);
+                block.set("prop:comments", undefined);
+                return { blockId, block, flavour: "affine:note" };
+            }
         }
     }
     async function appendBlockInternal(parsed) {
-        const workspaceId = parsed.workspaceId || defaults.workspaceId;
+        const normalized = normalizeAppendBlockInput(parsed);
+        const workspaceId = normalized.workspaceId || defaults.workspaceId;
         if (!workspaceId)
             throw new Error("workspaceId is required");
         const { endpoint, cookie } = await getCookieAndEndpoint();
@@ -194,25 +972,24 @@ export function registerDocTools(server, gql, defaults) {
         try {
             await joinWorkspace(socket, workspaceId);
             const doc = new Y.Doc();
-            const snapshot = await loadDoc(socket, workspaceId, parsed.docId);
+            const snapshot = await loadDoc(socket, workspaceId, normalized.docId);
             if (snapshot.missing) {
                 Y.applyUpdate(doc, Buffer.from(snapshot.missing, "base64"));
             }
             const prevSV = Y.encodeStateVector(doc);
             const blocks = doc.getMap("blocks");
-            const noteId = ensureNoteBlock(blocks);
-            const { blockId, block, flavour, blockType } = createBlock(noteId, parsed);
+            const context = resolveInsertContext(blocks, normalized);
+            const { blockId, block, flavour, blockType } = createBlock(context.parentId, normalized);
             blocks.set(blockId, block);
-            const note = blocks.get(noteId);
-            let noteChildren = note.get("sys:children");
-            if (!(noteChildren instanceof Y.Array)) {
-                noteChildren = new Y.Array();
-                note.set("sys:children", noteChildren);
+            if (context.insertIndex >= context.children.length) {
+                context.children.push([blockId]);
+            }
+            else {
+                context.children.insert(context.insertIndex, [blockId]);
             }
-            noteChildren.push([blockId]);
             const delta = Y.encodeStateAsUpdate(doc, prevSV);
-            await pushDocUpdate(socket, workspaceId, parsed.docId, Buffer.from(delta).toString("base64"));
-            return { appended: true, blockId, flavour, blockType };
+            await pushDocUpdate(socket, workspaceId, normalized.docId, Buffer.from(delta).toString("base64"));
+            return { appended: true, blockId, flavour, blockType, normalizedType: normalized.type, legacyType: normalized.legacyType || null };
         }
         finally {
             socket.disconnect();
@@ -520,19 +1297,52 @@ export function registerDocTools(server, gql, defaults) {
             blockId: result.blockId,
             flavour: result.flavour,
             type: result.blockType || null,
+            normalizedType: result.normalizedType,
+            legacyType: result.legacyType,
         });
     };
     server.registerTool("append_block", {
         title: "Append Block",
-        description: "Append a slash-command style block (heading/list/todo/code/divider/quote) to a document.",
+        description: "Append document blocks with canonical types and legacy aliases (supports placement + strict validation).",
         inputSchema: {
             workspaceId: WorkspaceId.optional(),
             docId: DocId,
-            type: AppendBlockType.describe("Block type to append"),
+            type: z.string().min(1).describe("Block type. Canonical: paragraph|heading|quote|list|code|divider|callout|latex|table|bookmark|image|attachment|embed_youtube|embed_github|embed_figma|embed_loom|embed_html|embed_linked_doc|embed_synced_doc|embed_iframe|database|data_view|surface_ref|frame|edgeless_text|note. Legacy aliases remain supported."),
             text: z.string().optional().describe("Block content text"),
+            url: z.string().optional().describe("URL for bookmark/embeds"),
+            pageId: z.string().optional().describe("Target page/doc id for linked/synced doc embeds"),
+            iframeUrl: z.string().optional().describe("Override iframe src for embed_iframe"),
+            html: z.string().optional().describe("Raw html for embed_html"),
+            design: z.string().optional().describe("Design payload for embed_html"),
+            reference: z.string().optional().describe("Target id for surface_ref"),
+            refFlavour: z.string().optional().describe("Target flavour for surface_ref (e.g. affine:frame)"),
+            width: z.number().int().min(1).max(10000).optional().describe("Width for frame/edgeless_text/note"),
+            height: z.number().int().min(1).max(10000).optional().describe("Height for frame/edgeless_text/note"),
+            background: z.string().optional().describe("Background for frame/note"),
+            sourceId: z.string().optional().describe("Blob source id for image/attachment"),
+            name: z.string().optional().describe("Attachment file name"),
+            mimeType: z.string().optional().describe("Attachment mime type"),
+            size: z.number().optional().describe("Attachment/image file size in bytes"),
+            embed: z.boolean().optional().describe("Attachment embed mode"),
+            rows: z.number().int().min(1).max(20).optional().describe("Table row count"),
+            columns: z.number().int().min(1).max(20).optional().describe("Table column count"),
+            latex: z.string().optional().describe("Latex expression"),
+            level: z.number().int().min(1).max(6).optional().describe("Heading level for type=heading"),
+            style: AppendBlockListStyle.optional().describe("List style for type=list"),
+            bookmarkStyle: AppendBlockBookmarkStyle.optional().describe("Bookmark card style"),
             checked: z.boolean().optional().describe("Todo state when type is todo"),
             language: z.string().optional().describe("Code language when type is code"),
             caption: z.string().optional().describe("Code caption when type is code"),
+            strict: z.boolean().optional().describe("Strict validation mode (default true)"),
+            placement: z
+                .object({
+                parentId: z.string().optional(),
+                afterBlockId: z.string().optional(),
+                beforeBlockId: z.string().optional(),
+                index: z.number().int().min(0).optional(),
+            })
+                .optional()
+                .describe("Optional insertion target/position"),
         },
     }, appendBlockHandler);
     // DELETE DOC

package/package.json

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