Common MCP Gateway

通用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使用

1. 添加新的MCP服务器：点击顶部的“+添加新MCP”按钮
2. 编辑服务器：单击任何服务器上的“编辑”按钮-该服务器下方将显示表单
3. 启用/禁用：单击“启用”或“禁用”按钮
4. 删除服务器：点击“删除”按钮并确认
5. 高级设置：配置超时、重试、断路器阈值、回退服务器

发展

构建

npm run build

观看模式

npm run dev

测试

npm test
npm run test:coverage

建筑

网关由以下组件组成：

1. 路由器：将工具名称路由到下游服务器
2. 超时监视器：可配置的超时管理
3. 重试引擎：具有抖动的指数回退
4. 断路器：打开/关闭/半打开状态管理
5. 连接池：下游连接生命周期
6. 日志记录器：结构化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服务器

1. 将服务器配置添加到 config.json:

{
  "downstreamServers": {
    "my-new-server": {
      "command": "npx",
      "args": ["-y", "@scope/my-mcp-server"],
      "timeout": 30000,
      "retryAttempts": 3,
      "env": {
        "API_KEY": "optional-key"
      }
    }
  }
}

1. 重新启动网关（或重新启动Windsurf以重新加载网关）

1. 工具将作为 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实时重载模式
• 配置验证示例

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 彻底测试（请参阅TESTING.md）
4. 提交拉取请求

版本历史

看 更改日志.md 查看详细的版本历史和发行说明。

📄 许可证

这个项目是 双重许可:

⚠️ 如果您在 商业或闭源产品, 你必须购买商业许可证。 联系人： support@bmsoft1024.com

链接

• 模型上下文协议规范
• MCP SDK文档
• Windsurf IDE
• 光标AI IDE
• 架构文档
• 测试文档
• 测试结果

支持

对于问题和疑问：

• GitHub问题： 创建问题
• 文档： 文档/EN/ 和 docs/HU/

作者

BMSoft1024 —

______________________________________________________________________

匈牙利文件：参见 docs/HU/ 匈牙利语版本的所有文件。