affine-mcp-server 1.6.0 → 1.7.1

package/README.md

@@ -1,8 +1,8 @@
 # AFFiNE MCP Server
 
-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.
+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 (default) or HTTP (`/mcp`).
 
-[![Version](https://img.shields.io/badge/version-1.6.0-blue)](https://github.com/dawncr0w/affine-mcp-server/releases)
+[![Version](https://img.shields.io/badge/version-1.7.1-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)
@@ -14,12 +14,12 @@ A Model Context Protocol (MCP) server that integrates with AFFiNE (self‑hosted
 ## Overview
 
 - Purpose: Manage AFFiNE workspaces and documents through MCP
-- Transport: stdio only (Claude Desktop / Codex compatible)
+- Transport: stdio (default) and optional HTTP (`/mcp`) for remote MCP deployments
 - Auth: Token, Cookie, or Email/Password (priority order)
 - Tools: 43 focused tools with WebSocket-based document editing
 - Status: Active
  
-> New in v1.6.0: Added tag workflows, markdown import/export/replace workflows, and direct database editing tools (`add_database_column`, `add_database_row`) with end-to-end validation coverage.
+> New in v1.7.1: Fixed MCP-created document structure parity with AFFiNE UI (`sys:parent` handling) and callout text rendering, plus regression coverage for UI visibility paths.
 
 ## Features
 
@@ -102,7 +102,7 @@ You can also configure via environment variables (they override the config file)
 
 - Required: `AFFINE_BASE_URL`
 - Auth (choose one): `AFFINE_API_TOKEN` | `AFFINE_COOKIE` | `AFFINE_EMAIL` + `AFFINE_PASSWORD`
-- Optional: `AFFINE_GRAPHQL_PATH` (default `/graphql`), `AFFINE_WORKSPACE_ID`, `AFFINE_LOGIN_AT_START` (`async` default, `sync` to block)
+- Optional: `AFFINE_GRAPHQL_PATH` (default `/graphql`), `AFFINE_WORKSPACE_ID`, `AFFINE_LOGIN_AT_START` (set `sync` only when you must block startup)
 
 Authentication priority:
 1) `AFFINE_API_TOKEN` → 2) `AFFINE_COOKIE` → 3) `AFFINE_EMAIL` + `AFFINE_PASSWORD`
@@ -175,8 +175,7 @@ Or with email/password for self-hosted instances (not supported on AFFiNE Cloud
       "env": {
         "AFFINE_BASE_URL": "https://your-self-hosted-affine.com",
         "AFFINE_EMAIL": "you@example.com",
-        "AFFINE_PASSWORD": "secret!",
-        "AFFINE_LOGIN_AT_START": "async"
+        "AFFINE_PASSWORD": "secret!"
       }
     }
   }
@@ -198,7 +197,7 @@ Register the MCP server with Codex:
   - `codex mcp add affine --env AFFINE_BASE_URL=https://app.affine.pro --env AFFINE_API_TOKEN=ut_xxx -- affine-mcp`
 
 - With email/password (self-hosted only):
-  - `codex mcp add affine --env AFFINE_BASE_URL=https://your-self-hosted-affine.com --env 'AFFINE_EMAIL=you@example.com' --env 'AFFINE_PASSWORD=secret!' --env AFFINE_LOGIN_AT_START=async -- affine-mcp`
+  - `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
 
@@ -237,6 +236,70 @@ If you prefer `npx`:
 }
 ```
 
+### Remote Server
+
+If you want to host the server remotely (e.g., using Render, Railway, Docker, or a VPS) and connect via HTTP MCP (Streamable HTTP on `/mcp`) instead of local `stdio`, run the server in HTTP mode.
+
+#### Environment variables (HTTP mode)
+
+Required:
+- `MCP_TRANSPORT=http`
+- `AFFINE_BASE_URL` (example: `https://app.affine.pro`)
+- One auth method:
+- `AFFINE_API_TOKEN` (recommended), or `AFFINE_COOKIE`, or `AFFINE_EMAIL` + `AFFINE_PASSWORD`
+
+Recommended for remote/public deployments:
+- `AFFINE_MCP_HTTP_HOST=0.0.0.0`
+- `AFFINE_MCP_HTTP_TOKEN=<strong-random-token>` (protects `/mcp`, `/sse`, `/messages`)
+- `AFFINE_MCP_HTTP_ALLOWED_ORIGINS=<comma-separated-origins>` (for browser clients)
+
+Optional:
+- `PORT` (defaults to `3000`; many platforms like Render inject this automatically)
+- `AFFINE_WORKSPACE_ID`
+- `AFFINE_GRAPHQL_PATH` (defaults to `/graphql`)
+- `AFFINE_MCP_HTTP_ALLOW_ALL_ORIGINS=true` (testing only)
+
+```bash
+# Export your configuration first
+export MCP_TRANSPORT=http
+export AFFINE_API_TOKEN="your_token..."
+export AFFINE_MCP_HTTP_HOST="0.0.0.0" # Default: 127.0.0.1
+export AFFINE_MCP_HTTP_TOKEN="your-super-secret-token"
+export PORT=3000
+
+# Start in HTTP mode (Streamable HTTP on /mcp)
+npm run start:http
+# OR manually:
+# MCP_TRANSPORT=http node dist/index.js
+# ("sse" is still accepted at /sse)
+```
+
+#### Recommended presets
+
+Local testing (HTTP mode):
+- `MCP_TRANSPORT=http`
+- `AFFINE_MCP_HTTP_HOST=127.0.0.1`
+- `AFFINE_MCP_HTTP_TOKEN=<token>` (recommended even locally)
+- `AFFINE_MCP_HTTP_ALLOWED_ORIGINS=http://localhost:3000` (if testing from a browser app)
+
+Docker / container runtime:
+- `MCP_TRANSPORT=http`
+- `AFFINE_MCP_HTTP_HOST=0.0.0.0`
+- `PORT=3000` (or container/platform port)
+- `AFFINE_MCP_HTTP_TOKEN=<strong-token>`
+- `AFFINE_MCP_HTTP_ALLOWED_ORIGINS=<your app origin(s)>`
+
+Render / Railway / VPS (public endpoint):
+- `MCP_TRANSPORT=http`
+- `AFFINE_MCP_HTTP_HOST=0.0.0.0`
+- `AFFINE_MCP_HTTP_TOKEN=<strong-token>`
+- `AFFINE_MCP_HTTP_ALLOWED_ORIGINS=<your client origin(s)>`
+
+Endpoints currently available:
+- `/mcp` - MCP server (Streamable HTTP)
+- `/sse` - SSE endpoint (old protocol compatible)
+- `/messages` - Messages endpoint (old protocol compatible)
+
 ## Available Tools
 
 ### Workspace
@@ -309,6 +372,7 @@ npm run pack:check
 
 - `tool-manifest.json` is the source of truth for publicly exposed tool names.
 - CI validates that `registerTool(...)` declarations match the manifest exactly.
+- For full tool-surface verification, run `npm run test:comprehensive`.
 - For full environment verification, run `npm run test:e2e` (Docker + MCP + Playwright).
 - Additional focused runners: `npm run test:db-create`, `npm run test:bearer`, `npm run test:playwright`.
 
@@ -345,6 +409,14 @@ Workspace visibility
 
 ## Version History
 
+### 1.7.0 (2026‑02‑27)
+- Added Streamable HTTP MCP support on `/mcp` for remote hosting while keeping legacy SSE compatibility paths (`/sse`, `/messages`)
+- Added HTTP deployment controls: `AFFINE_MCP_HTTP_HOST`, `AFFINE_MCP_HTTP_TOKEN`, `AFFINE_MCP_HTTP_ALLOWED_ORIGINS`, `AFFINE_MCP_HTTP_ALLOW_ALL_ORIGINS`
+- Added `npm run start:http` for one-command HTTP mode startup
+- Hardened HTTP request handling with explicit 50MB parser application and case-insensitive Bearer auth parsing
+- Expanded docs with remote deployment/security presets (Docker, Render, Railway, VPS)
+- Verified full release checks with `npm run ci`, `npm run test:e2e`, and `npm run test:comprehensive`
+
 ### 1.6.0 (2026‑02‑24)
 - Added 11 document workflow tools: tags (`list_tags`, `list_docs_by_tag`, `create_tag`, `add_tag_to_doc`, `remove_tag_from_doc`), markdown roundtrip (`export_doc_markdown`, `create_doc_from_markdown`, `append_markdown`, `replace_doc_with_markdown`), and database operations (`add_database_column`, `add_database_row`)
 - Added interactive CLI commands: `affine-mcp login`, `affine-mcp status`, `affine-mcp logout`
@@ -375,7 +447,7 @@ Workspace visibility
 
 ### 1.2.1 (2025‑09‑17)
 - Default to asynchronous email/password login after MCP stdio handshake
-- New `AFFINE_LOGIN_AT_START` env (`async` default, `sync` to block at startup)
+- `AFFINE_LOGIN_AT_START` supports `sync` when you need blocking startup (default is non-blocking)
 - Expanded docs for Codex/Claude using npm, npx, and local clone
 
 ### 1.2.0 (2025‑09‑16)

package/dist/config.js

@@ -5,20 +5,8 @@ import { createRequire } from "module";
 const require = createRequire(import.meta.url);
 const pkg = require("../package.json");
 export const VERSION = pkg.version;
-const defaultEndpoints = {
-    listWorkspaces: { method: "GET", path: "/api/workspaces" },
-    listDocs: { method: "GET", path: "/api/workspaces/:workspaceId/docs" },
-    getDoc: { method: "GET", path: "/api/docs/:docId" },
-    createDoc: { method: "POST", path: "/api/workspaces/:workspaceId/docs" },
-    updateDoc: { method: "PATCH", path: "/api/docs/:docId" },
-    deleteDoc: { method: "DELETE", path: "/api/docs/:docId" },
-    searchDocs: {
-        method: "GET",
-        path: "/api/workspaces/:workspaceId/search"
-    }
-};
 /** Config file location: ~/.config/affine-mcp/config */
-export const CONFIG_DIR = path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "affine-mcp");
+const CONFIG_DIR = path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "affine-mcp");
 export const CONFIG_FILE = path.join(CONFIG_DIR, "config");
 /** Read key=value config file, returns empty object if missing */
 export function loadConfigFile() {
@@ -98,44 +86,47 @@ export function validateBaseUrl(input) {
 function env(name, file, fallback) {
     return process.env[name] || file[name] || fallback;
 }
+function parseHeadersJson(raw) {
+    if (!raw)
+        return undefined;
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            console.warn("Failed to parse AFFINE_HEADERS_JSON; expected a JSON object of string headers.");
+            return undefined;
+        }
+        const headers = {};
+        for (const [key, value] of Object.entries(parsed)) {
+            if (typeof value !== "string") {
+                console.warn(`Ignoring non-string AFFINE_HEADERS_JSON value for header '${key}'.`);
+                continue;
+            }
+            headers[key] = value;
+        }
+        const sensitiveKeys = Object.keys(headers).filter((k) => /^(authorization|cookie)$/i.test(k));
+        if (sensitiveKeys.length) {
+            console.warn(`WARNING: AFFINE_HEADERS_JSON contains sensitive key(s): ${sensitiveKeys.join(", ")}. ` +
+                `These may conflict with built-in auth and are not protected by debug-logging guards.`);
+        }
+        return headers;
+    }
+    catch {
+        console.warn("Failed to parse AFFINE_HEADERS_JSON; ignoring.");
+        return undefined;
+    }
+}
 export function loadConfig() {
     const file = loadConfigFile();
-    const baseUrl = env("AFFINE_BASE_URL", file, "http://localhost:3010").replace(/\/$/, "");
+    const baseUrl = validateBaseUrl(env("AFFINE_BASE_URL", file, "http://localhost:3010"));
     const apiToken = env("AFFINE_API_TOKEN", file);
     const cookie = env("AFFINE_COOKIE", file);
     const email = env("AFFINE_EMAIL", file);
     const password = env("AFFINE_PASSWORD", file);
-    let headers = undefined;
-    const headersJson = process.env.AFFINE_HEADERS_JSON;
-    if (headersJson) {
-        try {
-            headers = JSON.parse(headersJson);
-            if (headers) {
-                const sensitiveKeys = Object.keys(headers).filter((k) => /^(authorization|cookie)$/i.test(k));
-                if (sensitiveKeys.length) {
-                    console.warn(`WARNING: AFFINE_HEADERS_JSON contains sensitive key(s): ${sensitiveKeys.join(", ")}. ` +
-                        `These may conflict with built-in auth and are not protected by debug-logging guards.`);
-                }
-            }
-        }
-        catch (e) {
-            console.warn("Failed to parse AFFINE_HEADERS_JSON; ignoring.");
-        }
-    }
+    let headers = parseHeadersJson(process.env.AFFINE_HEADERS_JSON);
     if (cookie) {
         headers = { ...(headers || {}), Cookie: cookie };
     }
     const graphqlPath = env("AFFINE_GRAPHQL_PATH", file, "/graphql");
     const defaultWorkspaceId = env("AFFINE_WORKSPACE_ID", file);
-    let endpoints = defaultEndpoints;
-    const endpointsJson = process.env.AFFINE_ENDPOINTS_JSON;
-    if (endpointsJson) {
-        try {
-            endpoints = { ...defaultEndpoints, ...JSON.parse(endpointsJson) };
-        }
-        catch (e) {
-            console.warn("Failed to parse AFFINE_ENDPOINTS_JSON; using defaults.");
-        }
-    }
-    return { baseUrl, apiToken, cookie, headers, graphqlPath, email, password, defaultWorkspaceId, endpoints };
+    return { baseUrl, apiToken, cookie, headers, graphqlPath, email, password, defaultWorkspaceId };
 }

