mcp-http-proxy

mcp-http-proxy

适用于使用 stdio 的模型上下文协议（MCP）应用的 HTTP/SSE 代理服务。支持通过 HTTP 发送原始 JSON-RPC 命令，并在不使用 MCP SDK 的情况下直接通过 stdio 通信。

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 协议访问： 将基于 stdio 的 MCP 服务通过标准 HTTP（GET/POST）和服务器发送事件（SSE）开放出来，使 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 服务作为子进程启动。
   • 使用子 MCP 进程的标准输入（stdin）、标准输出（stdout）和标准错误（stderr）与其通信。
   • 将部分 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： 代理会向 MCP 进程的 stdin 发送经过验证的 JSON-RPC 命令字符串。
• MCP -> 代理：
  • MCP 进程会将 JSON-RPC 响应字符串（结果、错误、协议消息）发送到其 stdout。
  • MCP 进程会将日志消息或致命错误发送到其 stderr。
• 用户交互： 用户不会直接通过代理的 stdio 发送命令。所有交互都通过 HTTP 端点进行。

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

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

• 连接： 客户端通过向 /sse 端点发送 HTTP GET 请求来建立 SSE 连接。代理会保持此连接处于打开状态。
• 推送事件： 当代理从 MCP 进程的 stdout（响应）或 stderr（日志/错误）收到数据时，会根据 SSE 协议（data: <json_string>\n\n）格式化这些数据，并通过打开的连接推送给所有当前已连接的 SSE 客户端。
• 发送命令： 客户端无法通过同一 SSE 连接向代理发送命令。要执行命令，SSE 客户端必须单独发送标准 HTTP 请求（例如，向 /rpc/raw/command 发送 POST 请求，或向 /tool/:toolName 发送 GET 请求）。该命令的结果通常会通过客户端正在监听的 /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。
  • 在 HTTP 响应正文中以 JSON 格式直接返回从 MCP 进程的 stdout 收到的原始 JSON-RPC 响应。这是以编程方式交互的主要端点，适用于自行构造完整 RPC 调用的场景。

• GET /sse

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

• GET /sse-client

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

• GET /help

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

• 调试端点：

  • GET /rpc/command：显示一个 HTML 界面，可通过网页表单手动构造和发送 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：

# Assuming a tool 'worker_get' exists that takes a 'name' parameter
curl "http://localhost:3005/tool/worker_get?name=my-worker"

错误处理

代理会尽量妥善处理错误：

• HTTP 错误： 返回标准 HTTP 状态码（例如，工具或端点未知时返回 404，/tool/:toolName 的参数无效时返回 400）。
• 参数验证： /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 客户端连接。