mcp-server

MCP 原因分析・仕様検証

問題の再現、最新仕様と実装の照合、不一致の根拠整理、修正前後の Inspector 検証

---

入力要件（不足している場合は確認）

まず、以下の3点だけを確認します。

1. 作業目的：원인 분석 または 스펙 검증
2. 対象コード／サーバーの場所：repo path、package 名、実行エントリー
3. ランタイム／transport：Node(TypeScript) または Python、stdio または SSE/HTTP

必要な場合に限り、以下の項目を追加で確認します。

• 再現手順：エラーログ、失敗したリクエスト／レスポンス、期待される動作
• 点検対象の Tool/Resource/Prompt 名
• デプロイ環境／認証情報（リモート呼び出しの問題の場合のみ）

---

判断ルール

1. 実装より分析と検証を優先します
2. サーバーの新規作成／スキャフォールディングは対象外です
3. 修正が必要な場合は、既存コードを基準に最小限の変更で進めます
4. 確定した事実と推定した仮説を分けて記録します

---

安全ルール

STDIO ロギング

• stdio transport では stdout へのログ出力を禁止します
• Node では console.log() の代わりに console.error() を使用します
• Python では print() の代わりに logging を使用します

入力／呼び出しの検証

• 必須入力が不足していないか、最初に検証します
• Tool handler の実行前に schema 検証を行います
• ファイルパス入力では path traversal（../）をブロックします
• 外部 API の呼び出しには timeout を強制します

---

実行手順

Step 1. 問題の再現

• 最小限の再現シナリオを定義します
• 失敗箇所を transport、tools、resources、prompts に分類します
• 再現結果を 確定事実 と 推定 に分けて記録します

Step 2. 最新仕様との照合

1. まず MCP Specification を確認します
2. MCP SDKs のドキュメントと、使用中の SDK バージョンを照合します
3. 実装コードと仕様を項目ごとに1対1で対応付けます
   • transport の初期化／接続方式
   • tools/list、tools/call のリクエスト／レスポンス構造
   • resources/list、resources/read の公開／取得構造
   • prompt の登録名、argument schema、handler のルーティング
   • レスポンス形式 content、isError
4. 不一致が見つかった場合は、影響範囲と修正箇所を併せて整理します

Step 3. 修正案の整理

• 原因ごとの修正順序を優先度順に整理します
• 各修正案の影響範囲と回帰リスクを明記します
• テスト可能な検証ケースも併せて提示します

Step 4. Inspector 検証

• 修正前後で同一のシナリオを使って結果を比較します
• 合格／不合格の基準をチェックリストに記録します

---

Resources / Prompts の検証項目

• resources/list が期待したリソースを公開しているか確認します
• resources/read が実際の payload を返すか確認します
• prompt の登録名が競合していないか確認します
• prompt の argument schema が呼び出し payload と一致しているか確認します
• handler またはルーティングが欠落していないか確認します

---

Inspector テストチェックリスト

• サーバーの起動および Inspector との接続維持の基準を満たしているか
• tools/list の結果が期待する tool の公開基準を満たしているか
• 代表的な tool 1つ以上で tools/call が成功する基準を満たしているか
• レスポンスが content / isError の構造基準を満たしているか
• stdout が汚染されず、プロトコルが維持される基準を満たしているか
• 修正前後の結果の差を検証する基準を満たしているか

---

Error の返却基準

以下の条件のいずれかに該当する場合は、isError: true を返します。

• サーバーの実行または接続自体に失敗した場合
• 必須入力の不足により検証を進められない場合
• 仕様との不一致が確認された場合
• 再現に失敗し、原因を特定できない場合
• 環境上の制約により Inspector テストを実施できない場合

Error レスポンスには、最低限以下の項目を含めます。

1. 失敗した段階
2. 観測された症状
3. 必要な追加入力または次の対応

---

出力仕様（Output Contract）

常に以下の順序で結果を整理します。

1. 問題の概要と再現条件
2. 確定した事実／推定した仮説
3. 仕様との照合結果（一致／不一致）
4. 修正箇所と影響範囲
5. Inspector による修正前後の検証結果
6. 残るリスクと今後の確認項目

---

Tool の返却形式

Success

{
  "content": [{ "type": "text", "text": "..." }]
}

Error

{
  "isError": true,
  "content": [{ "type": "text", "text": "..." }]
}