Gradle MCP 服务器

一个模型上下文协议 (MCP) 服务器，使 AI 工具能够以编程方式与 Gradle 项目交互。它使用 Gradle Tooling API 来查询项目信息和执行任务。

功能

提供以下工具：

• 检查项目: 检索关于 Gradle 项目的详细、结构化信息，包括：
  • 构建结构（根项目、子项目）
  • 可用任务（在根项目中）
  • 构建环境详情（Gradle 版本、Java 版本、JVM 参数）
  • 根项目详情（名称、路径、描述、构建脚本路径）
  • 允许选择性地查询信息类别。
• 执行任务: 运行特定的 Gradle 任务（例如，clean、build、assemble），并带有自定义参数、JVM 参数和环境变量。返回格式化的文本输出，包括 stdout/stderr 和状态。
• 分层运行测试: 执行 Gradle 测试任务（例如，test）并接收详细的、结构化的结果，以分层 JSON 格式（Suite -> Class -> Method）。包括：
  • 每个节点的 Outcome（passed、failed、skipped）。
  • 失败消息和经过过滤/截断的输出行 (stdout/stderr)，主要用于失败的测试（可配置）。
  • 支持通过模式进行测试过滤 (--tests)。
  • 用于控制输出包含和日志行数的选项。

要求

• JDK 21 或更高版本（如 build.gradle.kts 中配置的那样）

快速入门

构建

构建应用程序及其依赖项：

./gradlew build

打包

创建一个自包含的可运行 JAR：

./gradlew shadowJar

JAR 文件将位于 build/libs/ 中。

运行

可以使用在 --args 之后传递的命令行参数，以不同的模式运行服务器。

1. 标准 I/O 模式（默认）: 通过 stdin 和 stdout 进行通信。如果没有提供模式参数，则这是默认设置。

   # 直接通过 Gradle 运行
   ./gradlew run
   
   # 运行打包的 JAR
   java -jar build/libs/gradle-mcp-server-*-all.jar
   

2. 服务器发送事件 (SSE) 模式: 使用 Ktor 运行 HTTP 服务器，通过 SSE 公开 MCP 端点。

   # 通过 Gradle 在默认端口 3001 上运行
   ./gradlew run --args="--sse"
   
   # 通过 Gradle 在特定端口（例如，8080）上运行
   ./gradlew run --args="--sse 8080"
   
   # 在默认端口 3001 上运行打包的 JAR
   java -jar build/libs/gradle-mcp-server-*-all.jar --sse
   
   # 在特定端口（例如，8080）上运行打包的 JAR
   java -jar build/libs/gradle-mcp-server-*-all.jar --sse 8080
   

   将 MCP 客户端（如 Anthropic Console Inspector）连接到 http://localhost:<port>/sse。

3. 调试模式: 通过添加 --debug 标志启用详细的服务器端日志记录。这可以与其他模式结合使用。

   # 在 stdio 模式下运行，带有调试日志
   ./gradlew run --args="--debug"
   
   # 在 SSE 模式下于端口 3001 上运行，带有调试日志
   ./gradlew run --args="--sse --debug"
   
   # 在 SSE 模式下于端口 8080 上运行打包的 JAR，带有调试日志
   java -jar build/libs/gradle-mcp-server-*-all.jar --sse 8080 --debug
   

配置

服务器行为通过命令行参数控制：

• --stdio: (默认) 使用标准输入/输出进行 MCP 通信。
• --sse [port]: 在指定的 port 上作为 SSE 服务器运行（如果省略 port，则默认为 3001）。
• --debug: 在服务器控制台上启用详细日志记录。

可用工具

服务器通过模型上下文协议公开以下工具：

1. Get Gradle Project Info

   • 描述: 检索关于 Gradle 项目的特定详细信息，返回结构化的 JSON。允许仅请求必要的信息类别（buildStructure、tasks、environment、projectDetails）。如果省略 requestedInfo，则获取所有类别。
   • 主要输入:
     • projectPath (字符串，必需): Gradle 项目根目录的绝对路径。
     • requestedInfo (字符串数组，可选): 要检索的类别列表（例如，["tasks", "environment"]）。
   • 输出: JSON 对象 (GradleProjectInfoResponse)，包含请求的数据字段和潜在的错误。

2. Execute Gradle Task

   • 描述: 执行常规 Gradle 任务（如 build、clean）。如果需要详细的结果，不建议用于运行测试（请改用测试工具）。返回格式化的文本输出，总结执行情况并包括捕获的 stdout/stderr。
   • 主要输入:
     • projectPath (字符串，必需): Gradle 项目根目录的绝对路径。
     • tasks (字符串数组，必需): 要执行的任务名称列表（例如，["clean", "assemble"]）。
     • arguments (字符串数组，可选): Gradle 命令行参数（例如，["--info", "-PmyProp=value"]）。
     • jvmArguments (字符串数组，可选): Gradle 的 JVM 参数（例如，["-Xmx4g"]）。
     • environmentVariables (对象，可选): 构建的环境变量（例如，{"CI": "true"}）。
   • 输出: 格式化的文本响应，包含执行摘要、最终状态（Success/Failure）和组合的 stdout/stderr。

3. Run Gradle Tests

   • 描述: 执行 Gradle 测试任务，并将结果作为结构化的 JSON 层次结构（Suite > Class > Test）返回。默认情况下，过滤/截断输出行，重点关注失败。提供用于包含通过测试的输出和控制日志限制的选项。
   • 主要输入:
     • projectPath (字符串，必需): Gradle 项目根目录的绝对路径。
     • gradleTasks (字符串数组，可选): 要运行的测试任务（默认为 ["test"]）。
     • arguments (字符串数组，可选): 其他 Gradle 参数（过滤掉 verbose 标志，如 --info/--debug）。
     • environmentVariables (对象，可选): 测试执行的环境变量。
     • testPatterns (字符串数组，可选): 通过 --tests 传递的测试过滤器模式（例如，["*.MyTestClass"]）。
     • includeOutputForPassed (布尔值，可选): 设置为 true 以包含通过测试的输出（默认为 false）。
     • maxLogLines (整数，可选): 覆盖每个测试的输出行数的默认限制（0 表示无限制）。
     • defaultMaxLogLines (整数，可选): 设置默认的输出行数限制（内部默认为 100）。
   • 输出: JSON 对象 (GradleHierarchicalTestResponse)，包含执行详细信息、总体构建成功状态、信息性注释和 test_hierarchy 树。每个节点都包含显示名称、类型、Outcome、失败消息（如果有）、经过过滤/截断的输出行和子节点。

依赖项

• Gradle Tooling API（在 build.gradle.kts 中指定的版本）
• Anthropic MCP Kotlin SDK
• Ktor（用于 SSE 服务器模式）
• Logback（用于日志记录）