MCP代理服务器

Name: MCP代理服务器
Author: ptbsare

作者：ptbsare176 星标更新：2025-07-27

安装使用来源：spider==github.com

项目介绍

MCP 代理服务器

简体中文

✨ 主要特性亮点

🌐 Web UI 管理: 通过直观的 Web 界面轻松管理所有连接的 MCP 服务器（可选，需要启用）。
🔧 细粒度工具控制: 通过 Web UI 启用或禁用单个工具，并覆盖名称/描述。
🛡️ 灵活的端点认证: 使用灵活的认证选项保护基于 HTTP 的端点（如 /sse, /mcp），例如 Authorization: Bearer <token> 或 X-API-Key: <key>。
🔄 强大的会话处理与并发支持:
- 改进了客户端重新连接的 SSE 会话处理（依赖于服务器发送的 endpoint 事件），并支持并发连接。
- 流式 HTTP 端点（/mcp）也支持客户端的并发交互。
🚀 多用途 MCP 操作（服务器和代理）:
- 作为代理: 连接到并聚合多种类型的后端 MCP 服务器（Stdio, SSE, 流式 HTTP）。
- 作为服务器: 通过自己的流式 HTTP（/mcp）和 SSE（/sse）端点暴露这些聚合的能力。也可以以纯 Stdio 模式运行。
✨ 实时安装输出: 在 Web UI 中直接监控 Stdio 服务器的安装进度（stdout/stderr）。
✨ Web 终端: 在 Admin UI 中访问命令行终端，进行直接的服务器交互（可选，由于安全风险，请谨慎使用）。

此服务器充当模型上下文协议（MCP）资源服务器的中心枢纽。它可以：

连接到并管理多个后端 MCP 服务器（Stdio, SSE 和流式 HTTP 类型）。
通过单一统一的 SSE 接口、流式 HTTP 接口，或者作为一个单独的 Stdio 基础的 MCP 服务器来暴露它们的组合能力。
处理请求到适当后端服务器的路由。
如果需要的话，聚合响应（尽管主要作为代理）。
支持多个同时的 SSE 客户端连接，带有可选的 API 密钥认证。

功能

通过代理管理资源和工具

发现并连接到在 config/mcp_server.json 中定义的多个 MCP 资源服务器。
聚合来自所有已连接的活动服务器的工具和资源。
将工具调用和资源访问请求路由到正确的后端服务器。
维护一致的 URI 方案。

✨ 可选的 Web 管理界面 (`ENABLE_ADMIN_UI=true`)

提供一个基于浏览器的界面来管理代理服务器配置和连接的工具。功能包括：

服务器配置: 查看、添加、编辑和删除服务器条目（mcp_server.json）。支持 Stdio, SSE 和 HTTP 服务器类型及其相关选项（类型、命令、参数、环境变量、URL、API 密钥、Bearer Token、安装配置）。
工具配置: 查看从活动后端服务器发现的所有工具。启用或禁用特定工具。覆盖每个工具的显示名称和描述（tool_config.json）。
实时重载: 通过触发配置重载来应用服务器和工具配置更改，而无需重启整个代理服务器进程。
Stdio 服务器安装: 对于 Stdio 服务器，可以在配置中定义安装命令。Admin UI 允许您：
- 触发执行这些安装命令。
- 实时监控安装进度，将实时 stdout 和 stderr 输出直接流式传输到 UI。
Web 终端: 访问集成的基于 Web 的终端，提供对代理服务器运行环境的 shell 访问。
- 安全警告: 此功能授予重大访问权限，应谨慎使用，尤其是在管理员界面公开的情况下。

配置

配置主要通过环境变量和位于 ./config 目录中的 JSON 文件完成。

1. 服务器连接 (`config/mcp_server.json`)

此文件定义了代理应连接的后端 MCP 服务器。

示例 config/mcp_server.json:

