mcp-http-proxy

一个使用 stdio 的模型上下文协议 (MCP) 应用程序的 HTTP/SSE 代理服务器。支持通过 HTTP 发送原始 JSON-RPC 命令，并实现直接的 stdio 通信，无需 MCP SDK。

MCP RPC 代理工作进程

概述

这个 Node.js 脚本 (rpc-proxy-worker.js) 充当 HTTP 客户端和底层 MCP（模型上下文协议）服务器进程之间的中间代理服务器。它通过以下方式简化与 MCP 服务器的交互：

1. 管理 MCP 进程： 它生成并管理配置的 MCP 服务器的生命周期，该服务器作为子进程运行。
2. 提供 HTTP 端点： 它公开 HTTP 端点，允许客户端与 MCP 服务器的工具和资源进行交互，而无需直接处理 MCP 协议的 stdio 通信。
3. 提供实时事件： 它提供一个服务器发送事件 (SSE) 端点，供客户端接收来自 MCP 服务器的异步通知和响应。
4. 提供 Web 界面： 它包含一个基本的 Web 仪表板，用于查看可用工具以及用于调试和发送命令的简单界面。

优点

这个 mcp-http-proxy 提供了几个优点：

• 标准 Web 协议访问： 通过标准 HTTP (GET/POST) 和服务器发送事件 (SSE) 公开基于 stdio 的 MCP 服务器，使其可供 Web 应用程序和各种 HTTP 客户端（curl、Python requests、JavaScript fetch 等）访问。
• 解耦和集中化： 充当稳定的中间层，允许多个客户端与单个托管的 MCP 进程实例进行交互，而无需自行处理进程管理。
• 灵活的客户端交互： 支持多种交互方式：
  • 简化的 URL 参数 (/tool/:toolName)： 对于需要简单 GET 请求的客户端来说很容易；代理处理 JSON-RPC 转换。
  • 原始 JSON-RPC (/rpc/raw/command)： 为客户端通过 HTTP POST 构建自己的 JSON-RPC 命令提供完全控制。
• 实时通信： 使服务器能够通过 /sse 端点将异步响应、日志和事件推送到连接的客户端，非常适合长时间运行的任务和响应式 UI。
• 简化的客户端依赖项： 客户端通过标准 HTTP 进行交互，无需安装或使用特定的 MCP SDK 或处理 stdio 通信。
• 内置的内省和调试： 包括基本的 Web 界面（/、/rpc/command、/debug 等），用于工具发现、手动测试和观察原始通信流。
• 直接代理控制： 通过直接在代理中实现 stdio 通信（而不依赖于代理中的 MCP SDK），它可以对代理到 MCP 的交互进行细粒度控制，并最大限度地减少内部依赖性。

工作原理

该系统通过两个主要进程运行：

1. 代理工作进程（此脚本）：

   • 作为 Node.js 进程运行。
   • 启动一个 HTTP 服务器（使用 Express）来监听客户端请求。
   • 根据配置 (MCP_CONFIG) 将实际的 MCP 服务器作为子进程生成。
   • 使用其标准输入 (stdin)、标准输出 (stdout) 和标准错误 (stderr) 与子 MCP 进程通信。
   • 处理将某些 HTTP 请求（如 URL 参数）转换为 MCP 进程的 JSON-RPC 命令。
   • 将通过特定 HTTP 端点接收的原始 JSON-RPC 命令转发到 MCP 进程。
   • 从 MCP 进程的 stdout/stderr 读取响应和事件。
   • 将响应发送回 HTTP 客户端。
   • 将事件和异步响应推送到连接的 SSE 客户端。

2. MCP 服务器（子进程）：

   • 由代理工作进程启动。
   • 监听其 stdin 上的 JSON-RPC 命令。
   • 执行 MCP 操作（如列出/调用工具）。
   • 将 JSON-RPC 响应和协议消息写入其 stdout。
   • 将日志或错误写入其 stderr。

启动服务器

1. 先决条件： 确保已安装 Node.js。
2. 导航： 打开终端并将目录更改为 rpc-proxy-worker.js 所在的目录。
3. 运行： 执行命令：

   node rpc-proxy-worker.js
   

4. 输出： 您应该看到指示服务器正在运行的输出，通常包括：

   Web interface running on http://localhost:3005
   SSE endpoint available at http://localhost:3005/sse
   

   默认情况下，服务器在端口 3005 上监听。

通信机制

1. Stdio（代理 <-> MCP 进程）- 内部

这是代理工作进程脚本与其管理的子 MCP 服务器进程之间的内部通信通道。

• 代理 -> MCP： 代理将经过验证的 JSON-RPC 命令字符串发送到 MCP 进程的 stdin。
• MCP -> 代理：
  • MCP 进程将其 stdout 发送 JSON-RPC 响应字符串（结果、错误、协议消息）。
  • MCP 进程将其 stderr 发送日志消息或致命错误。
• 用户交互： 用户不直接与代理的 stdio 交互来发送命令。所有交互都通过 HTTP 端点进行。

2. 服务器发送事件 (SSE)（代理 -> 客户端）- 外部

这是一个外部的，主要为单向的通信通道，允许代理将事件实时推送到连接的 HTTP 客户端。

