Checkstyle MCP

🚀 Checkstyle MCP Server

Checkstyle MCP Server 是一个连接 LLM (大语言模型) 与 本地代码质量工具 的中间件。它实现了 Model Context Protocol (MCP)，允许 AI 助手（如 Cursor、Claude Desktop）直接调用本地的 Linter 和 Formatter，实现代码的自动检查与修复闭环。

🚀 快速开始

1. 环境准备

确保系统已安装 Go 1.21+。本项目依赖以下外部工具，可以通过 Web 界面一键安装（macOS），或手动安装：

# macOS (Homebrew)
brew install golangci-lint checkstyle luacheck stylua

# 其他系统请参考各工具官方文档

2. 编译项目

git clone https://github.com/yourusername/checkstyle_mcp.git
cd checkstyle_mcp

# 编译生成可执行文件
go build -o checkstyle-mcp cmd/server/*.go

3. 运行模式

模式 A: Stdio 模式 (推荐用于 Cursor)

直接在 Cursor 的 MCP 设置中配置，无需手动启动 Server。

1. 打开 Cursor Settings > Features > MCP。
2. 点击 Add New MCP Server。
3. 选择 Stdio 类型。
4. Command 填入编译后的绝对路径：

/absolute/path/to/checkstyle-mcp

模式 B: Remote (HTTP/SSE) 模式

适用于远程部署或分布式调用。

# 启动 HTTP Server (MCP 端口 3000, Web 管理端端口 8080)
./checkstyle-mcp -mode http -mcp-port 3000 -web-port 8080

• Web 管理端: http://localhost:8080
• MCP Endpoint: http://localhost:3000/mcp (支持 SSE)

✨ 主要特性

• 🛡️ 多语言代码检查与修复
  • Go：集成 golangci-lint（检查）和 gofmt（格式化）。
  • Java：集成 checkstyle（检查）和 google-java-format（格式化）。
  • Lua：集成 luacheck（检查）和 stylua（格式化）。
• 🏗️ 项目级配置隔离
  • 支持为不同项目配置独立的规则文件（如 .golangci.yml、checkstyle.xml、.luacheckrc）。
  • 提供开箱即用的默认配置模板。
• 🔌 双模式接入
  • Stdio 模式：适用于本地 IDE 直接集成（推荐 Cursor）。
  • Remote (HTTP/SSE) 模式：适用于远程部署或分布式调用。
• 📊 Web 管理控制台
  • 可视化管理项目与配置。
  • 环境自检：自动检测并安装缺失的系统工具（支持 macOS/Homebrew）。
  • 审计日志：记录每一次 AI 调用的检查结果与修复操作，支持查看详细的错误报告。
• 🤖 AI 自我纠错 (Self-Healing)
  • 提供标准化的 Prompt 模板，指导 AI 建立 "生成 -> 检查 -> 修复" 的自动化闭环。

💻 使用示例

基础用法

在配置好项目环境后，使用 Cursor 等 AI 助手时，可按照以下步骤调用代码检查与修复功能：

// 按照系统提示的流程，AI 会自动完成代码生成、检查与修复
// 1. 生成代码
// 2. 立即调用 `lint_code` 工具检查生成的代码（使用对应的 `projectName` 和 `language`）
// 3. 如果发现问题：分析错误，修正代码，并再次运行 `lint_code` 验证
// 4. 重复直到通过检查或尝试 3 次

高级用法

在远程部署场景下，使用 Remote (HTTP/SSE) 模式接入：

# 启动 HTTP Server (MCP 端口 3000, Web 管理端端口 8080)
./checkstyle-mcp -mode http -mcp-port 3000 -web-port 8080

通过 Web 管理端 http://localhost:8080 进行项目管理和配置，同时利用 MCP Endpoint http://localhost:3000/mcp (支持 SSE) 实现分布式调用。

📚 详细文档

1. 配置项目规则

1. 启动服务并访问 Web 管理端。
2. 点击 "New Project" 创建一个项目上下文（例如 my-backend）。
3. 在项目详情页，你可以：
   • 查看环境工具状态。
   • 上传自定义配置文件（如 checkstyle.xml）。
   • 点击 "Use Default Config" 应用最佳实践规则。

2. AI 自我纠错 (Self-Healing Loop)

为了让 AI 充分利用此工具，请在对话开始时发送以下 System Prompt：

你现在可以通过 MCP 访问本地代码质量工具。在编写代码时，请严格遵守以下流程：

1. 生成代码。
2. 立即调用 lint_code 工具检查生成的代码（使用对应的 projectName 和 language）。
3. 如果发现问题：分析错误，修正代码，并再次运行 lint_code 验证。
4. 重复直到通过检查或尝试 3 次。

(你也可以在 Web 管理端的侧边栏点击 "集成指南" 复制此 Prompt)

3. 前端开发指南

Web 管理界面使用 React + TypeScript + Vite 构建，UI 组件库使用 Ant Design。

技术栈

• Framework：React 18
• Build Tool：Vite
• UI Library：Ant Design 5
• HTTP Client：Axios
• State Management：React Hooks

开发步骤

1. 进入前端目录：

cd ui/web

2. 安装依赖：

npm install
# 或
yarn install

3. 启动开发服务器：

npm run dev
# 或
yarn dev

这将启动一个热重载的开发服务器（默认端口 5173），并配置了代理以转发 API 请求到后端（默认 localhost:8080）。 4. 构建生产版本：

npm run build
# 或
yarn build

构建产物将输出到 ui/web/dist 目录。 5. 集成到后端： 构建完成后，ui/web/dist 中的内容将自动被 golang 后端托管。确保在启动后端时指向该目录：

# 编译后端
go build -o checkstyle-mcp cmd/server/*.go

# 启动服务 (指定 web-root 为前端构建目录)
./checkstyle-mcp -mode http -web-root ./ui/web/dist

⚠️ 重要提示

如果修改了前端代码后刷新页面未生效，请尝试清除浏览器缓存或使用无痕模式访问，或者更换端口启动 (例如 -web-port 8081)。

4. 手动管理项目 (文件系统模式)

如果你不方便使用 Web 管理端，也可以直接通过文件系统管理项目和配置。

1. 创建项目目录： 在 data/projects/ 目录下创建一个新文件夹，文件夹名即为 projectName。

mkdir -p data/projects/my-java-project

2. 添加元数据 (可选)： 创建一个 meta.json 文件来指定项目类型（如果未指定，系统会自动推断，但建议显式指定）。

// data/projects/my-java-project/meta.json
{
  "name": "my-java-project",
  "type": "java" 
}

支持的类型: java, go, lua 3. 添加配置文件： 将你的规则文件复制到该目录中： - Java：checkstyle.xml - Go：.golangci.yml - Lua：.luacheckrc

cp my_checks.xml data/projects/my-java-project/checkstyle.xml

4. 重启生效：通常无需重启，系统会在下一次调用时读取新的配置。

🔧 技术细节

添加新的 Linter/语言支持

本项目采用模块化设计，扩展非常简单：

1. 实现接口：在 internal/linter 包中实现 Linter 接口：

type Linter interface {
    Lint(ctx LintContext) ([]LintResult, error)
    Fix(ctx LintContext) (string, error)
    Name() string
}

2. 注册工具：在 cmd/server/main.go 中，将新实现的 Linter 注册到 Manager：

linterMgr := linter.NewManager(
    // ... existing linters
    linter.WithLinter(NewPythonLinter()), // 添加你的 Linter
)

3. 配置系统检查：在 cmd/server/main.go 的 system.NewManager 中添加对应的工具检查项：

systemMgr := system.NewManager(
    // ...
    system.WithTool("pylint", []string{"--version"}),
)

📄 许可证

MIT License