mcp2websocket

一个桥接应用程序，使MCP标准I/O客户端能够通过翻译标准I/O和WebSocket协议连接到基于WebSocket的MCP服务器。

概述

此桥接充当协议转换器：

graph LR
    A[MCP 客户端] <-->|stdio/JSON-RPC| B[桥接]
    B <-->|WebSocket/JSON-RPC| C[MCP 服务器]
    
    style A fill:#e1bee7,stroke:#4a148c,stroke-width:2px,color:#000
    style B fill:#c5cae9,stroke:#1a237e,stroke-width:2px,color:#000
    style C fill:#c8e6c9,stroke:#1b5e20,stroke-width:2px,color:#000

• 输入：通过标准I/O从MCP客户端接收MCP消息
• 输出：通过WebSocket转发消息到MCP服务器

安装

npm install mcp2websocket

或者用于本地开发：

git clone https://github.com/williamkapke/mcp2websocket.git
cd mcp2websocket
npm install

使用方法

命令行

# 连接到WebSocket服务器
mcp2websocket ws://example.com:8080/mcp

# 带认证令牌
mcp2websocket wss://secure.example.com/mcp --token your-auth-token

# 启用调试日志
mcp2websocket --debug

配置示例

Claude Desktop

添加到您的claude_desktop_config.json：

{
  "mcpServers": {
    "websocket-server": {
      "command": "npx",
      "args": [
        "mcp2websocket",
        "ws://localhost:8765/mcp"
      ]
    }
  }
}

或使用环境变量：

{
  "mcpServers": {
    "websocket-server": {
      "command": "npx",
      "args": ["mcp2websocket"],
      "env": {
        "AUTH_TOKEN": "optional-token",
        "DEBUG": "true"
      }
    }
  }
}

功能

graph TD
    A[桥接功能]
    A --> B[自动重连]
    A --> C[消息队列]
    A --> D[心跳]
    A --> E[调试日志]
    A --> F[优雅关闭]
    
    B --> B1[指数退避]
    B --> B2[可配置间隔]
    
    C --> C1[断开时排队]
    C --> C2[重新连接时刷新]
    
    D --> D1[周期性ping/pong]
    D --> D2[连接健康检查]
    
    E --> E1[stderr输出]
    E --> E2[不干扰stdio]
    
    style A fill:#b3e5fc,stroke:#01579b,stroke-width:3px,color:#000
    style B fill:#ffccbc,stroke:#bf360c,stroke-width:2px,color:#000
    style C fill:#ffe0b2,stroke:#e65100,stroke-width:2px,color:#000
    style D fill:#c5e1a5,stroke:#33691e,stroke-width:2px,color:#000
    style E fill:#f8bbd0,stroke:#880e4f,stroke-width:2px,color:#000
    style F fill:#d1c4e9,stroke:#4527a0,stroke-width:2px,color:#000

• 自动重连：当连接丢失时，使用指数退避进行重连
• 消息队列：在断开连接时排队消息，并在重新连接时发送
• 心跳：通过周期性ping/pong维持连接
• 调试日志：可选的调试输出到stderr（不会干扰stdio协议）
• 优雅关闭：退出时正确关闭连接

选项

参数/选项	简写	描述	默认值
<url>	-	WebSocket服务器URL（必需）	-
--token	-t	认证令牌	none
--debug	-d	启用调试日志	false
--help	-h	显示帮助信息	-

环境变量

• AUTH_TOKEN：服务器的认证令牌
• DEBUG：设置为“true”以启用调试日志

架构

sequenceDiagram
    participant CD as MCP 客户端
    participant B as 桥接
    participant WS as WebSocket 服务器
    
    CD->>B: JSON-RPC 请求（stdin）
    B->>WS: 转发请求（WebSocket）
    WS->>B: JSON-RPC 响应
    B->>CD: 转发响应（stdout）
    
    Note over B: 消息队列
    Note over B: 自动重连
    Note over B: 心跳/Ping

桥接是透明的，不会修改消息——它只是在两种协议之间转发它们，同时处理连接管理。

消息流

flowchart TB
    subgraph "客户端进程"
        CD[MCP 客户端]
    end
    
    subgraph "桥接进程"
        STDIN[stdin处理器]
        QUEUE[消息队列]
        WSC[WebSocket客户端]
        STDOUT[stdout写入器]
    end
    
    subgraph "服务器进程"
        WSS[WebSocket服务器]
    end
    
    CD -->|JSON-RPC| STDIN
    STDIN --> QUEUE
    QUEUE --> WSC
    WSC <-->|WebSocket| WSS
    WSS -->|响应| WSC
    WSC --> STDOUT
    STDOUT -->|JSON-RPC| CD
    
    style CD fill:#e1bee7,stroke:#4a148c,stroke-width:2px,color:#000
    style STDIN fill:#c5cae9,stroke:#1a237e,stroke-width:2px,color:#000
    style QUEUE fill:#fff9c4,stroke:#f57f17,stroke-width:2px,color:#000
    style WSC fill:#c5cae9,stroke:#1a237e,stroke-width:2px,color:#000
    style STDOUT fill:#c5cae9,stroke:#1a237e,stroke-width:2px,color:#000
    style WSS fill:#c8e6c9,stroke:#1b5e20,stroke-width:2px,color:#000

故障排除

1. 连接问题：启用调试模式以查看详细的连接日志
2. 认证错误：验证您的令牌是否正确且服务器接受它
3. 消息错误：检查MCP客户端和WebSocket服务器是否使用兼容的MCP版本

程序化使用

您也可以在自己的Node.js应用程序中导入并使用该桥接：

const MCPWebSocketBridge = require('mcp2websocket');

// 创建桥接实例
const bridge = new MCPWebSocketBridge('ws://localhost:8080/mcp', {
  token: 'optional-auth-token',
  debug: true
});

// 监听事件
bridge.on('connected', () => {
  console.log('已连接到WebSocket服务器');
});

bridge.on('disconnected', () => {
  console.log('与WebSocket服务器断开连接');
});

bridge.on('error', (error) => {
  console.error('桥接错误:', error);
});

// 启动桥接
bridge.start();

// 在需要时优雅地关闭
process.on('SIGINT', () => {
  bridge.shutdown();
});

自定义Stdio流

默认情况下，桥接使用process.stdin和process.stdout。您可以通过扩展类来覆盖这一点：

const { Readable, Writable } = require('stream');
const MCPWebSocketBridge = require('mcp2websocket');

class CustomBridge extends MCPWebSocketBridge {
  constructor(options) {
    super(options);
    
    // 使用自定义流而不是process.stdin/stdout
    this.rl = require('readline').createInterface({
      input: customInputStream,  // 您的自定义Readable流
      output: customOutputStream, // 您的自定义Writable流
      terminal: false
    });
  }
}

const bridge = new CustomBridge('ws://localhost:8080/mcp');
bridge.start();

开发

要在开发模式下使用：

1. 启动您的WebSocket MCP服务器
2. 配置您的MCP客户端以使用此桥接并提供适当的URL
3. 桥接将自动连接并转发消息

许可证

MIT