Files

T

wehub-resource-sync c275ba2868 chore: import upstream snapshot with attribution

2026-07-13 13:31:35 +08:00

14 KiB

Raw Permalink Blame History

MCP Inspectorでのデバッグ

MCP Inspectorは、完全なAIホストアプリケーションを必要とせずに、インタラクティブにMCPサーバーのテストやトラブルシューティングを行うための重要なデバッグツールです。これを「MCPのためのPostman」と考えてください。リクエストの送信、レスポンスの表示、サーバーの挙動の理解に役立つ視覚的インターフェースを提供します。

MCP Inspectorを使う理由

MCPサーバーを構築する際に、よく直面する課題は次の通りです：

「サーバーは動いているの？」 - Inspectorは接続状態を表示します
「ツールは正しく登録されている？」 - Inspectorは利用可能なすべてのツールを一覧表示します
「レスポンスの形式は？」 - Inspectorは完全なJSONレスポンスを表示します
「なぜこのツールは動作しないの？」 - Inspectorは詳細なエラーメッセージを表示します

前提条件

Node.js 18以上がインストールされていること
npm（Node.jsに付属）
テストするMCPサーバー（モジュール3.1 - 最初のサーバーを参照）

インストール

オプション1: npxで実行（クイックテストに推奨）

npx @modelcontextprotocol/inspector

オプション2: グローバルインストール

npm install -g @modelcontextprotocol/inspector
mcp-inspector

オプション3: プロジェクトに追加

cd your-mcp-server-project
npm install --save-dev @modelcontextprotocol/inspector

package.jsonに追加：

{
  "scripts": {
    "inspector": "mcp-inspector"
  }
}

サーバーへの接続

stdioサーバー（ローカルプロセス）

標準入力/出力で通信するサーバーの場合：

# Python サーバー
npx @modelcontextprotocol/inspector python -m your_server_module

# Node.js サーバー
npx @modelcontextprotocol/inspector node ./build/index.js

# 環境変数を使用して
OPENAI_API_KEY=xxx npx @modelcontextprotocol/inspector python server.py

SSE/HTTPサーバー（ネットワーク）

HTTPサービスとして実行しているサーバーの場合：

まずサーバーを起動：

python server.py  # http://localhost:8080 でサーバーが実行中

Inspectorを起動して接続：

npx @modelcontextprotocol/inspector --sse http://localhost:8080/sse

Inspectorインターフェースの概要

Inspectorが起動すると、Webインターフェースが表示されます（通常は http://localhost:5173）：

┌─────────────────────────────────────────────────────────────┐
│  MCP Inspector                              [Connected ✅]   │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │   🔧 Tools  │  │ 📄 Resources│  │ 💬 Prompts  │         │
│  │    (3)      │  │    (2)      │  │    (1)      │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐ │
│  │  📋 Message Log                                       │ │
│  │  ─────────────────────────────────────────────────── │ │
│  │  → initialize                                         │ │
│  │  ← initialized (server info)                          │ │
│  │  → tools/list                                         │ │
│  │  ← tools (3 tools)                                    │ │
│  └───────────────────────────────────────────────────────┘ │
│                                                             │
└─────────────────────────────────────────────────────────────┘

ツールのテスト

利用可能なツールの一覧表示

Toolsタブをクリック
Inspectorが自動的にtools/listを呼び出し
登録されているすべてのツールが次の情報とともに表示されます：
- ツール名
- 説明
- 入力スキーマ（パラメータ）

ツールの呼び出し

リストからツールを選択
必要なパラメータをフォームに入力
Run Toolをクリック
結果パネルにレスポンスが表示されます

例：計算機ツールのテスト

Tool: add
Parameters:
  a: 25
  b: 17

Response:
{
  "content": [
    {
      "type": "text",
      "text": "42"
    }
  ]
}

ツールのエラーのデバッグ

ツールが失敗した場合、Inspectorは以下を表示します：

Error Response:
{
  "error": {
    "code": -32602,
    "message": "Invalid params: 'b' is required"
  }
}

よくあるエラーコード：

コード	意味
-32700	パースエラー（無効なJSON）
-32600	無効なリクエスト
-32601	メソッドが見つかりません
-32602	無効なパラメータ
-32603	内部エラー

リソースのテスト

リソースの一覧表示

Resourcesタブをクリック
Inspectorがresources/listを呼び出し
次のものが表示されます：
- リソースURI
- 名前と説明
- MIMEタイプ

