使用说明

MCP网桥服务器

一个基于TypeScript的HTTP网关，用于多个基于STDIO的MCP（模型上下文协议）服务器。该项目通过提供统一的HTTP API和现代基于web的管理界面，解决了VS Code的STDIO MCP服务器执行错误。

✨ 特性

核心功能

HTTP网关：为MCP服务器交互提供RESTful API端点
多运输支持：支持MCP服务器的STDIO、SSE和HTTP传输
多服务器支持：同时连接到多个MCP服务器
动态配置：具有环境变量扩展的热可重新加载JSON配置
工具名称冲突解决：自动检测和基于命名空间的解析

工具管理

自动工具发现：自动发现和注册与可配置通配符模式匹配的工具
工具别名：为来自任何服务器的工具创建自定义别名，以便直接访问
内部工具注册表：直接在网桥内管理工具，以实现高效访问
工具架构验证：自动修复无效的工具架构

服务器管理

服务器重试机制：具有指数回退和手动重试控制的自动重新连接
动态服务器配置：在运行时添加、更新和删除服务器，而无需重新启动
稳健的错误处理：针对所有运输类型的全面错误处理

管理界面

基于Web的管理UI：用于管理服务器和工具的现代基于React的界面
实时仪表盘：实时服务器状态监控和统计
全局设置管理：配置服务器设置，包括HTTP端口、日志记录和安全性
工具发现规则：用于管理自动发现模式的可视化界面

安全与运营

可配置绑定：默认为本地主机(127.0.0.1 或 ::1).启用身份验证后，可以通过以下方式配置网络访问 security.network.listenAddress.
综合录井：调试MCP连接的详细日志记录
类型安全：具有严格类型检查的完整TypeScript实现

🚀 快速开始

Docker（推荐）

# Run with Docker
docker run -d -p 3000:3000 mako10k/mcp-bridge:latest

# Or with docker-compose
curl -o docker-compose.yml https://raw.githubusercontent.com/mako10k/mcp-bridge-server/main/docker-compose.yml
docker-compose up -d

先决条件

Node.js 18+
npm或纱线

安装

# Clone the repository
git clone <repository-url>
cd mcp-bridge

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

# Access the admin interface
# Open http://localhost:3002 in your browser

发展

# Development mode with auto-reload (server)
npm run dev

# Development mode (admin UI)
cd admin-ui
npm install
npm run dev
# Admin UI will be available at http://localhost:5173

🌐 管理界面

MCP网桥服务器包括一个现代化的基于web的管理界面，便于管理：

仪表盘：实时服务器状态和工具统计
服务器管理：添加、编辑、删除和重试MCP服务器
工具管理：查看和管理工具别名和自动发现
全局设置：配置HTTP端口、日志记录级别和其他设置
工具发现设置：使用通配符模式管理自动发现规则

访问管理界面： http://localhost:3002 （默认端口）

⚙️ 配置

创建一个 mcp-config.json 项目根目录中的文件：

{
  "servers": [
    {
      "name": "git",
      "displayName": "Git Server",
      "transport": "stdio",
      "command": "uvx",
      "args": ["mcp-server-git", "--repository", "/path/to/repo"],
      "enabled": true,
      "timeout": 30000,
      "restartOnFailure": true,
      "maxRestarts": 3
    },
    {
      "name": "filesystem",
      "displayName": "File System",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "enabled": true,
      "timeout": 30000,
      "restartOnFailure": true,
      "maxRestarts": 3
    },
    {
      "name": "github",
      "displayName": "GitHub API",
      "transport": "stdio",
      "command": "npm",
      "args": ["exec", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token-here"
      },
      "enabled": true,
      "timeout": 60000,
      "restartOnFailure": true,
      "maxRestarts": 3
    }
  ],
  "toolAliases": [],
  "toolDiscoveryRules": [
    {
      "serverPattern": "git*",
      "toolPattern": "*",
      "exclude": false
    }
  ],
  "global": {
    "logLevel": "info",
    "httpPort": 3002,
    "maxConcurrentConnections": 10,
    "requestTimeout": 30000,
    "fixInvalidToolSchemas": false
  }
}

配置选项

服务器配置

