affine-mcp-server 1.3.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.3.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)
@@ -16,15 +16,15 @@ A Model Context Protocol (MCP) server that integrates with AFFiNE (self‑hosted
 - Purpose: Manage AFFiNE workspaces and documents through MCP
 - Transport: stdio only (Claude Desktop / Codex compatible)
 - Auth: Token, Cookie, or Email/Password (priority order)
-- Tools: 31 focused tools with WebSocket-based document editing
+- Tools: 32 focused tools with WebSocket-based document editing
 - Status: Active
  
-> New in v1.3.0: Added `append_block` for slash-command style blocks (heading/list/todo/code/divider/quote), removed duplicated aliases/non-core tools, and added CI + manifest quality gates.
+> 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
 
 - Workspace: create (with initial doc), read, update, delete
-- Documents: list/get/publish/revoke + create/append paragraph/delete (WebSocket‑based)
+- Documents: list/get/read/publish/revoke + create/append paragraph/delete (WebSocket‑based)
 - Comments: full CRUD and resolve
 - Version History: list
 - Users & Tokens: current user, sign in, profile/settings, and personal access tokens
@@ -112,6 +112,43 @@ Notes
 - Command: `affine-mcp`
 - Environment: `AFFINE_BASE_URL` + one auth method (`AFFINE_API_TOKEN` | `AFFINE_COOKIE` | `AFFINE_EMAIL`/`AFFINE_PASSWORD`)
 
+### Cursor
+
+Cursor also supports MCP over stdio with `mcp.json`.
+
+Project-local (`.cursor/mcp.json`) example:
+
+```json
+{
+  "mcpServers": {
+    "affine": {
+      "command": "affine-mcp",
+      "env": {
+        "AFFINE_BASE_URL": "https://your-affine-instance.com",
+        "AFFINE_API_TOKEN": "apt_xxx"
+      }
+    }
+  }
+}
+```
+
+If you prefer `npx`:
+
+```json
+{
+  "mcpServers": {
+    "affine": {
+      "command": "npx",
+      "args": ["-y", "-p", "affine-mcp-server", "affine-mcp"],
+      "env": {
+        "AFFINE_BASE_URL": "https://your-affine-instance.com",
+        "AFFINE_API_TOKEN": "apt_xxx"
+      }
+    }
+  }
+}
+```
+
 ## Available Tools
 
 ### Workspace
@@ -124,11 +161,12 @@ Notes
 ### Documents
 - `list_docs` – list documents with pagination
 - `get_doc` – get document metadata
+- `read_doc` – read document block content and plain text snapshot (WebSocket)
 - `publish_doc` – make document public
 - `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
@@ -186,6 +224,15 @@ Connection
 - GraphQL endpoint default is `/graphql`
 - Check firewall/proxy rules; verify CORS if self‑hosted
 
+Method not found
+- MCP tool names (for example `list_workspaces`) are not JSON-RPC top-level method names.
+- Use an MCP client (`tools/list`, `tools/call`) instead of sending direct JSON-RPC calls like `{\"method\":\"list_workspaces\"}`.
+- From v1.3.0, only canonical tool names are exposed (legacy `affine_*` aliases were removed).
+
+Workspace visibility
+- This MCP server can access server-backed workspaces only (AFFiNE cloud/self-hosted).
+- Browser local-storage workspaces are client-side data, so they are not visible via server GraphQL/WebSocket APIs.
+
 ## Security Considerations
 
 - Never commit `.env` with secrets
@@ -196,6 +243,16 @@ Connection
 
 ## 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
+- Added explicit local-storage workspace limitation notes
+
 ### 1.3.0 (2026‑02‑13)
 - Added `append_block` for slash-command style editing (`heading/list/todo/code/divider/quote`)
 - Tool surface simplified to 31 canonical tools (duplicate aliases removed)

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.2.2" });
+    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":
@@ -49,6 +82,32 @@ export function registerDocTools(server, gql, defaults) {
         }
         return yText;
     }
+    function asText(value) {
+        if (value instanceof Y.Text)
+            return value.toString();
+        if (typeof value === "string")
+            return value;
+        return "";
+    }
+    function childIdsFrom(value) {
+        if (!(value instanceof Y.Array))
+            return [];
+        const childIds = [];
+        value.forEach((entry) => {
+            if (typeof entry === "string") {
+                childIds.push(entry);
+                return;
+            }
+            if (Array.isArray(entry)) {
+                for (const child of entry) {
+                    if (typeof child === "string") {
+                        childIds.push(child);
+                    }
+                }
+            }
+        });
+        return childIds;
+    }
     function setSysFields(block, blockId, flavour) {
         block.set("sys:id", blockId);
         block.set("sys:flavour", flavour);
@@ -95,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();
@@ -168,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();
@@ -228,6 +1031,103 @@ export function registerDocTools(server, gql, defaults) {
             docId: DocId
         }
     }, getDocHandler);
