Checkstyle

Go Version MCP Protocol License

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

---

✨ 核心特性

• 🛡️ 多语言代码检查与修复
  • 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 建立 "生成 -> 检查 -> 修复" 的自动化闭环。

---

🚀 快速开始 (Quick Start)

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 模式

适用于需要远程访问或调试场景。

# 启动 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"}),
   )
   

---

📄 License

MIT License

checkstyle_mcp