affine-mcp-server 1.13.0 → 2.0.0

package/docs/configuration-and-deployment.md

@@ -40,6 +40,7 @@ Auth priority within the active configuration:
 
 | Variable | Purpose |
 | --- | --- |
+| `AFFINE_TOOL_PROFILE` | Select a predefined tool surface profile (`full`, `read_only`, `core`, `authoring`) |
 | `AFFINE_DISABLED_GROUPS` | Disable entire tool groups by comma-separated group name |
 | `AFFINE_DISABLED_TOOLS` | Disable individual tools by exact canonical name |
 
@@ -152,6 +153,25 @@ OAuth mode behavior:
 
 ## Least-privilege tool exposure
 
+### Use a tool profile
+
+Profiles are the easiest way to reduce the MCP tool surface without listing every tool by name.
+
+Example:
+
+```json
+{
+  "AFFINE_TOOL_PROFILE": "core"
+}
+```
+
+Available profiles:
+
+- `full`: expose the complete public tool surface; this is the default
+- `read_only`: expose discovery, reading, export, fidelity, and inspection tools, plus `sign_in`
+- `core`: expose the compact everyday surface for workspace/doc discovery, basic document authoring, tags, and database row/schema edits; omits admin tools, cleanup tools, experimental organize tools, and destructive tools
+- `authoring`: expose non-destructive creation and editing tools, including semantic pages, native templates, database composition, and edgeless canvas authoring; omits admin, cleanup, destructive, and experimental organize tools
+
 ### Disable whole groups
 
 Example:
@@ -165,14 +185,51 @@ Example:
 Current group names:
 
 - `workspaces`
+- `workspaces.read`
+- `workspaces.write`
 - `docs`
+- `docs.read`
+- `docs.write`
+- `docs.markdown`
+- `docs.tags`
+- `docs.tree`
+- `docs.export`
+- `docs.semantic`
+- `docs.template`
+- `docs.database`
+- `docs.edgeless`
+- `docs.surface`
+- `docs.intent`
+- `docs.share`
 - `comments`
+- `comments.read`
+- `comments.write`
 - `history`
+- `history.read`
 - `organize`
+- `organize.read`
+- `organize.write`
+- `organize.collections`
+- `organize.folders`
 - `users`
+- `users.read`
+- `users.write`
+- `users.auth`
 - `access_tokens`
+- `access_tokens.read`
+- `access_tokens.write`
 - `blobs`
+- `blobs.write`
 - `notifications`
+- `notifications.read`
+- `notifications.write`
+- `admin`
+- `auth`
+- `cleanup`
+- `destructive`
+- `experimental`
+- `read`
+- `write`
 
 ### Disable specific tools
 
