# MCP Research Router

<div align="center">
  <img src="logo.svg" alt="MCP Research Router Logo" width="200" height="200"/>
</div>

## 📖 引言

你是否遇到过这些问题？

- 有多个 MCP 服务器，每次都要逐个添加到客户端，很麻烦？
- 工具太多，不知道该用哪个？
- 需要同时调用多个工具，但只能一个一个来？

**MCP Research Router** 就是为你准备的。

它是一个 MCP 聚合器和智能路由器，帮你：
- ✅ **一次连接，访问所有 MCP 服务器**
- ✅ **自动推荐最适合的工具**
- ✅ **批量并行执行，性能提升 3-5 倍**

## 🎯 这个工具适合你吗？

### ✅ 适合使用

- 有多个 MCP 服务器需要统一管理
- 工具数量多，不知道该用哪个
- 需要批量调用多个工具
- 想通过 LLM 智能推荐工具

### ❌ 不适合使用

- 只有一个 MCP 服务器
- 工具数量少，能直接选择
- 不需要智能推荐功能

如果你的客户端已经支持添加多个 MCP，并且你只有少量工具，那么你不需要这个工具。

## ⚡ 特点

### 1. 统一管理多个 MCP 服务器

聚合多个 MCP 服务器，一次连接即可访问所有工具。无需在每个客户端中逐个添加。

### 2. 智能工具推荐

根据你的需求，通过 LLM 自动推荐最合适的工具。不用再翻阅长长的工具列表。

### 3. 批量并行执行

同时调用多个相关工具，性能提升 3-5 倍。适合需要综合多个工具结果的场景。

## 🚀 快速开始

### 1. 安装

```bash
npm install -g mcp-research-router
# 或直接运行
npx mcp-research-router
```

### 2. 配置

**推荐：使用环境变量**

在 MCP 客户端中添加环境变量：

```
MCP_LLM_ENABLED=true
MCP_LLM_API_KEY=your-api-key-here
MCP_LLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4
MCP_LLM_MODEL=glm-4.7-flash
MCP_SERVER_URL=http://127.0.0.1:3000/mcp/your-group-id
```

### 3. 连接到客户端

编辑配置文件（适用于 Claude Desktop、Cursor 等支持 MCP 的客户端）：

- **Claude Desktop**:
  - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
  - Mac: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Cursor**:
  - Windows: `%APPDATA%\Cursor\User\globalStorage\mcp_settings.json`
  - Mac: `~/Library/Application Support/Cursor/User/globalStorage/mcp_settings.json`

**最小配置（仅连接服务）：**

```json
{
  "mcpServers": {
    "mcp-research-router": {
      "command": "npx",
      "args": ["mcp-research-router"]
    }
  }
}
```

**包含环境变量：**

```json
{
  "mcpServers": {
    "mcp-research-router": {
      "command": "npx",
      "args": ["mcp-research-router"],
      "env": {
        "MCP_LLM_ENABLED": "true",
        "MCP_LLM_BASE_URL": "https://ark.cn-beijing.volces.com/api/coding/v3",
        "MCP_LLM_API_KEY": "your-api-key-here",
        "MCP_LLM_MODEL": "ark-code-latest",
        "MCP_SERVER_ENABLED": "true",
        "MCP_SERVER_URL": "http://your-server-url/mcp/endpoint",
        "MCP_SERVER_NAME": "my-server",
        "MCP_SERVER_HEADERS": "{\"Authorization\": \"Bearer your-token\"}"
      }
    }
  }
}
```

## 📖 使用方法

### 获取工具列表

```json
{
  "name": "get_tool_list"
}
```

### 智能工具推荐

```json
{
  "name": "get_tool_list",
  "arguments": {
    "user_query": "搜索关于人工智能的最新新闻",
    "max_tools": 3
  }
}
```

系统会根据你的需求推荐最合适的工具。

### 批量执行工具

```json
{
  "name": "execute_tools",
  "arguments": {
    "tools": [
      {
        "tool_name": "server-name-metaso-metaso_web_search",
        "arguments": {"q": "人工智能最新发展"}
      }
    ]
  }
}
```

## ⚙️ 配置说明

### 环境变量（推荐）

| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `MCP_LLM_ENABLED` | 是否启用 LLM 推荐 | `false` |
| `MCP_LLM_API_KEY` | LLM API 密钥 | - |
| `MCP_LLM_BASE_URL` | LLM 基础 URL | `https://api.siliconflow.cn/v1` |
| `MCP_LLM_MODEL` | LLM 模型名称 | `Qwen/Qwen2.5-7B-Instruct` |
| `MCP_LLM_TIMEOUT` | LLM 调用超时时间（毫秒） | `90000` |
| `MCP_SERVER_ENABLED` | 是否启用 MCP 服务器 | `false` |
| `MCP_SERVER_URL` | MCP 服务器 URL | - |
| `MCP_SERVER_NAME` | MCP 服务器名称（工具名前缀） | `default` |
| `MCP_SERVER_HEADERS` | MCP 服务器请求头（JSON 格式） | `{}` |
| `MCP_PROMPTS_PATH` | 自定义提示词目录路径 | 包内 `prompts` 目录 |
| `MCP_MAX_RECOMMENDATIONS` | 最大推荐数 | `5` |
| `MCP_MAX_ITERATIONS` | 最大迭代次数 | `3` |
| `MCP_MIN_CONFIDENCE` | 最小置信度 | `0.7` |

### MCP_SERVER_HEADERS 使用方法

需要填写 JSON 格式的字符串：

```
MCP_SERVER_HEADERS={"Authorization": "Bearer your-token"}
```

**示例：**

- Bearer Token 认证：`{"Authorization": "Bearer your-token"}`
- API Key 认证：`{"X-API-Key": "your-api-key"}`
- 多个请求头：`{"Authorization": "Bearer your-token", "X-Custom-Header": "value"}`

### 配置文件方式

如果需要使用配置文件，编辑 `config.json`：

```json
{
  "subAgent": {
    "enabled": true,
    "type": "openai",
    "baseUrl": "https://open.bigmodel.cn/api/paas/v4",
    "apiKey": "your-api-key-here",
    "model": "glm-4.7-flash",
    "timeout": 90000
  },
  "mcpServers": {
    "enabled": true,
    "servers": [
      {
        "name": "my-favorites",
        "type": "streamable-http",
        "url": "http://127.0.0.1:3000/mcp/your-group-id"
      }
    ]
  }
}
```

完整配置示例请参考 `config.full.example.json`。

## 🎨 提示词模式

系统支持多种提示词模式，你可以根据需求选择：

### 预定义模式

- **tool_recommendation**（默认）：快速工具推荐
- **deep_research**：深度研究模式，适合复杂任务

### 自定义模式

在 `prompts/` 文件夹中创建新文件夹：

```
prompts/
└── my_mode/
    ├── system.txt
    └── user.txt
```

使用时传入 `prompt_mode: "my_mode"`。

详细说明请查看 `prompts/README.md`。

## ❓ 常见问题

### Q: 如何配置 MCPHub 分组？

1. 在 MCPHub 网页端创建分组
2. 添加常用的 MCP 服务器到分组
3. 复制分组 ID
4. 配置环境变量：`MCP_SERVER_URL=http://127.0.0.1:3000/mcp/分组ID`

⚠️ 不要把 MCP Research Router 自己添加到分组里，否则会无限套娃。

### Q: 不配置 LLM 能使用吗？

可以，但功能受限：
- ✅ 可以获取工具列表
- ✅ 可以执行工具
- ❌ 无法使用智能推荐功能

## 🛠️ 开发

```bash
# 安装依赖
pnpm install

# 开发模式（支持热重载）
pnpm dev

# 构建
pnpm build

# 运行
pnpm start
```

## 📄 许可证

MIT

## 🙏 赞赏

如果你觉得这个项目对你有帮助，欢迎通过微信赞赏支持我的开发工作：

<div align="center">
  <img src="appreciation.png" alt="赞赏码" width="300"/>
</div>

## 🔗 相关链接

- [GitHub 仓库](https://github.com/SpiritHerb/mcp-research-router)
- [安装指南](https://github.com/SpiritHerb/mcp-research-router/blob/main/INSTALL.md)
- [部署文档](https://github.com/SpiritHerb/mcp-research-router/blob/main/DEPLOYMENT.md)
- [更新日志](https://github.com/SpiritHerb/mcp-research-router/blob/main/CHANGELOG.md)