リソースの読み取り

読みたいリソースを選択
Read Resourceをクリック
返されたコンテンツを確認

例の出力：

Resource: file:///config/settings.json
Content-Type: application/json

{
  "config": {
    "debug": true,
    "maxConnections": 10
  }
}

プロンプトのテスト

プロンプトの一覧表示

Promptsタブをクリック
Inspectorがprompts/listを呼び出し
利用可能なプロンプトテンプレートが表示されます

プロンプトの取得

プロンプトを選択
必要な引数を入力
Get Promptをクリック
レンダリングされたプロンプトメッセージを確認

メッセージログの解析

メッセージログはすべてのMCPプロトコルメッセージを表示します：

14:32:01 → {"jsonrpc":"2.0","id":1,"method":"initialize",...}
14:32:01 ← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25",...}}
14:32:02 → {"jsonrpc":"2.0","id":2,"method":"tools/list"}
14:32:02 ← {"jsonrpc":"2.0","id":2,"result":{"tools":[...]}}
14:32:05 → {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"add",...}}
14:32:05 ← {"jsonrpc":"2.0","id":3,"result":{"content":[...]}}

注目すべきポイント

リクエスト/レスポンスのペア：それぞれの→には対応する←があること
エラーメッセージ：レスポンス内の"error"を探す
タイミング：大きな間隔はパフォーマンス問題の可能性
プロトコルバージョン：サーバーとクライアントでバージョンが合っていることを確認

VS Codeとの連携

VS Codeから直接Inspectorを実行できます：

launch.jsonの使用

.vscode/launch.jsonに追加：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug with MCP Inspector",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "npx",
      "runtimeArgs": [
        "@modelcontextprotocol/inspector",
        "python",
        "${workspaceFolder}/server.py"
      ],
      "console": "integratedTerminal"
    },
    {
      "name": "Debug SSE Server with Inspector",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:5173",
      "preLaunchTask": "Start MCP Inspector"
    }
  ]
}

タスクの使用

.vscode/tasks.jsonに追加：

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Start MCP Inspector",
      "type": "shell",
      "command": "npx @modelcontextprotocol/inspector node ${workspaceFolder}/build/index.js",
      "isBackground": true,
      "problemMatcher": {
        "pattern": {
          "regexp": "^$"
        },
        "background": {
          "activeOnStart": true,
          "beginsPattern": "Inspector",
          "endsPattern": "listening"
        }
      }
    }
  ]
}

よくあるデバッグシナリオ

シナリオ1: サーバーに接続できない

症状: Inspectorが「Disconnected」と表示、または「Connecting...」で止まる

チェックリスト:

✅ サーバーコマンドは正しいか？
✅ 依存関係はすべてインストールされているか？
✅ サーバーのパスは絶対パスか、現在のディレクトリに対して正しいか？
✅ 必要な環境変数は設定されているか？

デバッグ手順：

# まず手動でサーバーをテストしてください
python -c "import your_server_module; print('OK')"

# インポートエラーを確認する
python -m your_server_module 2>&1 | head -20

# MCP SDKがインストールされていることを確認する
pip show mcp

シナリオ2: ツールが表示されない

症状: Toolsタブに何も表示されない

考えられる原因:

サーバー初期化時にツールが登録されていない
起動後にサーバーがクラッシュした
tools/listハンドラーが空の配列を返している

デバッグ手順:

メッセージログでtools/listのレスポンスを確認
ツール登録コードにログを追加
Pythonの場合は@mcp.tool()デコレータが正しくついているか確認

シナリオ3: ツールがエラーを返す

症状: ツールの呼び出しがエラー応答を返す

デバッグアプローチ:

エラーメッセージを注意深く読む
パラメータの型がスキーマに合っているか確認
詳細なエラーメッセージを含むtry/catchを追加
サーバーログでスタックトレースを確認

改善されたエラーハンドリングの例：

@mcp.tool()
async def my_tool(param1: str, param2: int) -> str:
    try:
        # ここにツールのロジックを書く
        result = process(param1, param2)
        return str(result)
    except ValueError as e:
        raise McpError(f"Invalid parameter: {e}")
    except Exception as e:
        raise McpError(f"Tool failed: {type(e).__name__}: {e}")

シナリオ4: リソースの内容が空

症状: リソースが返ってくるが、内容が空またはnull