MCP Test Runner

mcp-test-runner

用于确定性本地测试执行和标准化测试结果报告的 MCP 服务。

mcp-test-runner 是代码库上手 Agent 的验证层。它提供专用的 MCP 工具，用于运行 pytest 和 Jest、解析测试输出并汇总覆盖率，帮助下游 Agent 根据真实执行结果将声明标记为已验证、未验证或相矛盾。

代码库上手技术栈

mcp-test-runner 是 Project 6 wayfinder（一个代码库上手 Agent）的三服务 MCP 工具技术栈中的验证层。

• mcp-repo-mapper 映射仓库结构、语言、入口点、框架证据和 Python 依赖关系。
• mcp-ast-explorer 提供基于符号的 Python 定义、签名、引用、调用链和类层次结构查询。
• mcp-test-runner 运行本地 pytest/Jest 检查并汇总覆盖率，以便根据执行结果验证 Agent 的声明。

在 wayfinder 中，此服务将高风险的代码理解声明转化为来自真实测试执行的 verified、unverified 或 contradicted 证据。

状态

此仓库是一个以 Python 为主的 v1 MCP 测试运行器。它支持有界 pytest 执行、Jest 命令执行、单项测试定位、pytest 覆盖率汇总，以及标准化解析 pytest/Jest JSON。

此服务不使用大模型。测试结果来自子进程执行和结构化解析器输出。

工具

工具	用途
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 或一个 Jest 测试名称模式。
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 覆盖率。
• 执行工具返回原始命令输出；调用 parse_test_output 可标准化框架 JSON。

本地开发

安装依赖：

uv sync --extra dev

由于 mcp-test-runner 已被 PyPI 占用，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