@mseep/affine-mcp-server 2.3.0

package/docs/client-setup.md

@@ -0,0 +1,174 @@
+# Client Setup
+
+This guide provides copy-paste configuration for the most common MCP clients.
+
+## Client matrix
+
+| Client | Transport | Recommended auth | Best starting point |
+| --- | --- | --- | --- |
+| Claude Code | stdio | Saved config or API token | `affine-mcp login` + `command: "affine-mcp"` |
+| Claude Desktop | stdio | Saved config or API token | Config JSON with `command: "affine-mcp"` |
+| Codex CLI | stdio | Saved config or API token | `codex mcp add affine -- affine-mcp` |
+| Cursor | stdio | Saved config or API token | `.cursor/mcp.json` |
+| Remote HTTP MCP clients | HTTP | Bearer token or OAuth | See [configuration and deployment](configuration-and-deployment.md#http-mode) |
+
+## Claude Code
+
+Project-local `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "affine": {
+      "command": "affine-mcp"
+    }
+  }
+}
+```
+
+Explicit environment variables:
+
+```json
+{
+  "mcpServers": {
+    "affine": {
+      "command": "affine-mcp",
+      "env": {
+        "AFFINE_BASE_URL": "https://app.affine.pro",
+        "AFFINE_API_TOKEN": "ut_xxx"
+      }
+    }
+  }
+}
+```
+
+## Claude Desktop
+
+Typical config paths:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`
+- Linux: `~/.config/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "affine": {
+      "command": "affine-mcp",
+      "env": {
+        "AFFINE_BASE_URL": "https://app.affine.pro",
+        "AFFINE_API_TOKEN": "ut_xxx"
+      }
+    }
+  }
+}
+```
+
+Self-hosted email/password example:
+
+```json
+{
+  "mcpServers": {
+    "affine": {
+      "command": "affine-mcp",
+      "env": {
+        "AFFINE_BASE_URL": "https://your-self-hosted-affine.com",
+        "AFFINE_EMAIL": "you@example.com",
+        "AFFINE_PASSWORD": "secret"
+      }
+    }
+  }
+}
+```
+
+## Codex CLI
+
+With saved config:
+
+```bash
+codex mcp add affine -- affine-mcp
+```
+
+With an API token:
+
+```bash
+codex mcp add affine \
+  --env AFFINE_BASE_URL=https://app.affine.pro \
+  --env AFFINE_API_TOKEN=ut_xxx \
+  -- affine-mcp
+```
+
+With self-hosted email/password:
+
+```bash
+codex mcp add affine \
+  --env AFFINE_BASE_URL=https://your-self-hosted-affine.com \
+  --env 'AFFINE_EMAIL=you@example.com' \
+  --env 'AFFINE_PASSWORD=secret' \
+  -- affine-mcp
+```
+
+## Cursor
+
+Project-local `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "affine": {
+      "command": "affine-mcp",
+      "env": {
+        "AFFINE_BASE_URL": "https://app.affine.pro",
+        "AFFINE_API_TOKEN": "ut_xxx"
+      }
+    }
+  }
+}
+```
+
+`npx` variant:
+
+```json
+{
+  "mcpServers": {
+    "affine": {
+      "command": "npx",
+      "args": ["-y", "-p", "affine-mcp-server", "affine-mcp"],
+      "env": {
+        "AFFINE_BASE_URL": "https://app.affine.pro",
+        "AFFINE_API_TOKEN": "ut_xxx"
+      }
+    }
+  }
+}
+```
+
+## Remote HTTP MCP clients
+
+If your client connects to MCP over HTTP instead of stdio, configure the server first by following [configuration and deployment](configuration-and-deployment.md#http-mode).
+
+If you want the fastest containerized setup, start with the Docker quick start in [getting started](getting-started.md#path-c-run-from-the-docker-image).
+
+Typical bearer-mode client config:
+
+```json
+{
+  "mcpServers": {
+    "affine": {
+      "type": "http",
+      "url": "https://mcp.example.com/mcp",
+      "headers": {
+        "Authorization": "Bearer your-strong-secret"
+      }
+    }
+  }
+}
+```
+
+## Setup tips
+
+- Prefer `affine-mcp login` for local development
+- Prefer `AFFINE_API_TOKEN` for AFFiNE Cloud
+- Prefer tokens over passwords for automated environments
+- If your shell treats `!` specially, wrap passwords in single quotes
+- Use `affine-mcp doctor` whenever a client config looks correct but the connection still fails

package/docs/configuration-and-deployment.md

@@ -0,0 +1,265 @@
+# Configuration and Deployment
+
+This guide covers configuration precedence, environment variables, auth strategy, Docker, HTTP mode, and least-privilege deployment patterns.
+
+## Configuration precedence
+
+The server resolves configuration in this order:
+
+1. Environment variables
+2. Saved config file at `~/.config/affine-mcp/config`
+3. Built-in defaults
+
+Auth priority within the active configuration:
+
+1. `AFFINE_API_TOKEN`
+2. `AFFINE_COOKIE`
+3. `AFFINE_EMAIL` and `AFFINE_PASSWORD`
+
+## Environment variables
+
+### Core configuration
+
+| Variable | Required | Default | Notes |
+| --- | --- | --- | --- |
+| `AFFINE_BASE_URL` | Yes | None | Base URL for AFFiNE Cloud or self-hosted AFFiNE |
+| `AFFINE_GRAPHQL_PATH` | No | `/graphql` | Override only if your AFFiNE deployment uses a custom GraphQL path |
+| `AFFINE_WORKSPACE_ID` | No | Auto-detected when possible | Pins the active workspace |
+| `AFFINE_LOGIN_AT_START` | No | async login behavior | Set to `sync` only when you must block startup on login |
+
+### Authentication
+
+| Variable | Use when | Notes |
+| --- | --- | --- |
+| `AFFINE_API_TOKEN` | Preferred for cloud and automation | Recommended default for stable operation |
+| `AFFINE_COOKIE` | You must reuse browser-authenticated state | Copy only from a trusted local browser session |
+| `AFFINE_EMAIL` | Self-hosted email/password sign-in | Must be paired with `AFFINE_PASSWORD` |
+| `AFFINE_PASSWORD` | Self-hosted email/password sign-in | Avoid for automated public deployments |
+
+### Tool filtering
+
+| 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 |
+
+### HTTP mode
+
+| Variable | Required | Default | Notes |
+| --- | --- | --- | --- |
+| `MCP_TRANSPORT` | Yes for HTTP mode | stdio | Set to `http` |
+| `PORT` | No | `3000` | Commonly injected by container platforms |
+| `AFFINE_MCP_AUTH_MODE` | No | `bearer` | `bearer` or `oauth` |
+| `AFFINE_MCP_HTTP_HOST` | No | platform default | Use `0.0.0.0` in containers |
+| `AFFINE_MCP_HTTP_ALLOWED_ORIGINS` | No | none | Comma-separated list for browser clients |
+| `AFFINE_MCP_HTTP_ALLOW_ALL_ORIGINS` | No | `false` | Testing only; rejected in OAuth mode |
+| `AFFINE_MCP_HTTP_TOKEN` | Required in bearer mode | none | Shared bearer token for `/mcp`, `/sse`, and `/messages` |
+| `AFFINE_MCP_PUBLIC_BASE_URL` | Required in OAuth mode | none | Public base URL for this MCP server |
+| `AFFINE_OAUTH_ISSUER_URL` | Required in OAuth mode | none | OAuth issuer discovery URL |
+| `AFFINE_OAUTH_SCOPES` | No | `mcp` | Scopes advertised for OAuth-protected access |
+
+## Auth strategy matrix
+
+| Environment | Recommended auth | Why |
+| --- | --- | --- |
+| AFFiNE Cloud + stdio | `AFFINE_API_TOKEN` or saved config from `affine-mcp login` | Cloud sign-in is blocked by Cloudflare |
+| AFFiNE Cloud + HTTP | `AFFINE_API_TOKEN` + bearer or OAuth at the MCP layer | Stable and automation-friendly |
+| Self-hosted + stdio | API token first, email/password second | Token reduces startup and sign-in failure modes |
+| Self-hosted + HTTP | API token first, cookie or email/password only if necessary | Better for unattended deployments |
+
+Important note for AFFiNE Cloud:
+
+- Programmatic email/password sign-in to `/api/auth/sign-in` is not supported because Cloudflare blocks those requests
+
+## Docker
+
+Prebuilt images are published to GHCR:
+
+- `ghcr.io/dawncr0w/affine-mcp-server:latest`
+- `ghcr.io/dawncr0w/affine-mcp-server:1.12.0`
+
+Example:
+
+```bash
+docker run -d \
+  -p 3000:3000 \
+  -e MCP_TRANSPORT=http \
+  -e AFFINE_BASE_URL=https://your-affine-instance.com \
+  -e AFFINE_API_TOKEN=ut_your_token \
+  -e AFFINE_MCP_AUTH_MODE=bearer \
+  -e AFFINE_MCP_HTTP_TOKEN=your-strong-secret \
+  ghcr.io/dawncr0w/affine-mcp-server:latest
+```
+
+Health endpoints:
+
+- `/healthz`
+- `/readyz`
+
+## HTTP mode
+
+HTTP mode exposes:
+
+- `/mcp` - Streamable HTTP MCP endpoint
+- `/sse` - SSE endpoint for older-compatible clients
+- `/messages` - message endpoint for older-compatible clients
+- `/healthz` - liveness probe
+- `/readyz` - readiness probe
+
+### Bearer mode
+
+```bash
+export MCP_TRANSPORT=http
+export AFFINE_MCP_AUTH_MODE=bearer
+export AFFINE_BASE_URL="https://app.affine.pro"
+export AFFINE_API_TOKEN="ut_xxx"
+export AFFINE_MCP_HTTP_HOST="0.0.0.0"
+export AFFINE_MCP_HTTP_TOKEN="your-super-secret-token"
+export PORT=3000
+
+npm run start:http
+```
+
+Use bearer mode when:
+
+- the client can inject a shared secret header
+- you want the simplest remote deployment
+- you do not need OAuth discovery and token validation
+
+### OAuth mode
+
+```bash
+export MCP_TRANSPORT=http
+export AFFINE_MCP_AUTH_MODE=oauth
+export AFFINE_BASE_URL="https://app.affine.pro"
+export AFFINE_API_TOKEN="your-affine-service-token"
+export AFFINE_MCP_HTTP_HOST="0.0.0.0"
+export AFFINE_MCP_PUBLIC_BASE_URL="https://mcp.yourdomain.com"
+export AFFINE_OAUTH_ISSUER_URL="https://auth.yourdomain.com"
+export AFFINE_OAUTH_SCOPES="mcp"
+export PORT=3000
+
+npm run start:http
+```
+
+OAuth mode behavior:
+
+- exposes `/.well-known/oauth-protected-resource`
+- returns `401` + `WWW-Authenticate` challenge for unauthenticated `/mcp` requests
+- disables `AFFINE_MCP_HTTP_TOKEN` and `?token=`
+- does not register `sign_in`
+- still requires `AFFINE_API_TOKEN` so the server can call AFFiNE
+
+## 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:
+
+```json
+{
+  "AFFINE_DISABLED_GROUPS": "comments,history,blobs,users"
+}
+```
+
+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
+
+Example:
+
+```json
+{
+  "AFFINE_DISABLED_TOOLS": "delete_workspace,delete_doc"
+}
+```
+
+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
+
+Before exposing the server remotely, confirm:
+
+- `AFFINE_BASE_URL` is reachable from the MCP host
+- `AFFINE_API_TOKEN` works through `affine-mcp status` or an equivalent health path
+- `MCP_TRANSPORT=http` is set
+- `AFFINE_MCP_AUTH_MODE` is correct for your client model
+- `AFFINE_MCP_HTTP_HOST=0.0.0.0` is set in containerized deployments
+- `AFFINE_MCP_HTTP_ALLOWED_ORIGINS` is set for browser-based clients
+- `/healthz` and `/readyz` are wired into your platform checks
+- destructive tools are filtered if your deployment should be read-only or constrained
+
+## Troubleshooting pointers
+
+- Cloudflare / sign-in failures: switch to an API token
+- Startup timeouts: avoid `AFFINE_LOGIN_AT_START=sync` unless required
+- Missing tools: confirm filtering variables are not removing them
+- Browser CORS failures: verify `AFFINE_MCP_HTTP_ALLOWED_ORIGINS`
+- OAuth failures: verify issuer discovery metadata and JWKS availability

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.