mcp-router 1.0.5

A routing/proxy system for MCP servers

MCP Router

MCP Router 是一个模型上下文协议（MCP）路由/代理系统，作为MCP服务端和客户端，支持动态管理MCP工具配置，解决LLM无法区分同名工具的问题。

特性

• 动态路由: 文件系统路由，使用 mcp_settings.json 配置
• 快速启动: 后台加载客户端，启动时间<0.1秒
• 热加载: 自动检测配置变化并重新加载
• 多传输支持: Stdio、SSE、HTTP 传输协议
• 实时日志: WebSocket实时日志流（可选）
• 权限控制: 可配置的LLM实例管理权限
• 智能端口: 端口占用时自动查找可用端口
• 安全认证: Bearer Token认证，输入验证
• REST API: 完整的HTTP API用于配置管理

项目结构

mcp_router/
├── main.py                 # 项目入口
├── config.json            # 全局配置文件
├── requirements.txt       # 依赖文件
├── .python-version        # Python版本管理
├── pyproject.toml         # uv项目配置
│
├── src/
│   ├── core/              # 核心模块
│   │   ├── logger.py      # 日志系统
│   │   ├── config.py      # 配置管理器
│   │   └── exceptions.py  # 自定义异常
│   │
│   ├── mcp/               # MCP模块
│   │   ├── client.py      # MCP客户端管理
│   │   ├── server.py      # MCP服务端
│   │   ├── router.py      # 路由核心逻辑
│   │   └── transport.py   # 传输层
│   │
│   ├── api/               # API模块
│   │   ├── app.py         # FastAPI应用
│   │   └── routes.py      # API路由处理
│   │
│   └── utils/             # 工具模块
│       ├── validator.py   # 输入验证
│       ├── watcher.py     # 文件监视器
│       └── security.py    # 安全工具
│
├── data/                  # MCP配置目录
│   ├── example/
│   │   └── mcp_settings.json
│   ├── Openai/
│   │   └── mcp_settings.json
│   └── Wxcom/
│       └── mcp_settings.json
│
└── test/                  # 测试文件
    ├── test_router.py
    ├── test_api.py
    └── test_security.py

快速开始

环境要求

• Python 3.10+
• uv (推荐) 或 pip 或 conda

安装

从 PyPI 安装（推荐）：

pip install mcp-router

从源码安装：

# 使用 uv (推荐)
uv venv .venv
uv pip install -e ".[dev]"

# 或使用 pip
python -m venv .venv
.venv\Scripts\activate  # Windows
source .venv/bin/activate  # Linux/Mac
pip install -e ".[dev]"

# 或使用 conda
conda env create -f environment.yml
conda activate mcp_router

配置

编辑 config.json 文件：

{
  "api": {
    "enabled": false,
    "port": 8000,
    "host": "127.0.0.1",
    "cors_origin": "*",
    "auto_find_port": true,
    "enable_realtime_logs": false
  },
  "server": {
    "enabled": true,
    "transport_type": "stdio",
    "allow_instance_management": false
  },
  "mcp_client": {
    "enabled": true,
    "timeout": 30
  },
  "security": {
    "bearer_token": "",
    "enable_validation": true
  },
  "logging": {
    "level": "INFO",
    "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
    "directory": "logs"
  },
  "watcher": {
    "enabled": true,
    "watch_path": "data",
    "debounce_delay": 1.0
  }
}

主要配置项说明:

• auto_find_port: 端口占用时自动递增查找可用端口
• enable_realtime_logs: 启用WebSocket实时日志 (ws://host:port/ws)
• allow_instance_management: 允许LLM管理实例 (add/remove/enable/disable)
• logging.directory: 日志目录，使用Minecraft风格 (latest.txt + 时间戳备份)

添加MCP配置

在 data/{provider}/mcp_settings.json 中添加MCP服务器配置：

{
  "provider": "example",
  "isActive": true,
  "name": "example_instance",
  "type": "stdio",
  "command": "python",
  "args": ["-m", "example_mcp"],
  "env": {},
  "metadata": {
    "description": "Example MCP server",
    "version": "1.0.0"
  }
}

运行

# 使用 uv
uv run python main.py

# 或直接运行
python main.py

使用模式

1. MCP Server 模式 (Stdio)

适用于与 LLM 集成，通过 stdio 协议通信。

配置:

{
  "api": {"enabled": false},
  "server": {"enabled": true, "transport_type": "stdio"}
}

2. API 模式

仅启动 REST API 服务器，用于配置管理。

配置:

{
  "api": {"enabled": true},
  "server": {"enabled": false}
}

3. 组合模式

同时运行 MCP Server 和 REST API。

配置:

{
  "api": {"enabled": true},
  "server": {"enabled": true}
}

MCP 工具

MCP Router 提供以下工具给 LLM 使用：

基础工具 (总是可用):

• mcp.router.list() - 列出所有已注册的MCP客户端实例
• mcp.router.help() - 返回所有实例的工具列表和使用说明
• mcp.router.use(instance_name) - 使用指定的MCP实例
• mcp.router.call(instance_name, tool_name, **kwargs) - 调用指定实例的指定工具

管理工具 (需启用 allow_instance_management):

• mcp.router.add(provider_name, config) - 动态添加新的MCP配置
• mcp.router.remove(instance_name) - 移除MCP配置
• mcp.router.enable(instance_name) - 启用MCP实例
• mcp.router.disable(instance_name) - 禁用MCP实例

REST API

当 API 模式启用时，可通过以下端点管理 MCP Router：

实例管理:

• GET /api/instances - 列出所有实例
• GET /api/instances/{name} - 获取实例详情
• POST /api/instances - 添加新实例
• PATCH /api/instances/{name} - 更新实例配置
• DELETE /api/instances/{name} - 删除实例
• POST /api/instances/{name}/enable - 启用实例
• POST /api/instances/{name}/disable - 禁用实例

工具管理:

• GET /api/tools - 列出所有工具
• GET /api/tools/{instance_name} - 获取实例的工具列表
• POST /api/call - 调用工具

其他:

• GET / - 服务状态
• GET /health - 健康检查
• GET /api/config - 获取配置
• WS /ws - 实时日志流 (需启用 enable_realtime_logs)

与 LLM 集成

在您的 LLM 客户端配置中添加：

{
  "mcpServers": {
    "mcp_router": {
      "isActive": true,
      "name": "mcp_router",
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "path/to/mcp_router",
        "run",
        "python",
        "main.py"
      ]
    }
  }
}

开发

代码风格

本项目使用 Ruff 进行代码格式化和 linting：

# 安装开发依赖
pip install -e ".[dev]"

# 格式化代码
ruff format .

# 检查代码
ruff check .

# 自动修复问题
ruff check --fix .

运行测试

# 运行所有测试
pytest

# 运行特定测试
pytest test/test_router.py

# 带覆盖率
pytest --cov=src --cov-report=html

本项目配置了 GitHub Actions CI，每次推送到 main 分支时会自动运行代码检查和测试。

安全性

• 输入验证: 防止SQL注入、XSS攻击、路径遍历
• Bearer Token: 可选的API认证
• CORS配置: 灵活的跨域请求控制
• 日志记录: 不记录敏感信息如完整token

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！

贡献指南：

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

请确保：

• 代码通过 ruff 检查
• 添加或更新相关测试
• 更新文档（如果需要）

联系方式

如有问题，请提交 Issue。