Aider MCP WebSocket Server

Aider MCP WebSocket Server

クイックスタート

これは、WebSocket 経由で Aider をプログラムから制御できる実際の MCP（Model Context Protocol）サーバーです。Aider を API として利用できます。

# 1. Install
npm install
cp .env.example .env
# Add your OPENAI_API_KEY=sk-... to .env

# 2. Run the MCP server (recommended)
npm run mcp

# 3. Test it
python3 test-debug.py

できること：自然言語のコマンドを Aider に送信し、作成・編集されたファイルと完全な応答を受け取れます。各クライアントには分離されたワークスペースが割り当てられます。MCP 対応のクライアント（Claude Desktop、カスタムアプリなど）であれば、どれでも利用できます。

概要

Aider の機能を WebSocket 経由で公開し、エディタープラグインやサービスから Aider をプログラムで操作できる、本番環境対応の MCP（Model Context Protocol）ラッパーです。このプロジェクトでは、2 種類のサーバー実装を提供します。

1. src/mcp-server.ts - 実際の MCP プロトコルサーバー（推奨）

   • 標準の JSON-RPC 2.0 MCP プロトコルを実装します
   • MCP の正規メソッド：initialize、tools/list、tools/call
   • 完了をスマートに検出します（Aider の処理完了を待機します）
   • Claude Desktop などの MCP クライアントに対応します

2. src/index.ts - カスタム WebSocket ラッパー

   • hello/welcome ハンドシェイクを使用するカスタムプロトコル
   • Aider プロセスへの直接的な stdio パイプ
   • トークンベースの認証

アーキテクチャ

┌─────────────────┐         JSON-RPC 2.0        ┌─────────────────┐
│   MCP Client    │ ◄─────────────────────────► │   MCP Server    │
│  (Any MCP app)  │         WebSocket           │  (mcp-server.ts)│
└─────────────────┘                             └────────┬────────┘
                                                         │
                                                         │ spawn()
                                                         ▼
                                                ┌─────────────────┐
                                                │  Aider Process  │
                                                │  (CLI instance) │
                                                └─────────────────┘

機能

• MCP プロトコルの完全サポート：標準の MCP メソッドと JSON-RPC 2.0
• マルチテナントの分離：クライアントごとに Aider の子プロセスを 1 つ起動します
• 自動完了検出：Aider のタスク完了を待機します
• 分離されたワークスペース：セッションごとに専用のワークスペースディレクトリを割り当てます
• OpenAI API 連携：既存の OpenAI API キーを利用できます
• リアルタイム通信：WebSocket ベースの双方向通信
• 柔軟な設定：環境変数と CLI 引数に対応します
• 構造化ログ：Pino による JSON ロギング

インストール

# Clone and install
git clone <repo-url>
cd aider_mcp
npm install

# Configure environment
cp .env.example .env
# Edit .env and add your OpenAI API key:
# OPENAI_API_KEY=sk-...

前提条件

• Node.js 18+
• Aider がインストールされ、PATH から利用できること
• OpenAI API キー

使い方

サーバーの起動

# Run MCP protocol server (recommended)
npm run mcp

# Run custom WebSocket wrapper
npm run dev

# Production build
npm run build && npm start

テスト

# Quick test of MCP server
python3 test-debug.py

# Full test with waiting
python3 test-mcp-wait.py

# JavaScript test client
node test-mcp-client.js

MCP プロトコル通信

利用可能なツール

MCP サーバーは、以下のツールをクライアントに公開します。

1. aider_command - 自然言語のコマンドを実行します

   {
     "name": "aider_command",
     "arguments": {
       "command": "create a REST API with Flask"
     }
   }
   

2. aider_add_file - ファイルを Aider のコンテキストに追加します

   {
     "name": "aider_add_file", 
     "arguments": {
       "filename": "app.py"
     }
   }
   

3. aider_run_command - Aider 経由でシェルコマンドを実行します

   {
     "name": "aider_run_command",
     "arguments": {
       "command": "npm test"
     }
   }
   

接続の流れ

// 1. Connect via WebSocket
const ws = new WebSocket('ws://localhost:8080');

// 2. Initialize MCP session
ws.send(JSON.stringify({
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "protocolVersion": "0.1.0",
    "capabilities": {},
    "clientInfo": {
      "name": "your-client",
      "version": "1.0.0"
    }
  },
  "id": 1
}));

// 3. Call tools after initialization
ws.send(JSON.stringify({
  "jsonrpc": "2.0", 
  "method": "tools/call",
  "params": {
    "name": "aider_command",
    "arguments": {
      "command": "create a Python hello world script"
    }
  },
  "id": 2
}));

設定

