Gradle MCP 服务器

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

功能

提供以下工具：

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

要求

JDK 17 或更高版本
对于命令行安装：
- Linux/macOS: curl
- Windows: PowerShell 5+

安装

推荐方法：命令行下载

此方法将服务器 JAR 下载到您主目录中的标准位置。

Linux / macOS (需要 curl)：

# 下载 gradle-mcp-server-all.jar 到 ~/mcp-servers/gradle-mcp-server/
TARGET_DIR="$HOME/mcp-servers/gradle-mcp-server" && mkdir -p "$TARGET_DIR" && curl -fSL -o "$TARGET_DIR/gradle-mcp-server-all.jar" "https://github.com/IlyaGulya/gradle-mcp-server/releases/latest/download/gradle-mcp-server-all.jar" && echo "Downloaded to '$TARGET_DIR'." || echo "Download failed."

Windows (PowerShell 5+)：

# 下载 gradle-mcp-server-all.jar 到 %USERPROFILE%\mcp-servers\gradle-mcp-server\
$targetDir = Join-Path $env:USERPROFILE "mcp-servers\gradle-mcp-server"; if (-not (Test-Path $targetDir)) { New-Item -ItemType Directory -Path $targetDir -Force | Out-Null }; $outFile = Join-Path $targetDir "gradle-mcp-server-all.jar"; Write-Host "Downloading..."; Invoke-WebRequest -Uri "https://github.com/IlyaGulya/gradle-mcp-server/releases/latest/download/gradle-mcp-server-all.jar" -OutFile $outFile -ErrorAction Stop; Write-Host "Downloaded to '$targetDir'."

替代方法：手动下载

前往 GitHub 发布页面。
从最新发布中下载 gradle-mcp-server-all.jar 资产。
将下载的 JAR 文件保存到稳定位置。我们推荐：
- macOS / Linux: ~/mcp-servers/gradle-mcp-server/
- Windows: %USERPROFILE%\mcp-servers\gradle-mcp-server\ （如果不存在，请创建该目录）。

MCP 客户端配置

要使用此服务器与 MCP 客户端（如 VSCode 扩展或 Claude 桌面应用程序）一起使用，您需要将它的配置添加到客户端的设置文件中。

定位设置文件：
- VSCode 扩展（macOS 示例）：/Users/<YourUsername>/Library/Application Support/VSCodium/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json（根据标准 VSCode 或其他操作系统调整路径）。
- Claude 桌面应用程序（macOS 示例）：~/Library/Application Support/Claude/claude_desktop_config.json（根据其他操作系统调整路径）。

添加服务器配置：编辑 JSON 文件，并在 mcpServers 对象内添加以下条目。将 <absolute_path_to_home> 替换为您主目录的实际绝对路径。

{
  "mcpServers": {
    "gradle-mcp-server": {
      "command": "java",
      "args": [
        "-jar",
        "<absolute_path_to_home>/mcp-servers/gradle-mcp-server/gradle-mcp-server-all.jar"
      ],
      "env": {},
      "disabled": false,
      "autoApprove": []
    }
  }
}

使用

添加配置后，重启您的 MCP 客户端（例如，重新加载 VSCode 窗口或重启 Claude 应用程序）。
现在应该可以在客户端中使用 "Gradle MCP 服务器" 及其工具。当客户端需要时，服务器会自动通过 stdio 运行。

可用工具

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

获取 Gradle 项目信息
- 描述：检索有关 Gradle 项目的特定详细信息，返回结构化 JSON。允许仅请求必要的信息类别（buildStructure、tasks、environment、projectDetails）。如果 requestedInfo 被省略，则获取所有类别。
- 关键输入：
  - projectPath (字符串，必需): Gradle 项目根的绝对路径。
  - requestedInfo (字符串数组，可选): 要检索的类别列表（例如，["tasks", "environment"]）。
- 输出：JSON 对象（GradleProjectInfoResponse）包含请求的数据字段和潜在错误。
执行 Gradle 任务
- 描述：执行通用 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。
运行 Gradle 测试
- 描述：执行 Gradle 测试任务，并将结果作为分层 JSON 结构返回（套件 > 类 > 测试）。默认情况下过滤/截断输出行，主要关注失败。提供选项以包含通过测试的输出并控制日志限制。
- 关键输入：
  - projectPath (字符串，必需): Gradle 项目根的绝对路径。
  - gradleTasks (字符串数组，可选): 要运行的测试任务（默认为 ["test"]）。
  - arguments (字符串数组，可选): 额外的 Gradle 参数（像 --info/--debug 这样的详细标志默认会被过滤）。
  - environmentVariables (对象，可选): 测试执行的环境变量。
  - testPatterns (字符串数组，可选): 通过 --tests 传递的测试过滤模式（例如，["*.MyTestClass"]）。
  - includeOutputForPassed (布尔值，可选): 设置为 true 以包含通过测试的输出（默认 false）。
  - maxLogLines (整数，可选): 覆盖每个测试的默认输出行限制（0 表示无限制）。
  - defaultMaxLogLines (整数，可选): 设置默认输出行限制（内部默认为 100）。
- 输出：JSON 对象（GradleHierarchicalTestResponse）包含执行详细信息、整体构建成功状态、信息性注释和 test_hierarchy 树。每个节点包括显示名称、类型、结果、失败消息（如果有）、过滤/截断的输出行和子节点。

开发

从源代码构建

如果您想自己构建服务器：

克隆存储库。
确保已安装 JDK 17 或更高版本。
运行构建命令：
```
./gradlew shadowJar
```
将自包含 JAR (gradle-mcp-server-<version>-all.jar) 将创建在 build/libs/ 目录中。然后您可以配置您的 MCP 客户端以使用此 JAR（记住在配置中使用正确的绝对路径和版本）。

本地运行（用于测试）

您可以直接从命令行运行构建的 JAR 进行测试。服务器默认通过 stdio 通信。

# 以 stdio 模式运行打包的 JAR
java -jar build/libs/gradle-mcp-server-<version>-all.jar

# 使用特定参数运行（见配置部分）
java -jar build/libs/gradle-mcp-server-<version>-all.jar --sse 8080 --debug

配置（命令行参数）

当直接运行服务器 JAR（主要用于测试/开发）时，其行为可以通过命令行参数控制：

--stdio: (默认) 使用标准输入/输出进行 MCP 通信。
--sse [端口]: 在指定 端口 上运行作为 SSE 服务器（如果省略端口，默认为 3001）。将 MCP 客户端（如 Anthropic 控制台检查器）连接到 http://localhost:<端口>/sse。
--debug: 在服务器控制台上启用详细日志记录。

依赖项

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

IlyaGulya/gradle-mcp-server

星标增长

证据时间轴