name：唯一服务器标识符
displayName：人类可读的服务器名称
transport：运输类型(stdio, http, sse)
command：STDIO服务器执行的命令
args：命令参数
env：环境变量
enabled：服务器是否已启用
timeout：连接超时（毫秒）
restartOnFailure：故障时自动重启
maxRestarts：最大重启尝试次数

工具发现规则

自动发现规则使用通配符模式自动注册工具：

serverPattern：服务器名称模式（支持 * 和 ?)
toolPattern：工具名称模式（支持 * 和 ?)
exclude：是否排除匹配工具

全局配置

logLevel：日志记录级别(debug, info, warn, error).违约： info
httpPort：HTTP服务器端口。默认值： 3002
maxConcurrentConnections：最大并发连接数。违约： 10
requestTimeout：请求超时（毫秒）。违约： 30000
fixInvalidToolSchemas：自动修复无效的工具架构。违约： false

动态配置

可以在运行时通过以下方式更新配置：

管理用户界面：使用web界面进行简单的配置管理
REST API：对编程配置更新的直接API调用
热重载：文件更改会自动检测并应用

📡 API终点

健康检查

GET /health
GET /mcp/server-info

服务器管理

# List available servers with detailed status information
GET /mcp/servers

# Add a new server configuration
POST /mcp/config/servers
Content-Type: application/json

# Update an existing server configuration
PUT /mcp/config/servers/:serverId
Content-Type: application/json

# Remove a server configuration
DELETE /mcp/config/servers/:serverId

# Force retry connection to a specific server
POST /mcp/servers/:serverId/retry

# Force retry connection to all failed servers
POST /mcp/servers/retry-all

工具管理

# List tools from specific server
GET /mcp/servers/:serverId/tools

# List all tools from all servers (with namespace info)
GET /mcp/tools

# List all tool aliases
GET /mcp/tool-aliases

# Get tool name conflicts
GET /mcp/conflicts

# Call tool on specific server
POST /mcp/servers/:serverId/tools/call
Content-Type: application/json

{
  "name": "tool-name",
  "arguments": {
    "param1": "value1"
  }
}

# Call tool via MCP meta server
POST /mcp/meta/tools/call
Content-Type: application/json

{
  "name": "call_server_tool",
  "arguments": {
    "serverId": "server-name",
    "toolName": "tool-name",
    "arguments": {}
  }
}

配置管理

# Get global configuration
GET /mcp/config/global

# Update global configuration
PUT /mcp/config/global
Content-Type: application/json

# Get tool discovery rules
GET /mcp/config/discovery-rules

# Update tool discovery rules
PUT /mcp/config/discovery-rules
Content-Type: application/json

{
  "rules": [
    {
      "serverPattern": "git*",
      "toolPattern": "*",
      "exclude": false
    }
  ]
}

工具别名

# Create tool alias
POST /mcp/meta/tools/call
Content-Type: application/json

{
  "name": "remove_tool_alias",
  "arguments": {
    "aliasName": "custom-alias"
  }
}

MCP协议端点

# MCP protocol messages via HTTP
POST /mcp
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

🔒 安全

-重要：禁用身份验证时，服务器绑定到环回接口(127.0.0.1 或 ::1)为了安全。

可配置访问：启用身份验证后，使用 security.network.listenAddress 允许外部客户端
无身份验证：禁用时，只允许本地主机连接
开发利用：默认情况下仅供开发和本地使用

未来的版本将包括：

认证与授权
HTTPS支持
基于角色的访问控制
API速率限制

🚀 使用示例

基本工具执行

# List all available tools
curl http://localhost:3002/mcp/tools

# Call a specific tool
curl -X POST http://localhost:3002/mcp/servers/git/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "name": "git_status",
    "arguments": {}
  }'

服务器管理

# Check server status
curl http://localhost:3002/mcp/servers

# Add a new server
curl -X POST http://localhost:3002/mcp/config/servers \
  -H "Content-Type: application/json" \
  -d '{
    "serverId": "my-server",
    "config": {
      "name": "my-server",
      "command": "npx",
      "args": ["-y", "some-mcp-server"],
      "enabled": true
    }
  }'

# Retry failed server
curl -X POST http://localhost:3002/mcp/servers/my-server/retry

工具发现规则

# Get current discovery rules
curl http://localhost:3002/mcp/config/discovery-rules

