Verge MCP Server

# セッションノート - 2025年11月16日 (セッション3) ## 📅 セッション情報 - **日付**: 2025年11月16日 - **セッション番号**: 3 - **開始時刻**: 前回セッションからの継続 - **終了時刻**: 現在 - **総テスト数**: 143テスト (全て成功) ## 🎯 本日の実施内容 ### 1. カスタムエラークラスの実装 ✅ **実装内容**: - `src/client/errors.ts` 作成 - `PlumeApiError` クラスの実装 - エラータイプ分類 (NETWORK, TIMEOUT, API, VALIDATION, UNKNOWN) - リトライ可能性判定メソッド (`isRetryable()`) - JSON/文字列変換メソッド **テスト**: - `tests/client/errors.test.ts` 作成 (11テスト追加) - 基本的なエラー生成テスト - 全エラータイプのテスト - `toJSON()`, `toString()`, `isRetryable()` のテスト **コミット**: `67649f5` **主要コード**: ```typescript export enum PlumeErrorType { NETWORK = 'NETWORK', TIMEOUT = 'TIMEOUT', API = 'API', VALIDATION = 'VALIDATION', UNKNOWN = 'UNKNOWN', } export class PlumeApiError extends Error { readonly type: PlumeErrorType; readonly statusCode?: number; readonly responseBody?: unknown; readonly retryCount: number; readonly endpoint?: string; readonly cause?: Error; isRetryable(): boolean { // ネットワークエラー・タイムアウトは常にリトライ可能 // APIエラーは特定のステータスコード (500, 502, 503, 504, 429) のみ } } ``` ### 2. 指数バックオフ実装 ✅ **実装内容**: - `RetryConfig` に3つのフィールド追加: - `backoffMultiplier` (デフォルト: 2) - `maxRetryDelay` (デフォルト: 10000ms) - `jitter` (デフォルト: true) - `calculateRetryDelay()` メソッド実装 - 指数バックオフ計算式: `retryDelay * (backoffMultiplier ^ attempt)` - ジッター実装: `delay * (0.5 + Math.random() * 0.5)` で50-100%の範囲 **テスト**: - `tests/client/api-backoff.test.ts` 作成 (7テスト追加) - デフォルト動作テスト (200ms → 400ms → 800ms) - カスタム倍率テスト (backoffMultiplier=3) - 最大遅延上限テスト - ジッターランダム化テスト **既存テスト修正**: - `tests/client/api-retry.test.ts`: 全11テストに `jitter: false` を追加 - タイミング期待値を指数バックオフに合わせて調整 - `tests/client/api-config.test.ts`: デフォルト設定の期待値を更新 **コミット**: `5470a68` **主要コード**: ```typescript private calculateRetryDelay(attempt: number): number { const { retryDelay, backoffMultiplier, maxRetryDelay, jitter } = this.config.retry; // 指数バックオフ: baseDelay * (multiplier ^ attempt) const exponentialDelay = retryDelay * Math.pow(backoffMultiplier, attempt); // 最大遅延で上限設定 const cappedDelay = Math.min(exponentialDelay, maxRetryDelay); // ジッター適用 if (jitter) { return Math.floor(cappedDelay * (0.5 + Math.random() * 0.5)); } return cappedDelay; } ``` ### 3. ブラウザ認証フロー実装 ✅ **背景**: - ユーザーがMCPサーバーを外部公開したい意向 - GitHub CLI/Vercel CLIのような快適な認証体験を希望 - パスワードを環境変数に書かずにブラウザでログインできる仕組み **実装内容**: #### 3.1 トークンストレージ (`src/auth/token-storage.ts`) - ローカルファイルシステムへの安全なトークン保存 - 保存場所: `~/.plume-mcp/token.json` - ディレクトリ権限: 0o700 (所有者のみ) - ファイル権限: 0o600 (所有者のみ読み書き) - 有効期限チェック機能 #### 3.2 ブラウザ認証 (`src/auth/browser-auth.ts`) - ローカルHTTPサーバー (ポート: 34521) - 美しいHTMLログインフォーム (グラデーション背景) - 自動ブラウザ起動 (`open` パッケージ使用) - 成功ページ (5秒後に自動クローズ) - 3分タイムアウト #### 3.3 統合認証マネージャー (`src/auth/index.ts`) - 3段階の認証優先順位: 1. 保存されたトークンを使用 2. 環境変数 (`PLUME_EMAIL`, `PLUME_PASSWORD`) からログイン 3. ブラウザ認証フロー - トークン検証機能 - ログアウト機能 #### 3.4 サーバー起動統合 (`src/index.ts`) - `AuthManager` を使用した認証処理 - 起動時に自動認証実行 - 認証成功後にトークンをAPIクライアントに設定 **依存関係追加**: - `open` パッケージ (ブラウザ自動起動用) **コミット**: `a10faf5` **コミットメッセージ**: ``` feat: ブラウザ認証フロー実装 GitHub CLI/Vercel CLIのような快適な認証体験を実現。 パスワードを環境変数に書かずにブラウザでログインできます。 - トークンを ~/.plume-mcp/token.json に安全に保存 - ローカルサーバー起動でブラウザログイン - 3段階認証 (保存トークン → 環境変数 → ブラウザ) ``` ## 🐛 発生したエラーと解決方法 ### エラー1: TypeScript型エラー - Required<>の問題 **エラー内容**: ``` Type 'number | undefined' is not assignable to type 'number' ``` **原因**: - `Required<PlumeApiClientConfig>` を使用したため、`timeout` が必須プロパティになった - しかし実際の値は `number | undefined` のまま **解決方法**: ```typescript // Before: private config: Required<PlumeApiClientConfig>; // After: private config: { baseUrl: string; fetchFn: typeof fetch; timeout?: number; // オプショナルのまま維持 retry: Required<RetryConfig>; mode: 'mock' | 'production'; }; ``` ### エラー2: テストタイミングエラー **エラー内容**: リトライテストが失敗 (タイムアウト期待値の不一致) **原因**: 指数バックオフ実装により、遅延が (200, 200, 200) から (200, 400, 800) に変更 **解決方法**: ```typescript // テストのタイミング期待値を更新 await vi.advanceTimersByTimeAsync(200); // 2^0 * 200 await vi.advanceTimersByTimeAsync(400); // 2^1 * 200 await vi.advanceTimersByTimeAsync(800); // 2^2 * 200 ``` ### エラー3: Edit Tool - 複数一致エラー **エラー内容**: "Found 2 matches of the string to replace, but replace_all is false" **原因**: リトライ遅延ロジックがコード内2箇所に存在 **解決方法**: `replace_all: true` パラメータを使用 ## 📊 テスト統計 ### テスト追加内訳: - カスタムエラークラス: +11テスト - 指数バックオフ: +7テスト - **合計**: 143テスト (全て成功) ### テストファイル: - ✅ `tests/client/errors.test.ts` (11テスト) - ✅ `tests/client/api-backoff.test.ts` (7テスト) - ✅ `tests/client/api-retry.test.ts` (11テスト - 修正済み) - ✅ `tests/client/api-config.test.ts` (修正済み) ## 📁 作成・修正したファイル ### 新規作成: 1. `src/client/errors.ts` - カスタムエラークラス 2. `tests/client/errors.test.ts` - エラークラステスト 3. `tests/client/api-backoff.test.ts` - 指数バックオフテスト 4. `src/auth/token-storage.ts` - トークンストレージ 5. `src/auth/browser-auth.ts` - ブラウザ認証フロー 6. `src/auth/index.ts` - 統合認証マネージャー ### 修正: 1. `src/client/api.ts` - エラークラス統合、指数バックオフ実装 2. `src/index.ts` - 認証処理統合 3. `tests/client/api-retry.test.ts` - ジッター無効化、タイミング調整 4. `tests/client/api-config.test.ts` - デフォルト設定期待値更新 5. `package.json` - `open` 依存関係追加 ## 🚀 今後のタスクリスト ### 優先度: 高 1. **README.md 作成** - インストール手順 - セットアップガイド - 認証方法の説明 (3段階認証) - 使用例 2. **認証モジュールのテスト作成** - `tests/auth/token-storage.test.ts` - `tests/auth/browser-auth.test.ts` - `tests/auth/index.test.ts` ### 優先度: 中 3. **ブログ管理ツールの実装** - ブログ一覧取得ツール - ブログ作成ツール - ブログ更新ツール - ブログ削除ツール 4. **記事管理ツールの実装** - 記事一覧取得ツール - 記事作成ツール - 記事更新ツール - 記事削除ツール - 下書き/公開状態の切り替え 5. **ユーザー管理ツールの実装** - ユーザー情報取得ツール - プロフィール更新ツール ### 優先度: 低 6. **MCPリソース機能の実装** - ブログリストをリソースとして公開 - 記事リストをリソースとして公開 7. **ログアウトコマンドの実装** - トークン削除機能 - ユーザーフレンドリーなCLIコマンド 8. **エラーハンドリングの強化** - より詳細なエラーメッセージ - リトライ時のユーザー通知 9. **パフォーマンス最適化** - API応答のキャッシング - 並列リクエストの最適化 10. **ドキュメント拡充** - API仕様書 - 開発者ガイド - トラブルシューティングガイド ## 💡 技術的なハイライト ### 指数バックオフの計算式 ``` delay = baseDelay * (multiplier ^ attempt) delay = min(delay, maxDelay) if (jitter) { delay = delay * (0.5 + random() * 0.5) // 50-100%の範囲 } ``` ### 認証の優先順位 ``` 1. ~/.plume-mcp/token.json (保存されたトークン) ↓ なし 2. PLUME_EMAIL + PLUME_PASSWORD (環境変数) ↓ なし 3. Browser Authentication (http://localhost:34521) ``` ### トークンのセキュリティ - ディレクトリ: `~/.plume-mcp/` (0o700) - ファイル: `token.json` (0o600) - 所有者のみ読み書き可能 ## 🔧 バックグラウンドプロセス 以下のバックグラウンドプロセスが実行中です: - 複数のVitestプロセス (テスト実行) - Nodeプロセス **注意**: 一部のプロセスは "Operation not permitted" エラーのため終了できませんでした。手動での終了が必要な場合があります。 ## 📈 プロジェクト状態 - **ビルド状態**: ✅ 成功 - **テスト状態**: ✅ 143/143 成功 - **型チェック**: ✅ エラーなし - **認証機能**: ✅ 完全実装 - **エラーハンドリング**: ✅ 詳細なエラー情報 - **リトライメカニズム**: ✅ 指数バックオフ実装 ## 🎉 達成した主要機能 1. ✅ **カスタムエラークラス** - 詳細なエラー情報と分類 2. ✅ **指数バックオフ** - スマートなリトライ戦略 3. ✅ **ブラウザ認証** - GitHub CLI風の快適な認証体験 4. ✅ **トークン永続化** - セキュアなローカルストレージ 5. ✅ **3段階認証** - 柔軟な認証オプション ## 📝 次回セッションへの引き継ぎ事項 1. **未完了タスク**: なし (本セッションの全タスク完了) 2. **次のステップ**: README.md作成と認証モジュールのテスト作成 3. **技術的負債**: なし 4. **既知の問題**: バックグラウンドプロセスの一部が手動終了必要 --- **セッション完了時刻**: 2025年11月16日 **次回セッション推奨タスク**: README.md作成