環境変数

# Required
OPENAI_API_KEY=sk-...        # Your OpenAI API key

# Optional
PORT=8080                    # WebSocket server port (MCP server default)
PORT=7011                    # WebSocket server port (custom wrapper default)
AIDER_MODEL=gpt-4o-mini     # Default model
WORKSPACES_DIR=./workspaces # Where to create project directories
LOG_LEVEL=info              # Logging verbosity (debug|info|warn|error)
VALID_TOKENS=token1,token2  # Auth tokens for custom wrapper (empty = no auth)

CLI 引数

実行時に設定を上書きします。

# Custom port and workspace
npm run mcp -- --port 9000
npm run dev -- --port 8080 --workspaces ./custom-workspaces

# Override environment variables (custom wrapper only)
npm run dev -- --set AIDER_MODEL=gpt-4 --set LOG_LEVEL=debug

連携例

Claude Desktop アプリ

Claude Desktop の設定に追加します。

{
  "mcpServers": {
    "aider": {
      "command": "node",
      "args": ["/path/to/aider_mcp/dist/mcp-server.js"],
      "env": {
        "OPENAI_API_KEY": "your-key",
        "AIDER_MODEL": "gpt-4o-mini"
      }
    }
  }
}

カスタム MCP クライアント

import { WebSocket } from 'ws';

class AiderMCPClient {
  constructor(url = 'ws://localhost:8080') {
    this.ws = new WebSocket(url);
    this.requestId = 1;
    this.setup();
  }

  async callTool(toolName, args) {
    return this.sendRequest('tools/call', {
      name: toolName,
      arguments: args
    });
  }

  sendRequest(method, params) {
    const id = this.requestId++;
    this.ws.send(JSON.stringify({
      jsonrpc: '2.0',
      method,
      params,
      id
    }));
  }
}

プロジェクト構成

aider_mcp/
├── src/
│   ├── index.ts              # Custom WebSocket wrapper
│   └── mcp-server.ts         # Real MCP protocol server
├── workspaces/               # Auto-generated client workspaces  
├── test-*.py/js              # Various test clients
├── package.json              # Node.js dependencies
├── tsconfig.json             # TypeScript configuration
├── .env                      # Environment configuration
└── README.md                 # This file

スクリプト

• npm run mcp - MCP プロトコルサーバーを起動します（推奨）
• npm run dev - ホットリロード付きでカスタム WebSocket ラッパーを起動します
• npm run build - TypeScript を JavaScript にコンパイルします
• npm start - 本番サーバーを起動します
• npm run lint - ESLint を実行します
• npm run typecheck - TypeScript の型チェックを実行します

トラブルシューティング

よくある問題

1. 「ConnectionRefusedError」または「Connect call failed」

   • サーバーが起動していません。npm run mcp で起動してください
   • ポートが正しくありません。.env ファイルを確認してください（MCP のデフォルト：8080、カスタムのデフォルト：7011）

2. 「Aider not found」

   # Install Aider
   pip install aider-chat
   
   # Verify installation
   which aider
   

3. 「No API key」または Aider のエラー

   • OpenAI API キーを .env に追加してください。

   OPENAI_API_KEY=sk-proj-...
   

4. サーバーがすぐに応答を返す／応答が不完全

   • MCP サーバーで修正済みです。Aider の処理が完了するまで待機します（3 秒間の無通信を検出）

5. 「Tool execution timeout」

   • 複雑なタスクでは通常発生します
   • MCP サーバーは必要なだけ待機します

デバッグモード

# Run with debug logging
LOG_LEVEL=debug npm run mcp

結果の確認

Aider が作成したファイルは、ワークスペースディレクトリに保存されます。

# List all workspaces
ls -la workspaces/

# Check latest workspace  
ls -la workspaces/mcp-*/

# View created files
cat workspaces/mcp-*/your-file.py

セキュリティ上の考慮事項

• 分離されたワークスペース：クライアントセッションごとに専用のディレクトリを割り当てます
• 認証：カスタムラッパーは VALID_TOKENS によるトークンベースの認証に対応しています
• Git の無効化：安全のため、デフォルトで --no-git を指定して実行します
• API キーのセキュリティ：.env ファイルを絶対にコミットしないでください
• 本番環境：追加の分離のため、Docker での実行を検討してください

パフォーマンスに関する注意事項

• Aider への最初のリクエストは時間がかかる場合があります（モデルの読み込みのため）
• 2 回目以降のリクエストはより高速です
• サーバーはセッションごとに 1 つの Aider プロセスを維持します
• ワークスペースのクリーンアップは手動で行います（必要に応じて古いディレクトリを削除してください）

ライセンス

MIT