⚡ Omni-Tester: ゼロハルシネーション MCP テストエージェント

Omni-Tester は、AI エージェント（Claude、Cursor、Windsurf など）に証明ベースのハルシネーション防止検証エンジンを提供する Model Context Protocol (MCP) サーバーです。LLM にエンドポイントが動作するかどうかを「推測」させないでください。プログラムによる証明を要求しましょう。

このエージェントはバックエンドサーバーと直接通信し、HTTP ステータスコード、レスポンスヘッダー、JSON ペイロードを検査して、決定的で機械検証済みの結果を生成します。

✅ 現在実装済み（決定的証明）

これらのレイヤーは現在動作し、機械検証済みの証拠を返します。LLM による判断は一切関与しません：

• レイヤー 1 — プロトコルとステータスの検証： リクエストを送信し、返された HTTP ステータスコードが明示的な期待値（例：200 OK、201 Created）と一致するかを検証し、不一致や 5xx クラッシュをフラグ付けします。

• レイヤー 2 — スキーマとペイロードの整合性： Content-Type ヘッダーが application/json であるかを確認し、ボディを JSON として解析して、ペイロードのスナップショットを返します。オプションの expected_schema を渡すと、各フィールドの存在と型を決定的に強制します — トップレベル（"id"）、ドット区切りパスによるネスト（"address.geo.lat"）、リストのインデックス（"items.0.id"）。サポートされる型：int、float/number、str/string、bool、list/array、dict/object、null。（JSON の true/false は int としては受け付けられません。）

両方のレイヤーは常に実行されます — ステータスコードの失敗によってペイロード診断が抑制されることはないため、失敗した 4xx/5xx レスポンスのエラーボディも引き続き確認できます。

スキーマ強制の例：

run_api_4_layer_validation(
    endpoint_url="https://jsonplaceholder.typicode.com/users/1",
    expected_status=200,
    method="GET",
    expected_schema={"id": "int", "email": "str", "address.geo.lat": "str"},
)

また、実験的な run_ui_dom_checklist ツール（Playwright）もあります。これはヘッドレスブラウザでページを読み込み、フォーム数、alt タグのない画像、コンソールエラーを報告します。

Related MCP server: QA Testing MCP Server

🗺️ ロードマップ（未実装）

以下は計画中ですが、現在コードには含まれていません。これらは利用可能な機能としてではなく、透明性のためにここに記載されています：

• レイヤー 3 — 機能的なビジネスロジック： LLM を使用して、返されたデータがシナリオに論理的に適合するかを確認します。（注：このレイヤーは LLM ベースの判断であり、決定的証明ではありません。）

• レイヤー 4 — セキュリティと境界ストレステスト： 悪意のあるペイロード（SQL インジェクション文字列、不正なヘッダー、期限切れの認証トークン）を注入して、API が安全に失敗することを検証します。

• より深いレイヤー 2（ネスト型チェック）： ✅ 完了 — トップレベル、ドット区切りのネストパス、リストのインデックスはすべて強制されます。残りのアイデア：配列全体にわたる要素ごとの検証（例：「すべてのアイテムが int の id を持つ」）や enum/フォーマット制約。

• Sovereign API Agent： シナリオを計画し、Python テストコードを生成し、スキーマが変化したときに自己修復する自律型テストエンジニア。

• API Explorer Agent： 動的にアクションをファジングして連鎖させます（例：GET からトークンを取得して PUT に注入する）。

• 監査証跡： specs/api_plan.md、tests/api/、data/reports/api_report_*.html への構造化出力。

📦 インストール

uv を使用（推奨）：

uv venv
source .venv/bin/activate        # On Windows: .venv\Scripts\activate
uv sync                          # Install dependencies from pyproject.toml

UI チェックリストツール用に、Playwright ブラウザを一度インストールします：

uv run playwright install chromium

サーバーが起動することを確認します（stdio 経由で MCP 通信を行い、クライアントを待機します）：

uv run omni-tester

🔌 MCP クライアントへの接続

サーバーは uv run omni-tester で起動します。以下の任意のクライアントに追加してください。uv がクライアントの PATH にない場合は、command フィールドに uv バイナリの絶対パスを使用してください。

Claude Code (CLI)

次の 1 コマンドで追加します：

claude mcp add --transport stdio omni-tester -- uv run omni-tester

または、プロジェクトスコープの .mcp.json に手動で追加します：

{
  "mcpServers": {
    "omni-tester": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "omni-tester"],
      "env": {}
    }
  }
}

Claude Desktop

claude_desktop_config.json を編集します（Settings → Developer → Edit Config）：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "omni-tester": {
      "command": "uv",
      "args": ["run", "omni-tester"],
      "env": {}
    }
  }
}

保存後、Claude Desktop を再起動します。

Cursor

.cursor/mcp.json（プロジェクトスコープ）または ~/.cursor/mcp.json（グローバル）を編集します：

{
  "mcpServers": {
    "omni-tester": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "omni-tester"],
      "env": {}
    }
  }
}

Windsurf (Cascade)

mcp_config.json を編集します（Settings → Manage MCP Servers → View raw config）：

• macOS/Linux: ~/.codeium/windsurf/mcp_config.json

• Windows: %APPDATA%\Codeium\Windsurf\mcp_config.json

{
  "mcpServers": {
    "omni-tester": {
      "command": "uv",
      "args": ["run", "omni-tester"],
      "env": {}
    }
  }
}

保存後、Windsurf を再起動します。

🛠️ ツール

命名に関する注記： このツールは将来の互換性のために run_api_4_layer_validation という名前ですが、現在実装されているのはレイヤー 1–2 のみです（ロードマップを参照）。

🧪 例

稼働中のエンドポイントを検証し、200 を期待します：

run_api_4_layer_validation(
    endpoint_url="https://jsonplaceholder.typicode.com/users/1",
    expected_status=200,
    method="GET",
)

出力結果：

Backend 4-Layer Validation Complete:
✅ Layer 1 PASS: Expected 200, received 200.
✅ Layer 2 PASS: Valid JSON payload returned.
Payload Snapshot: {'id': 1, 'name': 'Leanne Graham', ...}