affine-mcp-server 1.9.0 → 1.10.1

package/README.md

@@ -2,7 +2,7 @@
 
 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.9.0-blue)](https://github.com/dawncr0w/affine-mcp-server/releases)
+[![Version](https://img.shields.io/badge/version-1.10.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)
@@ -16,10 +16,10 @@ A Model Context Protocol (MCP) server that integrates with AFFiNE (self‑hosted
 - 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: 47 focused tools with WebSocket-based document editing
+- Tools: 61 focused tools with WebSocket-based document editing
 - Status: Active
  
-> New in v1.9.0: Added database schema discovery, preset-backed data views, self-bootstrapping comprehensive regression, focused supporting-tools coverage, and markdown callout round-trips.
+> New in v1.10.1: Refreshed packaged docs and release metadata for the v1.10.x toolset, and tightened tag-publish validation with E2E coverage. No runtime or tool-behavior changes.
 
 ## Features
 
@@ -93,7 +93,12 @@ The MCP server will use these credentials automatically.
 ```
 
 Other CLI commands:
+- `affine-mcp --help` / `-h` / `help` — show command help
 - `affine-mcp status` — show current config and test connection
+- `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> [--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
 
@@ -186,6 +191,8 @@ Or with email/password for self-hosted instances (not supported on AFFiNE Cloud
 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.
 
 ### Codex CLI
 
@@ -246,12 +253,16 @@ If you want to host the server remotely (e.g., using Render, Railway, Docker, or
 Required:
 - `MCP_TRANSPORT=http`
 - `AFFINE_BASE_URL` (example: `https://app.affine.pro`)
-- One auth method:
+- `AFFINE_MCP_AUTH_MODE=bearer` (default) or `AFFINE_MCP_AUTH_MODE=oauth`
+
+Bearer mode backend auth:
 - `AFFINE_API_TOKEN` (recommended), or `AFFINE_COOKIE`, or `AFFINE_EMAIL` + `AFFINE_PASSWORD`
 
+OAuth mode backend auth:
+- `AFFINE_API_TOKEN` (required service credential for AFFiNE backend access)
+
 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:
@@ -260,31 +271,68 @@ Optional:
 - `AFFINE_GRAPHQL_PATH` (defaults to `/graphql`)
 - `AFFINE_MCP_HTTP_ALLOW_ALL_ORIGINS=true` (testing only)
 
+Bearer-mode only:
+- `AFFINE_MCP_HTTP_TOKEN=<strong-random-token>` (protects `/mcp`, `/sse`, `/messages`)
+
+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`)
+
+#### HTTP auth modes
+
+`AFFINE_MCP_AUTH_MODE=bearer` keeps the current static bearer-token behavior.
+
 ```bash
-# Export your configuration first
 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" # Default: 127.0.0.1
+export AFFINE_MCP_HTTP_HOST="0.0.0.0"
 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)
 ```
 
+`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
+
+```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
+```
+
+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>`
@@ -292,14 +340,19 @@ Docker / container runtime:
 
 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>`
+- `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
 
@@ -309,23 +362,33 @@ Endpoints currently available:
 - `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
 
 ### Documents
 - `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
+- `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)
 - `read_database_columns` – read database schema metadata including column IDs/types, select options, and table view column mappings
@@ -334,6 +397,10 @@ Endpoints currently available:
 - `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
@@ -380,7 +447,7 @@ npm run pack:check
 - 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:bearer`, `npm run test:cli-version`, `npm run test: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: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:playwright`.
 
 ## Troubleshooting