# 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** | 複数のトレースセッションから統合レポートを生成し、平均メトリクスと改善推奨事項を返します。 |

## セットアップ

### インストール

```bash
# uvでインストール
uv pip install -e .

# 開発用依存関係も含める場合
uv pip install -e ".[dev]"
```

### MCPクライアントへの登録

Claude Codeの場合、`.mcp.json` に以下を追加します。

```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