+    const readDocHandler = async (parsed) => {
+        const workspaceId = parsed.workspaceId || defaults.workspaceId;
+        if (!workspaceId) {
+            throw new Error("workspaceId is required. Provide it as a parameter or set AFFINE_WORKSPACE_ID in environment.");
+        }
+        const { endpoint, cookie } = await getCookieAndEndpoint();
+        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
+        const socket = await connectWorkspaceSocket(wsUrl, cookie);
+        try {
+            await joinWorkspace(socket, workspaceId);
+            const snapshot = await loadDoc(socket, workspaceId, parsed.docId);
+            if (!snapshot.missing) {
+                return text({
+                    docId: parsed.docId,
+                    title: null,
+                    exists: false,
+                    blockCount: 0,
+                    blocks: [],
+                    plainText: "",
+                });
+            }
+            const doc = new Y.Doc();
+            Y.applyUpdate(doc, Buffer.from(snapshot.missing, "base64"));
+            const blocks = doc.getMap("blocks");
+            const pageId = findBlockIdByFlavour(blocks, "affine:page");
+            const noteId = findBlockIdByFlavour(blocks, "affine:note");
+            const visited = new Set();
+            const blockRows = [];
+            const plainTextLines = [];
+            let title = "";
+            const visit = (blockId) => {
+                if (visited.has(blockId))
+                    return;
+                visited.add(blockId);
+                const raw = blocks.get(blockId);
+                if (!(raw instanceof Y.Map))
+                    return;
+                const flavour = raw.get("sys:flavour");
+                const parentId = raw.get("sys:parent");
+                const type = raw.get("prop:type");
+                const textValue = asText(raw.get("prop:text"));
+                const language = raw.get("prop:language");
+                const checked = raw.get("prop:checked");
+                const childIds = childIdsFrom(raw.get("sys:children"));
+                if (flavour === "affine:page") {
+                    title = asText(raw.get("prop:title")) || title;
+                }
+                if (textValue.length > 0) {
+                    plainTextLines.push(textValue);
+                }
+                blockRows.push({
+                    id: blockId,
+                    parentId: typeof parentId === "string" ? parentId : null,
+                    flavour: typeof flavour === "string" ? flavour : null,
+                    type: typeof type === "string" ? type : null,
+                    text: textValue.length > 0 ? textValue : null,
+                    checked: typeof checked === "boolean" ? checked : null,
+                    language: typeof language === "string" ? language : null,
+                    childIds,
+                });
+                for (const childId of childIds) {
+                    visit(childId);
+                }
+            };
+            if (pageId) {
+                visit(pageId);
+            }
+            else if (noteId) {
+                visit(noteId);
+            }
+            for (const [id] of blocks) {
+                const blockId = String(id);
+                if (!visited.has(blockId)) {
+                    visit(blockId);
+                }
+            }
+            return text({
+                docId: parsed.docId,
+                title: title || null,
+                exists: true,
+                blockCount: blockRows.length,
+                blocks: blockRows,
+                plainText: plainTextLines.join("\n"),
+            });
+        }
+        finally {
+            socket.disconnect();
+        }
+    };
+    server.registerTool("read_doc", {
+        title: "Read Document Content",
+        description: "Read document block content via WebSocket snapshot (blocks + plain text).",
+        inputSchema: {
+            workspaceId: WorkspaceId.optional(),
+            docId: DocId,
+        },
+    }, readDocHandler);
     const publishDocHandler = async (parsed) => {
         const workspaceId = parsed.workspaceId || defaults.workspaceId;
         if (!workspaceId) {
@@ -397,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.3.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.",
@@ -55,12 +55,12 @@
     "form-data": "^4.0.4",
     "node-fetch": "^3.3.2",
     "socket.io-client": "^4.8.1",
-    "undici": "^6.19.8",
+    "undici": "^7.21.0",
     "yjs": "^13.6.27",
     "zod": "^3.23.8"
   },
   "devDependencies": {
-    "@types/node": "^20.14.11",
+    "@types/node": "^25.2.3",
     "tsx": "^4.16.2",
     "typescript": "^5.5.4"
   }