Quack MCP Server

Quack MCP サーバー

Quack は、Python コードのコード分析とテストを自動化する MCP サーバーとして構築された継続的インテグレーションサーバーです。Python コードのリンティングと静的型分析を行うツールを提供します。

機能

• リンティング：pylint を使用して、Python コードのスタイル、フォーマット、コード品質に関する問題を分析します。
• 静的解析：mypy を使用して静的型チェックを実行し、型エラーを特定します。
• 非同期処理：ジョブは非同期で処理されるため、複数のコード送信を同時に分析できます。
• ジョブ管理：送信したジョブの結果を追跡、取得できます。

インストール

1. リポジトリをクローンします：

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

2. 依存関係をインストールします：

pip install -r requirements.txt

Quack サーバーには、以下の依存関係が必要です：

mcp[cli]
pylint
mypy
pytest
pytest-asyncio

使用方法

サーバーの起動

stdio トランスポート（デフォルト）で Quack サーバーを起動するには：

python3 quack.py

デバッグログを有効にするには：

python3 quack.py --debug

HTTP 通信に SSE（Server-Sent Events）トランスポートを使用してサーバーを起動するには：

python3 quack.py --sse --host=0.0.0.0 --port=8000

または、付属のシェルスクリプトを使用できます：

# For stdio transport (default)
./run_quack.sh

# For SSE transport
./run_quack.sh --sse --host=0.0.0.0 --port=8000

Docker コンテナ

Quack サーバーは Docker コンテナで実行できます。この場合、SSE トランスポートが自動的に使用されます：

# Build the Docker image
docker build -t quack-mcp-server .

# Run the container, exposing port 8000
docker run -p 8000:8000 quack-mcp-server

Docker コンテナで実行すると、サーバーはポート 8000 で SSE モードとして自動的に起動します。

MCP ツールの使用

Quack は以下の MCP ツールを公開します：

1. submit_code：リンティングと静的解析の両方を行うコードを送信します。
2. submit_code_for_linting：リンティングのみを行うコードを送信します。
3. submit_code_for_static_analysis：静的解析のみを行うコードを送信します。
4. get_job_results：送信したジョブの結果を取得します。
5. list_jobs：すべてのジョブとそのステータスを一覧表示します。

テストアーキテクチャ

Quack には、異なる 2 つのテスト概念があります：

1. Quack 自体のテスト：tests/ ディレクトリのテストでは、Quack サーバー、ジョブマネージャー、プロセッサが正しく動作することを確認します。新しいプロセッサを追加するときは、そのプロセッサが正しく動作することを確認するテストをここに追加してください。

2. Quack によるテスト：Quack が送信されたコードに対して実行する分析です。リンティングプロセッサと静的解析プロセッサは、Python コードの問題を分析します。新しいプロセッサも、個別に送信されたコードに対して同様の分析を行います。

ディレクトリ構成

tests/
  ├── server/          # Tests OF the server functionality
  │   ├── test_server_direct.py    # Direct testing of job manager
  │   ├── test_server_auto.py      # Auto-starts and stops the server
  │   └── test_server_client.py    # Tests the MCP client interface
  ├── processors/      # Tests OF the processors
  │   ├── test_lint_processor.py        # Tests for lint processor
  │   └── test_static_analysis_processor.py  # Tests for static analysis
  └── examples/        # Example submissions for testing BY the server
      └── example_code.py          # Contains intentional issues for testing

新しいプロセッサ（例：テストカバレッジプロセッサ）を実装するときは：

1. quack/processors/ にプロセッサを作成します
2. tests/processors/ にプロセッサのテストを追加します
3. プロセッサが分析する内容のテストには、tests/examples/ のコードを使用します

テストの実行

リポジトリには、tests ディレクトリに包括的なテストスイートが含まれています。すべてのテストは pytest を使用して管理されます。

1. すべてのテストを実行します：

python -m pytest tests/ --asyncio-mode=auto

2. 特定のテストファイルを実行します：

python -m pytest tests/server/test_server_direct.py -v --asyncio-mode=auto

3. 特定のプロセッサのテストを実行します：

python -m pytest tests/processors/test_lint_processor.py -v

4. 詳細な出力を表示し、テストの進行状況を確認しながらテストを実行します：

python -m pytest tests/ -v --asyncio-mode=auto

5. 最初の失敗で停止してテストを実行します：

python -m pytest tests/ -x --asyncio-mode=auto

サーバーの自動管理

多くのテストでは必要に応じて Quack サーバーが自動的に起動、停止するため、テスト中にサーバープロセスを手動で管理する必要はありません。これは conftest.py ファイルの pytest フィクスチャによって処理されます。

tests/server/test_server_auto.py のサーバーテストでは、テスト用にサーバーを自動的に起動、停止する方法を示しています。これらのテストでは、以下を確認します：

1. サーバーが正しく起動する
2. サーバーがジョブを処理できる
3. サーバーが正しくシャットダウンする