# Update discovery rules
curl -X PUT http://localhost:3002/mcp/config/discovery-rules \
  -H "Content-Type: application/json" \
  -d '{
    "rules": [
      {
        "serverPattern": "git*",
        "toolPattern": "git_*",
        "exclude": false
      }
    ]
  }'

“方法”：“初始化”，

🏗️ 建筑

Express.js：HTTP服务器框架
@模型上下文协议/sdk：用于客户端连接的官方MCP SDK
React+TypeScript：采用Vite和TailwindCSS的现代管理用户界面
萨德：配置和API请求的架构验证
TypeScript：类型安全和现代JavaScript功能

🛠️ 工具注册表

MCP网桥服务器包括一个内部工具注册表，用于管理工具并提供统一的接口：

特性

工具别名：创建自定义别名以便于工具访问
自动发现：根据可配置模式自动发现工具
命名空间管理：防止工具名称与自动命名空间冲突
动态管理：在运行时添加、删除和更新工具

管理工具

工具注册表通过MCP元服务器提供这些管理工具：

create_tool_alias：创建别名以便于工具访问
remove_tool_alias：删除工具别名
update_tool_alias：更新现有工具别名
list_aliased_tools：列出所有工具别名
call_server_tool：调用特定MCP服务器上的工具
list_all_tools：列出所有服务器中的所有工具
list_server_tools：列出特定服务器中的工具
list_conflicts：检测工具名称冲突

🔧 发展

项目结构

mcp-bridge/
├── src/                     # Backend TypeScript source
│   ├── config/             # Configuration management
│   ├── utils/              # Utilities and logging
│   └── *.ts               # Core server components
├── admin-ui/               # React admin interface
│   ├── src/
│   │   ├── components/     # Reusable UI components
│   │   ├── pages/         # Page components
│   │   ├── services/      # API services
│   │   └── types/         # TypeScript types
│   └── package.json
├── docs/                   # Documentation
├── examples/              # Configuration examples
└── package.json

建造和测试

# Install dependencies
npm install

# Build backend
npm run build

# Build admin UI
cd admin-ui && npm run build

# Run tests
npm test

# Development mode
npm run dev & cd admin-ui && npm run dev

守护进程管理

MCP网桥服务器现在支持后台执行的守护进程模式。使用以下命令：

# Start the daemon
node src/daemon.js start

# Stop the daemon
node src/daemon.js stop

# Restart the daemon
node src/daemon.js restart

代码空间设置

该项目与GitHub Codespace完全兼容。这 .devcontainer/devcontainer.json 文件提供了必要的配置。开始：

在Codespace中打开存储库。
环境将自动安装依赖项并设置开发环境。
环境变量，如 GOOGLE_API_KEY, GOOGLE_CX，以及 GITHUB_TOKEN 使用代码空间机密安全地传递。

📝 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🤝 贡献

克隆该仓库
创建功能分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add some amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

📞 支持

问题: GitHub问题
文档: 维基工程
例子：参见 examples/ 目录

由以下材料制成❤️ 对于MCP社区

这为跨多个MCP服务器管理工具提供了一种灵活统一的方法。

工具名称冲突解决

当多个MCP服务器提供同名工具时，MCP网桥服务器提供多种解决方案：

1.基于命名空间的工具名称

所有工具都会按照以下格式自动分配命名空间名称 serverId:toolName:

# Note: Since v1.2.1, explicit serverId and toolName are required
curl -X POST http://localhost:3000/mcp/servers/filesystem/tools/call \
  -H "Content-Type: application/json" \
  -d '{"name": "read_file", "arguments": {"path": "/tmp/test.txt"}}'

2.冲突检测

服务器会自动检测并报告工具名称冲突：

# Get all tool name conflicts
curl http://localhost:3000/mcp/conflicts

响应示例：

{
  "conflicts": [
    {
      "toolName": "read_file",
      "servers": ["filesystem", "filesystem2"]
    }
  ]
}

3.服务器级API

原始的服务器级API确保了没有歧义：

# Call tool on specific server
curl -X POST http://localhost:3000/mcp/servers/filesystem/tools/call \
  -H "Content-Type: application/json" \
  -d '{"name": "read_file", "arguments": {"path": "/tmp/test.txt"}}'

4.统一工具列表

从所有具有命名空间信息的服务器获取所有工具：

# Get all tools with namespace information
curl http://localhost:3000/mcp/tools

