Gradle MCP Server

Gradle MCP服务器

用于Gradle与AI助手无缝集成的模型上下文协议（MCP）服务器

  

*使您的AI编码助手能够通过实时监控构建、测试和管理Gradle项目*

特性 • 安装 • 快速开始 • 网络仪表盘 • API 参考 • 贡献

______________________________________________________________________

✨ 特性

🛠️ 构建自动化

• 项目发现 --自动检测并列出工作区中的所有Gradle项目
• 任务管理 --使用完整的参数支持浏览和执行任何Gradle任务
• 多任务执行 --在单个命令中运行多个任务
• 安全清洁 --专用清理工具可防止意外删除工件

📊 实时监控

• 实时进度跟踪 --任务执行过程中的可视化进度更新
• 网络仪表盘 --使用WebSocket更新进行基于浏览器的监控
• 守护进程管理 --监视和控制Gradle守护进程
• 生成日志 --可搜索的实时构建日志查看器

🔧 配置和诊断

• 配置检查 --查看JVM参数、守护进程设置和Gradle版本
• 内存监控 --跟踪守护进程内存使用情况和运行状况
• 结构化错误输出 --LLM友好的错误响应，包含重复数据消除的编译错误和任务失败摘要

______________________________________________________________________

📸 网络仪表盘

Gradle MCP Server包括一个功能强大的web仪表板，用于实时构建监控。当服务器运行时，仪表板会自动启动，可在以下网址访问 http://localhost:3333.

仪表板概述

主仪表板提供：

• 守护进程状态 --实时查看运行的Gradle守护进程的PID、状态和内存使用情况
• 活动建筑 --实时跟踪当前正在执行的任务
• 快捷操作 --一键守护进程管理（全部停止，刷新状态）
• 自动刷新 --WebSocket驱动的更新，无需手动刷新

构建日志查看器

日志查看器提供：

• 实时流媒体 --实时观察构建输出
• 日志筛选 --搜索并过滤构建历史记录
• 清除日志 --一键清除新会话日志
• 持久历史 --日志在会话期间的页面刷新过程中持续存在

______________________________________________________________________

📦 安装

需求

• Python 3.10+
• Gradle项目 带包装(gradlew / gradlew.bat)
• MCP兼容客户端 （例如，Claude Desktop、Cursor、VS Code with Copilot）

从源代码安装

git clone https://github.com/jermeyyy/gradle-mcp.git
cd gradle-mcp

# Using uv (recommended)
uv sync

# Or using pip
pip install -e .

______________________________________________________________________

🚀 快速开始

1.启动服务器

# Navigate to your Gradle project directory
cd /path/to/your/gradle/project

# Start the MCP server
uv run gradle-mcp

服务器将：

1. 自动检测当前目录中的Gradle包装器
2. 在以下位置启动web仪表板 http://localhost:3333 （如果端口已占用，则更高）
3. 开始监听MCP客户端连接

2.配置您的MCP客户端

将服务器添加到MCP客户端配置中。例如，在Claude Desktop的 claude_desktop_config.json:

{
  "mcpServers": {
    "gradle": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/gradle-mcp/installation",
        "gradle-mcp"
      ]
      "env": {
        "GRADLE_PROJECT_ROOT": "/path/to/your/gradle/project"
      }
    }
  }
}

3.开始建设！

您的AI助手现在可以执行Gradle命令：

"Build the app module"
"Run all tests except integration tests"
"Show me the available tasks for the core module"
"Check the Gradle daemon status"

______________________________________________________________________

🔧 配置

环境变量

配置示例

# Custom project location
export GRADLE_PROJECT_ROOT=/path/to/project
uv run gradle-mcp

# Custom wrapper location
export GRADLE_WRAPPER=/path/to/custom/gradlew
uv run gradle-mcp

______________________________________________________________________

📚 MCP工具API

项目与任务管理

list_projects()

列出工作区中的所有Gradle项目。

退货： 包含名称、路径和描述的项目列表

______________________________________________________________________

list_project_tasks(project, include_descriptions, group)

列出项目的可用任务，可选择按组筛选。

退货： 任务分组列表

______________________________________________________________________

run_task(task, args)

执行一个或多个Gradle任务。

退货： TaskResult 与：

• success: bool --任务是否成功完成
• error: ErrorInfo | None --结构化错误信息（参见 结构化错误输出)

⚠️ 注： 清洁任务被阻止--使用 clean 工具代替。

______________________________________________________________________

clean(project)

为项目清理构建工件。

退货： TaskResult 与：

• success: bool --清洁是否成功完成
• error: ErrorInfo | None --结构化错误信息（参见 结构化错误输出)

______________________________________________________________________

守护进程管理

daemon_status()

获取所有正在运行的Gradle守护进程的状态。

退货： 运行状态、守护进程信息列表（PID、状态、内存）和任何错误

______________________________________________________________________

stop_daemon()

停止所有Gradle守护进程。有助于释放内存或解决守护进程问题。

退货： 成功状态和错误消息（如果失败）

______________________________________________________________________

配置