{
  "mcpServers": {
    "unique-server-key1": {
      "type": "stdio",
      "name": "我的 Stdio 服务器",
      "active": true,
      "command": "/path/to/server/executable",
      "args": ["--port", "1234"],
      "env": {
        "API_KEY": "server_specific_key"
      },
      "installDirectory": "/custom_install_path/unique-server-key1",
      "installCommands": [
        "git clone https://github.com/some/repo unique-server-key1",
        "cd unique-server-key1 && npm install && npm run build"
      ]
    },
    "another-sse-server": {
      "type": "sse",
      "name": "我的 SSE 服务器",
      "active": true,
      "url": "http://localhost:8080/sse",
      "apiKey": "sse_server_api_key"
    },
    "http-mcp-server": {
      "type": "http",
      "name": "我的流式 HTTP 服务器",
      "active": true,
      "url": "http://localhost:8081/mcp",
      "bearerToken": "some_secure_token_for_http_server"
    },
    "stdio-default-install": {
        "type": "stdio",
        "name": "具有默认安装路径的 Stdio 服务器",
        "active": true,
        "command": "my_other_server",
        "installCommands": ["echo '正在安装到默认位置...'"]
    }
  }
}

字段：

mcpServers: (必需) 每个键是一个后端服务器的唯一标识符的对象。
name: (可选) 服务器的用户友好显示名称（用于 Admin UI）。
active: (可选，默认值：true) 设置为 false 以防止代理连接到该服务器。
type: (必需) 指定传输类型。必须是 "stdio", "sse" 或 "http"。
command: (如果 type 是 "stdio" 则必需) 执行服务器进程的命令。
args: (如果 type 是 "stdio" 则可选) 传递给命令的字符串参数数组。
env: (如果 type 是 "stdio" 则可选) 服务器进程的环境变量对象（KEY: "value"）。这些与代理服务器的环境合并。
url: (如果 type 是 "sse" 或 "http" 则必需) 后端服务器端点的完整 URL（例如，SSE 端点对于 "sse"，MCP 端点对于 "http"）。
apiKey: (如果 type 是 "sse" 或 "http" 则可选) 当代理连接到 这个特定的后端 服务器时发送的 API 密钥。
bearerToken: (如果 type 是 "sse" 或 "http" 则可选) 当连接到 这个特定的后端 服务器时发送的令牌。如果同时提供了 apiKey 和 bearerToken，则通常 bearerToken 对该特定后端连接优先。
installDirectory: (如果 type 是 "stdio" 则可选) 服务器本身应安装的绝对路径（例如，/opt/my-server-files）。由 Admin UI 的安装功能使用。
- 如果在 mcp_server.json 中提供，则使用此确切路径。
- 如果省略，则有效目录取决于 TOOLS_FOLDER 环境变量（参见环境变量部分）。
  - 如果设置了 TOOLS_FOLDER 并且不为空，则服务器将安装在该文件夹内的以服务器键命名的子目录中（例如，${TOOLS_FOLDER}/<server_key>）。
  - 如果 TOOLS_FOLDER 也为空或未设置，则默认为代理服务器工作目录内的 tools 子目录（例如，./tools/<server_key>）。
- 确保目标安装路径的父目录（例如，TOOLS_FOLDER 或 ./tools）对运行代理服务器的用户可写。
installCommands: (如果类型为 Stdio 则可选) 如果目标服务器目录（源自 installDirectory 或默认值）不存在，则由 Admin UI 的安装功能按顺序执行的 shell 命令数组。命令从目标服务器安装目录的 父目录 执行（例如，如果 installDirectory 解析为 /opt/tools/my-server，则命令在 /opt/tools/ 中执行）。由于安全风险，请谨慎使用。

2. 工具配置 (`config/tool_config.json`)

此文件允许覆盖从后端服务器发现的工具属性。主要通过 Admin UI 管理，但可以手动编辑。

示例 config/tool_config.json:

