affine-mcp-server 1.13.0 → 2.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 A Model Context Protocol (MCP) server for AFFiNE. It exposes AFFiNE workspaces and documents to AI assistants over stdio (default) or HTTP (`/mcp`) and supports both AFFiNE Cloud and self-hosted deployments.
 
-[![Version](https://img.shields.io/badge/version-1.13.0-blue)](https://github.com/dawncr0w/affine-mcp-server/releases)
+[![Version](https://img.shields.io/badge/version-2.0.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)
@@ -29,7 +29,6 @@ A Model Context Protocol (MCP) server for AFFiNE. It exposes AFFiNE workspaces a
 ## Overview
 
 AFFiNE MCP Server is designed for three common scenarios:
-
 - Run a local stdio MCP server for Claude Code, Codex CLI, Cursor, or Claude Desktop
 - Expose a remote HTTP MCP endpoint for hosted or browser-connected clients
 - Automate AFFiNE workspace, document, database, organization, and comment workflows through a stable MCP tool surface
@@ -39,7 +38,7 @@ Highlights:
 - Supports AFFiNE Cloud and self-hosted AFFiNE instances
 - Supports stdio and HTTP transports
 - Supports token, cookie, and email/password authentication
-- Exposes 87 canonical MCP tools backed by AFFiNE GraphQL and WebSocket APIs
+- Exposes 84 canonical MCP tools backed by AFFiNE GraphQL and WebSocket APIs
 - Includes semantic page composition, native template instantiation, database intent composition, capability and fidelity reporting, and workspace blueprint helpers
 - Includes Docker images, health probes, and end-to-end test coverage
 
@@ -49,10 +48,9 @@ Scope boundaries:
 - Browser-local workspaces stored only in local storage are not available through AFFiNE server APIs
 - AFFiNE Cloud requires API-token-based access for MCP usage; programmatic email/password sign-in is blocked by Cloudflare
 
-> New in v1.13.0: Added high-level semantic page, native template, fidelity, and workspace blueprint workflows, plus structured receipts and productized setup docs.
+> New in v2.0.0: Added native edgeless canvas tools and shipped a slimmer 84-tool public surface with least-privilege profiles for read-only, core, and authoring deployments.
 
 ## Choose Your Path
-
 | Goal | Start here |
 | --- | --- |
 | Set up a local stdio server with the least friction | [docs/getting-started.md](docs/getting-started.md) |
@@ -172,14 +170,16 @@ Domains:
 
 - Workspace: create, inspect, update, delete, and traverse workspaces
 - Organization: collections, collection-rule sync, workspace blueprints, and experimental organize or folder helpers
-- Documents: search, read, create, publish, move, tag, import/export, semantic composition, template inspection and native instantiation, capability and fidelity reporting, and text mutation
-- Databases: create columns, add rows, update cells, inspect schema, and compose database structures from intent
-- Comments: list, create, update, delete, resolve, and list unresolved threads
+- Documents: search, read, create, publish, move, tag, import/export, semantic composition, template inspection and native instantiation, capability and fidelity reporting, and block-level mutation
+- Databases: create columns, add rows, update rows, inspect schema, and compose database structures from intent
+- Comments: list, create, update, delete, and resolve
 - History: version history listing
 - Users and tokens: current user, sign-in, profile/settings, personal access tokens
 - Notifications: list and mark notifications as read
 - Blob storage: upload, delete, and cleanup blobs
 
+Use `AFFINE_TOOL_PROFILE=read_only`, `core`, or `authoring` when a deployment should expose a smaller surface than the complete `full` default. You can also combine profiles with `AFFINE_DISABLED_GROUPS` such as `docs.database`, `destructive`, or `admin` for finer control.
+
 For the grouped catalog, notes, and operational caveats, see [docs/tool-reference.md](docs/tool-reference.md).
 
 ## Documentation Map
@@ -191,6 +191,7 @@ For the grouped catalog, notes, and operational caveats, see [docs/tool-referenc
 | [docs/configuration-and-deployment.md](docs/configuration-and-deployment.md) | Environment variables, auth modes, Docker, HTTP mode, and deployment guidance |
 | [docs/workflow-recipes.md](docs/workflow-recipes.md) | End-to-end workflows and example tool sequences |
 | [docs/tool-reference.md](docs/tool-reference.md) | Tool catalog grouped by domain |
+| [docs/edgeless-canvas-cookbook.md](docs/edgeless-canvas-cookbook.md) | Edgeless canvas layout helpers and surface elements, worked end-to-end |
 | [CONTRIBUTING.md](CONTRIBUTING.md) | Contributor workflow |
 | [SECURITY.md](SECURITY.md) | Security reporting |
 

package/dist/edgeless/layout.js

@@ -0,0 +1,222 @@
+/** Pure-function edgeless-canvas layout helpers. No Y.Doc, no MCP wiring. */
+/** Only these four positions carry tangent vectors in BlockSuite's connector model. */
+export const SIDE_TO_NORMALIZED_POSITION = {
+    top: [0.5, 0],
+    bottom: [0.5, 1],
+    left: [0, 0.5],
+    right: [1, 0.5],
+};
+/** Pick connector sides for a src/tgt pair. Single-axis → that axis; diagonal →
+ *  dominant by center displacement; overlap → 4×4 midpoint minimization. Ports
+ *  BlockSuite's `getNearestConnectableAnchor` (`connector-manager.ts:174-190`). */
+export function pickConnectorSides(src, tgt) {
+    const srcBottom = src.y + src.h;
+    const srcRight = src.x + src.w;
+    const tgtBottom = tgt.y + tgt.h;
+    const tgtRight = tgt.x + tgt.w;
+    const above = srcBottom <= tgt.y;
+    const below = tgtBottom <= src.y;
+    const leftOf = srcRight <= tgt.x;
+    const rightOf = tgtRight <= src.x;
+    const vSeparated = above || below;
+    const hSeparated = leftOf || rightOf;
+    if (vSeparated && !hSeparated) {
+        return above ? { from: "bottom", to: "top" } : { from: "top", to: "bottom" };
+    }
+    if (hSeparated && !vSeparated) {
+        return leftOf ? { from: "right", to: "left" } : { from: "left", to: "right" };
+    }
+    if (vSeparated && hSeparated) {
+        const dx = (tgt.x + tgt.w / 2) - (src.x + src.w / 2);
+        const dy = (tgt.y + tgt.h / 2) - (src.y + src.h / 2);
+        if (Math.abs(dx) >= Math.abs(dy)) {
+            return dx >= 0 ? { from: "right", to: "left" } : { from: "left", to: "right" };
+        }
+        return dy >= 0 ? { from: "bottom", to: "top" } : { from: "top", to: "bottom" };
+    }
+    const anchors = (b) => [
+        { side: "top", x: b.x + b.w / 2, y: b.y },
+        { side: "bottom", x: b.x + b.w / 2, y: b.y + b.h },
+        { side: "left", x: b.x, y: b.y + b.h / 2 },
+        { side: "right", x: b.x + b.w, y: b.y + b.h / 2 },
+    ];
+    const srcA = anchors(src);
+    const tgtA = anchors(tgt);
+    let best = {
+        from: "bottom",
+        to: "top",
+        dist: Infinity,
+    };
+    for (const a of srcA) {
+        for (const b of tgtA) {
+            const dx = b.x - a.x;
+            const dy = b.y - a.y;
+            const dist = dx * dx + dy * dy;
+            if (dist < best.dist)
+                best = { from: a.side, to: b.side, dist };
+        }
+    }
+    return { from: best.from, to: best.to };
+}
+/** Enclosing bound of `children`, expanded by `padding` and `titleBand` (extra on top for a frame title). */
+export function encloseBounds(children, opts = {}) {
+    if (children.length === 0)
+        return null;
+    const padding = opts.padding ?? 40;
+    const titleBand = opts.titleBand ?? 60;
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    for (const c of children) {
+        minX = Math.min(minX, c.x);
+        minY = Math.min(minY, c.y);
+        maxX = Math.max(maxX, c.x + c.w);
+        maxY = Math.max(maxY, c.y + c.h);
+    }
+    return {
+        x: Math.floor(minX - padding),
+        y: Math.floor(minY - padding - titleBand),
+        w: Math.max(1, Math.ceil(maxX - minX + padding * 2)),
+        h: Math.max(1, Math.ceil(maxY - minY + padding * 2 + titleBand)),
+    };
+}
+/** Pick the bound furthest along `direction` (bottommost for `"down"`, etc). */
+export function pickFurthestInDirection(candidates, direction) {
+    if (candidates.length === 0)
+        return null;
+    let chosen = candidates[0];
+    for (let i = 1; i < candidates.length; i++) {
+        const c = candidates[i];
+        if (direction === "down" && c.y + c.h > chosen.y + chosen.h)
+            chosen = c;
+        else if (direction === "up" && c.y < chosen.y)
+            chosen = c;
+        else if (direction === "right" && c.x + c.w > chosen.x + chosen.w)
+            chosen = c;
+        else if (direction === "left" && c.x < chosen.x)
+            chosen = c;
+    }
+    return chosen;
+}
+/** Parse BlockSuite's `[x,y,w,h]` string. Returns null if the input isn't well-formed. */
+export function parseXywhString(value) {
+    if (typeof value !== "string")
+        return null;
+    const m = value.match(/^\s*\[\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*\]\s*$/);
+    if (!m)
+        return null;
+    return { x: Number(m[1]), y: Number(m[2]), width: Number(m[3]), height: Number(m[4]) };
+}
+/** Inverse of `parseXywhString`. */
+export function formatXywhString(x, y, width, height) {
+    return `[${x},${y},${width},${height}]`;
+}
+/** Asymmetric defaults: notes default to wide/short, so equal gaps feel tight horizontally. */
+export const DEFAULT_STACK_GAP_VERTICAL = 40;
+export const DEFAULT_STACK_GAP_HORIZONTAL = 80;
+/** BlockSuite's createDefaultDoc constants (packages/affine/model/src/consts/note.ts). */
+export const DEFAULT_PAGE_BLOCK_WIDTH = 800;
+export const DEFAULT_NOTE_HEIGHT = 92;
+export const DEFAULT_NOTE_XYWH = `[0,0,${DEFAULT_PAGE_BLOCK_WIDTH},${DEFAULT_NOTE_HEIGHT}]`;
+/** Position a new block relative to `ref` along `direction`. The orthogonal axis
+ *  inherits from `ref` unless `preserveX` / `preserveY` is supplied. */
+export function stackRelativeTo(ref, newSize, opts = {}) {
+    const direction = opts.direction ?? "down";
+    const isHorizontal = direction === "left" || direction === "right";
+    const gap = opts.gap ?? (isHorizontal ? DEFAULT_STACK_GAP_HORIZONTAL : DEFAULT_STACK_GAP_VERTICAL);
+    if (direction === "down") {
+        return { x: opts.preserveX ?? ref.x, y: ref.y + ref.h + gap };
+    }
+    if (direction === "up") {
+        return { x: opts.preserveX ?? ref.x, y: ref.y - gap - newSize.h };
+    }
+    if (direction === "right") {
+        return { x: ref.x + ref.w + gap, y: opts.preserveY ?? ref.y };
+    }
+    return { x: ref.x - gap - newSize.w, y: opts.preserveY ?? ref.y };
+}
+/** Over-estimate note height from markdown. BlockSuite's `EdgelessNoteMask`
+ *  `ResizeObserver` corrects `prop:xywh.h` to the DOM-measured height on first render. */
+export function estimateNoteHeightForMarkdown(markdown, widthPx) {
+    const NOTE_V_PADDING = 64;
+    const BODY_LINE_H = 34;
+    const CHAR_WIDTH = 8;
+    const H_PADDING = 52;
+    const H1_LINE_H = 58;
+    const H2_LINE_H = 48;
+    const H3_LINE_H = 40;
+    const CODE_LINE_H = 32;
+    const CODE_FENCE_PAD = 30;
+    const CODE_BLOCK_EXTRA = 20;
+    const BLANK_LINE_H = 14;
+    const usableWidth = Math.max(80, widthPx - H_PADDING);
+    const charsPerLine = Math.max(16, Math.floor(usableWidth / CHAR_WIDTH));
+    let total = NOTE_V_PADDING;
+    let inCode = false;
+    const lines = markdown.split("\n");
+    for (const raw of lines) {
+        const line = raw.trim();
+        if (line.startsWith("```")) {
+            inCode = !inCode;
+            total += CODE_FENCE_PAD;
+            if (inCode)
+                total += CODE_BLOCK_EXTRA;
+            continue;
+        }
+        if (inCode) {
+            total += CODE_LINE_H;
+            continue;
+        }
+        if (line === "") {
+            total += BLANK_LINE_H;
+            continue;
+        }
+        let lineHeight = BODY_LINE_H;
+        let prefixChars = 0;
+        if (/^#\s/.test(line)) {
+            lineHeight = H1_LINE_H;
+            prefixChars = 2;
+        }
+        else if (/^##\s/.test(line)) {
+            lineHeight = H2_LINE_H;
+            prefixChars = 3;
+        }
+        else if (/^###\s/.test(line)) {
+            lineHeight = H3_LINE_H;
+            prefixChars = 4;
+        }
+        else if (/^[-*]\s/.test(line)) {
+            prefixChars = 2;
+        }
+        else if (/^\d+\.\s/.test(line)) {
+            prefixChars = 3;
+        }
+        const contentChars = Math.max(1, line.length - prefixChars);
+        const wraps = Math.max(1, Math.ceil(contentChars / charsPerLine));
+        total += lineHeight * wraps;
+    }
+    return Math.max(120, Math.ceil(total));
+}
+/** Initial `labelXYWH` at source→target midpoint so BlockSuite's `hasLabel()` gate passes on first render. */
+export function estimateConnectorLabelXYWH(labelText, fontSize, midpoint, maxWidth) {
+    const charWidth = fontSize * 0.55;
+    const estimatedW = Math.max(16, Math.ceil(labelText.length * charWidth));
+    const w = Math.min(estimatedW, maxWidth);
+    const h = Math.ceil(fontSize + 4);
+    if (!midpoint)
+        return [0, 0, Math.max(w, 16), Math.max(h, 16)];
+    return [Math.round(midpoint.x - w / 2), Math.round(midpoint.y - h / 2), w, h];
+}
+/** Sort by fractional `index` string ascending. Y.Map iteration order is not stable across reloads. */
+export function sortByFractionalIndex(entries) {
+    return entries.slice().sort((a, b) => {
+        const ai = typeof a.index === "string" ? a.index : "";
+        const bi = typeof b.index === "string" ? b.index : "";
+        if (ai < bi)
+            return -1;
+        if (ai > bi)
+            return 1;
+        return 0;
+    });
+}

package/dist/index.js

@@ -18,6 +18,7 @@ import { runCli } from "./cli.js";
 import { startHttpMcpServer } from "./sse.js";
 import { existsSync } from "fs";
 import { CONFIG_FILE } from "./config.js";
+import { createToolFilter, toolFilterRequiresRegisterTool } from "./toolSurface.js";
 // CLI commands: affine-mcp login|status|logout|version
 const rawArgs = process.argv.slice(2);
 const cliArgs = rawArgs[0] === "--" ? rawArgs.slice(1) : rawArgs;
@@ -43,21 +44,8 @@ if (subcommand) {
 const config = loadConfig();
 const transportMode = (process.env.MCP_TRANSPORT || "stdio").toLowerCase();
 const useHttpTransport = transportMode === "sse" || transportMode === "http" || transportMode === "streamable";
-// ---------------------------------------------------------------------------
-// Tool filtering — parsed once at module load (not per-session in HTTP mode)
-// ---------------------------------------------------------------------------
-const KNOWN_GROUPS = new Set([
-    "workspaces", "docs", "comments", "history", "organize",
-    "users", "access_tokens", "blobs", "notifications",
-]);
-const DISABLED_GROUPS = new Set((process.env.AFFINE_DISABLED_GROUPS || "")
-    .split(",")
-    .map((s) => s.trim().toLowerCase())
-    .filter(Boolean));
-const DISABLED_TOOLS = new Set((process.env.AFFINE_DISABLED_TOOLS || "")
-    .split(",")
-    .map((s) => s.trim())
-    .filter(Boolean));
+// Tool filtering is parsed once at module load (not per-session in HTTP mode).
+const toolFilter = createToolFilter(process.env);
 // Startup diagnostics (visible in Claude Code MCP server logs via stderr)
 console.error(`[affine-mcp] Config: ${CONFIG_FILE} (${existsSync(CONFIG_FILE) ? 'found' : 'missing'})`);
 console.error(`[affine-mcp] Endpoint: ${config.baseUrl}${config.graphqlPath}`);
@@ -70,12 +58,8 @@ if (hasAuth && config.baseUrl.startsWith("http://")
     console.error("WARNING: Credentials configured over plain HTTP. Use HTTPS for remote servers.");
 }
 console.error(`[affine-mcp] Workspace: ${config.defaultWorkspaceId ? 'set' : '(none)'}`);
-// Warn about unknown group names (likely typos) before they silently do nothing
-for (const g of DISABLED_GROUPS) {
-    if (!KNOWN_GROUPS.has(g)) {
-        console.error(`[affine-mcp] WARNING: Unknown group "${g}" in AFFINE_DISABLED_GROUPS — ` +
-            `valid groups: ${[...KNOWN_GROUPS].join(", ")}`);
-    }
+for (const warning of toolFilter.warnings) {
+    console.error(`[affine-mcp] WARNING: ${warning}`);
 }
 if (config.authMode === "oauth" && !useHttpTransport) {
     throw new Error("AFFINE_MCP_AUTH_MODE=oauth requires MCP_TRANSPORT=http (or streamable/sse).");
@@ -155,52 +139,40 @@ async function buildServer() {
         console.error("WARNING: No authentication configured. Some operations may fail.");
         console.error("Set AFFINE_API_TOKEN or run: affine-mcp login");
     }
-    // ---------------------------------------------------------------------------
-    // Per-tool blacklist: patch registerTool on this server instance so individual
-    // tools in AFFINE_DISABLED_TOOLS are silently skipped during registration.
-    // All tool files use server.registerTool exclusively — no need to patch server.tool.
-    // ---------------------------------------------------------------------------
-    if (DISABLED_TOOLS.size > 0) {
-        const originalRegisterTool = server.registerTool?.bind(server);
-        if (typeof originalRegisterTool !== "function") {
-            console.error("[affine-mcp] WARNING: server.registerTool not found — " +
-                "AFFINE_DISABLED_TOOLS will have no effect. " +
-                "The MCP SDK API may have changed.");
-        }
-        else {
-            server.registerTool = (name, options, handler) => {
-                if (DISABLED_TOOLS.has(name))
-                    return;
-                return originalRegisterTool(name, options, handler);
-            };
+    const originalRegisterTool = server.registerTool?.bind(server);
+    if (typeof originalRegisterTool !== "function") {
+        const message = "[affine-mcp] server.registerTool not found - tool filtering cannot be enforced. " +
+            "The MCP SDK API may have changed.";
+        if (toolFilterRequiresRegisterTool(toolFilter)) {
+            throw new Error(`${message} Refusing to start because AFFINE_TOOL_PROFILE is not "full" ` +
+                "or AFFINE_DISABLED_GROUPS/AFFINE_DISABLED_TOOLS is configured.");
         }
+        console.error(`[affine-mcp] WARNING: ${message} Continuing with the full tool surface.`);
     }
-    // Log filters directly from environment variables
+    else {
+        server.registerTool = (name, options, handler) => {
+            if (!toolFilter.isEnabled(name))
+                return;
+            return originalRegisterTool(name, options, handler);
+        };
+    }
+    console.error(`[affine-mcp] Tool profile: ${toolFilter.profile}`);
     console.error(`[affine-mcp] Disabled groups: ${process.env.AFFINE_DISABLED_GROUPS || "(none)"}`);
     console.error(`[affine-mcp] Disabled tools: ${process.env.AFFINE_DISABLED_TOOLS || "(none)"}`);
-    if (!DISABLED_GROUPS.has("workspaces"))
-        registerWorkspaceTools(server, gql);
-    if (!DISABLED_GROUPS.has("docs"))
-        registerDocTools(server, gql, { workspaceId: config.defaultWorkspaceId });
-    if (!DISABLED_GROUPS.has("comments"))
-        registerCommentTools(server, gql, { workspaceId: config.defaultWorkspaceId });
-    if (!DISABLED_GROUPS.has("history"))
-        registerHistoryTools(server, gql, { workspaceId: config.defaultWorkspaceId });
-    if (!DISABLED_GROUPS.has("organize"))
-        registerOrganizeTools(server, gql, { workspaceId: config.defaultWorkspaceId });
-    if (!DISABLED_GROUPS.has("users")) {
-        registerUserTools(server, gql);
-        registerUserCRUDTools(server, gql);
-        if (config.authMode !== "oauth") {
-            registerAuthTools(server, gql, config.baseUrl);
-        }
+    console.error(`[affine-mcp] Enabled tools: ${toolFilter.enabledTools.length}/${toolFilter.totalToolCount}`);
+    registerWorkspaceTools(server, gql);
+    registerDocTools(server, gql, { workspaceId: config.defaultWorkspaceId });
+    registerCommentTools(server, gql, { workspaceId: config.defaultWorkspaceId });
+    registerHistoryTools(server, gql, { workspaceId: config.defaultWorkspaceId });
+    registerOrganizeTools(server, gql, { workspaceId: config.defaultWorkspaceId });
+    registerUserTools(server, gql);
+    registerUserCRUDTools(server, gql);
+    if (config.authMode !== "oauth") {
+        registerAuthTools(server, gql, config.baseUrl);
     }
-    if (!DISABLED_GROUPS.has("access_tokens"))
-        registerAccessTokenTools(server, gql);
-    if (!DISABLED_GROUPS.has("blobs"))
-        registerBlobTools(server, gql);
-    if (!DISABLED_GROUPS.has("notifications"))
-        registerNotificationTools(server, gql);
+    registerAccessTokenTools(server, gql);
+    registerBlobTools(server, gql);
+    registerNotificationTools(server, gql);
     return server;
 }
 async function start() {