Affine MCP Server

🚀 AFFiNE MCP Server

AFFiNE MCP Serverは、自前でホストしたAFFiNEインスタンスやクラウド上のAFFiNEインスタンスとシームレスに統合できる、Model Context Protocol (MCP) サーバーです。このサーバーにより、AIアシスタントは標準化されたインターフェースを通じてAFFiNEのワークスペースやドキュメントとやり取りすることができます。

🚀 クイックスタート

AFFiNE MCP Serverを使うことで、AIアシスタントがAFFiNEのワークスペースやドキュメントとやり取りできるようになります。以下の手順に従ってサーバーをセットアップしてください。

✨ 主な機能

• ワークスペース管理：初期ドキュメント付きでワークスペースを作成できます（UIからアクセス可能）。
• ドキュメント操作：ドキュメントの一覧表示、検索、管理が可能です。
• ユーザー管理：認証とプロファイル管理を行えます。
• コメントシステム：コメントのCRUD操作を完全にサポートします。
• バージョン履歴：ドキュメントの履歴と復元機能があります。
• 通知：通知の閲覧と管理ができます。

📦 インストール

# リポジトリをクローンする
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つの方法を選択）:

# オプション1: ベアラートークン（最優先）
AFFINE_API_TOKEN=your_personal_access_token

# オプション2: セッションクッキー
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. ベアラートークン (AFFINE_API_TOKEN) - 最優先
2. クッキー (AFFINE_COOKIE)
3. メールアドレス/パスワード (AFFINE_EMAIL + AFFINE_PASSWORD) - フォールバック

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"
    }
  }
}

利用可能なツール

ワークスペース管理 (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 - すべての通知を既読にします。

ブロブストレージ (3つのツール)

• upload_blob - ファイル/ブロブをアップロードします。
• delete_blob - ブロブを削除します。
• cleanup_blobs - 削除されたブロブをクリーンアップします。

高度な機能 (1つのツール)

• apply_doc_updates - CRDT更新をドキュメントに適用します。

テスト

# 包括的なテストを実行する
node test-comprehensive.mjs

# ワークスペース作成のテストを実行する
node test-fixed-workspace.mjs

トラブルシューティング

認証問題

1. メールアドレス/パスワードが失敗する場合：
   • AFFiNEインスタンスがパスワード認証を許可していることを確認してください。
   • AFFiNEサーバーへのネットワーク接続を確認してください。
   • 資格情報が正しいことを確認してください。
2. クッキー認証の場合：
   • ブラウザの開発者ツールのネットワークタブからクッキーを抽出してください。
   • ログイン後に affine_session クッキーを探してください。
   • AFFINE_COOKIE に関連するすべてのクッキーを含めてください。
3. トークン認証の場合：
   • AFFiNEのユーザー設定からトークンを生成してください。
   • トークンが期限切れになっていないことを確認してください。
   • AFFINE_API_TOKEN に完全なトークン文字列を使用してください。

接続問題

• AFFINE_BASE_URL にアクセスできることを確認してください。
• GraphQLエンドポイントが /graphql（デフォルト）にあることを確認してください。
• ファイアウォール/プロキシが接続をブロックしていないことを確認してください。
• 自前でホストしたインスタンスの場合は、CORS設定を確認してください。

セキュリティに関する考慮事項

• 資格情報を含む .env ファイルを決してコミットしないでください。
• 本番環境では環境変数を使用してください。
• アクセストークンを定期的にローテーションしてください。
• AFFiNEの接続には常にHTTPSを使用してください。
• 資格情報を安全な資格情報マネージャーに保存してください。

バージョン履歴

1.1.0 (2025-08-12)

• ✅ 初期ドキュメント付きのワークスペース作成の問題を修正しました。
• AFFiNEの包括的な管理のための30以上のツールを追加しました。
• ワークスペース作成をUIからアクセス可能にしました。
• エラーハンドリングと認証を改善しました。
• ツール名を簡素化して使いやすくしました。

1.0.0 (2025-08-12)

• 最初の安定版リリースです。
• 基本的なワークスペースとドキュメント操作をサポートします。
• 完全な認証サポートを提供します。

コントリビューション

コントリビューションは大歓迎です！以下の手順に従ってください。

1. リポジトリをフォークします。
2. 機能ブランチを作成します。
3. 新しい機能に対するテストを追加します。
4. すべてのテストが通過することを確認します。
5. プルリクエストを送信します。

📄 ライセンス

MITライセンス - 詳細は LICENSE ファイルを参照してください。

サポート

問題や質問については、以下の方法で対応します。

• GitHub でイシューを開いてください。
• https://docs.affine.pro のAFFiNEドキュメントを確認してください。

作者

dawncr0w - GitHub

謝辞

• AFFiNE 知識ベースプラットフォーム向けに構築されました。
• Model Context Protocol 仕様を使用しています。
• @modelcontextprotocol/sdk を使用しています。