MCP Notes Connector

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## プロジェクト概要 Evernote APIを利用したModel Context Protocol (MCP) サーバーの実装。Claude DesktopなどのMCPクライアントから、Evernoteのノート、ノートブック、タグなどにアクセス可能にする。 ## 開発コマンド ```bash # 仮想環境の作成 python -m venv venv # 仮想環境の有効化 # Windows: venv\Scripts\activate # Linux/Mac: source venv/bin/activate # 依存関係のインストール pip install -r requirements.txt # 開発版インストール（編集可能モード） pip install -e ".[dev]" # サーバー起動 python -m mcp_notes_connector.server # または（pip install後） mcp-notes-connector # テスト実行 pytest # コードフォーマット black src/ tests/ # Lint ruff check src/ tests/ # 型チェック mypy src/ ``` ## アーキテクチャ ### 3層構造 1. **MCPサーバー層** ([src/mcp_notes_connector/server.py](src/mcp_notes_connector/server.py)) - `EvernoteMCPServer`クラスがMCPプロトコルを実装 - stdio経由でMCPクライアントと通信 - `@server.list_tools()`デコレーターでツール一覧を提供 - `@server.call_tool()`デコレーターでツール実行を処理 - 各ツールに対応する`_handle_*`メソッドでロジックを実装 - 全て非同期処理（`async/await`）で実装 2. **Evernote統合層** ([src/mcp_notes_connector/evernote_client.py](src/mcp_notes_connector/evernote_client.py)) - `EvernoteClient`クラスがEvernote APIへのアクセスを抽象化 - 認証トークンとサンドボックス設定を管理 - APIレスポンスの正規化とエラーハンドリング - evernote3パッケージを使用 3. **型定義層** ([src/mcp_notes_connector/types.py](src/mcp_notes_connector/types.py)) - プロジェクト全体で共有される型定義 - TypedDictを使用した型安全性の確保 - Evernote APIのレスポンス型をPython型として定義 ### データフロー ``` MCPクライアント (stdio) ↓ EvernoteMCPServer (MCPハンドラー) ↓ EvernoteClient (API呼び出し) ↓ Evernote API ``` ## 新機能の追加方法 新しいEvernote機能（ツール）を追加する場合： 1. **ツール定義を追加** - [src/mcp_notes_connector/server.py](src/mcp_notes_connector/server.py)の`@server.list_tools()`デコレーター内の`return`リストに新しい`Tool`オブジェクトを追加 - `name`: ツール名（文字列） - `description`: 機能説明（日本語可） - `inputSchema`: JSON Schemaでパラメータを定義（辞書形式） 2. **ハンドラーメソッドを実装** - 同ファイル内に`async def _handle_*`メソッドを追加し、`@server.call_tool()`デコレーター内のif-elif分岐に新しいツール名を追加 3. **Evernote APIクライアントメソッドを追加** - [src/mcp_notes_connector/evernote_client.py](src/mcp_notes_connector/evernote_client.py)に`async def`で実際のAPI呼び出しロジックを実装 4. **型定義を追加** - 必要に応じて[src/mcp_notes_connector/types.py](src/mcp_notes_connector/types.py)に新しいTypedDictクラスを定義 ## 環境変数 必須の環境変数（`.env`ファイルまたはシステム環境変数で設定）： - `EVERNOTE_TOKEN`: Evernote開発者トークン（必須） - `EVERNOTE_SANDBOX`: サンドボックス環境使用時は`true`、本番環境は`false`（オプション、デフォルト: false） `.env.example`をコピーして`.env`を作成し、適切な値を設定すること。 ## Pythonプロジェクト構造 - パッケージは`src/mcp_notes_connector/`配下に配置 - `pyproject.toml`でプロジェクト設定とビルド設定を管理 - 仮想環境（`venv/`）を使用して依存関係を隔離 - エントリーポイントは`mcp-notes-connector`コマンドとして登録 - 開発時は`pip install -e ".[dev]"`で編集可能モードでインストール ## 非同期処理 - 全てのAPI呼び出しとMCP通信は非同期（`async/await`） - `asyncio.run()`でイベントループを起動 - `stdio_server()`でstdio通信を非同期処理 - テストには`pytest-asyncio`を使用 ## プロジェクトの現状 **実装状況**: 骨組み完成、APIクライアント未実装 現在、MCPサーバーの基本構造は完成していますが、Evernote API連携部分はスタブ状態です。 詳細な実装状況、動作確認状況、今後のロードマップは[docs/STATUS.md](docs/STATUS.md)を参照してください。 ### 次に実装すべき項目 1. Evernote APIクライアントの初期化（evernote3パッケージ） 2. 認証処理の実装 3. `list_notebooks()`の実装 4. `get_note()`の実装 ## Evernote API について - サンドボックス環境と本番環境でエンドポイントが異なる - ノート内容はENML（Evernote Markup Language）形式で管理される - GUIDはEvernote内のリソース識別子として使用される（ノート、ノートブック、タグなど） - evernote3パッケージは同期APIのため、`asyncio.to_thread()`等での非同期化が必要 ## 参考ドキュメント - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) - 詳細なアーキテクチャ解説 - [docs/STATUS.md](docs/STATUS.md) - 実装状況とロードマップ