affine-mcp-server 1.5.0 → 1.7.0

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.5.0-blue)](https://github.com/dawncr0w/affine-mcp-server/releases)
+[![Version](https://img.shields.io/badge/version-1.7.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)
@@ -14,17 +14,18 @@ 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: 32 focused tools with WebSocket-based document editing
+- Tools: 43 focused tools with WebSocket-based document editing
 - Status: Active
  
-> New in v1.5.0: `append_block` now supports 30 verified block profiles, including database/edgeless (`frame`, `edgeless_text`, `surface_ref`, `note`) insertion paths. For stability on AFFiNE 0.26.x, `type=\"data_view\"` is currently mapped to a database block.
+> New in v1.7.0: Added remote HTTP MCP support (`/mcp`) with token/CORS controls, while retaining legacy SSE compatibility (`/sse`, `/messages`) for older clients.
 
 ## Features
 
 - Workspace: create (with initial doc), read, update, delete
-- Documents: list/get/read/publish/revoke + create/append paragraph/delete (WebSocket‑based)
+- Documents: list/get/read/publish/revoke + create/append/replace/delete + markdown import/export + tags (WebSocket‑based)
+- Database workflows: create database blocks, then add columns/rows via MCP tools
 - Comments: full CRUD and resolve
 - Version History: list
 - Users & Tokens: current user, sign in, profile/settings, and personal access tokens
@@ -53,17 +54,95 @@ Note: From v1.2.2+ the CLI wrapper (`bin/affine-mcp`) ensures Node runs the ESM
 
 ## Configuration
 
-Configure via environment variables (shell or app config). `.env` files are no longer recommended.
+### Interactive login (recommended)
+
+The easiest way to configure credentials:
+
+```bash
+npm i -g affine-mcp-server
+affine-mcp login
+```
+
+This stores credentials in `~/.config/affine-mcp/config` (mode 600). The MCP server reads them automatically — no environment variables needed.
+
+**AFFiNE Cloud** (`app.affine.pro`): you'll be prompted to paste an API token from Settings → Integrations → MCP Server.
+
+**Self-hosted instances**: you can choose between email/password (recommended — auto-generates an API token) or pasting a token manually.
+
+```
+$ affine-mcp login
+Affine MCP Server — Login
+
+Affine URL [https://app.affine.pro]: https://my-affine.example.com
+
+Auth method — [1] Email/password (recommended)  [2] Paste API token: 1
+Email: user@example.com
+Password: ****
+Signing in...
+✓ Signed in as: User Name <user@example.com>
+
+Generating API token...
+✓ Created token: ut_abc123... (name: affine-mcp-2026-02-18)
+
+Detecting workspaces...
+  Found 1 workspace: abc-def-123  (by User Name, 1 member, 2/10/2026)
+  Auto-selected.
+
+✓ Saved to /home/user/.config/affine-mcp/config (mode 600)
+The MCP server will use these credentials automatically.
+```
+
+Other CLI commands:
+- `affine-mcp status` — show current config and test connection
+- `affine-mcp logout` — remove stored credentials
+
+### Environment variables
+
+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`
 
+> **Cloudflare note**: `AFFINE_EMAIL`/`AFFINE_PASSWORD` auth requires programmatic access to `/api/auth/sign-in`. AFFiNE Cloud (`app.affine.pro`) is behind Cloudflare, which blocks these requests. Use `AFFINE_API_TOKEN` for cloud, or use `affine-mcp login` which handles this automatically. Email/password works for self-hosted instances without Cloudflare.
+
 ## Quick Start
 
+### Claude Code
+
+After running `affine-mcp login`, add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "affine": {
+      "command": "affine-mcp"
+    }
+  }
+}
+```
+
+No `env` block needed — the server reads `~/.config/affine-mcp/config` automatically.
+
+If you prefer explicit env vars instead of the config file:
+
+```json
+{
+  "mcpServers": {
+    "affine": {
+      "command": "affine-mcp",
+      "env": {
+        "AFFINE_BASE_URL": "https://app.affine.pro",
+        "AFFINE_API_TOKEN": "ut_xxx"
+      }
+    }
+  }
+}
+```
+
 ### Claude Desktop
 
 Add to your Claude Desktop configuration:
@@ -78,10 +157,25 @@ Add to your Claude Desktop configuration:
     "affine": {
       "command": "affine-mcp",
       "env": {
-        "AFFINE_BASE_URL": "https://your-affine-instance.com",
+        "AFFINE_BASE_URL": "https://app.affine.pro",
+        "AFFINE_API_TOKEN": "ut_xxx"
+      }
+    }
+  }
+}
+```
+
+Or with email/password for self-hosted instances (not supported on AFFiNE Cloud — see Cloudflare note above):
+
+```json
+{
+  "mcpServers": {
+    "affine": {
+      "command": "affine-mcp",
+      "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!"
       }
     }
   }
@@ -89,28 +183,21 @@ Add to your Claude Desktop configuration:
 ```
 
 Tips
-- Prefer `AFFINE_COOKIE` or `AFFINE_API_TOKEN` for zero‑latency startup.
+- Prefer `affine-mcp login` or `AFFINE_API_TOKEN` for zero‑latency startup.
 - If your password contains `!` (zsh history expansion), wrap it in single quotes in shells or use the JSON config above.
 
 ### Codex CLI
 
 Register the MCP server with Codex:
 
-- Global install path (fastest)
-  - `npm i -g affine-mcp-server`
-  - `codex mcp add affine --env AFFINE_BASE_URL=https://your-affine-instance.com --env 'AFFINE_EMAIL=you@example.com' --env 'AFFINE_PASSWORD=secret!' --env AFFINE_LOGIN_AT_START=async -- affine-mcp`
-
-- Use npx (no global install)
-  - `codex mcp add affine --env AFFINE_BASE_URL=https://your-affine-instance.com --env 'AFFINE_EMAIL=you@example.com' --env 'AFFINE_PASSWORD=secret!' --env AFFINE_LOGIN_AT_START=async -- npx -y -p affine-mcp-server affine-mcp`
+- With config file (after `affine-mcp login`):
+  - `codex mcp add affine -- affine-mcp`
 
-- Token or cookie (no startup login)
-  - Token: `codex mcp add affine --env AFFINE_BASE_URL=https://... --env AFFINE_API_TOKEN=... -- affine-mcp`
-  - Cookie: `codex mcp add affine --env AFFINE_BASE_URL=https://... --env "AFFINE_COOKIE=affine_session=...; affine_csrf=..." -- affine-mcp`
+- With API token:
+  - `codex mcp add affine --env AFFINE_BASE_URL=https://app.affine.pro --env AFFINE_API_TOKEN=ut_xxx -- affine-mcp`
 
-Notes
-- MCP name: `affine`
-- Command: `affine-mcp`
-- Environment: `AFFINE_BASE_URL` + one auth method (`AFFINE_API_TOKEN` | `AFFINE_COOKIE` | `AFFINE_EMAIL`/`AFFINE_PASSWORD`)
+- 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!' -- affine-mcp`
 
 ### Cursor
 
@@ -124,8 +211,8 @@ Project-local (`.cursor/mcp.json`) example:
     "affine": {
       "command": "affine-mcp",
       "env": {
-        "AFFINE_BASE_URL": "https://your-affine-instance.com",
-        "AFFINE_API_TOKEN": "apt_xxx"
+        "AFFINE_BASE_URL": "https://app.affine.pro",
+        "AFFINE_API_TOKEN": "ut_xxx"
       }
     }
   }