{
  "tools": {
    "unique-server-key1__tool-name-from-server": {
      "enabled": true,
      "displayName": "我的自定义工具名称",
      "description": "更友好的用户描述。"
    },
    "another-sse-server__another-tool": {
      "enabled": false
    }
  }
}

键的格式为 <server_key><separator><original_tool_name>，其中 <separator> 是 SERVER_TOOLNAME_SEPERATOR 环境变量的值（默认为 __）。
enabled: (可选，默认值：true) 设置为 false 以隐藏此工具，使其不被连接到代理的客户端看到。
displayName: (可选) 覆盖客户端 UI 中的工具名称。
description: (可选) 覆盖工具的描述。

3. 环境变量

PORT: 代理服务器的基于 HTTP 的端点（/sse, /mcp 和如果启用的 Admin UI）的端口。默认值：3663。注意: 这仅在启动 HTTP 服务器的模式下使用（例如，通过 npm run dev:sse 或 Docker 容器）。npm run dev 脚本以 Stdio 模式运行。
```
export PORT=8080
```
ALLOWED_KEYS: (可选) 逗号分隔的 API 密钥列表，用于保护代理的基于 HTTP 的端点（/sse, /mcp）。如果既没有设置 ALLOWED_KEYS 也没有设置 ALLOWED_TOKENS，则这些端点的认证将被禁用。客户端必须通过 X-Api-Key 头或 ?key= 查询参数提供密钥。
```
export ALLOWED_KEYS="client_key1,client_key2"
```
ALLOWED_TOKENS: (可选) 逗号分隔的 Bearer Tokens 列表，用于保护代理的基于 HTTP 的端点（/sse, /mcp）。如果既没有设置 ALLOWED_KEYS 也没有设置 ALLOWED_TOKENS，则认证将被禁用。客户端必须通过 Authorization: Bearer <token> 头提供令牌。如果同时配置了 ALLOWED_KEYS 和 ALLOWED_TOKENS，则首先尝试 Bearer Token 认证。
```
export MCP_PROXY_SSE_ALLOWED_TOKENS="your_bearer_token_1,your_bearer_token_2"
```
ENABLE_ADMIN_UI: (可选) 设置为 true 以启用 Web 管理界面（仅适用于 SSE 模式）。默认值：false。
```
export ENABLE_ADMIN_UI=true
```
ADMIN_USERNAME: (如果启用了 Admin UI 则必需) Admin UI 登录的用户名。默认值：admin。
ADMIN_PASSWORD: (如果启用了 Admin UI 则必需) Admin UI 登录的密码。默认值：password（请更改！）。
```
export ADMIN_USERNAME=myadmin
export ADMIN_PASSWORD=aVerySecurePassword123!
```
SESSION_SECRET: (可选，建议启用 Admin UI 时设置) 用于签名会话 cookie 的秘密。如果没有设置，则使用默认的、不太安全的秘密，并发出警告。首次运行时，如果没有通过环境变量提供，则会自动生成并保存到 config/.session_secret。
```
# 建议：生成一个强秘密（例如，openssl rand -hex 32）
export SESSION_SECRET='your_very_strong_random_secret_here'
```
TOOLS_FOLDER: (可选) 指定通过 Admin UI 初始化的 Stdio 服务器安装的基本目录，当 installDirectory 在 mcp_server.json 中未明确设置时使用。
- 如果设置（例如，/custom/tools_path），则没有特定 installDirectory 的服务器的安装将针对该文件夹内的以服务器键命名的子目录（例如，${TOOLS_FOLDER}/<server_key>）。
- 如果 TOOLS_FOLDER 未设置或为空，则此类安装将默认为代理服务器工作目录内的 tools 子目录（例如，./tools/<server_key>）。
- Dockerfile 默认将其设置为 /tools。
```
export TOOLS_FOLDER=/srv/mcp_tools
```
SERVER_TOOLNAME_SEPERATOR: (可选) 定义用于组合服务器名称和工具名称以生成工具的唯一键的分隔符（例如，server-key__tool-name）。此键在内部和 tool_config.json 文件中使用。
- 默认值：__。
- 必须至少包含两个字符，并且只能包含字母（a-z, A-Z）、数字（0-9）、连字符（-）和下划线（_）。
- 如果提供的值无效，则将使用默认值（__），并且会记录警告。
```
export SERVER_TOOLNAME_SEPERATOR="___" # 示例：使用三下划线
```
LOGGING: (可选) 控制服务器输出的日志级别。
- 可能的值（大小写不敏感）：error, warn, info, debug。
- 指定级别的日志以及所有更高级别的日志将被显示。
- 默认值：info。
```
export LOGGING="debug"
```
RETRY_SSE_TOOL_CALL: (可选) 控制是否启用 SSE 工具调用的重试。设置为 "true" 启用，设置为 "false" 禁用。默认值：true。参见“增强可靠性功能”部分了解详情。
```
export RETRY_SSE_TOOL_CALL="true"
```
SSE_TOOL_CALL_MAX_RETRIES: (可选) SSE 工具调用的最大重试次数（初始失败后）。默认值：2。参见“增强可靠性功能”部分了解详情。
```
export SSE_TOOL_CALL_MAX_RETRIES="2"
```
SSE_TOOL_CALL_RETRY_DELAY_BASE_MS: (可选) SSE 工具调用重试的基础延迟（毫秒），用于指数退避。默认值：300。参见“增强可靠性功能”部分了解详情。
```
export SSE_TOOL_CALL_RETRY_DELAY_BASE_MS="300"
```
RETRY_HTTP_TOOL_CALL: (可选) 控制是否在 HTTP 工具调用连接错误时重试。设置为 "true" 启用，设置为 "false" 禁用。默认值：true。参见“增强可靠性功能”部分了解详情。
```
export RETRY_HTTP_TOOL_CALL="true"
```
HTTP_TOOL_CALL_MAX_RETRIES: (可选) HTTP 工具调用的最大重试次数（初始失败后）。默认值：2。参见“增强可靠性功能”部分了解详情。
```
export HTTP_TOOL_CALL_MAX_RETRIES="3"
```
HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS: (可选) HTTP 工具调用重试的基础延迟（毫秒），用于指数退避。默认值：300。参见“增强可靠性功能”部分了解详情。
```
export HTTP_TOOL_CALL_RETRY_DELAY_BASE_MS="500"
```
RETRY_STDIO_TOOL_CALL: (可选) 控制是否在 Stdio 工具调用连接错误时重试（尝试重启进程）。设置为 "true" 启用，设置为 "false" 禁用。默认值：true。参见“增强可靠性功能”部分了解详情。
```
export RETRY_STDIO_TOOL_CALL="true"
```
STDIO_TOOL_CALL_MAX_RETRIES: (可选) Stdio 工具调用的最大重试次数（初始失败后）。默认值：2。参见“增强可靠性功能”部分了解详情。
```
export STDIO_TOOL_CALL_MAX_RETRIES="5"
```
STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS: (可选) Stdio 工具调用重试的基础延迟（毫秒），用于指数退避。默认值：30/0。参见“增强可靠性功能”部分了解详情。
```
export STDIO_TOOL_CALL_RETRY_DELAY_BASE_MS="1000"
```

增强可靠性功能

MCP 代理服务器包括提高其弹性和与后端 MCP 服务交互可靠性的功能，确保操作更加顺畅和工具执行更加一致。

1. 错误传播

代理服务器确保从后端 MCP 服务产生的错误能够一致地传播到请求客户端。这些错误被格式化为标准的 JSON-RPC 错误响应，使客户端更容易统一处理它们。

2. SSE 工具调用重试

当对基于 SSE 的后端服务器进行 tools/call 操作时，如果底层连接丢失或遇到错误（包括超时），代理服务器将实现重试机制。

重试机制: