Aider MCP WebSocket Server

Aider MCP WebSocket 服务

快速开始

这是一个真正的 MCP（Model Context Protocol）服务，可让你通过 WebSocket 以编程方式控制 Aider。就像把 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、自定义应用等）。

概述

一个可用于生产环境的 MCP（Model Context Protocol）封装，通过 WebSocket 提供 Aider 的功能，让编辑器插件和服务能够以编程方式与 Aider 交互。本项目提供两种服务实现：

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 握手
   • 直接通过 stdio 管道与 Aider 进程通信
   • 基于令牌的身份验证

架构

┌─────────────────┐         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 子进程
• 自动检测完成状态：等待 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+
• 已安装并可通过 PATH 访问的 Aider
• 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 运行 shell 命令

   {
     "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 发送的第一个请求可能需要更长时间（模型加载）
• 后续请求会更快
• 服务会为每个会话维护一个 Aider 进程
• 工作区需要手动清理（按需删除旧目录）

许可证

MIT