@@ -141,14 +228,78 @@ If you prefer `npx`:
       "command": "npx",
       "args": ["-y", "-p", "affine-mcp-server", "affine-mcp"],
       "env": {
-        "AFFINE_BASE_URL": "https://your-affine-instance.com",
-        "AFFINE_API_TOKEN": "apt_xxx"
+        "AFFINE_BASE_URL": "https://app.affine.pro",
+        "AFFINE_API_TOKEN": "ut_xxx"
       }
     }
   }
 }
 ```
 
+### 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
@@ -159,14 +310,25 @@ If you prefer `npx`:
 - `delete_workspace` – delete workspace permanently
 
 ### Documents
-- `list_docs` – list documents with pagination
+- `list_docs` – list documents with pagination (includes `node.tags`)
+- `list_tags` – list all tags in a workspace
+- `list_docs_by_tag` – list documents by tag
 - `get_doc` – get document metadata
 - `read_doc` – read document block content and plain text snapshot (WebSocket)
+- `export_doc_markdown` – export document content as markdown
 - `publish_doc` – make document public
 - `revoke_doc` – revoke public access
 - `create_doc` – create a new document (WebSocket)
+- `create_doc_from_markdown` – create a document from markdown content
+- `create_tag` – create a reusable workspace-level tag
+- `add_tag_to_doc` – attach a tag to a document
+- `remove_tag_from_doc` – detach a tag from a document
 - `append_paragraph` – append a paragraph block (WebSocket)
 - `append_block` – append canonical block types (text/list/code/media/embed/database/edgeless) with strict validation and placement control (`data_view` currently falls back to database)
+- `add_database_column` – add a column to a database block (`rich-text`, `select`, `multi-select`, `number`, `checkbox`, `link`, `date`)
+- `add_database_row` – add a row to a database block with values mapped by column name/ID
+- `append_markdown` – append markdown content to an existing document
+- `replace_doc_with_markdown` – replace the main note content with markdown content
 - `delete_doc` – delete a document (WebSocket)
 
 ### Comments
@@ -210,13 +372,17 @@ 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`.
 
 ## Troubleshooting
 
 Authentication
-- Email/Password: ensure your instance allows password auth and credentials are valid
+- **Cloudflare (403 "Just a moment...")**: AFFiNE Cloud (`app.affine.pro`) uses Cloudflare protection, which blocks programmatic sign-in via `/api/auth/sign-in`. Use `AFFINE_API_TOKEN` instead, or run `affine-mcp login` which guides you through the right method automatically. Email/password auth only works for self-hosted instances.
+- Email/Password: only works on self-hosted instances without Cloudflare. Ensure your instance allows password auth and credentials are valid.
 - Cookie: copy cookies (e.g., `affine_session`, `affine_csrf`) from the browser DevTools after login
-- Token: generate a personal access token; verify it hasn't expired
+- Token: generate a personal access token; verify it hasn't expired. Run `affine-mcp status` to test.
 - Startup timeouts: v1.2.2+ includes a CLI wrapper fix and default async login to avoid blocking the MCP handshake. Set `AFFINE_LOGIN_AT_START=sync` only if needed.
 
 Connection
@@ -243,6 +409,21 @@ 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`
+- Added Docker + Playwright E2E pipeline and CI workflow for auth/database regression checks
+- Tool surface increased from 32 to 43 canonical tools
+- Added release test commands (`test:e2e`, `test:db-create`, `test:bearer`, `test:playwright`) and package dependencies for markdown conversion + Playwright
+
 ### 1.5.0 (2026‑02‑13)
 - Expanded `append_block` from Step1 to Step4 profiles: canonical text/list/code/divider/callout/latex/table/bookmark/media/embed plus `database`, `data_view`, `surface_ref`, `frame`, `edgeless_text`, `note` (`data_view` currently mapped to database for stability)
 - Added strict field validation and canonical parent enforcement for page/note/surface containers
@@ -266,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/auth.js

@@ -1,4 +1,5 @@
 import { fetch } from "undici";
+const AUTH_FETCH_TIMEOUT_MS = 30_000;
 function extractCookiePairs(setCookies) {
     const pairs = [];
     for (const sc of setCookies) {
@@ -8,16 +9,38 @@ function extractCookiePairs(setCookies) {
     }
     return pairs.join("; ");
 }
+/** Reject cookie values containing CR/LF to prevent header injection. */
+function assertNoCRLF(value, label) {
+    if (/[\r\n]/.test(value)) {
+        throw new Error(`${label} contains illegal CR/LF characters`);
+    }
+}
 export async function loginWithPassword(baseUrl, email, password) {
     const url = `${baseUrl.replace(/\/$/, "")}/api/auth/sign-in`;
-    const res = await fetch(url, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ email, password })
-    });
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), AUTH_FETCH_TIMEOUT_MS);
+    let res;
+    try {
+        res = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ email, password }),
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        if (err.name === "AbortError")
+            throw new Error(`Sign-in request timed out after ${AUTH_FETCH_TIMEOUT_MS / 1000}s`);
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
+    }
     if (!res.ok) {
-        const text = await res.text().catch(() => "");
-        throw new Error(`Sign-in failed: ${res.status} ${text}`);
+        const raw = await res.text().catch(() => "");
+        const sanitized = raw.replace(/<[^>]*>/g, "").replace(/\s+/g, " ").trim();
+        const truncated = sanitized.length > 200 ? sanitized.slice(0, 200) + "..." : sanitized;
+        throw new Error(`Sign-in failed: ${res.status} ${truncated}`);
     }
     const anyHeaders = res.headers;
     let setCookies = [];
@@ -33,5 +56,6 @@ export async function loginWithPassword(baseUrl, email, password) {
         throw new Error("Sign-in succeeded but no Set-Cookie received");
     }
     const cookieHeader = extractCookiePairs(setCookies);
+    assertNoCRLF(cookieHeader, "Cookie header from sign-in");
     return { cookieHeader };
 }