内容
# Gradle 优化 MCP 服务器
[](https://github.com/JosephSanjaya/gradle-opt-mcp/actions/workflows/ci.yml)
[](https://github.com/JosephSanjaya/gradle-opt-mcp/releases)
> 一个 Model Context Protocol（MCP）服务器，为 Claude 提供直接、结构化的访问您的 Gradle 构建 — 依赖关系图、构建扫描、缓存健康状况、测试结果等 — 无需您手动粘贴日志。
## 目录
- [关于](#关于)
- [功能](#功能)
- [技术栈](#技术栈)
- [前提条件](#前提条件)
- [安装](#安装)
- [配置](#配置)
- [使用](#使用)
- [开发](#开发)
- [发布](#发布)
- [故障排除](#故障排除)
- [贡献](#贡献)
- [许可证](#许可证)
## 关于
诊断缓慢或失败的 Gradle 构建通常意味着运行命令、复制其输出并粘贴到聊天中。该服务器消除了这一步骤：它通过 stdio 使用 MCP，因此 Claude 可以直接调用 Gradle 工具 — 检查依赖关系、运行干燥运行分析、配置文件缓存失效或提取测试摘要 — 并推理结构化结果而不是原始控制台文本。
## 功能
| 工具 | 功能描述 |
|---|---|
| `analyze_build_dry_run` | 分析 `--dry-run` 任务图而不执行构建 |
| `check_project_isolation_violations` | 标记破坏项目隔离的跨项目状态访问 |
| `get_dependency_insight` | 解释依赖关系为何解析为给定版本 |
| `audit_configuration_cache_inputs` | 审计使配置缓存失效的输入 |
| `verify_dependency_metadata` | 验证依赖关系元数据/签名 |
| `lint_gradle_plugins` | 检查已应用的 Gradle 插件的已知问题 |
| `analyze_build_scan` | 分析 Gradle 构建扫描 |
| `inspect_declarative_schemas` | 检查声明式 Gradle DSL 模式 |
| `profile_cache_invalidation_timeline` | 分析构建/配置缓存随时间推移的失效情况 |
| `analyze_parallelization_bottlenecks` | 查找阻止并行执行的任务 |
| `gradle_health` | 报告项目健康状况（模块、版本、结构） |
| `gradle_run` / `gradle_run_log` | 运行 Gradle 任务并检索其日志 |
| `gradle_test_summary` | 总结运行的测试结果 |
| `gradle_deps` | 渲染已解析的依赖关系图 |
## 技术栈
- **语言：** Kotlin 2.4.10（多平台，JVM 目标）
- **构建：** Gradle 9.6.1
- **运行时：** Ktor 服务器核心/Netty，Koin DI（编译器插件注解）
- **协议：** [Model Context Protocol](https://modelcontextprotocol.io) Kotlin SDK，stdio 传输
- **CI/CD：** GitHub Actions（基于主干的 CI + 标签触发的发布），[git-cliff](https://git-cliff.org) 用于发布说明
## 前提条件
| 需求 | 最低版本 | 备注 |
|---|---|---|
| JDK | 21 | 运行 fat jar 和构建项目所需 |
| Gradle | 9.6.1 | 仅在从源代码构建时需要。包装器 (`./gradlew`) 会处理此问题 |
| 支持 MCP 的客户端 | — | 例如 Claude Desktop 或 Claude Code |
## 安装
**选项 A — 下载发布版本（推荐）：**
```bash
gh release download --repo JosephSanjaya/gradle-opt-mcp --pattern '*.jar'
java -jar gradle-opt-mcp-*.jar
```
该过程会阻塞，等待 stdio 输入 — 这是预期的。只有当 MCP 客户端连接时，它才会响应。
**选项 B — 从源代码构建：**
```bash
git clone https://github.com/JosephSanjaya/gradle-opt-mcp.git
cd gradle-opt-mcp
./gradlew :server:fatJar
java -jar server/build/libs/*-all.jar
```
## 配置
服务器在启动时读取以下环境变量：
| 变量 | 默认值 | 描述 |
|---|---|---|
| `GRADLE_PROJECT_DIR` | 当前工作目录 | 应该分析的 Gradle 项目的绝对路径 |
| `GRADLE_VARIANT` | 无 | 传递给需要它的工具的构建变体/风格（例如 Android 产品风格） |
在您的 MCP 客户端配置中设置这些变量，而不是作为全局导出 — 每个您分析的项目都需要其自己的值。
## 使用
将服务器添加到您的 MCP 客户端配置中，将 `args` 指向下载/构建的 jar 文件，将 `GRADLE_PROJECT_DIR` 指向您要检查的项目：
```json
{
"mcpServers": {
"gradle-optimization": {
"command": "java",
"args": ["-jar", "/absolute/path/to/gradle-opt-mcp-1.0.0.jar"],
"env": {
"GRADLE_PROJECT_DIR": "/absolute/path/to/your/gradle/project"
}
}
}
}
```
重启您的 MCP 客户端，然后询问 Claude 类似“检查此项目的 Gradle 健康状况”或“为什么 `com.google.guava:guava` 解析为此版本？” — Claude 调用匹配的工具并推理结构化结果。
## 开发
| 意图 | 命令 |
|---|---|
| 编译 | `./gradlew compileKotlin` |
| 构建服务器分发 | `./gradlew :server:installDist` |
| 构建 fat jar | `./gradlew :server:fatJar` |
| 检查和自动格式化 | `./gradlew detekt` |
| 运行所有测试 | `./gradlew test` |
## 发布
该项目是基于主干的：`main` 分支始终可发布，没有长期存在的分支。每次推送到 `main` 分支和每个 PR 都运行 CI（`detekt` + `test`，以及 PR 上的约定提交检查）。
要发布版本，请从 `main` 分支上的提交推送标签，匹配 `vX.Y.Z`（可选地为 `-alpha`/`-beta`/`-rc`）。然后，[发布工作流](./.github/workflows/release.yml)：
1. 验证标签的提交是否可从 `origin/main` 访问
2. 使用标签作为版本号构建 fat jar
3. 为 jar 生成 SHA-256 校验和
4. 使用 git-cliff 从提交历史记录中生成发布说明
5. 发布包含 jar、校验和和说明的 GitHub 发布
## 故障排除
**`java.lang.UnsupportedClassVersionError`**
原因：使用比 21 旧的 JDK 运行 jar 文件。
解决方法：安装 JDK 21+（例如 Temurin）并使用 `java -version` 确认。
**Claude/您的 MCP 客户端显示服务器不可用或无工具**
原因：您的 MCP 配置中的 `args` 路径未指向实际的 jar 文件，或 `GRADLE_PROJECT_DIR` 不存在。
解决方法：手动从终端运行 `java -jar <path>` — 如果它启动时没有打印错误并且保持空闲，则 jar 文件正常，问题是客户端配置路径。
**基于 Gradle 的工具调用失败或超时**
原因：`GRADLE_PROJECT_DIR` 指向没有 Gradle 包装器（无 `gradlew`）的目录，或目标项目本身配置失败。
解决方法：将 `GRADLE_PROJECT_DIR` 指向包含 `gradlew` 的项目根目录，并确认项目独立构建。
## 贡献
1. 分叉仓库并从 `main` 分支创建新分支
2. 进行聚焦的、独立编译的提交 — 每个提交都必须通过 `./gradlew detekt test`
3. 遵循 [Conventional Commits](https://www.conventionalcommits.org)：`feat`、`fix`、`chore`、`refactor`、`docs`、`test`、`perf`、`build`、`ci`
4. 打开一个 PR 到 `main` 分支 — CI 强制执行提交格式并运行完整构建
## 许可证
该仓库中尚未发布许可证文件。在添加许可证文件之前，作者保留所有权利。
