MCP Gauge
コーディングエージェントによるMCPサーバーの自律的なテスト・評価・チューニングを実現する、計測・評価MCPサーバーです。
解決する課題
MCPサーバーの開発は「実装 → 手動でエージェントに使わせてみる → 問題を発見 → 修正」という人間依存のサイクルに縛られています。エージェントにMCPサーバーの開発を任せても、品質を評価する手段がないため、テスト・チューニングの段階で必ず人間がループに入る必要があります。
MCP Gaugeは、コーディングエージェント自身がこのサイクルを自律的に回せるようにします。エージェントがMCPサーバーを実装し、MCP Gaugeでテストを実行し、結果を解釈してツール説明文やパラメータ設計を改善する。この 「実装 → テスト → チューニング」ループを完全に自動化 します。
動作の仕組み
MCP Gauge自体がMCPサーバーである
MCP Gaugeの最大の特徴は、 MCP Gauge自体がMCPサーバーとして動作する ことです。Claude Codeなどのコーディングエージェントは、MCP Gaugeを通常のMCPツールとして呼び出すだけでテスト・評価を実行できます。特別なCLIやGUIは必要ありません。
プロキシ型アーキテクチャ
MCP Gaugeは プロキシ型アーキテクチャ を採用しています。テスト対象MCPサーバーとの間に立ち、ツール呼び出しを中継・記録する仕組みです。
┌─────────────────────┐ ┌─────────────┐ ┌─────────────────────┐
│ コーディング │ MCP │ MCP Gauge │ MCP │ テスト対象 │
│ エージェント │────→│ (プロキシ) │────→│ MCPサーバー │
│ (Claude Code等) │←────│ │←────│ │
└─────────────────────┘ └──────┬───────┘ └─────────────────────┘
│
記録・計測
│
┌──────▼───────┐
│ SQLite DB │
│ (トレースデータ) │
└──────────────┘このアーキテクチャの重要なポイントは、 MCP Gauge自身はLLMを持たない ことです。ツール呼び出しの判断は、呼び出し元のコーディングエージェント自身が行います。MCP Gaugeはあくまでプロキシとしてリクエストを中継し、その過程でトレースデータを記録・計測するだけです。
これにより、LLM APIキーの管理が不要になり、Claude Codeのサブスクリプションプランを含む 任意のMCPクライアントからそのまま利用 できます。
テスト実行の流れ
MCP Gaugeを使ったテストは、以下の流れで進みます。
- 接続: エージェントが
gauge_connectでテスト対象サーバーに接続を確立します。MCP Gaugeは対象サーバーのツール一覧をエージェントに返します。
- ツール呼び出し: エージェントはツール一覧を見て、自らの判断で
gauge_proxy_callを使いツールを呼び出します。MCP Gaugeは各呼び出しを対象サーバーに中継しながら、ツール名・引数・結果・所要時間・エラー有無をすべて記録します。
- 切断: タスクが終わったら
gauge_disconnectで接続を終了します。MCP Gaugeはセッション中の全呼び出しを集計し、トレースサマリー（総呼び出し回数、冗長呼び出し数、エラー回数、リカバリステップ数など）を返します。
- 評価:
gauge_evaluateで、記録されたトレースデータに対して成功条件を照合します。「最大ステップ数以内か」「必須ツールが呼ばれたか」「禁止ツールが呼ばれていないか」「タスクが成功したか」を判定し、合否と詳細な評価結果を返します。
すべての結果はエージェントが解釈・判断可能な 構造化JSON で返されるため、エージェントは結果を読み取り、次のアクション（ツール説明文の修正、パラメータ設計の変更など）を自律的に決定できます。
提供するツール
MCP Gaugeは7つのMCPツールを提供します。
リンティング
| ツール | 説明 | |-------|------| | gauge_lint | テスト対象サーバーのツール説明文を静的解析し、曖昧な表現・パラメータ説明の不足・戻り値の記載漏れなどを検出します。LLM呼び出し不要で高速に実行されます。 |
プロキシセッション
| ツール | 説明 | |-------|------| | gauge_connect | テスト対象サーバーに接続し、トレースセッションを開始します。利用可能なツール一覧を返します。 | | gauge_proxy_call | 接続済みのセッションを通じてツールを呼び出します。呼び出しは自動的にトレースとして記録されます。 | | gauge_disconnect | 接続を切断し、セッション中の全呼び出しを集計したトレースサマリーを返します。 |
評価・分析
| ツール | 説明 | |-------|------| | gauge_evaluate | トレースデータを成功条件（最大ステップ数、必須ツール、禁止ツールなど）に基づいて評価し、合否判定を返します。 | | gauge_compare | 2つのトレースセッション（変更前後）を比較し、各メトリクスの改善・悪化を判定します。 | | gauge_report | 複数のトレースセッションから統合レポートを生成し、平均メトリクスと改善推奨事項を返します。 |
セットアップ
インストール
# uvでインストール
uv pip install -e .
# 開発用依存関係も含める場合
uv pip install -e ".[dev]"MCPクライアントへの登録
Claude Codeの場合、.mcp.json に以下を追加します。
{
"mcpServers": {
"mcp-gauge": {
"command": "uv",
"args": ["run", "--directory", "/path/to/mcp-gauge", "python", "-m", "mcp_gauge"]
}
}
}環境変数
| 変数名 | 説明 | デフォルト | |--------|------|-----------| | MCP_GAUGE_DB_PATH | トレースデータの保存先 | ~/.mcp-gauge/gauge.db | | MCP_GAUGE_TIMEOUT | MCP接続タイムアウト（秒） | 30 | | MCP_GAUGE_TOOL_TIMEOUT | ツール呼び出しタイムアウト（秒） | 300 |
使い方
ローカルサーバーのテスト（stdio）
ローカルのMCPサーバーをテストする基本的な流れです。
# 1. ツール説明文をリンティング
gauge_lint(server_command="python", server_args=["-m", "my_mcp_server"])
# 2. テスト対象サーバーに接続
gauge_connect(server_command="python", server_args=["-m", "my_mcp_server"])
# → session_id と利用可能なツール一覧が返る
# 3. ツールをプロキシ経由で呼び出し（自動的にトレース記録）
gauge_proxy_call(session_id="...", tool_name="create", arguments={"name": "test"})
# 4. 接続を切断してサマリーを取得
gauge_disconnect(session_id="...", task_success=true)
# 5. 成功条件で評価
gauge_evaluate(session_id="...", success_criteria={
"max_steps": 5,
"required_tools": ["create", "list"],
"must_succeed": true
})リモートサーバーのテスト（Streamable HTTP / SSE）
リモートで稼働するMCPサーバーにも接続できます。
Streamable HTTP（推奨）:
gauge_connect(
server_url="https://example.com/mcp",
headers={"Authorization": "Bearer token123"}
)server_url を指定すると、トランスポートは自動的に streamable_http が選択されます。
SSE:
gauge_connect(
server_url="https://example.com/sse",
transport_type="sse",
headers={"Authorization": "Bearer token123"}
)SSEトランスポートを使う場合は transport_type="sse" を明示的に指定してください。
リモートサーバーのリンティング:
gauge_lint(
server_url="https://example.com/mcp",
headers={"Authorization": "Bearer token123"}
)接続パラメータ
gauge_connect と gauge_lint は共通の接続パラメータを受け取ります。
| パラメータ | 説明 | |-----------|------| | server_command | 対象サーバーの起動コマンド（stdio時に必須） | | server_args | 起動引数のリスト（デフォルト: []） | | server_url | リモートサーバーのURL（SSE/Streamable HTTP時に必須） | | transport_type | トランスポートの種類: stdio, sse, streamable_http（自動判定あり） | | headers | リモート接続時のHTTPヘッダー（デフォルト: {}） |
transport_type を省略した場合、server_url が指定されていれば streamable_http、それ以外は stdio が自動的に選択されます。
変更前後の比較
ツール説明文を改善した前後の効果を定量的に比較できます。
# 改善前のトレースをベースラインとして記録
gauge_connect(server_command="python", server_args=["-m", "my_server"])
# ... ツール呼び出し ...
gauge_disconnect(session_id="baseline-session")
# ツール説明文を改善した後、同じタスクを再実行
gauge_connect(server_command="python", server_args=["-m", "my_server"])
# ... ツール呼び出し ...
gauge_disconnect(session_id="current-session")
# 比較
gauge_compare(
baseline_trace_id="baseline-session",
current_trace_id="current-session"
)レポート生成
複数のテスト結果を統合して分析できます。
gauge_report(trace_ids=["session-1", "session-2", "session-3"])計測するメトリクス
MCP Gaugeは以下のメトリクスを自動計測します。
| メトリクス | 意味 | 改善のヒント | |-----------|------|------------| | 総ツール呼び出し回数 | タスク完了までに要した呼び出しの総数 | ツール説明文を明確にすることで、不要な試行錯誤を減らせます | | 冗長呼び出し回数 | 同一ツールに同一引数で繰り返された不必要な呼び出し | ツールの戻り値の説明を充実させ、エージェントが1回で正しい情報を得られるようにします | | エラー回数 | エラーレスポンスが返された回数 | エラーメッセージに原因と対処法を含め、エージェントが自律的にリカバリできるようにします | | リカバリステップ数 | エラー発生後、正常フローに復帰するまでの追加ステップ数 | この値が大きいほど、エラーメッセージの品質が低いことを示します | | 所要時間 | セッション全体のエンドツーエンド所要時間 | ツール設計の効率性を示す指標です |
アーキテクチャ
レイヤー構成
MCP Gaugeは3層のレイヤードアーキテクチャで構成されています。
MCPサーバーレイヤー は、MCPプロトコルでツールを公開し、リクエストを受け付けます。プロトコル固有の処理のみを担当し、ビジネスロジックはエンジンレイヤーに委譲します。
エンジンレイヤー は、各機能のビジネスロジックを実装します。リンティング、トレース記録、プロキシセッション管理、成功条件評価、ベースライン比較、レポート生成の6つのエンジンで構成されます。
インフラレイヤー は、外部サービスへの接続とデータ永続化を担当します。テスト対象MCPサーバーへのMCPクライアント接続と、SQLiteによるトレースデータの永続化を行います。
各レイヤーは上位から下位への一方向の依存関係を持ち、逆方向の依存は禁止されています。
データ永続化
トレースデータはSQLiteデータベースに保存されます。WALモードを有効化しており、プロセスが異常終了した場合でも、コミット済みのトレースレコードは保護されます。起動時にはクラッシュリカバリーとして、未完了セッションの検出と状態復旧を自動的に行います。
技術スタック
| 技術 | 用途 | |------|------| | Python 3.12+ | 実装言語 | | MCP Python SDK | MCPサーバー/クライアント実装 | | aiosqlite | 非同期SQLiteアクセス | | Pydantic 2.x | データモデル定義・バリデーション |
ライセンス
MIT
