MCP Server Runner

MCP 服务运行器

注意：此项目目前正在积极开发中，处于 WIP（开发中）状态。功能和 API 可能会发生重大变化。

这是一个用于运行 Model Context Protocol（MCP）服务的 WebSocket 服务实现。此应用可通过 WebSocket 连接访问 MCP 服务，从而便于与 Web 应用及其他支持网络的客户端集成。

开发状态

• 🚧 开发中：此软件正在积极开发中
• ⚠️ API 稳定性：API 和功能可能会随时变更，恕不另行通知
• 🧪 测试：目前正在进行测试和完善
• 📝 文档：文档正在积极更新

概述

MCP 服务运行器充当 WebSocket 客户端与 MCP 服务实现之间的桥梁。它可以：

• 启动 MCP 服务进程
• 管理 WebSocket 连接
• 处理客户端与 MCP 服务之间的双向通信
• 支持平稳关闭和错误处理

功能

• 支持单客户端连接的 WebSocket 服务实现
• 管理 MCP 服务实例的进程
• 客户端与服务端之间的双向消息传递
• 平稳关闭处理
• 全面的错误日志记录
• 跨平台支持（Unix/Windows）

先决条件

• Rust 1.70 或更高版本
• MCP 服务实现的可执行文件

配置

环境变量

可通过环境变量配置此应用：

PROGRAM=        # Path to the MCP server executable (required if no config file)
ARGS=           # Comma-separated list of arguments for the MCP server
HOST=0.0.0.0    # Host address to bind to (default: 0.0.0.0)
PORT=8080       # Port to listen on (default: 8080)
CONFIG_FILE=    # Path to JSON configuration file

其他环境变量将传递给 MCP 服务进程。

JSON 配置

也可以提供 JSON 配置文件：

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/workspace"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here"
      }
    }
  },
  "default_server": "filesystem",
  "host": "0.0.0.0",
  "port": 8080
}

可通过以下两种方式指定配置文件：

1. 作为命令行参数：mcp-server-runner config.json
2. 使用 CONFIG_FILE 环境变量：CONFIG_FILE=config.json mcp-server-runner

JSON 配置允许定义多个服务配置，并选择其中一个作为默认配置。

配置优先级

1. 通过命令行指定的配置文件
2. CONFIG_FILE 环境变量
3. 环境变量（PROGRAM、ARGS 等）
4. 默认值

用法

1. 使用环境变量：

   export PROGRAM=npx
   export ARGS=-y,@modelcontextprotocol/server-github
   export PORT=8080
   export GITHUB_PERSONAL_ACCESS_TOKEN=github_pat_***
   cargo run
   

2. 使用配置文件：

   # Either specify the config file as an argument
   cargo run config.json
   
   # Or use the CONFIG_FILE environment variable
   CONFIG_FILE=config.json cargo run
   

3. 连接到 WebSocket 服务：

   const ws = new WebSocket("ws://localhost:8080");
   

Docker 支持

提供了 Dockerfile 和 docker-compose.yml，支持容器化部署：

docker-compose up --build

开发

构建项目：

cargo build

运行测试：

cargo test

启用调试日志运行：

RUST_LOG=debug cargo run

架构

此应用采用模块化架构：

• main.rs：应用入口和服务设置
• config/：配置加载和管理
• process/：进程管理和 I/O 处理
• websocket/：WebSocket 连接管理
• state.rs：全局状态管理
• shutdown.rs：平稳关闭处理

错误处理

• MCP 服务的标准错误输出会被记录，但不会转发给客户端
• WebSocket 连接错误会得到妥善处理
• 进程错误会连同详细信息一起记录

限制

• 一次仅支持一个客户端连接
• 不支持 WebSocket SSL/TLS（如需安全连接，请使用反向代理）
• 没有内置身份验证机制

贡献

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 推送到该分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

许可证

此项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

更多资源

• Model Context Protocol 规范
• WebSocket 协议（RFC 6455）