MCP Notes Connector

# アーキテクチャ概要 ## システム構成 MCP Notes Connectorは、Model Context Protocol (MCP) を実装し、Evernote APIへのアクセスを提供するPythonサーバーです。 ### 主要コンポーネント ``` ┌─────────────────────┐ │ MCP Client │ (Claude Desktop等) │ (stdio通信) │ └──────────┬──────────┘ │ ↓ ┌─────────────────────┐ │ EvernoteMCPServer │ server.py │ - MCPハンドラー │ │ - ツール定義 │ └──────────┬──────────┘ │ ↓ ┌─────────────────────┐ │ EvernoteClient │ evernote_client.py │ - API呼び出し │ │ - レスポンス変換 │ └──────────┬──────────┘ │ ↓ ┌─────────────────────┐ │ Evernote API │ └─────────────────────┘ ``` ## レイヤー構造 ### 1. エントリーポイント層 (`server.py::main()`) - 環境変数の読み込み（dotenvを使用） - サーバーインスタンスの初期化 - 非同期イベントループの起動 - エラーハンドリング ### 2. MCPサーバー層 (`EvernoteMCPServer`) - MCPプロトコルの実装（mcp SDKを使用） - ツールの登録とリクエストハンドリング - `@server.list_tools()`: 利用可能なツール一覧を返す - `@server.call_tool()`: ツールの実行リクエストを処理 - stdio経由の通信管理 ### 3. Evernote統合層 (`EvernoteClient`) - Evernote APIクライアント（evernote3パッケージ）のラッパー - APIレスポンスの正規化 - エラーハンドリングと再試行ロジック - サンドボックス/本番環境の切り替え ### 4. 型定義層 (`types.py`) - TypedDictを使用した型安全性の確保 - 共通データ構造の定義 - Evernote APIのレスポンス型 ## データフロー 1. MCPクライアントがstdio経由でツール呼び出しリクエストを送信 2. `EvernoteMCPServer`の`call_tool`ハンドラーがリクエストを受信 3. 対応する`_handle_*`メソッドにディスパッチ 4. `EvernoteClient`を使用してEvernote APIを非同期呼び出し 5. レスポンスをMCP形式（TextContent）に変換してクライアントに返却 ## 非同期処理 - 全てのAPI呼び出しは`async/await`を使用 - `asyncio.run()`でイベントループを起動 - `stdio_server()`でstdio通信を非同期で処理 ## 拡張ポイント 新しいEvernote機能を追加する場合： 1. **`list_tools()`にツール定義を追加** - ツール名、説明、入力スキーマを定義 2. **`call_tool()`に分岐を追加** - 新しいツール名に対応するハンドラーを呼び出し 3. **`_handle_*`メソッドを実装** - ツールの実装ロジック 4. **`EvernoteClient`にメソッド追加** - 実際のEvernote API呼び出し 5. **必要に応じて`types.py`に型定義追加** - 新しいデータ構造の定義 ## テスト戦略 - `pytest`と`pytest-asyncio`を使用した非同期テスト - モックを使用してEvernote APIへの実際の呼び出しを回避 - 単体テスト、統合テスト、E2Eテストの3層構造