• 连接： 客户端通过向 /sse 端点发出 HTTP GET 请求来建立 SSE 连接。 代理保持此连接打开。
• 推送事件： 当代理从 MCP 进程的 stdout（响应）或 stderr（日志/错误）接收到数据时，它会根据 SSE 协议 (data: <json_string>\n\n) 格式化此数据，并将其推送到当前连接的所有 SSE 客户端。
• 发送命令： 客户端无法通过同一 SSE 连接将命令发送回代理。 要执行命令，SSE 客户端必须发出单独的标准 HTTP 请求（例如，POST 到 /rpc/raw/command 或 GET 到 /tool/:toolName）。 然后，该命令的结果通常会通过它正在监听的 /sse 流推送回客户端。

与代理交互（HTTP 端点）

代理公开了几个 HTTP 端点：

• GET /

  • 显示主 HTML 仪表板，列出从子进程发现的可用 MCP 工具。 提供通过 /tool/:toolName 端点执行工具的表单。

• GET /tools

  • 返回一个 JSON 数组，列出 MCP 服务器提供的所有可用工具，包括它们的名称、描述和输入模式。

• GET /tool/:toolName

  • 执行特定工具。
  • 该工具的参数作为 URL 查询参数 提供（例如，/tool/my_tool?param1=valueA&param2=123）。
  • 代理将这些 URL 参数转换为有效的 JSON-RPC tools/call 请求对象，并根据该工具的模式对其进行验证。
  • 通过 stdio 将命令发送到 MCP 进程。
  • 返回一个 HTML 页面，显示发送的 RPC 命令和从 MCP 进程收到的响应。

• POST /rpc/raw/command

  • 执行原始 JSON-RPC 命令。
  • 期望 POST 请求正文中包含完整的 JSON-RPC 2.0 请求对象，并且 Content-Type: application/json。
  • 代理验证传入请求正文的结构是否符合基本 RPC 模式。
  • 它将经过验证的原始命令直接转发到 MCP 进程的 stdin。
  • 将从 MCP 进程的 stdout 收到的原始 JSON-RPC 响应直接作为 JSON 返回到 HTTP 响应正文中。 这是程序化交互的主要端点，您可以在其中自己构建完整的 RPC 调用。

• GET /sse

  • 建立服务器发送事件流。 客户端连接到此处以接收从服务器推送的实时事件（MCP 响应、日志）。

• GET /sse-client

  • 提供一个简单的 HTML 页面，该页面连接到 /sse 端点并显示收到的事件。 用于调试 SSE 流。

• GET /help

  • 显示一个 HTML 页面，提供有关可用工具以及如何使用 /tool/:toolName 端点的文档。

• 调试端点：

  • GET /rpc/command：显示一个 HTML 界面，用于通过 Web 表单手动构建和发送 RPC 命令（内部使用 /rpc/raw/command）。
  • GET /rpc/raw：显示代理和 MCP 进程之间交换的原始消息的 JSON 历史记录。
  • POST /rpc/raw/clear：清除原始消息历史记录。
  • GET /debug：显示更全面的 HTML 调试界面，显示 RPC、进程和 SSE 事件。
  • GET /debug/logs：以 JSON 格式返回当前调试日志。
  • GET /debug/sse：专门用于调试日志事件的 SSE 流。

• （可选）MCP 管理端点： (/mcp/*)

  • 如果使用 mcp-manager.js，则存在诸如 /mcp/install、/mcp/start、/mcp/stop、/mcp/list 之类的端点，用于动态管理不同的 MCP 服务器安装。

发送命令（示例）

使用 POST /rpc/raw/command（推荐用于程序化使用）

在正文中发送完整的 JSON-RPC 请求。

curl (Bash/zsh/WSL):

curl -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' \
  http://localhost:3005/rpc/raw/command

curl (Windows cmd - 注意引号):

curl -X POST -H "Content-Type: application/json" -d "{\"jsonrpc\":\"2.0\",\"method\":\"tools/list\",\"id\":1}" http://localhost:3005/rpc/raw/command

PowerShell:

$rpcBody = @{
    jsonrpc = "2.0"
    method = "tools/call"
    id = 2
    params = @{
        name = "your_tool_name"
        arguments = @{
            param1 = "value1"
            count = 10
        }
    }
} | ConvertTo-Json -Depth 5

Invoke-RestMethod -Uri http://localhost:3005/rpc/raw/command -Method Post -ContentType 'application/json' -Body $rpcBody

使用 GET /tool/:toolName（方便简单的 GET 请求）

在 URL 查询字符串中提供参数。

curl:

# 假设存在一个 'worker_get' 工具，它接受一个 'name' 参数
curl "http://localhost:3005/tool/worker_get?name=my-worker"

错误处理

代理尝试优雅地处理错误：

• HTTP 错误： 返回标准 HTTP 状态代码（例如，404 表示未知的工具/端点，400 表示 /tool/:toolName 上的无效参数）。
• 参数验证： /tool/:toolName 端点在发送命令之前，会根据工具的模式验证查询参数。 错误在 HTML 响应中返回。 /rpc/raw/command 端点执行基本的 JSON-RPC 结构验证。
• MCP 错误： 底层 MCP 进程返回的错误（例如，工具执行失败）从其 stdout（作为 JSON-RPC 错误响应）或 stderr 捕获，并中继回客户端，无论是在直接 HTTP 响应中（对于 /rpc/raw/command），还是在 HTML 页面中（对于 /tool/:toolName），并且可能会通过 SSE 推送。

清理

该脚本为 exit 和 SIGINT (Ctrl+C) 注册处理程序。 退出时，它尝试：

1. 终止子 MCP 进程 (MCPWorker.mcpProcess.kill())。
2. 关闭所有活动的 SSE 客户端连接。