affine-mcp-server 1.12.0 → 1.13.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 (default) or HTTP (`/mcp`).
+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.12.0-blue)](https://github.com/dawncr0w/affine-mcp-server/releases)
+[![Version](https://img.shields.io/badge/version-1.13.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)
@@ -11,604 +11,256 @@ A Model Context Protocol (MCP) server that integrates with AFFiNE (self‑hosted
   <img width="380" height="200" src="https://glama.ai/mcp/servers/@DAWNCR0W/affine-mcp-server/badge" alt="AFFiNE Server MCP server" />
 </a>
 
+## Table of Contents
+
+- [Overview](#overview)
+- [Choose Your Path](#choose-your-path)
+- [Quick Start](#quick-start)
+- [Compatibility Matrix](#compatibility-matrix)
+- [Tool Surface](#tool-surface)
+- [Documentation Map](#documentation-map)
+- [Verify Your Setup](#verify-your-setup)
+- [Security and Scope](#security-and-scope)
+- [Development](#development)
+- [Release Notes](#release-notes)
+- [License](#license)
+- [Support](#support)
+
 ## Overview
 
-- Purpose: Manage AFFiNE workspaces and documents through MCP
-- Transport: stdio (default) and optional HTTP (`/mcp`) for remote MCP deployments
-- Auth: Token, Cookie, or Email/Password (priority order)
-- Tools: 76 focused tools with WebSocket-based document editing
-- Status: Active
- 
-> New in v1.12.0: Added linked documents on database rows, restored MCP CRUD for rows created in the AFFiNE UI, fixed self-hosted table exports, and documented GHCR Docker releases.
+AFFiNE MCP Server is designed for three common scenarios:
 
-## Features
+- 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
 
-- Workspace: create (with initial doc), read, update, delete
-- Documents: list/get/read/publish/revoke + create/append/replace/delete + markdown import/export + tags (WebSocket‑based)
-- Sidebar data: collections, folders, and organize links for AFFiNE workspace trees
-- Database workflows: create database blocks, inspect schema, add/update/delete rows, and read or update cell values via MCP tools
-- Comments: full CRUD and resolve
-- Version History: list
-- Users & Tokens: current user, sign in, profile/settings, and personal access tokens
-- Notifications: list and mark as read
-- Blob storage: upload/delete/cleanup
+Highlights:
 
-## Requirements
+- 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
+- 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
 
-- Node.js 18+
-- An AFFiNE instance (self‑hosted or cloud)
-- Valid AFFiNE credentials or access token
+Scope boundaries:
 
-## Installation
+- This server can access only server-backed AFFiNE workspaces
+- 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
 
-```bash
-# Global install (recommended)
-npm i -g affine-mcp-server
+> New in v1.13.0: Added high-level semantic page, native template, fidelity, and workspace blueprint workflows, plus structured receipts and productized setup docs.
 
-# Or run ad‑hoc via npx (no install)
-npx -y -p affine-mcp-server affine-mcp -- --version
-```
+## Choose Your Path
 
-The package installs a CLI named `affine-mcp` that runs the MCP server over stdio.
+| Goal | Start here |
+| --- | --- |
+| Set up a local stdio server with the least friction | [docs/getting-started.md](docs/getting-started.md) |
+| Run the server in Docker or another OCI runtime | [docs/getting-started.md#path-c-run-from-the-docker-image](docs/getting-started.md#path-c-run-from-the-docker-image) |
+| Configure Claude Code, Claude Desktop, Codex CLI, or Cursor | [docs/client-setup.md](docs/client-setup.md) |
+| Run the server remotely over HTTP or behind OAuth | [docs/configuration-and-deployment.md](docs/configuration-and-deployment.md) |
+| Lock down tool exposure for least-privilege deployments | [docs/configuration-and-deployment.md#least-privilege-tool-exposure](docs/configuration-and-deployment.md#least-privilege-tool-exposure) |
+| Learn common AFFiNE workflows and tool sequences | [docs/workflow-recipes.md](docs/workflow-recipes.md) |
+| Browse the tool catalog by domain | [docs/tool-reference.md](docs/tool-reference.md) |
 
-Note: From v1.2.2+ the CLI wrapper (`bin/affine-mcp`) ensures Node runs the ESM entrypoint, preventing shell from misinterpreting JS.
-
-## Configuration
-
-### Interactive login (recommended)
+## Quick Start
 
-The easiest way to configure credentials:
+### 1. Install the CLI
 
 ```bash
 npm i -g affine-mcp-server
-affine-mcp login
+affine-mcp --version
 ```
 
-This stores credentials in `~/.config/affine-mcp/config` (mode 600). The MCP server reads them automatically — no environment variables needed.
+You can also run the package ad hoc:
 
-**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.
+```bash
+npx -y -p affine-mcp-server affine-mcp -- --version
 ```
 
-Other CLI commands:
-- `affine-mcp --help` / `-h` / `help` — show command help
-- `affine-mcp status` — show current config and test connection
-- `affine-mcp status --json` — machine-readable status output
-- `affine-mcp doctor` — run config and connectivity diagnostics
-- `affine-mcp show-config` — print the effective config with secrets redacted
-- `affine-mcp config-path` — print the config file path
-- `affine-mcp snippet <claude|cursor|codex|all> [--env]` — print ready-to-paste client configuration snippets
-- `affine-mcp logout` — remove stored credentials
-- `affine-mcp --version` / `-v` / `version` — print the installed CLI version and exit
-
-Non-interactive login helpers:
-- `affine-mcp login --url <url> --token <token> --workspace-id <id> --force`
-
-### 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` (set `sync` only when you must block startup)
-- Tool filtering: `AFFINE_DISABLED_GROUPS`, `AFFINE_DISABLED_TOOLS` (see [Filtering Exposed Tools](#filtering-exposed-tools))
-
-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`:
+### 2. Or run the server in Docker
 
-```json
-{
-  "mcpServers": {
-    "affine": {
-      "command": "affine-mcp"
-    }
-  }
-}
+```bash
+docker run -d \
+  -p 3000:3000 \
+  -e MCP_TRANSPORT=http \
+  -e AFFINE_BASE_URL=https://your-affine-instance.com \
+  -e AFFINE_API_TOKEN=ut_your_token \
+  -e AFFINE_MCP_AUTH_MODE=bearer \
+  -e AFFINE_MCP_HTTP_TOKEN=your-strong-secret \
+  ghcr.io/dawncr0w/affine-mcp-server:latest
 ```
 
-No `env` block needed — the server reads `~/.config/affine-mcp/config` automatically.
-
-If you prefer explicit env vars instead of the config file:
+Then point your client at:
 
 ```json
 {
   "mcpServers": {
     "affine": {
-      "command": "affine-mcp",
-      "env": {
-        "AFFINE_BASE_URL": "https://app.affine.pro",
-        "AFFINE_API_TOKEN": "ut_xxx"
+      "type": "http",
+      "url": "http://localhost:3000/mcp",
+      "headers": {
+        "Authorization": "Bearer your-strong-secret"
       }
     }
   }
 }
 ```
 
-### Claude Desktop
-
-Add to your Claude Desktop configuration:
-
-- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
-- Linux: `~/.config/Claude/claude_desktop_config.json`
-
-```json
-{
-  "mcpServers": {
-    "affine": {
-      "command": "affine-mcp",
-      "env": {
-        "AFFINE_BASE_URL": "https://app.affine.pro",
-        "AFFINE_API_TOKEN": "ut_xxx"
-      }
-    }
-  }
-}
-```
+For Docker, health checks, and remote deployment details, see [docs/configuration-and-deployment.md#docker](docs/configuration-and-deployment.md#docker).
 
-Or with email/password for self-hosted instances (not supported on AFFiNE Cloud — see Cloudflare note above):
+### 3. Save credentials with interactive login
 
-```json
-{
-  "mcpServers": {
-    "affine": {
-      "command": "affine-mcp",
-      "env": {
-        "AFFINE_BASE_URL": "https://your-self-hosted-affine.com",
-        "AFFINE_EMAIL": "you@example.com",
-        "AFFINE_PASSWORD": "secret!"
-      }
-    }
-  }
-}
+```bash
+affine-mcp login
 ```
 
-Tips
-- 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.
-- `affine-mcp doctor` is the fastest way to confirm that your saved config still works.
-- `affine-mcp snippet claude --env` and `affine-mcp snippet codex --env` can generate ready-to-paste client setup from your current config.
-- `affine-mcp snippet all --env` prints Claude, Cursor, and Codex setup in one shot.
-
-### Codex CLI
-
-Register the MCP server with Codex:
-
-- With config file (after `affine-mcp login`):
-  - `codex mcp add affine -- affine-mcp`
+This stores credentials in `~/.config/affine-mcp/config` with mode `600`.
 
-- With API token:
-  - `codex mcp add affine --env AFFINE_BASE_URL=https://app.affine.pro --env AFFINE_API_TOKEN=ut_xxx -- affine-mcp`
+- For AFFiNE Cloud, use an API token from `Settings -> Integrations -> MCP Server`
+- For self-hosted AFFiNE, you can use either an API token or email/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`
+### 4. Register the server with your client
 
-### Cursor
-
-Cursor also supports MCP over stdio with `mcp.json`.
-
-Project-local (`.cursor/mcp.json`) example:
+Claude Code project config:
 
 ```json
 {
   "mcpServers": {
     "affine": {
-      "command": "affine-mcp",
-      "env": {
-        "AFFINE_BASE_URL": "https://app.affine.pro",
-        "AFFINE_API_TOKEN": "ut_xxx"
-      }
+      "command": "affine-mcp"
     }
   }
 }
 ```
 
-If you prefer `npx`:
+Codex CLI:
 
-```json
-{
-  "mcpServers": {
-    "affine": {
-      "command": "npx",
-      "args": ["-y", "-p", "affine-mcp-server", "affine-mcp"],
-      "env": {
-        "AFFINE_BASE_URL": "https://app.affine.pro",
-        "AFFINE_API_TOKEN": "ut_xxx"
-      }
-    }
-  }
-}
+```bash
+codex mcp add affine -- affine-mcp
 ```
 
-### Docker
+More client-specific setup is in [docs/client-setup.md](docs/client-setup.md).
 
-Pre-built multi-arch images (`linux/amd64`, `linux/arm64`) are published to the GitHub Container Registry on every release tag:
-
-```
-ghcr.io/dawncr0w/affine-mcp-server:latest      # latest release
-ghcr.io/dawncr0w/affine-mcp-server:1.12.0      # specific version
-```
-
-Quick start:
+### 5. Verify the connection
 
 ```bash
-docker run -d \
-  -p 3000:3000 \
-  -e AFFINE_BASE_URL=https://your-affine-instance.com \
-  -e AFFINE_API_TOKEN=ut_your_token \
-  -e AFFINE_MCP_HTTP_TOKEN=your-strong-secret \
-  ghcr.io/dawncr0w/affine-mcp-server:latest
+affine-mcp status
+affine-mcp doctor
 ```
 
-Then add to your MCP client config:
+If you want to expose the server remotely over HTTP instead of stdio, start with [docs/configuration-and-deployment.md](docs/configuration-and-deployment.md).
 
-```json
-{
-  "mcpServers": {
-    "affine": {
-      "type": "http",
-      "url": "http://localhost:3000/mcp",
-      "headers": { "Authorization": "Bearer your-strong-secret" }
-    }
-  }
-}
-```
+## Compatibility Matrix
 
-The container runs as a non-root user and exposes `/healthz` and `/readyz` for liveness/readiness probes.
+| Target | Transport | Recommended auth | Recommended path |
+| --- | --- | --- | --- |
+| Claude Code | stdio | Saved config or API token | [docs/client-setup.md#claude-code](docs/client-setup.md#claude-code) |
+| Claude Desktop | stdio | Saved config or API token | [docs/client-setup.md#claude-desktop](docs/client-setup.md#claude-desktop) |
+| Codex CLI | stdio | Saved config or API token | [docs/client-setup.md#codex-cli](docs/client-setup.md#codex-cli) |
+| Cursor | stdio | Saved config or API token | [docs/client-setup.md#cursor](docs/client-setup.md#cursor) |
+| Containerized remote deployment | HTTP | Bearer token or OAuth | [docs/getting-started.md#path-c-run-from-the-docker-image](docs/getting-started.md#path-c-run-from-the-docker-image) |
+| Remote MCP clients | HTTP | Bearer token or OAuth | [docs/configuration-and-deployment.md#http-mode](docs/configuration-and-deployment.md#http-mode) |
+| AFFiNE Cloud | stdio or HTTP | API token | [docs/configuration-and-deployment.md#auth-strategy-matrix](docs/configuration-and-deployment.md#auth-strategy-matrix) |
+| Self-hosted AFFiNE | stdio or HTTP | API token, cookie, or email/password | [docs/configuration-and-deployment.md#auth-strategy-matrix](docs/configuration-and-deployment.md#auth-strategy-matrix) |
 
-### Remote Server
+## Tool Surface
 
-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.
+`tool-manifest.json` is the source of truth for canonical tool names. The MCP server exposes those tools through `tools/list` and `tools/call`.
 
-#### Environment variables (HTTP mode)
+Domains:
 
-Required:
-- `MCP_TRANSPORT=http`
-- `AFFINE_BASE_URL` (example: `https://app.affine.pro`)
-- `AFFINE_MCP_AUTH_MODE=bearer` (default) or `AFFINE_MCP_AUTH_MODE=oauth`
+- 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
+- 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
 
-Bearer mode backend auth:
-- `AFFINE_API_TOKEN` (recommended), or `AFFINE_COOKIE`, or `AFFINE_EMAIL` + `AFFINE_PASSWORD`
+For the grouped catalog, notes, and operational caveats, see [docs/tool-reference.md](docs/tool-reference.md).
 
-OAuth mode backend auth:
-- `AFFINE_API_TOKEN` (required service credential for AFFiNE backend access)
+## Documentation Map
 
-Recommended for remote/public deployments:
-- `AFFINE_MCP_HTTP_HOST=0.0.0.0`
-- `AFFINE_MCP_HTTP_ALLOWED_ORIGINS=<comma-separated-origins>` (for browser clients)
+| Document | Purpose |
+| --- | --- |
+| [docs/getting-started.md](docs/getting-started.md) | First-run setup paths and verification |
+| [docs/client-setup.md](docs/client-setup.md) | Client-specific configuration snippets and tips |
+| [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 |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Contributor workflow |
+| [SECURITY.md](SECURITY.md) | Security reporting |
 
-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)
+## Verify Your Setup
 
-Bearer-mode only:
-- `AFFINE_MCP_HTTP_TOKEN=<strong-random-token>` (protects `/mcp`, `/sse`, `/messages`)
+Useful CLI commands:
 
-OAuth-mode only:
-- `AFFINE_MCP_PUBLIC_BASE_URL=https://mcp.yourdomain.com`
-- `AFFINE_OAUTH_ISSUER_URL=https://auth.yourdomain.com`
-- `AFFINE_OAUTH_SCOPES=mcp` (defaults to `mcp`)
+- `affine-mcp status` - test the effective configuration
+- `affine-mcp status --json` - machine-readable status output
+- `affine-mcp doctor` - diagnose config and connectivity issues
+- `affine-mcp show-config` - print the effective config with secrets redacted
+- `affine-mcp config-path` - print the config file path
+- `affine-mcp snippet <claude|cursor|codex|all> [--env]` - generate ready-to-paste client config
+- `affine-mcp logout` - remove stored credentials
 
-#### HTTP auth modes
+For common failures, see:
 
-`AFFINE_MCP_AUTH_MODE=bearer` keeps the current static bearer-token behavior.
+- [docs/getting-started.md#common-first-run-failures](docs/getting-started.md#common-first-run-failures)
+- [docs/configuration-and-deployment.md#deployment-checklist](docs/configuration-and-deployment.md#deployment-checklist)
 
-```bash
-export MCP_TRANSPORT=http
-export AFFINE_MCP_AUTH_MODE=bearer
-export AFFINE_API_TOKEN="your_token..."
-export AFFINE_MCP_HTTP_HOST="0.0.0.0"
-export AFFINE_MCP_HTTP_TOKEN="your-super-secret-token"
-export PORT=3000
-
-npm run start:http
-```
+## Security and Scope
 
-`AFFINE_MCP_AUTH_MODE=oauth` turns the MCP endpoint into an OAuth-protected resource for web MCP clients. In this mode:
-- the server exposes `/.well-known/oauth-protected-resource`
-- unauthenticated `/mcp` requests return `401` with a `WWW-Authenticate` challenge
-- `AFFINE_MCP_HTTP_TOKEN` and `?token=` are disabled
-- `sign_in` is not registered
-- `AFFINE_API_TOKEN` is still required so the server can call AFFiNE as a service credential
+- Never commit secrets or long-lived tokens
+- Prefer API tokens over cookies or passwords in production
+- Use HTTPS for non-local deployments
+- Rotate access tokens regularly
+- Restrict exposed tools with `AFFINE_DISABLED_GROUPS` and `AFFINE_DISABLED_TOOLS` for least-privilege setups
+- Use `/healthz` and `/readyz` when running the HTTP server behind a container platform or load balancer
 
-```bash
-export MCP_TRANSPORT=http
-export AFFINE_MCP_AUTH_MODE=oauth
-export AFFINE_API_TOKEN="your-affine-service-token"
-export AFFINE_MCP_HTTP_HOST="0.0.0.0"
-export AFFINE_MCP_PUBLIC_BASE_URL="https://mcp.yourdomain.com"
-export AFFINE_OAUTH_ISSUER_URL="https://auth.yourdomain.com"
-export AFFINE_OAUTH_SCOPES="mcp"
-export PORT=3000
-
-npm run start:http
-```
+## Development
 
-Notes for OAuth mode:
-- use HTTPS for non-local deployments
-- `AFFINE_MCP_HTTP_ALLOW_ALL_ORIGINS=true` is rejected in OAuth mode
-- tokens are validated against the issuer discovery metadata and JWKS
-- the protected resource metadata is also served at `/.well-known/oauth-protected-resource/mcp` for path-specific discovery
-- `GET /healthz` and `GET /readyz` are available for deployment diagnostics
-
-#### Recommended presets
-
-Local testing (HTTP mode):
-- `MCP_TRANSPORT=http`
-- `AFFINE_MCP_AUTH_MODE=bearer`
-- `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_AUTH_MODE=bearer`
-- `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_AUTH_MODE=bearer` or `oauth`
-- `AFFINE_MCP_HTTP_HOST=0.0.0.0`
-- `AFFINE_MCP_HTTP_TOKEN=<strong-token>` (bearer mode)
-- `AFFINE_MCP_PUBLIC_BASE_URL=<public base URL>` (OAuth mode)
-- `AFFINE_OAUTH_ISSUER_URL=<issuer URL>` (OAuth mode)
-- `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)
-- `/healthz` - HTTP liveness probe
-- `/readyz` - HTTP readiness probe
-
-
-## Available Tools
-
-### Workspace
-- `list_workspaces` – list all workspaces
-- `get_workspace` – get workspace details
-- `create_workspace` – create workspace with initial document
-- `update_workspace` – update workspace settings
-- `delete_workspace` – delete workspace permanently
-- `list_workspace_tree` – return the workspace document hierarchy as a tree
-- `get_orphan_docs` – find documents that are not linked from any parent doc in the sidebar tree
-
-### Organization
-- `list_collections` – list workspace collections
-- `get_collection` – get a collection by id
-- `create_collection` – create a collection
-- `update_collection` – rename a collection
-- `delete_collection` – delete a collection
-- `add_doc_to_collection` – add a document to a collection allow-list
-- `remove_doc_from_collection` – remove a document from a collection allow-list
-- `list_organize_nodes` – experimental organize/folder tree dump
-- `create_folder` – experimental root or nested folder creation
-- `rename_folder` – experimental folder rename
-- `delete_folder` – experimental recursive folder delete
-- `move_organize_node` – experimental folder/link move
-- `add_organize_link` – experimental doc/tag/collection link under a folder
-- `delete_organize_link` – experimental doc/tag/collection link delete
-
-
-### Documents
-- `list_docs` – list documents with pagination (includes `node.tags`)
-- `list_tags` – list all tags in a workspace
-- `search_docs` – fast title search with substring/prefix/exact matching, optional tag filtering, and updatedAt sorting
-- `list_docs_by_tag` – list documents that contain the requested tag
-- `get_docs_by_tag` – discover documents by case-insensitive tag substring and return `availableTags` when nothing matches
-- `get_doc` – get document metadata
-- `get_doc_by_title` – find a document by title and return its Markdown content
-- `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_doc_from_template` – clone a template doc, substitute `{{variables}}`, and optionally link it under a parent doc
-- `duplicate_doc` – clone a document into a new doc, optionally under a parent doc
-- `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
-- `update_doc_title` – rename a document in both workspace metadata and the internal page block
-- `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 (`viewMode=kanban` enables preset-backed data views; `data_view` defaults to kanban)
-- `move_doc` – move a document in the sidebar by relinking it under a different parent
-- `batch_create_docs` – create up to 20 documents in a single call
-- `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 (`title` / `Title` updates the built-in row title)
-- `delete_database_row` – delete a row from a database block by row block id
-- `read_database_columns` – read database schema metadata including column IDs/types, select options, and table view column mappings
-- `read_database_cells` – read row titles plus decoded database cell values with optional row / column filters
-- `update_database_cell` – update a single database cell or the built-in row title (`createOption` defaults to `true` for select fields)
-- `update_database_row` – batch update multiple cells on a database row (`createOption` defaults to `true` for select fields)
-- `append_markdown` – append markdown content to an existing document
-- `replace_doc_with_markdown` – replace the main note content with markdown content
-- `list_children` – list the direct child docs linked from a document
-- `list_backlinks` – list the parent/reference docs that link to a document
-- `cleanup_orphan_embeds` – remove linked-doc embeds that point to missing docs
-- `find_and_replace` – preview or apply text replacement across a document
-- `delete_doc` – delete a document (WebSocket)
-
-### Comments
-- `list_comments`, `create_comment`, `update_comment`, `delete_comment`, `resolve_comment`
-
-### Version History
-- `list_histories`
-
-### Users & Tokens
-- `current_user`, `sign_in`, `update_profile`, `update_settings`
-- `list_access_tokens`, `generate_access_token`, `revoke_access_token`
-
-### Notifications
-- `list_notifications`, `read_all_notifications`
-
-### Blob Storage
-- `upload_blob`, `delete_blob`, `cleanup_blobs`
-
-## Filtering Exposed Tools
-
-Optional environment variables to narrow the exposed surface. 
-
-### Group-level — `AFFINE_DISABLED_GROUPS`
-
-| Group name | Tools included |
-|---|---|
-| `workspaces` | `list_workspaces`, `get_workspace`, `create_workspace`, `update_workspace`, `delete_workspace` |
-| `docs` | `list_docs`, `read_doc`, `search_docs`, `create_doc`, `create_doc_from_markdown`, `create_doc_from_template`, `duplicate_doc`, `append_paragraph`, `append_block`, `append_markdown`, `replace_doc_with_markdown`, `delete_doc`, `publish_doc`, `revoke_doc`, `list_tags`, `list_docs_by_tag`, `create_tag`, `add_tag_to_doc`, `remove_tag_from_doc`, `list_workspace_tree`, `get_orphan_docs`, `list_children`, `update_doc_title`, `get_doc_by_title`, `get_docs_by_tag`, `list_backlinks`, `move_doc`, `batch_create_docs`, `cleanup_orphan_embeds`, `find_and_replace`, `add_database_column`, `add_database_row`, `delete_database_row`, `read_database_columns`, `read_database_cells`, `update_database_cell`, `update_database_row` |
-| `comments` | `list_comments`, `create_comment`, `update_comment`, `delete_comment`, `resolve_comment` |
-| `history` | `list_histories` |
-| `organize` | `list_collections`, `get_collection`, `create_collection`, `update_collection`, `delete_collection`, `add_doc_to_collection`, `remove_doc_from_collection`, `list_organize_nodes`, `create_folder`, `rename_folder`, `delete_folder`, `move_organize_node`, `add_organize_link`, `delete_organize_link` |
-| `users` | `current_user`, `sign_in`, `update_profile`, `update_settings` |
-| `access_tokens` | `list_access_tokens`, `generate_access_token`, `revoke_access_token` |
-| `blobs` | `upload_blob`, `delete_blob`, `cleanup_blobs` |
-| `notifications` | `list_notifications`, `read_all_notifications` |
+Run the main quality gates before opening a PR:
 
-```json
-"env": {
-  "AFFINE_DISABLED_GROUPS": "comments,history,blobs,users"
-}
+```bash
+npm run build
+npm run test:tool-manifest
+npm run pack:check
 ```
 
-### Tool-level — `AFFINE_DISABLED_TOOLS`
-
-Disables individual tools by exact name (comma-separated). 
+Additional validation:
 
-```json
-"env": {
-  "AFFINE_DISABLED_TOOLS": "delete_workspace,delete_doc"
-}
-```
+- `npm run test:comprehensive` boots a local Docker AFFiNE stack and validates the tool surface
+- `npm run test:e2e` runs Docker, MCP, and Playwright together
+- `npm run test:playwright` runs the Playwright suite only
+- Focused runners for the new high-level tool surface include `npm run test:create-placement`, `npm run test:capabilities-fidelity`, `npm run test:native-template`, `node tests/test-database-intent.mjs`, `node tests/test-semantic-page-composer.mjs`, `node tests/test-structured-receipts.mjs`, `node tests/test-organize-tools.mjs`, and `node tests/test-supporting-tools.mjs`
 
-## Use Locally (clone)
+Local clone flow:
 
 ```bash
 git clone https://github.com/dawncr0w/affine-mcp-server.git
 cd affine-mcp-server
 npm install
 npm run build
-# Run directly
 node dist/index.js
-
-# Or expose as a global CLI for Codex/Claude without publishing
-npm link
-# Now use `affine-mcp` like a global binary
 ```
 
-## Quality Gates
-
-```bash
-npm run build
-npm run test:tool-manifest
-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` (self-bootstraps a local Docker AFFiNE stack).
-- For pre-provisioned environments, use `npm run test:comprehensive:raw`.
-- For full environment verification, run `npm run test:e2e` (Docker + MCP + Playwright).
-- Additional focused runners: `npm run test:db-create`, `npm run test:db-cells`, `npm run test:db-schema`, `npm run test:supporting-tools`, `npm run test:organize`, `npm run test:bearer`, `npm run test:http-email-password`, `npm run test:http-bearer`, `npm run test:oauth-http`, `npm run test:doc-discovery`, `npm run test:cli-version`, `npm run test:cli-commands`, `npm run test:cli-live`, `npm run test:tool-filtering`, `npm run test:markdown-rich-text-import`, `npm run test:playwright`.
-
-## Troubleshooting
-
-Authentication
-- **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. 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
-- Confirm `AFFINE_BASE_URL` is reachable
-- GraphQL endpoint default is `/graphql`
-- Check firewall/proxy rules; verify CORS if self‑hosted
-
-Method not found
-- MCP tool names (for example `list_workspaces`) are not JSON-RPC top-level method names.
-- Use an MCP client (`tools/list`, `tools/call`) instead of sending direct JSON-RPC calls like `{\"method\":\"list_workspaces\"}`.
-- From v1.3.0, only canonical tool names are exposed (legacy `affine_*` aliases were removed).
-
-Workspace visibility
-- This MCP server can access server-backed workspaces only (AFFiNE cloud/self-hosted).
-- Browser local-storage workspaces are client-side data, so they are not visible via server GraphQL/WebSocket APIs.
-
-## Security Considerations
-
-- Never commit `.env` with secrets
-- Prefer environment variables in production
-- Rotate access tokens regularly
-- Use HTTPS
-- Store credentials in a secrets manager
-
 ## Release Notes
 
-- Changelog: [CHANGELOG.md](CHANGELOG.md)
-- Release notes: [RELEASE_NOTES.md](RELEASE_NOTES.md)
-- GitHub Releases: [Releases](https://github.com/dawncr0w/affine-mcp-server/releases)
-
-## Contributing
-
-Contributions are welcome!
-1. Read `CONTRIBUTING.md`
-2. Run `npm run ci` locally before opening PR
-3. Keep tool changes synced with `tool-manifest.json`
-4. Use issue/PR templates in `.github/`
-
-## Community Health
-
-- Code of Conduct: `CODE_OF_CONDUCT.md`
-- Security policy: `SECURITY.md`
-- Contributing guide: `CONTRIBUTING.md`
+- [CHANGELOG.md](CHANGELOG.md)
+- [RELEASE_NOTES.md](RELEASE_NOTES.md)
+- [GitHub Releases](https://github.com/dawncr0w/affine-mcp-server/releases)
 
 ## License
 
-MIT License - see LICENSE file for details
+MIT License - see [LICENSE](LICENSE).
 
 ## Support
 
-For issues and questions:
 - Open an issue on [GitHub](https://github.com/dawncr0w/affine-mcp-server/issues)
-- Check AFFiNE documentation at https://docs.affine.pro
-
-## Author
-
-**dawncr0w** - [GitHub](https://github.com/dawncr0w)
+- Review AFFiNE product documentation at [docs.affine.pro](https://docs.affine.pro)
 
 ## Acknowledgments