AFFiNE MCP Server

# Changelog All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] ## [1.7.0] - 2026-02-27 ### Added - Optional HTTP deployment mode with Streamable HTTP endpoint `/mcp` and backward-compatible legacy endpoints (`/sse`, `/messages`) for remote MCP clients. - New `start:http` npm script (`MCP_TRANSPORT=http node dist/index.js`) for one-command HTTP mode startup. - HTTP runtime dependencies and typings for remote hosting (`express`, `cors`, `@types/express`, `@types/cors`). ### Changed - `MCP_TRANSPORT` now supports `stdio` (default), `http`/`streamable`, and legacy alias `sse`. - Added HTTP deployment environment controls: `AFFINE_MCP_HTTP_HOST`, `AFFINE_MCP_HTTP_TOKEN`, `AFFINE_MCP_HTTP_ALLOWED_ORIGINS`, `AFFINE_MCP_HTTP_ALLOW_ALL_ORIGINS`. - WebSocket ack flow was simplified with shared timeout/error handling utilities. - Workspace bootstrap now propagates the optional `avatar` argument into initial workspace metadata. - README and remote deployment guidance expanded with security defaults and hosting presets. ### Fixed - `/mcp` now consistently applies the 50MB JSON parser for large MCP payloads. - HTTP bearer authentication now accepts case-insensitive scheme variants (`Bearer` / `bearer`). - Removed dead config/type scaffolding and tightened internal config parsing for header JSON. ## [1.6.0] - 2026-02-24 ### Added - 11 new document workflow tools: `list_tags`, `list_docs_by_tag`, `create_tag`, `add_tag_to_doc`, `remove_tag_from_doc`, `export_doc_markdown`, `create_doc_from_markdown`, `append_markdown`, `replace_doc_with_markdown`, `add_database_column`, `add_database_row`. - Interactive CLI subcommands: `affine-mcp login`, `affine-mcp status`, `affine-mcp logout`. - End-to-end verification pipeline with Docker and Playwright (`tests/run-e2e.sh`, `.github/workflows/e2e.yml`). - New npm test commands: `test:e2e`, `test:db-create`, `test:bearer`, `test:playwright`. ### Changed - Tool surface expanded from 32 to 43 canonical tools. - Runtime server version now resolves from `package.json` through `src/config.ts` (`VERSION`) and is reused by runtime/CLI user-agent headers. - Authentication/bootstrap flow supports config-file fallback (`~/.config/affine-mcp/config`) and Bearer headers across GraphQL/WebSocket paths. - `list_docs` now enriches each document node with tags from workspace metadata snapshots. - Added markdown and E2E test dependencies in package metadata (`markdown-it`, `@types/markdown-it`, `@playwright/test`). - `workspaces` and `blobStorage` tools now use typed `GraphQLClient` accessors and shared bearer/cookie propagation. - `test-comprehensive.mjs` now asserts tag workflows and markdown roundtrip workflows. ### Fixed - Hardened GraphQL/auth error handling for redirects, non-JSON responses, and timeout boundaries. - Added CR/LF guardrails for cookie/header handling to prevent header-injection edge cases. - Added `.gitignore` rules for generated E2E and Playwright artifacts. ## [1.5.0] - 2026-02-13 ### Added - `append_block` Step4 types: `database`, `data_view`, `surface_ref`, `frame`, `edgeless_text`, `note`. - Local integration coverage for all append profiles (`step1`..`step4`) in `scripts/test-append-block-expansion.mjs`. ### Changed - `append_block` canonical type set expanded to 30 verified cases with stricter field validation and parent-container checks. - Step4 creation payloads now use Yjs-native value types (`Y.Map`/`Y.Array`) to avoid runtime serialization failures. ### Fixed - Resolved `Unexpected content type` failures while appending database/edgeless blocks. - Aligned `surface_ref` caption validation with block creation behavior. - Prevented AFFiNE UI runtime crashes from `type=data_view` by mapping it to stable `affine:database` output. ## [1.4.0] - 2026-02-13 ### Added - `read_doc` tool to read document block snapshots and plain text via WebSocket. ### Changed - README now includes Cursor MCP setup examples and explicit troubleshooting for `Method not found` JSON-RPC misuse. - README now documents that browser local-storage workspaces are not accessible via server APIs. ### Fixed - Runtime MCP server metadata version in `src/index.ts` updated to `1.4.0`. ## [1.3.0] - 2026-02-13 ### Added - Open-source community health files: `CODE_OF_CONDUCT.md`, `CONTRIBUTING.md`, `SECURITY.md`. - GitHub community templates: bug/feature issue templates and PR template. - CI workflow (`.github/workflows/ci.yml`) and Dependabot config. - Tool manifest (`tool-manifest.json`) and static verification script (`npm run test:tool-manifest`). ### Changed - Tool surface simplified to 31 canonical tools with no duplicated alias names. - Comprehensive integration test script now validates runtime tool list against `tool-manifest.json`. - Package metadata improved (`bugs`, `homepage`) and new quality scripts (`npm run ci`, `npm run pack:check`). ### Removed - Duplicated alias tools (`affine_*`) and low-value/unstable tools from default surface. - Deprecated `src/tools/updates.ts` and legacy workspace fixed alias tooling. ## [1.2.2] - 2025-09-18 ### Fixed - CLI binary now runs through Node via `bin/affine-mcp`, preventing shells from misinterpreting ESM JS files and avoiding false startup timeouts. ### Changed - Documentation: removed `.env`-based configuration guidance; recommend environment variables via shell or app configuration. - Version badges and examples refreshed; clarified non-blocking login default. ## [1.2.1] - 2025-09-17 ### Changed - Default startup authentication is now asynchronous when using email/password to avoid MCP stdio handshake timeouts. Use `AFFINE_LOGIN_AT_START=sync` only when blocking startup is required. - Docs fully refreshed: clear instructions for Codex CLI and Claude Desktop using npm, npx, and local clone workflows. ### Added - README examples for `codex mcp add` with `affine-mcp` and with `npx -p affine-mcp-server affine-mcp`. - Local clone usage guide and `npm link` workflow. ### Removed - Unnecessary repo artifacts (e.g., `.env.example`, `.dockerignore`). ## [1.2.0] - 2025-09-16 ### 🚀 Major Document create/edit/delete is now supported. These are synchronized to real AFFiNE docs via WebSocket (Yjs) updates. Tools: `create_doc`, `append_paragraph`, `delete_doc`. ### Added - WebSocket-based document tools: `create_doc`, `append_paragraph`, `delete_doc` - CLI binary `affine-mcp` for stdio MCP integration (Claude / Codex) - Tool aliases: support both prefixed (`affine_*`) and non-prefixed names - Published on npm with a one-line global install: `npm i -g affine-mcp-server` ### Changed - TypeScript ESM resolution switched to NodeNext for stable `.js` imports in TS - Docs updated for npm publish and Codex usage ### Fixed - Unified MCP return types with helper to satisfy SDK type constraints ## [1.1.0] - 2025-08-12 ### 🎯 Key Achievement - **FIXED**: Critical workspace creation issue - workspaces are now fully accessible in UI - Successfully creates workspaces with initial documents using Yjs CRDT structure ### Added - ✨ Workspace creation with initial document support - 📦 Blob storage management tools (3 tools) - 🔔 Notification management tools (3 tools) - 👤 User CRUD operations (4 tools) - 🧪 Comprehensive test suite ### Changed - 🎯 Simplified tool names (removed `affine_` prefix) - 📁 Consolidated workspace tools into single module - 🔧 Improved authentication with fallback chain - 📝 Enhanced error messages and validation - ⚡ Streamlined codebase structure ### Fixed - 🐛 Workspace creation now works correctly with UI - 🐛 Document metadata properly structured - 🐛 Authentication flow issues resolved - 🐛 GraphQL query structures corrected ### Removed - ❌ Experimental tools (not production ready) - ❌ Docker support (incompatible with stdio) - ❌ Non-working realtime tools - ❌ Redundant CRUD duplicates ### Technical Details - Uses Yjs CRDT for document structure - BlockSuite-compatible document format - WebSocket support for sync operations - 30+ verified working tools ## [1.0.0] - 2025-08-12 ### Added - Initial stable release - 21 core tools for AFFiNE operations - Full MCP SDK 1.17.2 compatibility - Complete authentication support (Token, Cookie, Email/Password) - GraphQL API integration - Comprehensive documentation ### Features - Workspace management - Document operations - Comments system - Version history - User management - Access tokens [1.7.0]: https://github.com/dawncr0w/affine-mcp-server/releases/tag/v1.7.0 [1.2.2]: https://github.com/dawncr0w/affine-mcp-server/releases/tag/v1.2.2 [1.2.1]: https://github.com/dawncr0w/affine-mcp-server/releases/tag/v1.2.1 [1.2.0]: https://github.com/dawncr0w/affine-mcp-server/releases/tag/v1.2.0 [1.1.0]: https://github.com/dawncr0w/affine-mcp-server/releases/tag/v1.1.0 [1.0.0]: https://github.com/dawncr0w/affine-mcp-server/releases/tag/v1.0.0 [1.5.0]: https://github.com/dawncr0w/affine-mcp-server/releases/tag/v1.5.0 [1.4.0]: https://github.com/dawncr0w/affine-mcp-server/releases/tag/v1.4.0 [1.3.0]: https://github.com/dawncr0w/affine-mcp-server/releases/tag/v1.3.0 [1.6.0]: https://github.com/dawncr0w/affine-mcp-server/releases/tag/v1.6.0 [Unreleased]: https://github.com/dawncr0w/affine-mcp-server/compare/v1.7.0...HEAD