# MCPサーバー esa.io APIクライアント仕様
このドキュメントは、esa.io API クライアント（EsaClientクラス）の実装仕様とテスト方針を記述します。
## 1. 目的
esa.io API との通信を行うための基本的なクライアント機能を提供します。認証情報の管理、リクエストの送信、基本的なエンドポイントへのアクセス機能を含みます。
## 2. クライアント仕様
- .envからESA_TOKEN/ESA_TEAM_NAMEを取得
- requests.Sessionによる認証付き通信
- get_user, get_posts, get_postメソッドを提供
- エラー時は例外送出・ログ出力
### 2.1. EsaClient クラス
- 初期化時にdotenv.load_dotenv()で環境変数を取得し、認証情報を検証
- APIベースURL（https://api.esa.io/v1/teams/{team_name}）を構築
- 共通ヘッダー（Authorization, Content-Type）を設定
- _requestヘルパーでAPIリクエストを共通化
- get_user: 認証ユーザー情報取得
- get_posts: 記事一覧取得（q, page, per_page対応）
- get_post: 記事詳細取得（post_number指定）
## 3. テスト方針・構成
- pytestによるユニットテスト・インテグレーションテスト
- モックによる外部依存排除
- テストディレクトリ・マーカーの使い分け
### 3.1. テスト構成
- **ユニットテスト:**
- APIクライアントやMCPツールのロジックをモックで高速に検証します。
- テストファイル例: `tests/test_esa_client.py`, `tests/test_main_tools.py`
- **インテグレーションテスト:**
- 実際のesa.io APIと通信し、全体の連携を検証します（.envとネットワークが必要）。
- テストファイル例: `tests/integration/test_esa_client_integration.py`
- テストディレクトリは `tests/` 配下にあり、`integration/` サブディレクトリでインテグレーションテストを分離しています。
- pytestのマーカー（`@pytest.mark.integration`）でインテグレーションテストを区別しています。
### 3.2. ユニットテスト詳細
- 主なテストファイル:
- `tests/test_esa_client.py`: EsaClientクラスの初期化・APIメソッドの正常系/異常系
- `tests/test_main_tools.py`: MCPツールの引数処理・EsaClient呼び出し・エラーハンドリング
- モック・フィクスチャ:
- `monkeypatch` で環境変数をセット
- `unittest.mock.patch` で requests や EsaClient のメソッドをモック
- 主なテストケース例:
- 認証情報がない場合の初期化エラー
- get_user の正常/エラー応答
- get_posts のパラメータ有無・エラー応答
- MCPツールが正しいEsaClientメソッドを呼ぶか
### 3.3. インテグレーションテスト詳細
- 主なテストファイル:
- `tests/integration/test_esa_client_integration.py`
- 内容:
- 実際のesa.io APIと通信し、ユーザー情報・記事一覧・記事詳細の取得を検証
- 存在しない記事番号で404エラーを検証
- 注意点:
- `.env`ファイルに有効なESA_TOKEN/ESA_TEAM_NAMEが必要
- ネットワーク接続が必要
- 実行に時間がかかる場合あり
## 4. テスト実行方法
- **ユニットテストのみ実行:**
```bash
uv run pytest tests/ -m "not integration"
```
- **インテグレーションテストのみ実行:**
```bash
uv run pytest -m integration tests/integration/
```
- **全テスト実行:**
```bash
uv run pytest
```
- **テストカバレッジを表示**
```bash
uv run pytest --cov=. tests
```
---
※サーバー全体の設計・開発まとめは docs/20250504/mcp_esa_development_summary.md を参照。
※利用方法・MCPツールの説明は docs/mcp_esa_server_usage.md を参照。