每个工具包括：

name：原始工具名称
namespacedName：命名空间工具名称（服务器ID:toolName）
serverId：源服务器ID
description：工具说明
inputSchema：工具输入模式

运输支持

MCP网桥服务器支持多种传输协议，用于连接到MCP服务器：

1.STDIO传输（默认）

对于基于本地流程的MCP服务器：

{
  "name": "filesystem",
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
  "env": {
    "CUSTOM_VAR": "value"
  },
  "cwd": "/custom/working/directory"
}

2.SSE传输（服务器发送事件）

对于使用服务器发送事件的基于HTTP的MCP服务器：

{
  "name": "remote-sse-server",
  "transport": "sse",
  "url": "http://localhost:3001/sse",
  "headers": {
    "Authorization": "Bearer your-token",
    "Custom-Header": "value"
  }
}

3.HTTP传输（流式HTTP）

对于使用StreamableHTTP的基于HTTP的MCP服务器：

{
  "name": "remote-http-server",
  "transport": "http", 
  "url": "http://localhost:3002/mcp",
  "headers": {
    "Authorization": "Bearer your-token",
    "Content-Type": "application/json"
  }
}

传输配置选项

选项	STDIO	SSE	HTTP	描述
`command`	✅ 必填	❌	❌	要执行的命令
`args`	✅ 可选	❌	❌	命令参数
`env`	✅ 可选	❌	❌	环境变量
`cwd`	✅ 可选	❌	❌	工作目录
`url`	❌	✅ 必填	✅ 必需	服务器URL
`headers`	❌	✅ 可选	✅ 可选	HTTP标头

混合运输示例

{
  "servers": [
    {
      "name": "local-filesystem",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    {
      "name": "remote-api-server",
      "transport": "sse",
      "url": "https://api.example.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer sk-...",
        "X-Client-Version": "1.0.0"
      }
    },
    {
      "name": "cloud-mcp-service",
      "transport": "http",
      "url": "https://mcp-service.cloud.com/api",
      "headers": {
        "API-Key": "your-api-key"
      }
    }
  ]
}

使用示例

测试多种运输方式

启动测试SSE服务器 （在单独的终端中）：

npm run test-sse-server

更新配置 包括SSE服务器：

cp examples/mcp-config-multi-transport.json mcp-config.json

启动网桥服务器:

npm start

测试多路传输设置:

# List all connected servers
curl http://localhost:3000/mcp/servers

# Get tools from STDIO server
curl http://localhost:3000/mcp/servers/filesystem-stdio/tools

# Get tools from SSE server  
curl http://localhost:3000/mcp/servers/test-sse-server/tools

# Call tool on SSE server with explicit serverId and toolName
curl -X POST http://localhost:3000/mcp/servers/test-sse-server/tools/call \
  -H "Content-Type: application/json" \
  -d '{"name": "echo", "arguments": {"text": "Hello from SSE!"}}'

Docker部署

MCP Bridge Server包括全面的Docker支持，便于部署和扩展。

Docker快速入门

使用Docker Compose（推荐）：

# Production deployment
docker-compose up -d

# Development with live reload
docker-compose -f docker-compose.dev.yml up -d

使用npm脚本：

# Build and run production
npm run docker:run

# Build and run development
npm run docker:run:dev

# Stop services
npm run docker:stop

直接使用Docker：

# Build image
docker build -t mcp-bridge-server .

# Run container
docker run -d \
  --name mcp-bridge \
  -p 3000:3000 \
  -v $(pwd)/mcp-config.json:/app/mcp-config.json:ro \
  -v $(pwd)/logs:/app/logs \
  mcp-bridge-server

Docker配置

创建特定于Docker的配置：

cp docker/mcp-config.docker.json mcp-config.json
# Edit mcp-config.json with your settings

高级Docker操作

包括 docker/build.sh 脚本提供高级操作：

# Build with specific tag
./docker/build.sh --action build --tag v1.0.0

# Build and push to registry
./docker/build.sh --action build --tag v1.0.0 --push

# Clean up Docker resources
./docker/build.sh --action clean

多服务架构

将MCP服务器部署为单独的容器：