get_gradle_config()

获取当前Gradle配置，包括内存设置。

退货： 配置对象具有：

• jvm_args --gradle.properties中的JVM参数
• daemon_enabled --是否启用守护进程
• parallel_enabled --是否启用并行执行
• caching_enabled --是否启用了构建缓存
• max_workers --最大工人人数
• distribution_url --分级分发URL
• gradle_version --Gradle版本

______________________________________________________________________

💡 使用示例

使用MCP客户端

# Discover projects
list_projects()

# List build tasks for a module
list_project_tasks(project=":app", group="Build")

# Build with verbose output
run_task(task=":app:build", args=["--info"])

# Run tests, skipping integration tests
run_task(task=":app:test", args=["-x", "integrationTest"])

# Run multiple tasks
run_task(task=[":core:build", ":app:assemble"])

# Check daemon health
daemon_status()

# Free up memory
stop_daemon()

作为Python库

from gradle_mcp.gradle import GradleWrapper

gradle = GradleWrapper("/path/to/gradle/project")

# List projects
projects = gradle.list_projects()
for project in projects:
    print(f"Project: {project.name} at {project.path}")

# List tasks with descriptions
tasks = gradle.list_tasks(":app", include_descriptions=True)
for group in tasks:
    print(f"\n{group.group}:")
    for task in group.tasks:
        print(f"  {task.name}: {task.description}")

# Run a task
result = await gradle.run_task([":app:build"])
if result["success"]:
    print("✅ Build succeeded!")
else:
    print(f"❌ Build failed: {result['error']}")

______________________________________________________________________

🏗️ 建筑

设计安全

• 单独清洁 --The run_task 工具阻止所有清洁操作(clean, cleanBuild等等）。使用专用 clean 用于去除伪影的工具。
• Gradle包装 --始终使用项目的Gradle包装器来保持版本一致性
• 进度报告 --通过MCP协议实现实时进度

结构化错误输出

这 run_task 和 clean 工具返回针对LLM消费优化的结构化错误信息：

class ErrorInfo:
    summary: str                        # e.g., "Build failed: 2 tasks failed with 12 compilation errors in 1 file"
    failed_tasks: list[FailedTask]      # List of failed task names and reasons
    compilation_errors: list[CompilationError]  # Deduplicated compilation errors

class CompilationError:
    file: str      # Full path (without file:// prefix)
    line: int
    column: int | None
    message: str

class FailedTask:
    name: str      # e.g., ":app:compileKotlin"
    reason: str    # e.g., "Compilation finished with errors"

示例响应：

{
  "success": false,
  "error": {
    "summary": "Build failed: 2 tasks failed with 2 compilation errors in 1 file",
    "failed_tasks": [
      {"name": ":app:compileKotlin", "reason": "Compilation finished with errors"}
    ],
    "compilation_errors": [
      {
        "file": "/Users/dev/project/src/Main.kt",
        "line": 45,
        "column": 49,
        "message": "Argument type mismatch: actual type is 'String', but 'Int' was expected."
      }
    ]
  }
}

主要特点：

• 去重 --来自多个目标（例如iOS Arm64+模拟器）的相同错误被合并
• 清洁路径 — file:// 从文件路径中删除前缀
• 简明摘要 --带有任务/错误/文件计数的可读摘要
• 代币高效 --结构化数据而不是原始构建输出

______________________________________________________________________

🧪 发展

设置开发环境

# Clone the repository
git clone https://github.com/jermeyyy/gradle-mcp.git
cd gradle-mcp

# Install with dev dependencies
uv sync --all-extras

运行测试

pytest tests/

代码质量

# Format code
black src/

# Lint code
ruff check src/

# Type checking
mypy src/

项目结构

gradle-mcp/
├── src/gradle_mcp/
│   ├── __init__.py           # Package initialization
│   ├── server.py             # MCP server implementation
│   ├── gradle.py             # Gradle wrapper interface
│   └── dashboard/            # Web dashboard
│       ├── app.py            # Flask application
│       ├── daemon_monitor.py # Daemon monitoring
│       ├── log_store.py      # Log management
│       ├── templates/        # HTML templates
│       └── static/           # CSS/JS assets
├── tests/                    # Test suite
├── art/                      # Screenshots and artwork
├── pyproject.toml            # Project configuration
└── README.md

______________________________________________________________________

🤝 贡献

欢迎投稿！以下是您可以提供帮助的方式：

1. 分叉 存储库
2. 创建 特征分支(git checkout -b feature/amazing-feature)
3. 提交 您的更改(git commit -m 'Add amazing feature')
4. 推 到分行(git push origin feature/amazing-feature)
5. 打开 拉取请求

贡献的想法

• \[\]额外的构建系统支持（Maven、Bazel）
• \[\]增强了仪表板中的错误可视化
• \[\]建立统计数据和历史记录
• \[\]自定义任务预设

______________________________________________________________________

📄 许可证

该项目根据MIT许可证获得许可——请参阅 许可证 文件以获取详细信息。

______________________________________________________________________

内置于❤️ Gradle和AI社区