Checkstyle MCP

🚀 Checkstyle MCP Server

Checkstyle MCP Server is a middleware that connects LLMs (Large Language Models) with local code quality tools. It implements the Model Context Protocol (MCP), enabling AI assistants (such as Cursor, Claude Desktop) to directly invoke local Linters and Formatters, thus closing the loop on automatic code checking and fixing.

✨ Features

• 🛡️ Multi-language Code Checking and Fixing
  • Go: Integrates golangci-lint (checking) and gofmt (formatting).
  • Java: Integrates checkstyle (checking) and google-java-format (formatting).
  • Lua: Integrates luacheck (checking) and stylua (formatting).
• 🏗️ Project-level Configuration Isolation
  • Supports configuring independent rule files (such as .golangci.yml, checkstyle.xml, .luacheckrc) for different projects.
  • Provides out-of-the-box default configuration templates.
• 🔌 Dual-mode Access
  • Stdio Mode: Suitable for direct integration with local IDEs (recommended for Cursor).
  • Remote (HTTP/SSE) Mode: Suitable for remote deployment or distributed calls.
• 📊 Web Management Console
  • Visualizes project and configuration management.
  • Environment Self-check: Automatically detects and installs missing system tools (supports macOS/Homebrew).
  • Audit Logs: Records the checking results and fixing operations of each AI call, and supports viewing detailed error reports.
• 🤖 AI Self-healing
  • Provides standardized Prompt templates to guide AI in establishing an automated loop of "generate -> check -> fix".

🚀 Quick Start

1. Environment Preparation

Ensure that Go 1.21+ is installed on your system. This project depends on the following external tools, which can be installed with one click through the Web interface (macOS) or manually:

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

# For other systems, please refer to the official documentation of each tool.

2. Compile the Project

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

# Compile to generate an executable file
go build -o checkstyle-mcp cmd/server/*.go

3. Running Modes

Mode A: Stdio Mode (Recommended for Cursor)

Configure directly in Cursor's MCP settings without manually starting the Server.

1. Open Cursor Settings > Features > MCP.
2. Click Add New MCP Server.
3. Select the Stdio type.
4. Enter the absolute path after compilation in the Command field:

   /absolute/path/to/checkstyle-mcp
   

Mode B: Remote HTTP Mode

Suitable for scenarios requiring remote access or debugging.

# Start the HTTP Server (MCP port 3000, Web management port 8080)
./checkstyle-mcp -mode http -mcp-port 3000 -web-port 8080

• Web Management Interface: http://localhost:8080
• MCP Endpoint: http://localhost:3000/mcp (supports SSE)

💻 Usage Examples

1. Configure Project Rules

1. Start the service and access the Web Management Interface.
2. Click "New Project" to create a project context (e.g., my-backend).
3. On the project details page, you can:
   • View the status of environment tools.
   • Upload custom configuration files (such as checkstyle.xml).
   • Click "Use Default Config" to apply best practice rules.

2. AI Self-healing Loop

To enable AI to fully utilize this tool, send the following System Prompt at the beginning of the conversation:

⚠️ Important Note

You can now access local code quality tools via MCP. When writing code, please strictly follow the following process:

1. Generate code.
2. Immediately call the lint_code tool to check the generated code (using the corresponding projectName and language).
3. If issues are found: Analyze the errors, correct the code, and run lint_code again for verification.
4. Repeat until the check passes or 3 attempts are made.

(You can also click "Integration Guide" in the sidebar of the Web management interface to copy this Prompt)

3. Front-end Development Guide

The Web management interface is built using React + TypeScript + Vite, and the UI component library uses Ant Design.

Technology Stack

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

Development Steps

1. Enter the front-end directory:

   cd ui/web
   

2. Install dependencies:

   npm install
   # or
   yarn install
   

3. Start the development server:

   npm run dev
   # or
   yarn dev
   

   This will start a hot-reloading development server (default port 5173) and configure a proxy to forward API requests to the backend (default localhost:8080).

4. Build the production version:

   npm run build
   # or
   yarn build
   

   The build artifacts will be output to the ui/web/dist directory.

5. Integrate with the backend: After the build is complete, the contents of ui/web/dist will be automatically hosted by the golang backend. Make sure to point to this directory when starting the backend:

   # Compile the backend
   go build -o checkstyle-mcp cmd/server/*.go
   
   # Start the service (specify web-root as the front-end build directory)
   ./checkstyle-mcp -mode http -web-root ./ui/web/dist
   

   ⚠️ Important Note

   If the page does not refresh after modifying the front-end code, try clearing the browser cache or accessing in incognito mode, or start on a different port (e.g., -web-port 8081).

4. Manual Project Management (File System Mode)

If you are unable to use the Web management interface, you can directly manage projects and configurations through the file system.

1. Create a project directory: Create a new folder in the data/projects/ directory, and the folder name will be the projectName.

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

2. Add metadata (optional): Create a meta.json file to specify the project type (if not specified, the system will automatically infer it, but explicit specification is recommended).

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

   Supported types: java, go, lua

3. Add configuration files: Copy your rule files to this directory:

   • Java: checkstyle.xml
   • Go: .golangci.yml
   • Lua: .luacheckrc

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

4. Restart to take effect: Usually, there is no need to restart. The system will read the new configuration on the next call.

🔧 Technical Details

Adding Support for New Linters/Languages

This project uses a modular design, making it very easy to extend:

1. Implement the interface: Implement the Linter interface in the internal/linter package:

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

2. Register the tool: In cmd/server/main.go, register the newly implemented Linter with the Manager:

   linterMgr := linter.NewManager(
       // ... existing linters
       linter.WithLinter(NewPythonLinter()), // Add your Linter
   )
   

3. Configure system checks: Add the corresponding tool check item in system.NewManager of cmd/server/main.go:

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

📄 License

This project is licensed under the MIT License.