# docker-compose.yml
services:
  mcp-bridge:
    build: .
    ports:
      - "3000:3000"
    depends_on:
      - mcp-filesystem
      - mcp-search
      
  mcp-filesystem:
    image: your-filesystem-server:latest
    
  mcp-search:
    image: your-search-server:latest

健康监测

# Check container health
docker ps

# View health check endpoint
curl http://localhost:3000/health

# Monitor logs
docker-compose logs -f

看 docker/README.md 获取全面的Docker文档。

工具注册模式

MCP Bridge Server支持使用通配符模式进行自动工具注册。此功能允许您：

从特定服务器自动注册工具
注册所有与命名模式匹配的工具
从注册中排除某些工具

配置示例

添加 registrationPatterns 到你的 mcp-config.json:

{
  "servers": [...],
  "registrationPatterns": [
    {
      "serverPattern": "filesystem",     // Server name pattern
      "toolPattern": "*",               // Register all tools
      "exclude": false                  // Register (false=register, true=exclude)
    },
    {
      "serverPattern": "*",             // From all servers
      "toolPattern": "read_*",          // Register tools starting with read_
      "exclude": false
    },
    {
      "serverPattern": "*",             // From all servers
      "toolPattern": "internal_*",      // Tools starting with internal_
      "exclude": true                   // Don't register (exclude)
    }
  ],
  "directTools": [
    {
      "serverId": "brave-search",       // Individually register specific tools
      "toolName": "search",
      "newName": "brave_search"         // Register with an alias
    }
  ]
}

模式匹配规则

通配符模式支持：
- *：匹配任何字符序列
- ?：匹配任何单个字符
模式按顺序评估，以后的排除模式优先
如果没有与工具匹配的模式，则不会注册

用法示例

# Start with registration patterns config
npm start -- ./examples/mcp-config-with-patterns.json

# Check which tools were automatically registered
curl http://localhost:3000/mcp/tools/registered

环境变量扩展

MCP网桥服务器支持配置文件中的环境变量扩展。配置文件中的任何字符串值都可以使用 ${VARIABLE_NAME} 引用环境变量的语法。

例子：

{
  "servers": [
    {
      "name": "filesystem",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${HOME}/data"],
      "env": {
        "DEBUG": "${DEBUG_LEVEL:-false}",
        "MAX_MEMORY": "${MAX_MEMORY:-1024}",
        "USER_PATH": "${HOME}/user"
      }
    },
    {
      "name": "http-server",
      "transport": "http",
      "url": "${API_URL:-http://localhost:3001}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  ]
}

使用说明：

如果未定义环境变量，则使用原始字符串(${VAR})保持不变
环境变量扩展适用于整个配置中的所有字符串值
这对于以下情况特别有用：
- 路径和目录
- API密钥和令牌
- URL和端点
- 环境特定设置

贡献

克隆该仓库
创建要素分支
进行更改
如果适用，添加测试
提交拉取请求

许可证

MIT许可证

使用说明

MCP网桥服务器

✨ 特性

核心功能

工具管理

服务器管理

管理界面

安全与运营

🚀 快速开始

Docker（推荐）

先决条件

安装

发展

🌐 管理界面

⚙️ 配置

配置选项

服务器配置

工具发现规则

全局配置

动态配置

📡 API终点

健康检查

服务器管理

工具管理

配置管理

工具别名

MCP协议端点

🔒 安全

🚀 使用示例

基本工具执行

服务器管理

工具发现规则

🏗️ 建筑

🛠️ 工具注册表

特性

管理工具

🔧 发展

项目结构

建造和测试

守护进程管理

代码空间设置

📝 许可证

🤝 贡献

📞 支持

工具名称冲突解决

1.基于命名空间的工具名称

2.冲突检测

3.服务器级API

4.统一工具列表

运输支持

1.STDIO传输（默认）

2.SSE传输（服务器发送事件）

3.HTTP传输（流式HTTP）

传输配置选项

混合运输示例

使用示例

测试多种运输方式

Docker部署

Docker快速入门

Docker配置

高级Docker操作

多服务架构

健康监测

工具注册模式

配置示例

模式匹配规则

用法示例

环境变量扩展

例子：

使用说明：

贡献

许可证

相关 MCP

Blender 3D建模MCP服务

iOS模拟器交互服务器

网页抓取与搜索MCP服务器

B站视频搜索服务

Minecraft MCP服务器

SSH远程命令执行MCP服务器