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