Verge MCP Server

# セッションノート - 2025年11月16日 (セッション1) ## プロジェクト概要 **プロジェクト名**: Plume MCP Server **リポジトリ**: `/Users/fukudatomohiro/DevCode/plume-mcp-server` **前セッション成果**: 全93テスト100%パス達成 (2025-11-15 セッション6) --- ## 🎯 本セッションの目標 優先度の高いタスク実装: 1. Plume API仕様調査 2. PlumeApiClientに設定注入(DI)機構を実装 3. HTTPラッパーにリトライ機構を実装 --- ## ✅ 完了した作業 ### 1. Plume API仕様調査 ✅ **実施内容**: - Plume公式ドキュメント調査 - GitHub リポジトリ調査 - API認証方式の確認 **調査結果**: #### 確認できた情報 **認証方式**: OAuth2 **認証フロー**: 1. アプリ登録: `POST /api/v1/apps` 2. トークン取得: `GET /api/v1/oauth2` 3. API呼び出し: `Authorization: Bearer <token>` **エンドポイント: /api/v1/apps** ```json // リクエスト (推測) { "name": "アプリ名", "website": "https://example.com" (optional), "redirect_uri": "https://example.com/callback" (optional) } ``` **エンドポイント: /api/v1/oauth2** ``` GET /api/v1/oauth2?client_id=xxx&client_secret=yyy&scopes=read+write&username=user&password=pass レスポンス: { "token": "<YOUR TOKEN HERE>" } ``` **スコープ**: - `read`: 全体読み取り - `write`: 全体書き込み - `read:SCOPE`: 特定領域の読み取り - `write:SCOPE`: 特定領域の書き込み #### 不明な点 - 記事関連エンドポイントの詳細 (推測ベース) - レスポンス形式の詳細 - エラーレスポンスの形式 - ページネーション仕様 **ドキュメント化**: `docs/PLUME_API_RESEARCH.md` に詳細を記録 **参考資料**: - [Plume API Documentation](https://docs.joinplu.me/api/) - [GitHub Issue #275](https://github.com/Plume-org/Plume/issues/275) ### 2. CODEX MCPへの開発方針相談 ✅ **相談内容**: - 本物のPlume APIとの接続方法 - エラーハンドリング強化の方針 - TDD vs 先行調査の切り分け **アドバイス要約**: 1. **実装準備** - 実API調査優先 - モックと実APIを切り替え可能な設計 (DI) - 契約テストを別階層に配置 2. **TDD vs 先行調査** - 仕様不明な部分は調査を先行 - HTTP ラッパー層の改善はTDDで進める 3. **エラーハンドリング方針** - リトライ: 指数バックオフ + ジッター - タイムアウト: AbortController使用 - 詳細エラー: Zod失敗時に構造化された情報を返す 4. **次アクション** - PlumeApiClientの設定注入 (DI) - HTTPラッパーにリトライ/タイムアウト - 実APIスモークテスト追加 ### 3. PlumeApiClientに設定注入(DI)機構を実装 ✅ **実装内容**: #### 新しいインターフェース ```typescript export interface RetryConfig { maxRetries?: number; // デフォルト: 3 retryDelay?: number; // デフォルト: 200ms retryOn?: number[]; // デフォルト: [500, 502, 503, 504, 429] } export interface PlumeApiClientConfig { baseUrl: string; fetchFn?: typeof fetch; // カスタムfetch関数 timeout?: number; // タイムアウト (ms) retry?: RetryConfig; // リトライ設定 mode?: 'mock' | 'production'; // 動作モード } ``` #### コンストラクタの改善 ```typescript // 下位互換性: stringも受け入れ constructor(configOrBaseUrl: string | PlumeApiClientConfig) // 新しい使い方 const client = new PlumeApiClient({ baseUrl: 'https://api.example.com', fetchFn: customFetch, timeout: 5000, retry: { maxRetries: 5, retryDelay: 1000, }, mode: 'production', }); // 既存の使い方 (引き続き動作) const client = new PlumeApiClient('https://api.example.com'); ``` #### テスト 新規テストファイル: `tests/client/api-config.test.ts` (16テスト) - ✅ デフォルトbaseUrlでの初期化 - ✅ カスタム設定オブジェクトでの初期化 - ✅ 末尾スラッシュの自動削除 - ✅ カスタムfetch関数の注入 - ✅ タイムアウト設定 - ✅ リトライ設定 - ✅ 環境別設定 (mock/production) - ✅ 下位互換性 **テスト結果**: 全109テスト100%パス (既存93 + 新規16) ### 4. HTTPラッパーにリトライ機構を実装 ✅ **実装内容**: #### リトライロジック ```typescript private async request<T>( endpoint: string, options: RequestInit, schema?: { parse: (data: unknown) => T } ): Promise<T> { let lastError: Error | null = null; let lastResponse: Response | undefined; for (let attempt = 0; attempt <= this.config.retry.maxRetries; attempt++) { try { const response = await this.config.fetchFn(...); if (!response.ok) { // リトライ可能なエラーかチェック if (attempt < maxRetries && shouldRetry(error, response)) { await sleep(retryDelay); continue; } throw error; } return data; } catch (error) { // ネットワークエラーもリトライ if (shouldRetry(error, lastResponse)) { await sleep(retryDelay); continue; } throw error; } } } ``` #### リトライ判定ロジック ```typescript private shouldRetry(error: unknown, response?: Response): boolean { // ネットワークエラーの場合はリトライ if (error instanceof Error && !response) { return true; } // レスポンスがある場合、ステータスコードでリトライ判定 if (response && !response.ok) { return this.config.retry.retryOn.includes(response.status); } return false; } ``` #### デフォルト設定 - **maxRetries**: 3 - **retryDelay**: 200ms - **retryOn**: [500, 502, 503, 504, 429] #### テスト 新規テストファイル: `tests/client/api-retry.test.ts` (11テスト) **テストケース**: - ✅ 500エラー時に3回までリトライ - ✅ 429 Too Many Requests時にリトライ - ✅ 最大リトライ回数を超えたらエラー - ✅ 400エラーはリトライしない - ✅ 401エラーはリトライしない - ✅ 404エラーはリトライしない - ✅ maxRetries=0でリトライ無効化 - ✅ カスタムretryDelay設定 - ✅ カスタムretryOn配列設定 - ✅ retryOnに含まれないステータスはリトライしない - ✅ ネットワークエラー時にリトライ **既存テストの修正**: - `tests/client/api.test.ts`: ネットワークエラーテストをリトライ対応に修正 **テスト結果**: 全120テスト100%パス (既存109 + 新規11) --- ## 📊 最終テスト結果サマリー ### 🎊 **全120テスト100%パス達成!** 🎊 ``` Test Files 9 passed (9) Tests 120 passed (120) ``` | カテゴリ | テスト数 | 成功率 | |---------|---------|--------| | **ユニットテスト** | 91 | **100%** ✅ | | - types.test.ts | 43 | 100% | | - api.test.ts | 21 | 100% | | - api-config.test.ts | 16 | 100% ✨ NEW | | - api-retry.test.ts | 11 | 100% ✨ NEW | | **ツールテスト** | 12 | **100%** ✅ | | - auth.test.ts | 4 | 100% | | - articles.test.ts | 8 | 100% | | **統合テスト** | 17 | **100%** ✅ | | - server.e2e.test.ts | 6 | 100% | | - articles.scenario.test.ts | 3 | 100% | | - error-handling.test.ts | 8 | 100% | | **全体** | **120** | **100%** ✅ | **前セッションとの比較**: - 前セッション: 93/93パス (100%) - 今セッション: 120/120パス (100%) - **追加**: +27テスト (新機能実装) --- ## 🔄 変更ファイル | ファイル | 変更内容 | 行数 | |---------|---------|------| | `docs/PLUME_API_RESEARCH.md` | Plume API調査結果ドキュメント | 新規作成 (300行) | | `src/client/api.ts` | 設定注入機構とリトライ機構実装 | 大幅修正 | | `tests/client/api-config.test.ts` | 設定注入テスト | 新規作成 (16テスト) | | `tests/client/api-retry.test.ts` | リトライ機構テスト | 新規作成 (11テスト) | | `tests/client/api.test.ts` | ネットワークエラーテスト修正 | 小修正 | --- ## 💡 技術的な学び ### 1. 依存性注入(DI)の実装パターン **課題**: 実APIとモックAPIを切り替え可能にしたい **解決策**: 設定オブジェクトを注入する設計 ```typescript // Before: 固定されたfetch const response = await fetch(url, options); // After: 注入されたfetchFn const response = await this.config.fetchFn(url, options); ``` **メリット**: - テストでモック関数を注入可能 - 環境ごとに異なるfetch実装を使用可能 - タイムアウトやリトライなどの横断的関心事を外部から制御 ### 2. リトライ機構の実装戦略 **CODEX MCPのアドバイス**: - idempotent操作のみ自動リトライ - 指数バックオフ + ジッター - HTTPステータスごとに判定を切り替え **今回の実装**: - 固定間隔リトライ (将来的に指数バックオフに拡張可能) - ステータスコードベースの判定 - ネットワークエラーも自動リトライ **リトライ対象の判定基準**: ```typescript // サーバーエラー: リトライ 500, 502, 503, 504 // レート制限: リトライ 429 // クライアントエラー: リトライしない 400, 401, 403, 404 // ネットワークエラー: リトライ fetch失敗 (response未取得) ``` ### 3. 下位互換性の維持 **課題**: 既存コードを壊さずに新機能を追加 **解決策**: Union型とオーバーロードパターン ```typescript // 既存の使い方も引き続き動作 constructor(configOrBaseUrl: string | PlumeApiClientConfig) { const config: PlumeApiClientConfig = typeof configOrBaseUrl === 'string' ? { baseUrl: configOrBaseUrl } : configOrBaseUrl; // ... } ``` **効果**: - 既存の全93テストがそのまま動作 - 新しいテストのみ新機能を検証 ### 4. fake timersを使ったリトライテスト **課題**: リトライ間隔(200ms × 3回)を実際に待つとテストが遅い **解決策**: Vitestのfake timers ```typescript beforeEach(() => { vi.useFakeTimers(); }); // テスト内 const loginPromise = client.login(...); await vi.advanceTimersByTimeAsync(200 * 3); const result = await loginPromise; ``` **効果**: - テスト実行時間が大幅短縮 - タイミングを正確に制御可能 --- ## コミット履歴 ```bash e892299 - feat: PlumeApiClientに設定注入(DI)機構を実装 20720f7 - feat: HTTPラッパーにリトライ機構を実装 ``` ### コミット1: 設定注入(DI)機構 **主な変更**: - `PlumeApiClientConfig`インターフェース追加 - カスタムfetch関数の注入機能 - タイムアウト、リトライ、モード設定のサポート - 下位互換性維持 **テスト**: 全109テスト100%パス ### コミット2: リトライ機構 **主な変更**: - `request`メソッドにリトライロジック追加 - `shouldRetry`: リトライ判定 - `sleep`: リトライ間隔待機 - デフォルトリトライ設定 **テスト**: 全120テスト100%パス --- ## 参考資料 - **CODEX MCP**: 開発方針アドバイス - **Plume公式ドキュメント**: https://docs.joinplu.me/ - **Plume API Documentation**: https://docs.joinplu.me/api/ - **GitHub: Plume-org/Plume**: https://github.com/Plume-org/Plume - **前セッションノート**: `SESSION_NOTES/SESSION_NOTES_20251115_6.md` --- ## セッション統計 - **作業時間**: 約2時間 - **主な成果**: - Plume API仕様調査完了 ✅ - 設定注入(DI)機構実装完了 ✅ - リトライ機構実装完了 ✅ - **変更ファイル数**: 5 - **追加テスト数**: 27 (16 + 11) - **テストパス率**: **100%** (120/120) - **テスト増加**: +27テスト (93 → 120) --- ## 次のセッションへの引き継ぎ事項 ### ✅ 現在の状態 **全120テスト100%パス達成** - 設定注入とリトライ機構が完成! **実装済み機能**: - ✅ 設定注入(DI)機構 - ✅ リトライ機構 (デフォルト3回, カスタマイズ可能) - ✅ カスタムfetch関数注入 - ✅ 動作モード設定 ### 今後の実装候補 #### 優先度: 高 🔴 1. **タイムアウト処理の実装** - AbortControllerを使用 - デフォルト5-10秒 - カスタマイズ可能 - fake timersでテスト 2. **詳細なエラー情報の実装** - Zodバリデーションエラーの構造化 - HTTPステータス、ボディ、リクエスト情報を含む - API固有のerror_codeサポート #### 優先度: 中 🟡 3. **実APIスモークテストの追加** - `tests/e2e/plume-api.spec.ts` - 環境変数で実行制御 - 最小限のhappy pathから - VCR録画/再生の検討 4. **指数バックオフの実装** - 現在: 固定間隔 (200ms) - 改善: `delay = base * 2^attempt + random(0,50ms)` - ジッター追加でサーバー負荷分散 #### 優先度: 低 🟢 5. **その他の機能拡張** - カテゴリ、タグ、メディア管理 - ページネーション改善 - キャッシュ機構 --- ## 備考 ### 成果 - **27テスト追加で全120テスト100%パス** 🎉 - CODEX MCPのアドバイスに従い、TDD方式で実装 - 下位互換性を維持しながら新機能を追加 - API仕様が不明な点は文書化し、将来の対応に備えた ### 次のステップ **推奨順序**: 1. タイムアウト処理 (AbortController + fake timers) 2. 詳細なエラー情報 (構造化されたエラーオブジェクト) 3. 実APIスモークテスト (環境変数制御) 4. 指数バックオフ (より堅牢なリトライ) **長期的な目標**: - 実際のPlume APIとの接続検証 - 本番環境での動作確認 - パフォーマンス最適化 --- 🎉 **今セッションでの大きな前進!** Plume MCP Serverのエラーハンドリングが大幅に強化されました!