Java Test Runner MCP

java测试运行程序mcp

一个MCP（模型上下文协议）服务器，用于编译和运行Java项目（Maven和Gradle），解析测试结果，并返回结构化输出。专为Cursor、Claude Desktop和其他MCP客户端中的AI辅助开发工作流程而构建。

工具

推荐的代理工作流程

1. compile          -- verify the project builds cleanly
2. run_test         -- execute the test; get a compact summary with
                       pass/fail per scenario and capped failure output
3. get_full_report  -- if the compact summary isn't enough:
      source=scenario   -> full uncapped Cucumber step log for a scenario
      source=build_log  -> full Maven/Gradle console output
4. Fix the code, then go back to step 1.

安装

使用npx（建议用于Cursor）

无需安装。添加到光标MCP配置中：

项目级别 (.cursor/mcp.json 在您的仓库中）：

{
  "mcpServers": {
    "java-test-runner": {
      "command": "npx",
      "args": ["-y", "java-test-runner-mcp"],
      "env": {
        "PROJECT_PATH": "C:\\Repos\\my-java-project",
        "JAVA_HOME": "C:\\Program Files\\Java\\jdk-17"
      }
    }
  }
}

用户级别 (~/.cursor/mcp.json):

{
  "mcpServers": {
    "java-test-runner": {
      "command": "npx",
      "args": ["-y", "java-test-runner-mcp"],
      "env": {
        "PROJECT_PATH": "C:\\Repos\\my-java-project",
        "JAVA_HOME": "C:\\Program Files\\Java\\jdk-17",
        "TIMEOUT_MS": "600000"
      }
    }
  }
}

本地开发服务器

如果您已在本地克隆并构建了此仓库，请直接指向已构建的入口点：

{
  "mcpServers": {
    "java-test-runner": {
      "command": "node",
      "args": ["C:\\Repos\\java-test-runner-mcp\\build\\index.js"],
      "env": {
        "PROJECT_PATH": "C:\\Repos\\my-java-project"
      }
    }
  }
}

克劳德桌面版

添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上，或 %AppData%\Claude\claude_desktop_config.json 在Windows上）：

{
  "mcpServers": {
    "java-test-runner": {
      "command": "npx",
      "args": ["-y", "java-test-runner-mcp"],
      "env": {
        "PROJECT_PATH": "/Users/me/repos/my-java-project",
        "JAVA_HOME": "/usr/lib/jvm/java-17"
      }
    }
  }
}

全局安装

npm install -g java-test-runner-mcp

使用示例

配置后，AI代理可以自动使用这些工具。以下是交互示例：

编译项目：

“在C:\\Repos\\my应用程序中编译我的Java项目”

运行测试运行程序：

“运行WpandTaskStatusRemapping测试运行器”

run_test后调试失败会给出一个简洁的总结：

“获取失败测试的完整场景输出”

获取完整的Maven构建日志：

“显示上次运行的完整生成日志”

使用指标获取测试结果：

“显示带有执行时间的测试结果”

列出所有跑步者：

“此项目中有哪些测试运行程序？”

工具详细信息

编译

编译Maven或Gradle项目。自动从项目根目录检测构建工具。

run_test

运行特定的测试或运行程序类。返回一个简洁、对代理友好的摘要：

• 每个场景的通过/失败状态和执行时间
• 对于 失败 场景：断言消息加上Cucumber步骤日志的前4000个字符（API请求/响应、DataTables、堆栈跟踪）
• 完整的构建输出将持续到 `

/.java-test-runner/last-run.log 通过以下方式检索 get_full_report`

输出示例：

=== Run Test: runner.WpandTaskStatusRemapping ===
Exit code: 1 | Elapsed: 343.0s

--- Test Results ---
Total: 9 | Passed: 8 | Failed: 1 | Errors: 0 | Skipped: 0 | Time: 316.5s

--- All Scenarios ---
  [FAIL] Create HM Contract with contract rule (5.59s)
  [PASS] Create WP1 with ad hoc task (126.82s)
  [PASS] Create customer order for WP1 (3.53s)
  ...

--- Failure #1: Create HM Contract with contract rule [5.59s] ---
java.lang.AssertionError: Create contract rule failed with status 500

Scenario output:
@api @PreRequisite
Scenario: Create HM Contract with contract rule  # feature:9
  Given User creates HM contract ...
    | Company | ContractId | ...
  {"error":{"code":"DB_OBJECT_EXIST","message":"Resource already in use."}}

get_full_report

紧凑型潜水时的深潜回退 run_test 摘要不足以诊断故障。支持两种模式：

来源=场景 --返回完整的、无上限的 `` 来自Surefire XML的匹配场景。包含完整的Cucumber步骤日志，包括API请求/响应JSON、DataTables和完整的堆栈跟踪。

• 随着 scenarioName：模糊子字符串匹配返回任何匹配场景的输出（即使是传递的场景）。
• 没有 scenarioName：返回所有失败/错误的场景。

源代码=构建日志 --返回最新Maven/Gradle控制台的完整输出 run_test 执行（保存到 .java-test-runner/last-run.log).可用于诊断编译错误、依赖关系问题或插件故障。

run_main_class

使用以下命令执行Java类 main() 方法。

run_feature

运行Cucumber功能文件。

get_test_results

解析Surefire/Gradle XML测试报告并返回结构化结果。

返回结构化JSON：

{
  "summary": {
    "total": 9,
    "passed": 9,
    "failed": 0,
    "errors": 0,
    "skipped": 0,
    "totalTime": 324.79
  },
  "tests": [
    {
      "name": "Create HM Contract with contract rule",
      "className": "WP and Task Status Remapping",
      "time": 6.66,
      "status": "passed"
    }
  ]
}

get_build_info

从pom.xml或build.gradle读取项目元数据。

list_runners/list_test_classes

用于查找跑步者和测试类的发现工具。

环境变量

在中配置这些 env 你的块 mcp.json 以消除重复参数并防止代理混淆。所有这些都是可选的——工具参数总是优先于环境变量。

完整示例(mcp.json):

{
  "mcpServers": {
    "java-test-runner": {
      "command": "npx",
      "args": ["-y", "java-test-runner-mcp"],
      "env": {
        "PROJECT_PATH": "C:\\Repos\\my-java-project",
        "JAVA_HOME": "C:\\Program Files\\Java\\jdk-17",
        "TIMEOUT_MS": "600000",
        "BUILD_TOOL": "maven",
        "TEST_BASE_DIR": "src/test/java",
        "MAVEN_PROFILES": "dev"
      }
    }
  }
}

它如何帮助代理商： 当 PROJECT_PATH 和 JAVA_HOME 设置好后，代理可以调用以下工具 compile, run_test，以及 list_runners 而不需要找出绝对路径——这是代理错误最常见的来源。

需求

• Node.js>=18
• 使用Maven的Java项目(pom.xml)或Gradle(build.gradle / build.gradle.kts)
• Maven或Gradle已安装并可在PATH上使用（或项目包含包装器脚本）

发展

# Clone the repo
git clone 
cd java-test-runner-mcp

# Install dependencies
pnpm install

# Build
pnpm build

# Watch mode
pnpm dev

出版

# Build and publish to npm
pnpm build
pnpm publish --access public

许可证

麻省理工学院