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を使ったテストは、以下の流れで進みます。

1. 接続: エージェントが gauge_connect でテスト対象サーバーに接続を確立します。MCP Gaugeは対象サーバーのツール一覧をエージェントに返します。

2. ツール呼び出し: エージェントはツール一覧を見て、自らの判断で gauge_proxy_call を使いツールを呼び出します。MCP Gaugeは各呼び出しを対象サーバーに中継しながら、ツール名・引数・結果・所要時間・エラー有無をすべて記録します。

3. 切断: タスクが終わったら gauge_disconnect で接続を終了します。MCP Gaugeはセッション中の全呼び出しを集計し、トレースサマリー（総呼び出し回数、冗長呼び出し数、エラー回数、リカバリステップ数など）を返します。

4. 評価: 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