package/dist/index.js

@@ -14,6 +14,7 @@ import { registerNotificationTools } from "./tools/notifications.js";
 import { loginWithPassword } from "./auth.js";
 import { registerAuthTools } from "./tools/auth.js";
 import { runCli } from "./cli.js";
+import { startHttpMcpServer } from "./sse.js";
 // CLI subcommands: affine-mcp login|status|logout
 const subcommand = process.argv[2];
 if (subcommand && await runCli(subcommand)) {
@@ -101,12 +102,34 @@ async function buildServer() {
     return server;
 }
 async function start() {
-    // stdio transport is the only supported mode in MCP SDK 1.17+
-    const server = await buildServer();
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-    // The server is now ready to accept stdio communication
-    // It will continue running until the process is terminated
+    // MCP_TRANSPORT aliases:
+    // - "stdio" (default): local desktop MCP clients
+    // - "http" / "streamable": HTTP MCP server exposing /mcp (preferred)
+    // - "sse": legacy alias retained for backward compatibility
+    const transportMode = (process.env.MCP_TRANSPORT || "stdio").toLowerCase();
+    const useHttpTransport = transportMode === "sse" || transportMode === "http" || transportMode === "streamable";
+    if (useHttpTransport) {
+        const DEFAULT_PORT = 3000;
+        const portEnvValue = process.env.PORT;
+        let port = DEFAULT_PORT;
+        // Validate the HTTP server port if provided.
+        if (portEnvValue != null && portEnvValue.trim() !== "") {
+            const parsedPort = Number(portEnvValue);
+            if (Number.isInteger(parsedPort) && parsedPort >= 0 && parsedPort <= 65535) {
+                port = parsedPort;
+            }
+            else {
+                console.warn(`[affine-mcp] Invalid PORT "${portEnvValue}" (expected 0..65535 integer). Falling back to ${DEFAULT_PORT}.`);
+            }
+        }
+        await startHttpMcpServer(buildServer, port);
+    }
+    else {
+        // stdio transport is the default for typical desktop MCP clients
+        const server = await buildServer();
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+    }
 }
 start().catch((err) => {
     console.error("Failed to start affine-mcp server:", err);

package/dist/sse.js

@@ -0,0 +1,284 @@
+import { randomUUID } from "node:crypto";
+import express from "express";
+import cors from "cors";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+export async function startHttpMcpServer(createMcpServer, port) {
+    // --- HTTP host binding ---
+    // AFFINE_MCP_HTTP_HOST: network interface to bind (default: "127.0.0.1" — loopback only).
+    // Set to "0.0.0.0" for Docker / remote deployments (Render, Railway, etc.).
+    const host = (process.env.AFFINE_MCP_HTTP_HOST || "127.0.0.1").trim();
+    // --- Bearer Token guard (AFFINE_MCP_HTTP_TOKEN) ---
+    // When set, all requests to /mcp, /sse and /messages must include:
+    //   Authorization: Bearer <token>   OR   ?token=<token> (fallback for limited clients)
+    // When the server is bound to 0.0.0.0 without a token, a startup warning is emitted.
+    const httpAuthToken = process.env.AFFINE_MCP_HTTP_TOKEN?.trim();
+    if (!httpAuthToken && host === "0.0.0.0") {
+        console.warn("[affine-mcp] WARNING: HTTP MCP server is bound to 0.0.0.0 without AFFINE_MCP_HTTP_TOKEN. " +
+            "The endpoint is unprotected. Set AFFINE_MCP_HTTP_TOKEN for public deployments.");
+    }
+    // Use a plain Express app here so it can fully control JSON parser ordering/limits.
+    // `createMcpExpressApp()` installs its own JSON parser first, which can enforce
+    // a smaller default limit before the intended 50mb parser runs on /mcp.
+    const app = express();
+    const jsonBody = express.json({ limit: "50mb" });
+    // --- CORS origin allowlist ---
+    // AFFINE_MCP_HTTP_ALLOWED_ORIGINS: comma-separated list, e.g. "https://app.example.com,http://localhost:3000".
+    // AFFINE_MCP_HTTP_ALLOW_ALL_ORIGINS=true: explicit opt-in to allow any origin (use with caution).
+    // Default (no env set): only loopback addresses (localhost / 127.0.0.1 / ::1) are allowed.
+    //
+    // CORS is applied per-route (/mcp, /sse, /messages) — not globally — to minimise attack surface.
+    const allowAnyOrigin = process.env.AFFINE_MCP_HTTP_ALLOW_ALL_ORIGINS === "true";
+    const allowedOrigins = (process.env.AFFINE_MCP_HTTP_ALLOWED_ORIGINS || "")
+        .split(",")
+        .map((o) => o.trim())
+        .filter(Boolean);
+    // Returns true if origin is a loopback address (http or https, any port).
+    const isLoopbackOrigin = (origin) => {
+        try {
+            const { protocol, hostname } = new URL(origin);
+            if (protocol !== "http:" && protocol !== "https:")
+                return false;
+            return (hostname === "localhost" ||
+                hostname === "127.0.0.1" ||
+                hostname === "::1");
+        }
+        catch {
+            return false;
+        }
+    };
+    const corsOptions = {
+        origin: (origin, callback) => {
+            // Non-browser clients (curl, MCP Inspector, server-to-server) send no Origin header.
+            // CORS is a browser mechanism only; the token guard covers programmatic access.
+            if (!origin)
+                return callback(null, true);
+            if (allowAnyOrigin)
+                return callback(null, true);
+            const allowed = allowedOrigins.length > 0
+                ? allowedOrigins.includes(origin)
+                : isLoopbackOrigin(origin);
+            return allowed
+                ? callback(null, true)
+                : callback(new Error("Origin not allowed"));
+        },
+        methods: ["GET", "POST", "DELETE", "OPTIONS"],
+        allowedHeaders: ["Content-Type", "Authorization", "mcp-session-id"],
+        exposedHeaders: ["mcp-session-id"],
+    };
+    // Wraps cors() to return an explicit 403 on rejected origins (rather than silently
+    // withholding CORS headers, which still lets the request reach the handler).
+    const corsMiddleware = (req, res, next) => {
+        cors(corsOptions)(req, res, (err) => {
+            if (err) {
+                if (!res.headersSent)
+                    res.status(403).send("Forbidden: Origin not allowed");
+                return;
+            }
+            if (res.headersSent || res.writableEnded)
+                return;
+            next();
+        });
+    };
+    // Validates the Bearer token on all non-preflight requests.
+    // The auth scheme match is case-insensitive for client compatibility.
+    // OPTIONS is allowed through so CORS preflight can complete before auth is checked.
+    const authMiddleware = (req, res, next) => {
+        if (req.method === "OPTIONS")
+            return next();
+        if (!httpAuthToken)
+            return next();
+        const authHeader = req.headers["authorization"];
+        const queryToken = typeof req.query.token === "string" ? req.query.token : undefined;
+        let token;
+        if (authHeader !== undefined) {
+            // Normalize string | string[] to string (HTTP spec allows duplicate headers).
+            const raw = Array.isArray(authHeader) ? authHeader[0] : authHeader;
+            const bearerMatch = /^Bearer\s+(.+)$/i.exec(raw);
+            if (bearerMatch) {
+                token = bearerMatch[1];
+            }
+            else {
+                // Strictly reject non-Bearer schemes to avoid accidentally accepting Basic / Digest.
+                console.warn("[affine-mcp] Authorization header is not Bearer scheme. " +
+                    "Expected: 'Authorization: Bearer <token>'.");
+                res
+                    .status(401)
+                    .send("Unauthorized: Use 'Authorization: Bearer <token>'");
+                return;
+            }
+        }
+        else if (queryToken !== undefined) {
+            token = queryToken;
+        }
+        if (token !== httpAuthToken) {
+            res.status(401).send("Unauthorized: Invalid or missing token");
+            return;
+        }
+        next();
+    };
+    // Explicit preflight handlers for the legacy SSE routes.
+    app.options("/sse", corsMiddleware);
+    app.options("/messages", corsMiddleware);
+    const transports = {};
+    // ===========================================================================
+    // STREAMABLE HTTP TRANSPORT — MCP protocol 2025-03-26
+    // Single endpoint /mcp (GET / POST / DELETE) replaces the old two-endpoint SSE
+    // pattern. Use this for all new integrations.
+    // ===========================================================================
+    app.all("/mcp", corsMiddleware, authMiddleware, async (req, res) => {
+        console.error(`[affine-mcp] Received ${req.method} request to /mcp`);
+        try {
+            // mcp-session-id header can technically be string | string[]; normalise.
+            const sidHeader = req.headers["mcp-session-id"];
+            const sessionId = Array.isArray(sidHeader) ? sidHeader[0] : sidHeader;
+            let transport;
+            const existing = sessionId ? transports[sessionId] : undefined;
+            if (existing instanceof StreamableHTTPServerTransport) {
+                transport = existing;
+            }
+            else if (!sessionId && req.method === "POST") {
+                // Parse body only for the initialize POST (lazy — avoids consuming the stream early).
+                await new Promise((resolve, reject) => {
+                    jsonBody(req, res, (err) => (err ? reject(err) : resolve()));
+                });
+                if (!isInitializeRequest(req.body)) {
+                    res.status(400).json({
+                        jsonrpc: "2.0",
+                        error: {
+                            code: -32000,
+                            message: "Bad Request: Not an initialize request",
+                        },
+                        id: null,
+                    });
+                    return;
+                }
+                transport = new StreamableHTTPServerTransport({
+                    sessionIdGenerator: () => randomUUID(),
+                    onsessioninitialized: (sid) => {
+                        console.error(`[affine-mcp] StreamableHTTP session initialized: ${sid}`);
+                        transports[sid] = transport;
+                    },
+                });
+                transport.onclose = () => {
+                    const sid = transport.sessionId;
+                    if (sid && transports[sid]) {
+                        console.error(`[affine-mcp] StreamableHTTP session closed: ${sid}`);
+                        delete transports[sid];
+                    }
+                };
+                const server = await createMcpServer();
+                await server.connect(transport);
+            }
+            else {
+                res.status(400).json({
+                    jsonrpc: "2.0",
+                    error: {
+                        code: -32000,
+                        message: "Bad Request: No valid session ID or not an initialize request",
+                    },
+                    id: null,
+                });
+                return;
+            }
+            // Ensure JSON body is available for subsequent POST requests within the session.
+            if (req.method === "POST" && req.body === undefined) {
+                await new Promise((resolve, reject) => {
+                    jsonBody(req, res, (err) => (err ? reject(err) : resolve()));
+                });
+            }
+            await transport.handleRequest(req, res, req.body);
+        }
+        catch (e) {
+            console.error("[affine-mcp] Error handling /mcp request:", e);
+            if (!res.headersSent) {
+                res.status(500).json({
+                    jsonrpc: "2.0",
+                    error: { code: -32603, message: "Internal server error" },
+                    id: null,
+                });
+            }
+        }
+    });
+    // ===========================================================================
+    // LEGACY HTTP+SSE TRANSPORT — MCP protocol 2024-11-05
+    // Kept for backward compatibility with older MCP clients that have not yet
+    // migrated to the Streamable HTTP transport above.
+    // @deprecated — SSEServerTransport is deprecated by the SDK; use /mcp for new clients.
+    // ===========================================================================
+    app.get("/sse", corsMiddleware, authMiddleware, async (req, res) => {
+        try {
+            // @ts-ignore — intentional: SSEServerTransport retained for backward compat only
+            const transport = new SSEServerTransport("/messages", res);
+            const sessionId = transport.sessionId;
+            transports[sessionId] = transport;
+            res.on("close", () => {
+                console.error(`[affine-mcp] Legacy SSE session closed: ${sessionId}`);
+                delete transports[sessionId];
+            });
+            const server = await createMcpServer();
+            await server.connect(transport);
+            console.error(`[affine-mcp] Legacy SSE session established: ${sessionId}`);
+        }
+        catch (e) {
+            console.error("[affine-mcp] Error establishing legacy SSE stream:", e);
+            if (!res.headersSent)
+                res.status(500).send("Error establishing SSE stream");
+        }
+    });
+    app.post("/messages", corsMiddleware, authMiddleware, jsonBody, async (req, res) => {
+        const sessionId = typeof req.query.sessionId === "string"
+            ? req.query.sessionId
+            : undefined;
+        if (!sessionId) {
+            res.status(400).send("Missing sessionId parameter");
+            return;
+        }
+        const transport = transports[sessionId];
+        if (!(transport instanceof SSEServerTransport)) {
+            res.status(400).json({
+                jsonrpc: "2.0",
+                error: {
+                    code: -32000,
+                    message: "Bad Request: Session uses a different transport protocol",
+                },
+                id: null,
+            });
+            return;
+        }
+        try {
+            // @ts-ignore — intentional: SSEServerTransport retained for backward compat only
+            await transport.handlePostMessage(req, res, req.body);
+        }
+        catch (e) {
+            console.error("[affine-mcp] Error handling legacy SSE message:", e);
+            if (!res.headersSent)
+                res.status(500).send("Error handling POST message");
+        }
+    });
+    const server = app.listen(port, host, () => {
+        const displayHost = host === "0.0.0.0" ? "localhost" : host;
+        console.error(`[affine-mcp] MCP server listening on ${host}:${port}`);
+        console.error(`[affine-mcp] Streamable HTTP (2025-03-26): http://${displayHost}:${port}/mcp`);
+        console.error(`[affine-mcp] Legacy SSE     (2024-11-05): http://${displayHost}:${port}/sse`);
+    });
+    // Graceful shutdown: stop accepting new connections, then close active transports.
+    const shutdown = async (signal) => {
+        console.error(`[affine-mcp] ${signal} received - shutting down gracefully`);
+        server.close(() => {
+            void (async () => {
+                for (const sessionId in transports) {
+                    try {
+                        await transports[sessionId].close();
+                    }
+                    catch { }
+                    delete transports[sessionId];
+                }
+                process.exit(0);
+            })();
+        });
+    };
+    process.on("SIGINT", () => void shutdown("SIGINT"));
+    process.on("SIGTERM", () => void shutdown("SIGTERM"));
+}

package/dist/tools/docs.js

@@ -219,7 +219,7 @@ export function registerDocTools(server, gql, defaults) {
         const noteId = generateId();
         const note = new Y.Map();
         setSysFields(note, noteId, "affine:note");
-        note.set("sys:parent", pageId);
+        note.set("sys:parent", null);
         note.set("sys:children", new Y.Array());
         note.set("prop:xywh", "[0,0,800,95]");
         note.set("prop:index", "a0");
@@ -251,7 +251,7 @@ export function registerDocTools(server, gql, defaults) {
         const surfaceId = generateId();
         const surface = new Y.Map();
         setSysFields(surface, surfaceId, "affine:surface");
-        surface.set("sys:parent", pageId);
+        surface.set("sys:parent", null);
         surface.set("sys:children", new Y.Array());
         const elements = new Y.Map();
         elements.set("type", "$blocksuite:internal:native$");
@@ -601,6 +601,30 @@ export function registerDocTools(server, gql, defaults) {
         });
         return index;
     }
+    function findParentIdByChild(blocks, childId) {
+        for (const [id, value] of blocks) {
+            if (!(value instanceof Y.Map)) {
+                continue;
+            }
+            const childIds = childIdsFrom(value.get("sys:children"));
+            if (childIds.includes(childId)) {
+                return String(id);
+            }
+        }
+        return null;
+    }
+    function resolveBlockParentId(blocks, blockId) {
+        const block = findBlockById(blocks, blockId);
+        if (!block) {
+            return null;
+        }
+        const rawParentId = block.get("sys:parent");
+        if (typeof rawParentId === "string" && rawParentId.trim().length > 0) {
+            return rawParentId;
+        }
+        // AFFiNE UI commonly stores sys:parent as null and derives hierarchy from sys:children.
+        return findParentIdByChild(blocks, blockId);
+    }
     function resolveInsertContext(blocks, normalized) {
         const placement = normalized.placement;
         let parentId;
@@ -612,8 +636,8 @@ export function registerDocTools(server, gql, defaults) {
             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) {
+            const refParentId = resolveBlockParentId(blocks, referenceBlockId);
+            if (!refParentId) {
                 throw new Error(`Block '${referenceBlockId}' has no parent.`);
             }
             parentId = refParentId;
@@ -624,8 +648,8 @@ export function registerDocTools(server, gql, defaults) {
             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) {
+            const refParentId = resolveBlockParentId(blocks, referenceBlockId);
+            if (!refParentId) {
                 throw new Error(`Block '${referenceBlockId}' has no parent.`);
             }
             parentId = refParentId;
@@ -688,16 +712,17 @@ export function registerDocTools(server, gql, defaults) {
         }
         return { parentId, parentBlock, children, insertIndex };
     }
-    function createBlock(parentId, normalized) {
+    function createBlock(normalized) {
         const blockId = generateId();
         const block = new Y.Map();
         const content = normalized.text;
+        // Keep parity with AFFiNE UI-created docs: sys:parent stays null and hierarchy is represented by sys:children.
         switch (normalized.type) {
             case "paragraph":
             case "heading":
             case "quote": {
                 setSysFields(block, blockId, "affine:paragraph");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 const blockType = normalized.type === "heading"
                     ? `h${normalized.headingLevel}`
@@ -710,7 +735,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "list": {
                 setSysFields(block, blockId, "affine:list");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:type", normalized.listStyle);
                 block.set("prop:checked", normalized.listStyle === "todo" ? normalized.checked : false);
@@ -719,7 +744,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "code": {
                 setSysFields(block, blockId, "affine:code");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:language", normalized.language);
                 if (normalized.caption) {
@@ -730,22 +755,35 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "divider": {
                 setSysFields(block, blockId, "affine:divider");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 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("sys:parent", null);
+                const calloutChildren = new Y.Array();
+                const textBlockId = generateId();
+                const textBlock = new Y.Map();
+                setSysFields(textBlock, textBlockId, "affine:paragraph");
+                textBlock.set("sys:parent", null);
+                textBlock.set("sys:children", new Y.Array());
+                textBlock.set("prop:type", "text");
+                textBlock.set("prop:text", makeText(content));
+                calloutChildren.push([textBlockId]);
+                block.set("sys:children", calloutChildren);
                 block.set("prop:icon", { type: "emoji", unicode: "💡" });
                 block.set("prop:backgroundColorName", "grey");
-                block.set("prop:text", makeText(content));
-                return { blockId, block, flavour: "affine:callout" };
+                return {
+                    blockId,
+                    block,
+                    flavour: "affine:callout",
+                    extraBlocks: [{ blockId: textBlockId, block: textBlock }],
+                };
             }
             case "latex": {
                 setSysFields(block, blockId, "affine:latex");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:xywh", "[0,0,16,16]");
                 block.set("prop:index", "a0");
@@ -757,7 +795,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "table": {
                 setSysFields(block, blockId, "affine:table");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 const rows = {};
                 const columns = {};
@@ -792,7 +830,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "bookmark": {
                 setSysFields(block, blockId, "affine:bookmark");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:style", normalized.bookmarkStyle);
                 block.set("prop:url", normalized.url);
@@ -810,7 +848,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "image": {
                 setSysFields(block, blockId, "affine:image");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:caption", normalized.caption ?? "");
                 block.set("prop:sourceId", normalized.sourceId);
@@ -825,7 +863,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "attachment": {
                 setSysFields(block, blockId, "affine:attachment");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:name", normalized.name);
                 block.set("prop:size", normalized.size);
@@ -843,7 +881,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "embed_youtube": {
                 setSysFields(block, blockId, "affine:embed-youtube");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:index", "a0");
                 block.set("prop:xywh", "[0,0,0,0]");
@@ -863,7 +901,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "embed_github": {
                 setSysFields(block, blockId, "affine:embed-github");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:index", "a0");
                 block.set("prop:xywh", "[0,0,0,0]");
@@ -887,7 +925,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "embed_figma": {
                 setSysFields(block, blockId, "affine:embed-figma");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:index", "a0");
                 block.set("prop:xywh", "[0,0,0,0]");
@@ -902,7 +940,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "embed_loom": {
                 setSysFields(block, blockId, "affine:embed-loom");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:index", "a0");
                 block.set("prop:xywh", "[0,0,0,0]");
@@ -919,7 +957,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "embed_html": {
                 setSysFields(block, blockId, "affine:embed-html");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:index", "a0");
                 block.set("prop:xywh", "[0,0,0,0]");
@@ -933,7 +971,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "embed_linked_doc": {
                 setSysFields(block, blockId, "affine:embed-linked-doc");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:index", "a0");
                 block.set("prop:xywh", "[0,0,0,0]");
@@ -949,7 +987,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "embed_synced_doc": {
                 setSysFields(block, blockId, "affine:embed-synced-doc");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:index", "a0");
                 block.set("prop:xywh", "[0,0,800,100]");
@@ -966,7 +1004,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "embed_iframe": {
                 setSysFields(block, blockId, "affine:embed-iframe");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:index", "a0");
                 block.set("prop:xywh", "[0,0,0,0]");
@@ -983,7 +1021,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "database": {
                 setSysFields(block, blockId, "affine:database");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 // Create a default table view so AFFiNE UI renders the database
                 const defaultView = new Y.Map();
@@ -1008,7 +1046,7 @@ export function registerDocTools(server, gql, defaults) {
                 // 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:parent", null);
                 block.set("sys:children", new Y.Array());
                 const dvDefaultView = new Y.Map();
                 dvDefaultView.set("id", generateId());
@@ -1030,7 +1068,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "surface_ref": {
                 setSysFields(block, blockId, "affine:surface-ref");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:reference", normalized.reference);
                 block.set("prop:caption", normalized.caption ?? "");
@@ -1040,7 +1078,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "frame": {
                 setSysFields(block, blockId, "affine:frame");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:title", makeText(content || "Frame"));
                 block.set("prop:background", normalized.background);
@@ -1053,7 +1091,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "edgeless_text": {
                 setSysFields(block, blockId, "affine:edgeless-text");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:xywh", `[0,0,${normalized.width},${normalized.height}]`);
                 block.set("prop:index", "a0");
@@ -1071,7 +1109,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             case "note": {
                 setSysFields(block, blockId, "affine:note");
-                block.set("sys:parent", parentId);
+                block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:xywh", `[0,0,${normalized.width},${normalized.height}]`);
                 block.set("prop:background", normalized.background);
@@ -1110,8 +1148,13 @@ export function registerDocTools(server, gql, defaults) {
             const prevSV = Y.encodeStateVector(doc);
             const blocks = doc.getMap("blocks");
             const context = resolveInsertContext(blocks, normalized);
-            const { blockId, block, flavour, blockType } = createBlock(context.parentId, normalized);
+            const { blockId, block, flavour, blockType, extraBlocks } = createBlock(normalized);
             blocks.set(blockId, block);
+            if (Array.isArray(extraBlocks)) {
+                for (const extra of extraBlocks) {
+                    blocks.set(extra.blockId, extra.block);
+                }
+            }
             if (context.insertIndex >= context.children.length) {
                 context.children.push([blockId]);
             }
@@ -1444,8 +1487,13 @@ export function registerDocTools(server, gql, defaults) {
                 try {
                     const normalized = normalizeAppendBlockInput(appendInput);
                     const context = resolveInsertContext(blocks, normalized);
-                    const { blockId, block } = createBlock(context.parentId, normalized);
+                    const { blockId, block, extraBlocks } = createBlock(normalized);
                     blocks.set(blockId, block);
+                    if (Array.isArray(extraBlocks)) {
+                        for (const extra of extraBlocks) {
+                            blocks.set(extra.blockId, extra.block);
+                        }
+                    }
                     if (context.insertIndex >= context.children.length) {
                         context.children.push([blockId]);
                     }
@@ -1499,7 +1547,7 @@ export function registerDocTools(server, gql, defaults) {
             const surfaceId = generateId();
             const surface = new Y.Map();
             setSysFields(surface, surfaceId, "affine:surface");
-            surface.set("sys:parent", pageId);
+            surface.set("sys:parent", null);
             surface.set("sys:children", new Y.Array());
             const elements = new Y.Map();
             elements.set("type", "$blocksuite:internal:native$");
@@ -1510,7 +1558,7 @@ export function registerDocTools(server, gql, defaults) {
             const noteId = generateId();
             const note = new Y.Map();
             setSysFields(note, noteId, "affine:note");
-            note.set("sys:parent", pageId);
+            note.set("sys:parent", null);
             note.set("prop:displayMode", "both");
             note.set("prop:xywh", "[0,0,800,95]");
             note.set("prop:index", "a0");
@@ -1527,7 +1575,7 @@ export function registerDocTools(server, gql, defaults) {
                 const paraId = generateId();
                 const para = new Y.Map();
                 setSysFields(para, paraId, "affine:paragraph");
-                para.set("sys:parent", noteId);
+                para.set("sys:parent", null);
                 para.set("sys:children", new Y.Array());
                 para.set("prop:type", "text");
                 const paragraphText = new Y.Text();

package/dist/tools/workspaces.js

@@ -14,13 +14,13 @@ function generateDocId() {
     return id;
 }
 // Create initial workspace data with a document
-function createInitialWorkspaceData(workspaceName = 'New Workspace') {
+function createInitialWorkspaceData(workspaceName = 'New Workspace', avatar = '') {
     // Create workspace root YDoc
     const rootDoc = new Y.Doc();
     // Set workspace metadata
     const meta = rootDoc.getMap('meta');
     meta.set('name', workspaceName);
-    meta.set('avatar', '');
+    meta.set('avatar', avatar);
     // Create pages array with initial document
     const pages = new Y.Array();
     const firstDocId = generateDocId();
@@ -58,7 +58,7 @@ function createInitialWorkspaceData(workspaceName = 'New Workspace') {
     const surfaceBlock = new Y.Map();
     surfaceBlock.set('sys:id', surfaceId);
     surfaceBlock.set('sys:flavour', 'affine:surface');
-    surfaceBlock.set('sys:parent', pageId);
+    surfaceBlock.set('sys:parent', null);
     surfaceBlock.set('sys:children', new Y.Array());
     blocks.set(surfaceId, surfaceBlock);
     pageChildren.push([surfaceId]);
@@ -67,7 +67,7 @@ function createInitialWorkspaceData(workspaceName = 'New Workspace') {
     const noteBlock = new Y.Map();
     noteBlock.set('sys:id', noteId);
     noteBlock.set('sys:flavour', 'affine:note');
-    noteBlock.set('sys:parent', pageId);
+    noteBlock.set('sys:parent', null);
     noteBlock.set('prop:displayMode', 'DocAndEdgeless');
     noteBlock.set('prop:xywh', '[0,0,800,600]');
     noteBlock.set('prop:index', 'a0');
@@ -81,7 +81,7 @@ function createInitialWorkspaceData(workspaceName = 'New Workspace') {
     const paragraphBlock = new Y.Map();
     paragraphBlock.set('sys:id', paragraphId);
     paragraphBlock.set('sys:flavour', 'affine:paragraph');
-    paragraphBlock.set('sys:parent', noteId);
+    paragraphBlock.set('sys:parent', null);
     paragraphBlock.set('sys:children', new Y.Array());
     paragraphBlock.set('prop:type', 'text');
     const paragraphText = new Y.Text();
@@ -158,7 +158,7 @@ export function registerWorkspaceTools(server, gql) {
             const cookie = gql.cookie;
             const bearer = gql.bearer;
             // Create initial workspace data
-            const { workspaceUpdate, firstDocId, docUpdate } = createInitialWorkspaceData(name);
+            const { workspaceUpdate, firstDocId, docUpdate } = createInitialWorkspaceData(name, avatar || '');
             // Only send workspace update - document will be created separately
             const initData = Buffer.from(workspaceUpdate);
             // Create multipart form

package/dist/ws.js

@@ -2,6 +2,35 @@ import { io } from "socket.io-client";
 const DEFAULT_WS_CLIENT_VERSION = process.env.AFFINE_WS_CLIENT_VERSION || '0.26.0';
 const WS_CONNECT_TIMEOUT_MS = Number(process.env.AFFINE_WS_CONNECT_TIMEOUT_MS || 10000);
 const WS_ACK_TIMEOUT_MS = Number(process.env.AFFINE_WS_ACK_TIMEOUT_MS || 10000);
+function ackErrorMessage(ack, fallback) {
+    const message = ack?.error?.message;
+    if (typeof message === "string" && message.trim())
+        return message;
+    return ack?.error ? fallback : null;
+}
+function emitWithAck(socket, event, payload, onAck) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const timeout = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            reject(new Error(`${event} timeout after ${WS_ACK_TIMEOUT_MS}ms`));
+        }, WS_ACK_TIMEOUT_MS);
+        socket.emit(event, payload, (ack) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            try {
+                resolve(onAck(ack));
+            }
+            catch (err) {
+                reject(err);
+            }
+        });
+    });
+}
 export function wsUrlFromGraphQLEndpoint(endpoint) {
     return endpoint
         .replace('https://', 'wss://')
@@ -10,6 +39,7 @@ export function wsUrlFromGraphQLEndpoint(endpoint) {
 }
 export async function connectWorkspaceSocket(wsUrl, cookie, bearer) {
     return new Promise((resolve, reject) => {
+        let settled = false;
         const extraHeaders = {};
         if (cookie)
             extraHeaders['Cookie'] = cookie;
@@ -22,16 +52,25 @@ export async function connectWorkspaceSocket(wsUrl, cookie, bearer) {
             autoConnect: true
         });
         const timeout = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
             cleanup();
             socket.disconnect();
             reject(new Error(`socket connect timeout after ${WS_CONNECT_TIMEOUT_MS}ms`));
         }, WS_CONNECT_TIMEOUT_MS);
         const onError = (err) => {
+            if (settled)
+                return;
+            settled = true;
             cleanup();
             socket.disconnect();
             reject(err);
         };
         const onConnect = () => {
+            if (settled)
+                return;
+            settled = true;
             cleanup();
             resolve(socket);
         };
@@ -45,45 +84,28 @@ export async function connectWorkspaceSocket(wsUrl, cookie, bearer) {
     });
 }
 export async function joinWorkspace(socket, workspaceId, clientVersion = DEFAULT_WS_CLIENT_VERSION) {
-    return new Promise((resolve, reject) => {
-        const timeout = setTimeout(() => {
-            reject(new Error(`space:join timeout after ${WS_ACK_TIMEOUT_MS}ms`));
-        }, WS_ACK_TIMEOUT_MS);
-        socket.emit('space:join', { spaceType: 'workspace', spaceId: workspaceId, clientVersion }, (ack) => {
-            clearTimeout(timeout);
-            if (ack?.error)
-                return reject(new Error(ack.error.message || 'join failed'));
-            resolve();
-        });
+    return emitWithAck(socket, 'space:join', { spaceType: 'workspace', spaceId: workspaceId, clientVersion }, (ack) => {
+        const message = ackErrorMessage(ack, "join failed");
+        if (message)
+            throw new Error(message);
     });
 }
 export async function loadDoc(socket, workspaceId, docId) {
-    return new Promise((resolve, reject) => {
-        const timeout = setTimeout(() => {
-            reject(new Error(`space:load-doc timeout after ${WS_ACK_TIMEOUT_MS}ms`));
-        }, WS_ACK_TIMEOUT_MS);
-        socket.emit('space:load-doc', { spaceType: 'workspace', spaceId: workspaceId, docId }, (ack) => {
-            clearTimeout(timeout);
-            if (ack?.error) {
-                if (ack.error.name === 'DOC_NOT_FOUND')
-                    return resolve({});
-                return reject(new Error(ack.error.message || 'load-doc failed'));
-            }
-            resolve(ack?.data || {});
-        });
+    return emitWithAck(socket, 'space:load-doc', { spaceType: 'workspace', spaceId: workspaceId, docId }, (ack) => {
+        if (ack?.error) {
+            if (ack.error.name === 'DOC_NOT_FOUND')
+                return {};
+            throw new Error(ackErrorMessage(ack, "load-doc failed") || "load-doc failed");
+        }
+        return ack?.data || {};
     });
 }
 export async function pushDocUpdate(socket, workspaceId, docId, updateBase64) {
-    return new Promise((resolve, reject) => {
-        const timeout = setTimeout(() => {
-            reject(new Error(`space:push-doc-update timeout after ${WS_ACK_TIMEOUT_MS}ms`));
-        }, WS_ACK_TIMEOUT_MS);
-        socket.emit('space:push-doc-update', { spaceType: 'workspace', spaceId: workspaceId, docId, update: updateBase64 }, (ack) => {
-            clearTimeout(timeout);
-            if (ack?.error)
-                return reject(new Error(ack.error.message || 'push-doc-update failed'));
-            resolve(ack?.data?.timestamp || Date.now());
-        });
+    return emitWithAck(socket, 'space:push-doc-update', { spaceType: 'workspace', spaceId: workspaceId, docId, update: updateBase64 }, (ack) => {
+        const message = ackErrorMessage(ack, "push-doc-update failed");
+        if (message)
+            throw new Error(message);
+        return ack?.data?.timestamp || Date.now();
     });
 }
 export function deleteDoc(socket, workspaceId, docId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "affine-mcp-server",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "private": false,
   "type": "module",
   "description": "Model Context Protocol server for AFFiNE - enables AI assistants to interact with AFFiNE workspaces, documents, and collaboration features.",
@@ -31,6 +31,7 @@
     "build": "npm run clean && tsc -p tsconfig.json",
     "dev": "tsx watch src/index.ts",
     "start": "node dist/index.js",
+    "start:http": "MCP_TRANSPORT=http node dist/index.js",
     "test": "npm run test:tool-manifest",
     "test:tool-manifest": "node scripts/verify-tool-manifest.mjs",
     "test:comprehensive": "node test-comprehensive.mjs",
@@ -56,6 +57,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.17.2",
+    "cors": "^2.8.6",
+    "express": "^5.2.1",
     "form-data": "^4.0.4",
     "markdown-it": "^14.1.0",
     "node-fetch": "^3.3.2",
@@ -66,6 +69,8 @@
   },
   "devDependencies": {
     "@playwright/test": "^1.50.0",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.6",
     "@types/markdown-it": "^14.1.2",
     "@types/node": "^25.2.3",
     "tsx": "^4.16.2",

package/dist/markdown/index.js

@@ -1,3 +0,0 @@
-export * from "./types.js";
-export * from "./parse.js";
-export * from "./render.js";

package/dist/types.js

@@ -1 +0,0 @@
-export {};