mcp2websocket

mcp2websocket

一种桥接应用程序，通过在stdio和WebSocket协议之间进行转换，使MCP stdio客户端能够连接到基于WebSocket的MCP服务器。

概述

此网桥充当协议转换器：

graph LR
    A[MCP Client] |stdio/JSON-RPC| B[Bridge]
    B |WebSocket/JSON-RPC| C[MCP Server]
    
    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

• 输入：通过stdio从MCP客户端接受MCP消息
• 输出：通过WebSocket将消息转发到MCP服务器

安装

npm install mcp2websocket

或者为了当地发展：

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

用法

命令行

# Connect to a WebSocket server
mcp2websocket ws://example.com:8080/mcp

# With authentication token
mcp2websocket wss://secure.example.com/mcp --token your-auth-token

# Enable debug logging
mcp2websocket --debug

配置示例

克劳德桌面

添加到您的 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[Bridge Features]
    A --> B[Automatic Reconnection]
    A --> C[Message Queuing]
    A --> D[Heartbeat]
    A --> E[Debug Logging]
    A --> F[Graceful Shutdown]
    
    B --> B1[Exponential Backoff]
    B --> B2[Configurable Intervals]
    
    C --> C1[Queue during disconnect]
    C --> C2[Flush on reconnect]
    
    D --> D1[Periodic ping/pong]
    D --> D2[Connection health check]
    
    E --> E1[stderr output]
    E --> E2[No stdio interference]
    
    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

• 自动重新连接：当连接丢失时，使用指数回退重新连接
• 消息队列：在断开连接期间排队消息，并在重新连接时发送
• 心跳：与定期的乒乓球保持联系
• 调试日志记录：stderr的可选调试输出（不干扰stdio协议）
• 优雅地关闭：正确关闭出口连接

选项

环境变量

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

建筑

sequenceDiagram
    participant CD as MCP Client
    participant B as Bridge
    participant WS as WebSocket Server
    
    CD->>B: JSON-RPC Request (stdin)
    B->>WS: Forward Request (WebSocket)
    WS->>B: JSON-RPC Response
    B->>CD: Forward Response (stdout)
    
    Note over B: Message Queue
    Note over B: Auto-reconnect
    Note over B: Heartbeat/Ping

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

消息流

flowchart TB
    subgraph "Client Process"
        CD[MCP Client]
    end
    
    subgraph "Bridge Process"
        STDIN[stdin handler]
        QUEUE[Message Queue]
        WSC[WebSocket Client]
        STDOUT[stdout writer]
    end
    
    subgraph "Server Process"
        WSS[WebSocket Server]
    end
    
    CD -->|JSON-RPC| STDIN
    STDIN --> QUEUE
    QUEUE --> WSC
    WSC |WebSocket| WSS
    WSS -->|Response| 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');

// Create bridge instance
const bridge = new MCPWebSocketBridge('ws://localhost:8080/mcp', {
  token: 'optional-auth-token',
  debug: true
});

// Listen to events
bridge.on('connected', () => {
  console.log('Connected to WebSocket server');
});

bridge.on('disconnected', () => {
  console.log('Disconnected from WebSocket server');
});

bridge.on('error', (error) => {
  console.error('Bridge error:', error);
});

// Start the bridge
bridge.start();

// Gracefully shutdown when needed
process.on('SIGINT', () => {
  bridge.shutdown();
});

自定义标准流

默认情况下，网桥使用 process.stdin 和 process.stdout。您可以通过扩展类来覆盖此内容：

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

class CustomBridge extends MCPWebSocketBridge {
  constructor(options) {
    super(options);
    
    // Use custom streams instead of process.stdin/stdout
    this.rl = require('readline').createInterface({
      input: customInputStream,  // Your custom Readable stream
      output: customOutputStream, // Your custom Writable stream
      terminal: false
    });
  }
}

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

发展

在开发模式下使用：

1. 启动WebSocket MCP服务器
2. 配置您的MCP客户端，使其使用具有适当URL的网桥
3. 网桥将自动连接和中继消息

许可证

麻省理工学院