checkstyle MCP

Checkstyle MCP Server

](https://golang.org)  

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

1. 安装依赖:

    npm install
    # 或
    yarn install

1. 启动开发服务器:

    npm run dev
    # 或
    yarn dev

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

1. 构建生产版本:

    npm run build
    # 或
    yarn build

构建产物将输出到 ui/web/dist 目录。

1. 集成到后端:

构建完成后，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

1. 添加元数据 (可选):

创建一个 meta.json 文件来指定项目类型（如果未指定，系统会自动推断，但建议显式指定）。

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

*支持的类型*: java, go, lua

1. 添加配置文件:

将你的规则文件复制到该目录中： * Java: checkstyle.xml * Go: .golangci.yml * Lua: .luacheckrc

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

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

🛠️ 扩展指南

添加新的 Linter/语言支持

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

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

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

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

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

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

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

📄 License

MIT License

checkstyle_mcp