Affine MCP Server

🚀 AFFiNE MCP 服務器

AFFiNE MCP 服務器是一個基於模型上下文協議（MCP）的服務器，它能夠與自託管或雲端的 AFFiNE 實例實現無縫集成。藉助該服務器，AI 助手可以通過標準化接口與 AFFiNE 工作區和文檔進行交互。

🚀 快速開始

與 Claude Desktop 集成

將以下內容添加到你的 Claude Desktop 配置文件中：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "affine": {
      "command": "node",
      "args": ["/path/to/affine-mcp-server/dist/index.js"],
      "env": {
        "AFFINE_BASE_URL": "https://your-affine-instance.com",
        "AFFINE_EMAIL": "your@email.com",
        "AFFINE_PASSWORD": "your_password"
      }
    }
  }
}

與 Codebase CLI (codex) 集成

將以下內容添加到你的 Codebase CLI 配置文件中：

{
  "affine": {
    "command": "node",
    "args": ["/path/to/affine-mcp-server/dist/index.js"],
    "env": {
      "AFFINE_BASE_URL": "https://your-affine-instance.com",
      "AFFINE_EMAIL": "your@email.com", 
      "AFFINE_PASSWORD": "your_password"
    }
  }
}

✨ 主要特性

• 工作區管理：可以創建帶有初始文檔的工作區，並且可通過 UI 進行操作。
• 文檔操作：支持列出、搜索和管理文檔。
• 用戶管理：提供認證和用戶資料管理功能。
• 評論系統：具備完整的評論創建、讀取、更新和刪除操作。
• 版本歷史：可查看文檔歷史記錄並進行恢復操作。
• 通知管理：支持讀取和管理通知。

📦 安裝指南

# 克隆倉庫
git clone https://github.com/dawncr0w/affine-mcp-server.git
cd affine-mcp-server

# 安裝依賴
npm install

# 構建 TypeScript 代碼
npm run build

📚 詳細文檔

配置

在項目根目錄下創建一個 .env 文件：

# AFFiNE 服務器 URL（必需）
AFFINE_BASE_URL=https://your-affine-instance.com

# 認證方式（選擇一種）：

# 選項 1：Bearer Token（優先級最高）
AFFINE_API_TOKEN=your_personal_access_token

# 選項 2：會話 Cookie
AFFINE_COOKIE=affine_session=xxx; affine_csrf=yyy

# 選項 3：郵箱/密碼（備用）
AFFINE_EMAIL=your@email.com
AFFINE_PASSWORD=your_password

# 可選設置
AFFINE_GRAPHQL_PATH=/graphql  # 默認值：/graphql
AFFINE_WORKSPACE_ID=workspace-uuid  # 操作的默認工作區

認證優先級

服務器按以下順序檢查認證方式：

1. Bearer Token (AFFINE_API_TOKEN) - 優先級最高
2. Cookie (AFFINE_COOKIE)
3. 郵箱/密碼 (AFFINE_EMAIL + AFFINE_PASSWORD) - 備用

可用工具

工作區管理（5 個工具）

• list_workspaces - 列出所有可訪問的工作區
• get_workspace - 獲取工作區詳細信息
• create_workspace - 創建帶有初始文檔的工作區 ✅
• update_workspace - 更新工作區設置
• delete_workspace - 永久刪除工作區

文檔操作（6 個工具）

• list_docs - 分頁列出文檔
• get_doc - 獲取文檔元數據
• search_docs - 按關鍵字搜索文檔
• recent_docs - 列出最近更新的文檔
• publish_doc - 使文檔公開
• revoke_doc - 撤銷文檔的公開訪問權限

評論（5 個工具）

• list_comments - 列出文檔評論
• create_comment - 創建新評論
• update_comment - 更新評論內容
• delete_comment - 刪除評論
• resolve_comment - 解決/未解決評論

版本歷史（2 個工具）

• list_histories - 查看文檔歷史記錄
• recover_doc - 恢復到之前的版本

用戶管理（4 個工具）

• current_user - 獲取當前用戶信息
• sign_in - 使用郵箱/密碼登錄
• update_profile - 更新用戶資料
• update_settings - 更新用戶設置

訪問令牌（3 個工具）

• list_access_tokens - 列出個人訪問令牌
• generate_access_token - 創建新的訪問令牌
• revoke_access_token - 撤銷訪問令牌

通知（3 個工具）

• list_notifications - 獲取通知
• read_notification - 將通知標記為已讀
• read_all_notifications - 將所有通知標記為已讀

Blob 存儲（3 個工具）

• upload_blob - 上傳文件/blob
• delete_blob - 刪除 blob
• cleanup_blobs - 清理已刪除的 blob

高級（1 個工具）

• apply_doc_updates - 將 CRDT 更新應用到文檔

測試

# 運行全面測試
node test-comprehensive.mjs

# 測試工作區創建
node test-fixed-workspace.mjs

故障排除

認證問題

1. 郵箱/密碼認證失敗：
   • 確保你的 AFFiNE 實例允許使用密碼認證。
   • 檢查與 AFFiNE 服務器的網絡連接。
   • 驗證憑證是否正確。
2. Cookie 認證：
   • 從瀏覽器開發者工具的網絡選項卡中提取 Cookie。
   • 登錄後查找 affine_session Cookie。
   • 將所有相關 Cookie 包含在 AFFINE_COOKIE 中。
3. Token 認證：
   • 從 AFFiNE 用戶設置中生成 Token。
   • 確保 Token 未過期。
   • 在 AFFINE_API_TOKEN 中使用完整的 Token 字符串。

連接問題

• 驗證 AFFINE_BASE_URL 是否可訪問。
• 檢查 GraphQL 端點是否為 /graphql（默認值）。
• 確保沒有防火牆或代理阻止連接。
• 對於自託管實例，驗證 CORS 設置。

安全注意事項

• 切勿提交包含憑證的 .env 文件。
• 在生產環境中使用環境變量。
• 定期輪換訪問令牌。
• 始終使用 HTTPS 進行 AFFiNE 連接。
• 將憑證存儲在安全的憑證管理器中。

版本歷史

1.1.0 (2025-08-12)

• ✅ 修復了創建帶有初始文檔的工作區的問題。
• 添加了 30 多個用於全面管理 AFFiNE 的工具。
• 現在可以通過 UI 創建工作區。
• 改進了錯誤處理和認證機制。
• 簡化了工具名稱，提高了可用性。

1.0.0 (2025-08-12)

• 初始穩定版本。
• 支持基本的工作區和文檔操作。
• 提供完整的認證支持。

貢獻

歡迎貢獻代碼！請按照以下步驟進行：

1. 分叉倉庫。
2. 創建功能分支。
3. 為新功能添加測試。
4. 確保所有測試通過。
5. 提交拉取請求。

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

支持

如有問題或疑問：

• 在 GitHub 上提交問題。
• 查看 AFFiNE 文檔：https://docs.affine.pro

作者

dawncr0w - GitHub

致謝

• 為 AFFiNE 知識庫平臺構建。
• 使用 Model Context Protocol 規範。
• 由 @modelcontextprotocol/sdk 提供支持。