AI导哈

WebSocket MCP服务器

一个基于WebSocket的MCP（Model Context Protocol）服务器，允许通过编程方式控制Aider，支持多租户隔离和实时通信。

  • by larock22
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 larock22/aider-mcp

使用说明

MCP WebSocket服务器助手

快速开始

这是一个 真实MCP（模型上下文协议）服务器 它允许您通过WebSocket以编程方式控制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（模型上下文协议）包装器，通过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包装器

    • 带有问候/欢迎握手的自定义协议
    • 将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
  • 多租户隔离：每个客户一个助手儿童流程
  • 自动完成检测：等待助手完成任务
  • 独立工作区：每个会话都有自己的工作区目录
  • 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中可用
  • 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桌面配置：

{
  "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”或“连接调用失败”

    • 服务器未运行。从以下内容开始 npm run mcp
    • 端口错误。请检查 .env 文件（MCP默认值：8080，自定义默认值：7011）

  2. “未找到助手”

    # Install Aider
pip install aider-chat

# Verify installation
which aider

  3. “无API密钥”或助手错误

    • 将您的OpenAI API密钥添加到 .env:
    OPENAI_API_KEY=sk-proj-...

  4. 服务器返回太快/响应不完整

    • 在MCP服务器中修复了等待Aider完成（3秒静音检测）的问题

  5. “工具执行超时”

    • 复杂任务正常
    • 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进程
  • 工作区清理是手动的（根据需要删除旧目录）

许可证

麻省理工学院

相关 MCP