MCP Test Runner

mcp-test-runner

決定論的なローカルテスト実行と、正規化されたテスト結果のレポートを行う MCP サーバーです。

mcp-test-runner は、コードベースのオンボーディングエージェント向けの検証レイヤーです。pytest と Jest の実行、テスト出力の解析、カバレッジの要約を行う専用の MCP ツールを提供します。これにより、後続のエージェントは、実際の実行結果に基づいて主張を「検証済み」「未検証」「矛盾あり」と判定できます。

コードベースのオンボーディングスタック

mcp-test-runner は、コードベースのオンボーディングエージェントである Project 6 wayfinder 向けの、3 つの MCP ツールサーバースタックにおける検証レイヤーです。

• mcp-repo-mapper は、リポジトリの構造、言語、エントリーポイント、フレームワークの根拠、Python の依存関係をマッピングします。
• mcp-ast-explorer は、シンボルに基づいて Python の定義、シグネチャ、参照、呼び出しチェーン、クラス階層を検索できます。
• mcp-test-runner は、ローカルで pytest／Jest のチェックを実行し、カバレッジを要約して、エージェントの主張を実行結果に照らして検証できるようにします。

wayfinder では、このサーバーにより、リスクの高いコード理解に関する主張を、実際のテスト実行に基づく「検証済み」「未検証」「矛盾あり」の根拠に変換できます。

ステータス

このリポジトリは、Python を主体とした v1 の MCP テストランナーです。制限付きの pytest 実行、Jest コマンドの実行、単一テストの指定、pytest のカバレッジ要約、正規化された pytest／Jest JSON の解析に対応しています。

このサーバーは LLM を使用しません。テスト結果は、サブプロセスの実行と構造化されたパーサーの出力から取得します。

ツール

ツール	目的
health()	スモークチェック用に ok を返します。
run_pytest(path, test_filter?, timeout_seconds?, cpu_seconds?, memory_mb?)	作業ディレクトリを制限して pytest を実行し、コマンドの生出力を返します。
run_jest(path, test_filter?, timeout_seconds?, cpu_seconds?, memory_mb?)	npx jest を介して Jest を実行し、コマンドの生出力を返します。
run_single_test(path, test_id, framework?, timeout_seconds?, cpu_seconds?, memory_mb?)	pytest のノード ID を 1 つ、または Jest のテスト名パターンを 1 つ実行します。
parse_test_output(stdout, framework)	テストランナーの JSON 出力を正規化します。
get_coverage_summary(path, framework?, timeout_seconds?, cpu_seconds?, memory_mb?)	pytest-cov の JSON カバレッジ集計値を返します。

サポート範囲

• Python 3.11 以降のパッケージ。
• FastMCP 2.x サーバー。
• pytest-json-report による JSON レポート出力付きの pytest 実行。
• npx jest --json --outputFile による Jest コマンドの実行。
• pytest と Jest の JSON を単一の TestRunResult スキーマに正規化。
• pytest の単一ノード ID の実行と、Jest のテスト名指定。
• .coverage.json に基づく pytest-cov のカバレッジ要約。
• サブプロセスのタイムアウトと、POSIX resource.setrlimit による CPU／メモリー制限。

現在の制限事項

• v1 では Docker を使用しません。cwd の検証、サブプロセスのタイムアウト、POSIX のリソース制限を使用します。
• リソース制限には、resource.setrlimit をサポートする POSIX プラットフォームが必要です。
• Jest の実行には、Node.js と、プロジェクトローカルまたは npx から解決可能な Jest が必要です。
• Jest の単一テスト指定には --testNamePattern を使用します。Jest のファイル固有のノード ID は解析しません。
• v1 のカバレッジ要約は pytest のみを対象とします。
• ツールは実行時にコマンドの生出力を返します。フレームワークの JSON を正規化するには parse_test_output を呼び出してください。

ローカル開発

依存関係をインストールします：

uv sync --extra dev

PyPI では mcp-test-runner がすでに使用されているため、PyPI の配布名は lovranran-mcp-test-runner です。インストールされるコンソールスクリプト名は引き続き mcp-test-runner です。

MCP サーバーを起動します：

uv run mcp-test-runner

検証を実行します：

uv run ruff check .
uv run mypy
uv run pytest

ライセンス

MIT