通用MCP网关
具有强大超时、重试和断路器处理功能的集中式MCP（模型上下文协议）网关。
特性
- 聚合多个MCP服务器 在单一端点下
- 超时监视器 具有可配置的截止日期
- 指数回退重试 有抖动
- 断路器型式 （打开/关闭/半打开状态）
- 结构化JSON日志记录 与温斯顿
- 全球可用性 在所有项目中
- 完全可配置 （超时、重试、断路器设置）
安装
全球安装
cd Common_MCP
npm install
npm run build
npm install -g .配置设置
网关会自动创建配置目录：
- 窗户：
C:\Users\[username]\.common-mcp\ - 配置文件：
C:\Users\[username]\.common-mcp\config.json
配置文件是在首次运行时使用默认设置自动创建的。您还可以：
mkdir C:\Users\%USERNAME%\.common-mcp
copy config\default.json C:\Users\%USERNAME%\.common-mcp\config.json配置格式：
{
"common-mcp": {
"version": "1.0.0",
"globalDefaults": {
"timeout": 30000,
"retryAttempts": 3,
"retryDelay": 1000,
"circuitBreaker": {
"enabled": true,
"failureThreshold": 5,
"resetTimeout": 60000
}
},
"downstreamServers": {
"your-mcp-server": {
"command": "npx",
"args": ["-y", "your-mcp-package"],
"timeout": 30000,
"retries": 3,
"env": {}
}
}
}
}用法
IDE集成
Windsurf IDE
编辑 mcp_config.json 文件：
- 视窗:
C:\Users\[username]\.codeium\windsurf\mcp_config.json - Linux/macOS:
~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"common-mcp-gateway": {
"command": "common-mcp",
"args": [],
"disabled": false
}
}
}光标AI IDE
编辑光标MCP配置文件：
- 视窗:
C:\Users\[username]\AppData\Roaming\Cursor\User\mcp.json - Linux:
~/.config/Cursor/User/mcp.json - macOS:
~/Library/Application Support/Cursor/User/mcp.json
{
"mcpServers": {
"common-mcp-gateway": {
"command": "common-mcp",
"args": [],
"env": {
"COMMON_MCP_CONFIG": "~/.common-mcp/config.json"
},
"disabled": false
}
}
}重要：禁用中的所有下游MCP服务器 mcp_config.json （套 "disabled": true)因为它们将由网关管理。
添加下游MCP服务器
在 config.json 文件，添加下游服务器：
{
"common-mcp": {
"downstreamServers": {
"my-server": {
"command": "npx",
"args": ["-y", "my-mcp-server"],
"timeout": 30000,
"retryAttempts": 3
}
}
}
}工具命名约定
网关使用 serverId__toolName 格式（双下划线）：
time__get_current_time
fetch__fetch
filesystem__read_file
memory__create_entities
cursor-playwright__playwright_navigate为什么使用双下划线？ Windsurf要求工具名称匹配 ^[a-zA-Z0-9_-]{1,64}$.斜线字符(/)不允许，所以我们使用 __ 作为分离器。
配置参考
全局默认值
{
"globalDefaults": {
"timeout": 30000, // milliseconds
"retryAttempts": 3,
"retryDelay": 1000, // base delay in ms
"circuitBreaker": {
"enabled": true,
"failureThreshold": 5,
"resetTimeout": 60000 // milliseconds
}
}
}下游服务器配置
{
"downstreamServers": {
"server-id": {
"command": "npx",
"args": ["-y", "package-name"],
"timeout": 45000, // Override global
"retryAttempts": 3, // Override global
"env": {
"API_KEY": "your-key-here"
},
"healthCheck": {
"enabled": true,
"method": "tool_name",
"interval": 30000
}
}
}
}日志记录配置
{
"logging": {
"level": "INFO", // DEBUG|INFO|WARN|ERROR
"format": "json", // json|simple
"file": "path/to/log.log",
"maxSize": "10MB",
"maxFiles": 5
}
}市场UI（管理界面）
基于Web的配置编辑器
通用MCP网关包括一个基于web的管理界面，用于管理您的MCP服务器：
特征：
- 查看所有下游MCP服务器
- 添加具有完整配置的新MCP服务器
- 编辑现有服务器（内联，位于所选项目下方）
- 启用/禁用服务器
- 删除服务器
- 实时WebSocket更新（无需重新启动）
- 超时、重试、断路器和回退配置
运行市场UI
选项1：手动启动（开发）
# Terminal 1: Start backend
cd marketplace/backend
npm run dev
# Terminal 2: Start frontend
cd marketplace/frontend
npm run dev访问地址：http://localhost:5173
选项2:PM2自动启动（生产）
使用PM2进程管理器自动启动：
# Install PM2 globally (if not installed)
npm install -g pm2
# Start both backend and frontend
pm2 start ecosystem.config.js
# View status
pm2 status
# View logs
pm2 logs mcp-marketplace-backend
pm2 logs mcp-marketplace-frontend
# Stop all
pm2 stop all
# Enable startup on system boot
pm2 startup
pm2 save配置路径：
- 市场UI编辑：
C:\Users\[username]\.common-mcp\config.json - 非 Windsurf配置：
C:\Users\[username]\.codeium\windsurf\mcp_config.json - 更改会立即保存并通过WebSocket广播
UI使用
- 添加新的MCP服务器：点击顶部的“+添加新MCP”按钮
- 编辑服务器：单击任何服务器上的“编辑”按钮-该服务器下方将显示表单
- 启用/禁用：单击“启用”或“禁用”按钮
- 删除服务器：点击“删除”按钮并确认
- 高级设置：配置超时、重试、断路器阈值、回退服务器
发展
构建
npm run build观看模式
npm run dev测试
npm test
npm run test:coverage建筑
网关由以下组件组成：
- 路由器：将工具名称路由到下游服务器
- 超时监视器：可配置的超时管理
- 重试引擎：具有抖动的指数回退
- 断路器：打开/关闭/半打开状态管理
- 连接池：下游连接生命周期
- 日志记录器：结构化JSON日志记录
详细的架构文档： 建筑.md
故障排除
未找到MCP服务器
检查 command 和 args 在您的配置中：
# Test manually
npx -y package-name超时错误
增加配置中的超时值：
{
"timeout": 60000 // 60 seconds
}断路器打开
如果发生太多错误，断路器将进入断开状态。等待重置超时（默认值：60秒）或重新启动网关。
日志检查
# Windows
type C:\Users\%USERNAME%\.common-mcp\logs\common-mcp-*.log
# Or open the file in a JSON viewer扩展网关
添加新的MCP服务器
- 将服务器配置添加到
config.json:
{
"downstreamServers": {
"my-new-server": {
"command": "npx",
"args": ["-y", "@scope/my-mcp-server"],
"timeout": 30000,
"retryAttempts": 3,
"env": {
"API_KEY": "optional-key"
}
}
}
}- 重新启动网关（或重新启动Windsurf以重新加载网关）
- 工具将作为
my-new-server__toolname
自定义中间件
您可以使用自定义中间件扩展网关。看 建筑.md 了解详情。
MCP市场用户界面
基于web的配置管理界面可用于轻松管理MCP服务器。
特性
- 可视化配置管理：查看、添加、编辑和删除MCP服务器
- 启用/禁用切换：可快速打开/关闭任何服务器
- 实时重新加载：通过WebSocket实时更新
- 配置验证：保存前自动验证
- 暗模式用户界面：现代、干净的界面
快速开始
启动后端：
cd marketplace/backend
npm install
npm run dev启动前端：
cd marketplace/frontend
npm install
npm run dev访问地址： http://localhost:5173
看 市场/README.md 详细文档。
测试
全面的测试结果可在 MCP_TOOLS_TEST_RESULTS.md.
经过测试的MCP服务器：
- ✅ 时间MCP（2个工具）
- ✅ 获取MCP（1个工具）
- ✅ 文件系统MCP（10+工具）
- ✅ 内存MCP（8个工具）
- ✅ 顺序思维MCP（1个工具）
- ✅ 光标剧作家MCP（30+工具）
测试结果： 13+个测试工具，成功率100%。
示例
请参阅 市场 目录：
- 后端API服务器示例
- React前端实现
- WebSocket实时重载模式
- 配置验证示例
贡献
欢迎投稿！拜托：
- 分叉存储库
- 创建要素分支
- 彻底测试（请参阅TESTING.md）
- 提交拉取请求
版本历史
看 更改日志.md 查看详细的版本历史和发行说明。
📄 许可证
这个项目是 双重许可:
⚠️ 如果您在 商业或闭源产品, 你必须购买商业许可证。 联系人： support@bmsoft1024.com
链接
支持
对于问题和疑问：
作者
BMSoft1024 —
______________________________________________________________________
匈牙利文件：参见 docs/HU/ 匈牙利语版本的所有文件。