Dragulin Bogdan MCP

MCP stdio到HTTP代理

一个Node.js包，提供代理工具将MCP（模型上下文协议）请求从stdio重定向到HTTP服务器。当您需要将需要stdio通信的客户端（如Codex）连接到仅支持HTTP的MCP服务器时，此工具特别有用。

特性

• ✅ stdio和HTTP之间的双向代理
• ✅ JSON-RPC消息处理
• ✅ 可配置的超时和重试逻辑
• ✅ 用于调试的详细日志记录
• ✅ 错误处理和优雅关机
• ✅ 支持npx的CLI工具

安装

全球安装

npm install -g mcp-stdio-http-proxy

与npx一起使用（推荐）

npx mcp-stdio-http-proxy --url http://localhost:3000/mcp

用法

命令行接口

mcp-stdio-http-proxy --url  [options]

选项

• -u, --url （必需）：MCP服务器的HTTP端点URL
• -t, --timeout ：请求超时（毫秒）（默认值：30000）
• -r, --retries ：重试尝试次数（默认值：3）
• -v, --verbose：启用详细日志记录
• -h, --help：显示帮助信息

例子

基本用法：

npx mcp-stdio-http-proxy --url http://localhost:3000/mcp

使用自定义超时和重试：

npx mcp-stdio-http-proxy --url http://localhost:3000/mcp --timeout 10000 --retries 5

使用详细日志记录：

npx mcp-stdio-http-proxy --url http://localhost:3000/mcp --verbose

程序化使用

import { MCPProxy, ProxyConfig } from 'mcp-stdio-http-proxy';

const config: ProxyConfig = {
  httpEndpoint: 'http://localhost:3000/mcp',
  timeout: 30000,
  retryAttempts: 3,
  verbose: true
};

const proxy = new MCPProxy(config);
await proxy.start();

运作原理

1. 输入：代理在stdin上监听MCP JSON-RPC消息
2. 处理：每条消息都经过解析和验证
3. 转发：将有效消息发送到配置的HTTP端点
4. 回应：HTTP响应被转发回stdout
5. 错误处理：通过正确的JSON-RPC错误响应，可以优雅地处理错误

MCP消息格式

代理处理MCP协议定义的标准JSON-RPC 2.0消息：

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {}
  }
}

集成示例

使用VS Code和Codex

1. 将MCP客户端配置为将此代理用作stdio传输
2. 启动指向HTTP MCP服务器的代理
3. 代理将无缝处理协议转换

作为一种开发工具

使用代理调试MCP通信：

# Start with verbose logging
npx mcp-stdio-http-proxy --url http://localhost:3000/mcp --verbose

# Send test messages via stdin
echo '{"jsonrpc":"2.0","id":"1","method":"ping"}' | npx mcp-stdio-http-proxy --url http://localhost:3000/mcp

错误处理

代理提供了强大的错误处理：

• 解析错误：无效的JSON消息返回正确的JSON-RPC解析错误
• 网络错误：使用指数回退重试HTTP失败
• 超时错误：可配置的超时可防止挂起请求
• 优雅关闭：信号情报/信号处理得当

发展

# Clone the repository
git clone https://github.com/DragulinBogdan/mcp-stdio-http-proxy.git
cd mcp-stdio-http-proxy

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

测试

该项目包括一个全面的测试套件，涵盖：

• 单元测试：MCPProxy类的核心功能
• CLI测试：命令行界面验证和错误处理
• 集成测试：端到端消息流测试
• 边缘案例：JSON格式错误、网络错误、超时、重试逻辑

运行测试

# Run all tests
npm test

# Run tests with coverage report
npm run test:coverage

# Run tests in watch mode during development
npm run test:watch

# Run specific test files
npm test -- --testPathPattern=proxy
npm test -- --testPathPattern=cli

该测试套件使用Jest，并包括对HTTP请求、进程I/O和错误条件的全面模拟。

贡献

欢迎投稿！请随时提交拉取请求。

许可证

麻省理工学院-见 许可证 文件以获取详细信息。