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 設定で直接構成し、サーバーを手動で起動する必要はありません。

1. Cursor Settings > Features > MCP を開きます。
2. Add New MCP Server をクリックします。
3. Stdio タイプを選択します。
4. Command にコンパイル後の絶対パスを入力します。

   /absolute/path/to/checkstyle-mcp
   

モード B: Remote HTTP モード

リモートアクセスまたはデバッグが必要なシナリオに適しています。

# HTTP サーバーを起動する (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 が "生成 -> チェック -> 修正" の自動化閉ループを構築するようにガイドします。

💻 使用例

基本的な使用法

環境準備

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

プロジェクトのコンパイル

git clone https://github.com/yourusername/checkstyle_mcp.git
cd checkstyle_mcp
go build -o checkstyle-mcp cmd/server/*.go

Stdio モードでの使用 (Cursor 推奨)

# Cursor の設定での操作手順
1. 「Cursor Settings」>「Features」>「MCP」を開く
2. 「Add New MCP Server」をクリック
3. 「Stdio」タイプを選択
4. Command にコンパイル後の絶対パスを入力
   /absolute/path/to/checkstyle-mcp

Remote HTTP モードでの使用

./checkstyle-mcp -mode http -mcp-port 3000 -web-port 8080

高度な使用法

新しい Linter/言語サポートの追加

// 1. インターフェースの実装
type Linter interface {
    Lint(ctx LintContext) ([]LintResult, error)
    Fix(ctx LintContext) (string, error)
    Name() string
}

// 2. ツールの登録
linterMgr := linter.NewManager(
    // ... 既存の Linter
    linter.WithLinter(NewPythonLinter()), // 新しい Linter を追加
)

// 3. システムチェックの設定
systemMgr := system.NewManager(
    // ...
    system.WithTool("pylint", []string{"--version"}),
)

📚 ドキュメント

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(
       // ... 既存の Linter
       linter.WithLinter(NewPythonLinter()), // 新しい Linter を追加
   )
   

3. システムチェックを設定します：cmd/server/main.go の system.NewManager で、対応するツールチェック項目を追加します。

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

📄 ライセンス

MIT License