@@ -184,7 +241,7 @@ Example:
 }
 ```
 
-Use tool-level filtering when you want a mostly complete tool surface but need to remove destructive operations.
+Use tool-level filtering when you want a mostly complete tool surface but need to remove specific operations such as destructive actions or administrative access-token tools.
 
 ## Deployment checklist
 

package/docs/edgeless-canvas-cookbook.md

@@ -0,0 +1,226 @@
+# Edgeless Canvas Cookbook
+
+A worked, live-authored walkthrough of the edgeless canvas tools. Every call in this doc was executed against a running AFFiNE instance while authoring it; the IDs, coordinates, and responses below are real output from that session, not illustrative fiction.
+
+## What you'll build
+
+An auth-flow diagram: four rectangles (User, Auth Service, Database, Cache) stitched with labeled connectors, wrapped in a **Frame that owns the diagram** — drag the frame in the editor and everything inside moves with it. Followed by an epilogue note that lands in the right place by itself, no coordinate math.
+
+```
+┌─ Frame "Auth Flow" ────────────────────────────────────────┐
+│                                                            │
+│   [ User ]  ──authenticate─→  [ Auth Service ]             │
+│                                    │                       │
+│                              ──verify──→                   │
+│                                    │                       │
+│                              [ Database ]                  │
+│                                                            │
+│                              [ Cache ]  ←─session lookup─  │
+└────────────────────────────────────────────────────────────┘
+
+[ Epilogue note — auto-placed below the frame with padding gap ]
+```
+
+## The full call sequence
+
+Every step below is copy-pasteable. Replace `W` with your workspace id.
+
+### 1. Fresh doc
+
+```js
+const { docId: D } = await call("create_doc", {
+  workspaceId: W,
+  title: "Edgeless Canvas Cookbook — Live Demo",
+  content: "This doc was seeded live by the edgeless-canvas cookbook.",
+});
+```
+
+AFFiNE seeds a default note at `[0,0,800,~268]` — we'll leave it; step 6 demonstrates how the auto-placement default dodges it.
+
+### 2. Three surface shapes
+
+```js
+const user = await call("add_surface_element", {
+  workspaceId: W, docId: D, type: "shape", shapeType: "rect", radius: 0.2,
+  x: 200, y: 400, width: 160, height: 80, text: "User", fontSize: 18,
+  fillColor: "--affine-palette-shape-blue",
+});
+const auth = await call("add_surface_element", {
+  workspaceId: W, docId: D, type: "shape", shapeType: "rect", radius: 0.2,
+  x: 500, y: 400, width: 160, height: 80, text: "Auth Service", fontSize: 18,
+  fillColor: "--affine-palette-shape-green",
+});
+const db = await call("add_surface_element", {
+  workspaceId: W, docId: D, type: "shape", shapeType: "rect", radius: 0.2,
+  x: 800, y: 400, width: 160, height: 80, text: "Database", fontSize: 18,
+  fillColor: "--affine-palette-shape-purple",
+});
+// → returns { added: true, elementId: "cczYKQ593K", type: "shape", surfaceBlockId: "wpv4iPX3Qj" }, ...
+```
+
+### 3. Labeled connectors between them
+
+```js
+const c1 = await call("add_surface_element", {
+  workspaceId: W, docId: D, type: "connector",
+  sourceId: user.elementId, targetId: auth.elementId, label: "authenticate",
+});
+const c2 = await call("add_surface_element", {
+  workspaceId: W, docId: D, type: "connector",
+  sourceId: auth.elementId, targetId: db.elementId, label: "verify",
+});
+```
+
+With both endpoints bound by id and no explicit `sourcePosition` / `targetPosition`, BlockSuite's side-midpoint auto-snap kicks in — each endpoint lands on one of `[0.5,0]`, `[0.5,1]`, `[0,0.5]`, `[1,0.5]`. `labelXYWH` is seeded at the source→target midpoint so the label renders on first open.
+
+### 4. Wrap the diagram in a frame that **owns** it
+
+```js
+const frame = await call("append_block", {
+  workspaceId: W, docId: D, type: "frame",
+  text: "Auth Flow",
+  childElementIds: [user.elementId, auth.elementId, db.elementId, c1.elementId, c2.elementId],
+  padding: 50,
+});
+// → {
+//     appended: true, blockId: "wx0OB2I2cp", flavour: "affine:frame",
+//     ownedIds: ["cczYKQ593K","dSfmVkc3Io","goh9bQO5sg","jDvyiSy5Su","O5Gtcr17O2"],
+//     missing: []
+//   }
+```
+
+With `width`/`height` omitted, the frame auto-sizes to the union of its children's bounds plus `padding` on each side and a 30px title band at the top. Every resolved id lands in `ownedIds` — dragging the frame in the editor now drags the whole diagram. BlockSuite's `prop:childElementIds` accepts both surface elements (shapes/connectors/groups) and edgeless blocks (notes/frames/edgeless-text), so you can wrap either without triage.
+
+### 5. Add a new member and let the frame regrow
+
+```js
+const cache = await call("add_surface_element", {
+  workspaceId: W, docId: D, type: "shape", shapeType: "rect", radius: 0.2,
+  x: 500, y: 600, width: 160, height: 80, text: "Cache", fontSize: 18,
+  fillColor: "--affine-palette-shape-orange",
+});
+const c3 = await call("add_surface_element", {
+  workspaceId: W, docId: D, type: "connector", mode: 1,
+  sourceId: auth.elementId, targetId: cache.elementId, label: "session lookup",
+});
+
+await call("update_frame_children", {
+  workspaceId: W, docId: D, blockId: frame.blockId,
+  childElementIds: [user.elementId, auth.elementId, db.elementId, c1.elementId, c2.elementId, cache.elementId, c3.elementId],
+  padding: 50,
+});
+// → {
+//     updated: true, blockId: "wx0OB2I2cp", flavour: "affine:frame",
+//     ownedIds: [..., "9aYW_HNajo", "wzoKIrLkO-"],
+//     missing: [],
+//     resized: true, xywh: { x: 150, y: 290, width: 860, height: 440 }
+//   }
+```
+
+`update_frame_children` replaces ownership **wholesale** (same semantics as `update_surface_element` for a group's `children`) and by default recomputes `xywh` so the box fits its new contents. Pass `resizeToFit: false` to keep the box untouched:
+
+```js
+await call("update_frame_children", {
+  workspaceId: W, docId: D, blockId: frame.blockId,
+  childElementIds: [user.elementId, auth.elementId, db.elementId, c1.elementId, c2.elementId],
+  resizeToFit: false,
+});
+// → { updated: true, ownedIds: [...], resized: false }
+```
+
+Use the opt-out when you want to shrink ownership without the frame jumping around the canvas.
+
+### 6. Append a note with no coordinates — it lands in the right place
+
+```js
+await call("append_block", {
+  workspaceId: W, docId: D, type: "note",
+  width: 800, height: 120,
+  markdown: [
+    "## How this canvas was built",
+    "",
+    "Every block, shape, and frame above was authored with a single MCP tool call.",
+    "The frame owns its shapes via `prop:childElementIds` — drag it and the diagram moves with it.",
+  ].join("\n"),
+});
+// → note xywh ends up at [150, 770, 800, 166.5]
+```
+
+No `x`/`y`, no `stackAfter` — yet the note lands at `y=770`, which is the frame's bottom edge (`290 + 440 = 730`) plus the default `padding` gap of 40. When you append a `frame`/`note`/`edgeless_text` to a doc and don't provide an explicit position or `stackAfter`, the server auto-stacks it below whichever edgeless block sits lowest. The common "new note overlaps AFFiNE's seeded default note at `[0,0,…]`" papercut is gone.
+
+Pass `x: 0, y: 0` explicitly if you *want* the old behavior back.
+
+## The id triage: owned vs missing
+
+`childElementIds` (on both `append_block` and `update_frame_children`) accepts any mix of surface-element and block ids. Everything that resolves gets written to the frame's `prop:childElementIds` Y.Map — the same shape BlockSuite's editor writes when you drag members into a frame, so dragging the frame drags every owned member regardless of flavour.
+
+| Lands in | When |
+| --- | --- |
+| `ownedIds` | id resolves to an existing surface element OR edgeless block. Written to `prop:childElementIds`. Frame drags them along. |
+| `missing` | id doesn't resolve to either. Skipped; returned so callers can tell stale ids from intentional ones. |
+
+If **every** id is missing on `append_block`, the call throws (`None of the ids in childElementIds were found: [...]`) — that's almost always a caller bug. `update_frame_children` tolerates all-missing and treats it as "clear ownership" (paired with a skipped resize).
+
+## Read the whole canvas back
+
+```js
+const canvas = await call("get_edgeless_canvas", { workspaceId: W, docId: D });
+// canvas.edgelessBlocks: [
+//   { flavour: "affine:note",  xywh: "[0,0,800,268]",     bounds: {...}, children: [...] },
+//   { flavour: "affine:frame", xywh: "[150,290,860,440]", title: "Auth Flow",
+//     childElementIds: ["cczYKQ593K","dSfmVkc3Io","goh9bQO5sg","jDvyiSy5Su","O5Gtcr17O2","9aYW_HNajo","wzoKIrLkO-"] },
+//   { flavour: "affine:note",  xywh: "[150,770,800,166.5]", children: [
+//       { flavour: "affine:paragraph", text: "How this canvas was built", type: "h2" },
+//       { flavour: "affine:paragraph", text: "Every block, shape, and frame above...", type: "text" },
+//   ] },
+// ],
+// canvas.surfaceElements: [shape(User), shape(Auth), shape(Database),
+//                          connector(authenticate), connector(verify),
+//                          shape(Cache), connector(session lookup)],
+// canvas.bounds: { minX: 0, minY: 0, maxX: 1010, maxY: 936.5, width: 1010, height: 936.5 }
+```
+
+Frame entries now carry `childElementIds: string[]` so agents can see ownership without crawling the surface layer. Note entries emit a structured `children: [{ flavour, type, text, language?, checked? }]` array — markdown round-trips with heading/list/code semantics intact, no re-parsing needed.
+
+## Running it
+
+From the repo root with Docker available:
+
+```bash
+. tests/generate-test-env.sh
+docker compose -f docker/docker-compose.yml up -d
+node tests/acquire-credentials.mjs
+npm run build
+```
+
+Then drop the calls above into a Node script that opens a `StdioClientTransport` against `dist/index.js` — `tests/test-canvas-tool-map-demo.mjs` is a complete example of the client wiring, minus the auth-flow content. The script prints the seeded doc URL; open it in a browser, switch to edgeless mode (icon next to the doc title), and the frame + its five owned elements select and drag as one.
+
+## Advanced: the tool-map showcase
+
+`tests/test-canvas-tool-map-demo.mjs` seeds a much larger canvas — three color-coded columns mapping the full tool catalog, with each column's notes owned by a frame via `childElementIds` so dragging the frame moves the entire column together. It doubles as a layout-helper regression test wired into `tests/run-e2e.sh`. It's the right place to look for end-to-end coverage of `stackAfter`, `childElementIds` ownership across flavours, connector side-midpoint auto-snap, and `labelXYWH` seeding all in one run.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="./assets/edgeless-canvas-demo-advanced-dark.png">
+  <img alt="AFFiNE MCP Tool Map — three color-coded columns wrapped in frames, connectors fanning out from a top banner into column chains and fanning in to a bottom agent-view banner" src="./assets/edgeless-canvas-demo-advanced-light.png">
+</picture>
+
+## Tool surface at a glance
+
+| Tool | Purpose |
+| --- | --- |
+| `add_surface_element` | Shapes / connectors / canvas text / groups on `affine:surface`. Connectors auto-snap endpoints to side-midpoints when both are bound by id. |
+| `append_block(type="frame", childElementIds)` | Create a frame that owns surface elements and auto-sizes to contain them. |
+| `update_frame_children` | Replace a frame's contents wholesale. Default resizes to fit; `resizeToFit: false` preserves the current box. |
+| `append_block(type="note" / "frame" / "edgeless_text")` | Edgeless blocks. Bare calls auto-stack below existing blocks; pass `x`/`y` or `stackAfter` to override. |
+| `get_edgeless_canvas` | Read the full canvas: edgeless blocks + surface elements with parsed bounds, aggregate bounding box, and per-type counts. Frame entries now include `childElementIds`. |
+
+## BlockSuite alignment notes
+
+Everything above writes to the native BlockSuite schema — no custom overlay:
+
+- Surface elements land in `affine:surface` → `prop:elements.value` as `Y.Map` entries with fractional-index strings for stable z-order.
+- Frame ownership uses `prop:childElementIds` as a `Y.Map<boolean>` keyed by element id — identical shape to a group's `children` map.
+- Connectors with both endpoints bound by id and no explicit position auto-snap to the four tangent-carrying side-midpoints (`[0.5,0]`, `[0.5,1]`, `[0,0.5]`, `[1,0.5]`).
+- `labelXYWH` is seeded at the source→target midpoint so BlockSuite's label renderer doesn't short-circuit on first render.
+- `append_block(type="edgeless_text", text=…)` auto-creates a child `affine:paragraph` — the edgeless-text view walks `sys:children` for glyphs, so without it the block renders as an invisible sliver.
+- `src/edgeless/layout.ts` is a dependency-free module citing the upstream BlockSuite files each helper mirrors (`connector.ts`, `connector-manager.ts`, `edgeless-note-mask.ts`), so future parity audits stay cheap.

package/docs/tool-reference.md

@@ -9,7 +9,7 @@ Use this document as a grouped catalog. For exact schemas, your MCP client shoul
 - Canonical names only: legacy alias names are not part of the public tool surface
 - Document editing relies on AFFiNE WebSocket-backed operations where noted
 - Experimental organize tools are marked explicitly
-- Use tool filtering in production if you want a reduced or read-only surface
+- Use `AFFINE_TOOL_PROFILE=read_only`, `core`, or `authoring` in production if you want a reduced surface
 
 ## Workspace
 
@@ -54,14 +54,11 @@ Use this document as a grouped catalog. For exact schemas, your MCP client shoul
 | `list_tags` | List all tags in a workspace | |
 | `search_docs` | Search titles with substring, prefix, or exact matching | Supports tag filter and updatedAt sorting |
 | `list_docs_by_tag` | List documents with a specific tag | |
-| `get_docs_by_tag` | Search documents by case-insensitive tag substring | Returns `availableTags` when nothing matches |
 | `get_doc` | Read document metadata | |
-| `get_doc_by_title` | Find a document by title and return Markdown content | Useful for title-based lookup |
 | `read_doc` | Read block content and plain text snapshot | WebSocket-backed |
 | `get_capabilities` | Inspect the server's high-level authoring and fidelity capabilities | Useful for adaptive clients |
 | `analyze_doc_fidelity` | Analyze how a document maps to Markdown and which native AFFiNE structures are lossy | Good before export or migration |
 | `list_children` | List direct child docs linked from a document | |
-| `list_backlinks` | List parent or reference docs that link to a document | |
 
 ### Publish and visibility
 
@@ -76,12 +73,9 @@ Use this document as a grouped catalog. For exact schemas, your MCP client shoul
 | --- | --- | --- |
 | `create_doc` | Create a new document | WebSocket-backed |
 | `create_doc_from_markdown` | Create a document from Markdown content | |
-| `create_doc_from_template` | Clone a template doc and substitute `{{variables}}` | Can optionally link the new doc under a parent |
 | `inspect_template_structure` | Inspect a template's native AFFiNE structure and native-clone support | Helps choose a clone strategy |
 | `instantiate_template_native` | Instantiate a template via native AFFiNE block cloning, with optional Markdown fallback | Higher-fidelity than Markdown-only cloning |
-| `duplicate_doc` | Clone a document into a new doc | Can optionally place the copy under a parent |
 | `move_doc` | Move a document in the sidebar by relinking it under another parent | |
-| `batch_create_docs` | Create up to 20 documents in one call | |
 | `delete_doc` | Delete a document | WebSocket-backed and destructive |
 
 ### Content editing
@@ -89,14 +83,11 @@ Use this document as a grouped catalog. For exact schemas, your MCP client shoul
 | Tool | Purpose | Notes |
 | --- | --- | --- |
 | `update_doc_title` | Rename a document in workspace metadata and in the page block | |
-| `append_paragraph` | Append a paragraph block | WebSocket-backed |
-| `append_block` | Append canonical block types with validation and placement control | Supports text, media, embeds, database, and edgeless blocks |
+| `append_block` | Append canonical block types with validation and placement control | Supports text, media, embeds, database, and edgeless blocks. `frame`/`edgeless_text`/`note` accept `x`/`y`/`width`/`height`. `note` with `text` auto-creates a child paragraph so it renders on the edgeless canvas. |
 | `create_semantic_page` | Create an AFFiNE-native page with an intentional section skeleton and native block composition | High-level authoring helper |
 | `append_semantic_section` | Append a semantic section to an existing page by heading title | High-level authoring helper |
 | `append_markdown` | Append Markdown content to an existing document | |
 | `replace_doc_with_markdown` | Replace the main note content with Markdown | Overwrites main note content |
-| `find_and_replace` | Preview or apply text replacement across a document | |
-| `cleanup_orphan_embeds` | Remove linked-doc embeds that point to missing docs | Cleanup-oriented |
 
 ### Tags
 
@@ -123,15 +114,39 @@ Use this document as a grouped catalog. For exact schemas, your MCP client shoul
 | `delete_database_row` | Delete a row by row block id | Destructive |
 | `read_database_columns` | Read schema metadata, types, options, and view mappings | Useful before edits |
 | `read_database_cells` | Read row titles and decoded cell values | Supports row and column filters |
-| `update_database_cell` | Update a single cell or built-in title | `createOption` defaults to `true` for select-like fields |
 | `update_database_row` | Update multiple cells on a row at once | `createOption` defaults to `true` |
 
+## Edgeless canvas and surface elements
+
+AFFiNE's edgeless doc has two layers: top-level edgeless blocks (`note`, `frame`, `edgeless-text`) with `prop:xywh`, and the surface layer (`affine:surface`) which stores free-floating shapes, connectors, canvas text, and groups in `prop:elements.value` — the native BlockSuite representation.
+
+| Tool | Purpose | Notes |
+| --- | --- | --- |
+| `get_edgeless_canvas` | Read the full canvas: edgeless blocks + surface elements with parsed `{x,y,width,height}`, aggregate `bounds`, per-type `elementCounts` | Deterministic z-order (fractional-index sorted). Note entries carry a structured `children` array of their block descendants (`flavour`, `type`, `text`, `language`, `checked`) so markdown-seeded content round-trips faithfully. |
+| `add_surface_element` | Add a `shape`, `connector`, `text`, or `group` to the surface | Shapes: rect/ellipse/diamond/triangle with fill, stroke, and text. Connectors accept `sourceId`/`targetId` and optional `sourcePosition`/`targetPosition` relative `[x,y]` in `[0,1]`. When both endpoints are bound by id and neither position is supplied, they auto-snap to BlockSuite's four tangent-carrying side-midpoints based on relative bounds. Creates the surface block if the doc doesn't have one. |
+| `list_surface_elements` | List all surface elements (optionally filter by `type` or `elementId`) | Returns raw `xywh` plus parsed `bounds` sorted by fractional `index` ascending; serializes `Y.Text` fields to plain strings. |
+| `update_surface_element` | Partially update an element by id | `x`/`y`/`width`/`height` merge with current `xywh` (move without resizing, or vice versa). `text`/`label`/`title` replace their `Y.Text` wholesale. Fields not applicable to the element's type come back in the response `ignored` list. |
+| `delete_surface_element` | Delete an element by id | `pruneConnectors: true` additionally removes any connectors referencing the deleted element. |
+| `update_frame_children` | Replace a frame block's contents wholesale | Every resolved id (surface element or edgeless block) goes into `prop:childElementIds` and comes back in `ownedIds`; unknown ids in `missing`. Default `resizeToFit: true` recomputes xywh to match new contents + `padding` + title band; pass `resizeToFit: false` to preserve the current box. Pass `[]` to clear ownership (resize skipped). |
+| `update_edgeless_block` | Partially update a note/frame/edgeless-text block | `x`/`y`/`width`/`height` merge with current `prop:xywh`; `background` replaces `prop:background`. Fields not applicable to the flavour come back under `ignored`. Use for repositioning / resizing / recoloring without re-creating the block. |
+| `delete_block` | Delete a block by id | Removes descendants and unlinks from the parent's `sys:children` by default. `deleteChildren: false` keeps descendants orphaned; `pruneConnectors: true` also drops surface connectors referencing any deleted id. Refuses `affine:page`. |
+
+### Layout helpers on `append_block`
+
+When the new block is a frame/note/edgeless_text on the canvas, `append_block` accepts three optional fields that compute coordinates from the current doc state instead of the caller doing arithmetic:
+
+| Field | Applies to | Purpose |
+| --- | --- | --- |
+| `markdown` | `type="note"` | Parse markdown into heading/paragraph/list/code child blocks inside the note. Height auto-estimated from the content when `height` is omitted. |
+| `childElementIds: [id, ...]` | `type="frame"` | The frame's contents. Accepts ids of surface elements (shapes/connectors/groups) AND edgeless blocks (notes/frames/edgeless-text) — every resolved id goes into `prop:childElementIds`, matching what BlockSuite's editor writes when you drag members into a frame. Dragging the frame drags every owned member. Unresolved ids come back under `missing`. If `width`/`height` are omitted, the frame is sized to the union of resolvable bounds + `padding` + a 30px title band. |
+| `stackAfter: { blockId, direction?, gap? }` | any canvas block | Position relative to one or more existing siblings. `blockId` may be an array — picks whichever ref is furthest in the stack direction (useful when stacking below a row of columns) and centers the new block on the union bounds' orthogonal axis (when widths match, same as inheriting the anchor's x). Caller-provided `x` / `y` on the orthogonal axis still wins. Default `gap` is direction-aware: **80px horizontal** (left/right), **40px vertical** (up/down) — mirrors native-flowchart spacing where the flow axis gets more breathing room. |
+| `padding` | used by `childElementIds` auto-sizing and as fallback `gap` for `stackAfter` | Default 40. Explicit `padding` on the block overrides the direction-aware default; explicit `stackAfter.gap` wins over both. |
+
 ## Comments
 
 | Tool | Purpose | Notes |
 | --- | --- | --- |
 | `list_comments` | List comments on a document | |
-| `list_unresolved_threads` | List unresolved comment threads on a document | Useful for review and triage flows |
 | `create_comment` | Create a comment on a document | |
 | `update_comment` | Update comment content | |
 | `delete_comment` | Delete a comment | Destructive |

package/docs/workflow-recipes.md

@@ -30,7 +30,7 @@ Use when:
 
 Typical tool sequence:
 
-1. `search_docs` or `get_doc_by_title` to find the parent
+1. `search_docs` to find the parent
 2. `create_doc` or `create_doc_from_markdown`
 3. `move_doc` if you created the doc before deciding its final parent
 4. `list_children` to verify placement
@@ -49,7 +49,7 @@ Use when:
 Typical tool sequence:
 
 1. `list_tags`
-2. `get_docs_by_tag` or `list_docs_by_tag`
+2. `list_docs_by_tag` or `search_docs` with `tag`
 3. `update_doc_title`
 4. `add_tag_to_doc` or `remove_tag_from_doc`
 
@@ -67,7 +67,7 @@ Use when:
 Typical tool sequence:
 
 1. `read_doc`
-2. `append_paragraph`, `append_block`, or `append_markdown`
+2. `append_block` or `append_markdown`
 3. `replace_doc_with_markdown` only when you intend to overwrite the main note
 
 Prompt example:
@@ -87,7 +87,7 @@ Typical tool sequence:
 2. `read_database_columns` to inspect schema
 3. `add_database_column` if needed
 4. `add_database_row`
-5. `update_database_cell` or `update_database_row`
+5. `update_database_row`
 6. `read_database_cells` to verify
 
 Prompt example:
@@ -133,15 +133,15 @@ Prompt example:
 Use when:
 
 - you need a markdown backup
-- you want to clone a page
-- you need to remove stale linked-doc embeds
+- you want to recreate a page from Markdown
+- you need to inspect linked child pages
 
 Typical tool sequence:
 
-1. `export_doc_markdown` or `duplicate_doc`
-2. `list_backlinks` or `list_children` if you need structural context
-3. `cleanup_orphan_embeds` if linked-doc embeds reference deleted pages
+1. `export_doc_markdown`
+2. `create_doc_from_markdown` if you need a Markdown-based copy
+3. `list_children` if you need structural context
 
 Prompt example:
 
-> Duplicate the template page under the current parent, export the original as Markdown, and clean up any orphaned linked-doc embeds on the copy.
+> Export the template page as Markdown, create a copy under the current parent, and verify the copied page's child links.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "affine-mcp-server",
-  "version": "1.13.0",
+  "version": "2.0.0",
   "private": false,
   "type": "module",
   "description": "Model Context Protocol server for AFFiNE - enables AI assistants to interact with AFFiNE workspaces, documents, and collaboration features.",
@@ -48,6 +48,10 @@
     "test:data-view": "node tests/test-data-view.mjs",
     "test:doc-discovery": "node tests/test-doc-discovery.mjs",
     "test:create-placement": "node tests/test-create-placement.mjs",
+    "test:surface-elements": "node tests/test-surface-elements.mjs",
+    "test:surface-element-gating": "node scripts/verify-surface-element-gating.mjs",
+    "test:edgeless-seed": "node tests/test-edgeless-canvas-setup.mjs",
+    "test:edgeless-ui": "npx playwright test tests/playwright/verify-edgeless-canvas.pw.ts --config tests/playwright/playwright.config.ts",
     "test:capabilities-fidelity": "node tests/test-capabilities-fidelity.mjs",
     "test:native-template": "node tests/test-native-template-instantiation.mjs",
     "test:data-view-ui": "npx playwright test tests/playwright/verify-data-view.pw.ts --config tests/playwright/playwright.config.ts",

package/tool-manifest.json

@@ -1,25 +1,22 @@
 {
-  "version": "1.13.0",
+  "version": "2.0.0",
   "tools": [
     "add_database_column",
     "add_database_row",
     "add_doc_to_collection",
     "add_organize_link",
+    "add_surface_element",
     "add_tag_to_doc",
     "analyze_doc_fidelity",
     "append_block",
     "append_markdown",
-    "append_paragraph",
     "append_semantic_section",
-    "batch_create_docs",
     "cleanup_blobs",
-    "cleanup_orphan_embeds",
     "compose_database_from_intent",
     "create_collection",
     "create_comment",
     "create_doc",
     "create_doc_from_markdown",
-    "create_doc_from_template",
     "create_folder",
     "create_semantic_page",
     "create_tag",
@@ -27,29 +24,27 @@
     "create_workspace_blueprint",
     "current_user",
     "delete_blob",
+    "delete_block",
     "delete_collection",
     "delete_comment",
     "delete_database_row",
     "delete_doc",
     "delete_folder",
     "delete_organize_link",
+    "delete_surface_element",
     "delete_workspace",
-    "duplicate_doc",
     "export_doc_markdown",
     "export_with_fidelity_report",
-    "find_and_replace",
     "generate_access_token",
     "get_capabilities",
     "get_collection",
     "get_doc",
-    "get_doc_by_title",
-    "get_docs_by_tag",
+    "get_edgeless_canvas",
     "get_orphan_docs",
     "get_workspace",
     "inspect_template_structure",
     "instantiate_template_native",
     "list_access_tokens",
-    "list_backlinks",
     "list_children",
     "list_collections",
     "list_comments",
@@ -58,8 +53,8 @@
     "list_histories",
     "list_notifications",
     "list_organize_nodes",
+    "list_surface_elements",
     "list_tags",
-    "list_unresolved_threads",
     "list_workspace_tree",
     "list_workspaces",
     "move_doc",
@@ -81,11 +76,13 @@
     "update_collection",
     "update_collection_rules",
     "update_comment",
-    "update_database_cell",
     "update_database_row",
     "update_doc_title",
+    "update_edgeless_block",
+    "update_frame_children",
     "update_profile",
     "update_settings",
+    "update_surface_element",
     "update_workspace",
     "upload_blob"
   ]