Cline で Quack をセットアップする

Quack を Cline と統合すると、Cline インターフェースから直接コード分析機能を利用できます。

設定手順

1. Cline の MCP 設定を構成します

   Quack サーバーは、以下の場所にある Cline の MCP 設定ファイルで構成できます：

   ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
   

   ローカルの Stdio モード（デフォルト）の場合

   {
     "mcpServers": {
       "quack": {
         "command": "python3",
         "args": ["/path/to/your/quack.py", "--debug"],
         "env": {},
         "disabled": false,
         "autoApprove": []
       }
     }
   }
   

   SSE を使用する Docker コンテナの場合

   サーバーを Docker コンテナで実行する場合は、HTTP/SSE 経由で接続するよう Cline を構成します：

   {
     "mcpServers": {
       "quack": {
         "url": "http://localhost:8000/sse",
         "disabled": false,
         "autoApprove": []
       }
     }
   }
   

   注：Docker コンテナを別のポートにマッピングした場合は、localhost:8000 を適切なホストとポートに置き換えてください。

Cline で Quack を使う

設定が完了すると、Cline を使って Quack サーバーで Python コードを分析できます。プロンプトの例を以下に示します。

• リントの問題についてコードを分析する：

  Analyze this Python code for linting issues:
  [paste your code here]
  

• コードに型エラーがないか確認する：

  Check this Python code for type errors:
  [paste your code here]
  

• 包括的なフィードバックを取得する：

  What's wrong with this Python function?
  [paste your function here]
  

テスト用のサンプルコード

意図的に問題を含めた以下のサンプルコードを使って、Quack サーバーをテストできます。

# Linting issues
unused_var = 42  # Unused variable
x = 10  # Single-letter variable name

# Type issues
def add(a: int, b: int) -> int:
    return a + b

# Function with both linting and type issues
def calculate_average(numbers):  # Missing type annotations
    total = 0
    for num in numbers:
        total += num
    unused_result = total * 2  # Unused variable
    return total / len(numbers)

# Call with wrong type
result = add("5", 10)  # Type error: str + int

仕組み

1. Cline に Python コードの分析を依頼すると、Cline は Quack MCP サーバーを使用します
2. Quack サーバーは、リントツールと静的解析ツールを使ってコードを処理します
3. 結果が Cline に返され、読みやすい形式で表示されます

トラブルシューティング

Cline が Quack サーバーを使用していないように見える場合は、次の点を確認してください。

1. MCP 設定ファイルで Quack サーバーが正しく設定されていることを確認します
2. quack.py ファイルへのパスが正しいことを確認します（stdio モードの場合）
3. URL が正しく、サーバーが稼働していることを確認します（SSE モードの場合）
4. すべての依存関係がインストールされていることを確認します
5. VSCode を再起動して、MCP 設定を再読み込みします

Docker 固有の問題

Docker で実行する場合：

1. ポートマッピング：コンテナのポート 8000 がホストポートに正しくマッピングされていることを確認します。

   docker run -p 8000:8000 quack-mcp-server
   

2. ネットワークアクセス：複雑なネットワーク環境で Docker を実行している場合は、ホストからコンテナのポートにアクセスできることを確認します。

3. コンテナログ：起動時の問題がないか、コンテナのログを確認します。

   docker logs <container_id>
   

4. 接続のテスト：SSE エンドポイントにアクセスできるかテストできます。

   curl http://localhost:8000
   

   ルートエンドポイントがないため 404 レスポンスが返されますが、これによりサーバーが稼働していることを確認できます。

アーキテクチャ

Quack は Model Context Protocol（MCP）を使用して構築されており、次のコンポーネントで構成されています。

• サーバー：クライアント接続とツールの呼び出しを処理するメインの MCP サーバーです。
• ジョブマネージャー：ジョブの送信、処理、結果の取得など、ジョブのライフサイクルを管理します。
• プロセッサー：コード分析を実行する専用コンポーネントです。
  • リントプロセッサー：pylint を使って、コードのスタイルと品質を分析します。
  • 静的解析プロセッサー：mypy を使って静的型チェックを実行します。

開発

新しいプロセッサーの追加

新しいプロセッサーを追加するには：

1. quack/processors ディレクトリに新しいプロセッサークラスを作成します。
2. 分析を実行する process メソッドを実装します。
3. サーバーにプロセッサーを登録します。
4. tests/processors/ にプロセッサーのテストを追加します。

例：テストカバレッジプロセッサーの追加

1. プロセッサーの実装を記述した quack/processors/coverage.py を作成します
2. quack/server.py でプロセッサーをサーバーに追加します
3. tests/processors/test_coverage_processor.py にテストを作成します
4. tests/examples/ のサンプルコードを使ってプロセッサーをテストします

デバッグ

--debug フラグを付けてサーバーを実行すると、詳細なログを有効にできます。

python3 quack.py --debug

ログはコンソールと logs/quack.log の両方に書き込まれます。