[English](./README_EN.md)

# MCP Manager

MCP 统一中继管理工具 — 将多个下游 MCP 聚合为单一入口，支持热插拔、多协议、Web 与 CLI 双模管理 

## 功能

- **多协议接入** — 支持 stdio、SSE、Streamable HTTP 三种 MCP 传输协议
- **统一中继** — 将多个下游 MCP 聚合为一个 MCP Server，外部客户端只需连接一个端点
- **热插拔** — 添加/删除/启用/禁用 MCP 资源即时生效，无需重启
- **工具过滤** — 支持按正则表达式屏蔽或允许特定工具，可精确到单个函数
- **访问控制** — Web 管理界面需要 JWT 登录认证
- **调用日志** — 记录所有工具调用的来源、参数、结果和耗时，支持搜索和过滤
- **自动发现** — 接入 MCP 后自动获取工具列表，支持手动刷新同步上游变更

## 快速开始

```bash
# 安装依赖
npm install

# 构建
npm run build

# 启动（Web 管理界面 + 统一 MCP 中继）
npm start
```

启动后：
- Web 管理界面：`http://localhost:3100`（默认用户名/密码：`admin` / `admin123`）
- 统一 MCP 端点：`http://localhost:3101/mcp`（HTTP 模式）

## 架构

```
外部 MCP 客户端 (Claude Desktop / MCP Inspector)
         │
         ▼
  ┌─────────────────┐
  │ Unified MCP     │  ← 统一中继（对外暴露 relay_* 管理工具）
  │ Server :3101    │
  └────────┬────────┘
           │
  ┌────────▼────────┐
  │ MCP Manager     │  ← 工具路由 + 访问控制 + 日志
  │ + Tool Router   │
  └────────┬────────┘
           │
  ┌────────▼────────┐
  │ Protocol        │  ← stdio / SSE / HTTP 适配器
  │ Adapters        │
  └────────┬────────┘
           │
  ┌────────▼────────┐
  │ 下游 MCP        │
  │ Servers         │
  └─────────────────┘
```

## 项目结构

```
MCPManager/
├── src/
│   ├── index.ts              # 主入口
│   ├── types.ts              # TypeScript 类型定义
│   ├── storage.ts            # JSON 配置持久化
│   ├── relay.ts              # 独立中继入口
│   ├── core/
│   │   ├── manager.ts        # MCP 连接管理器
│   │   ├── tool-router.ts    # 工具路由表
│   │   └── logger.ts         # 调用日志引擎
│   ├── protocols/
│   │   ├── stdio.ts          # Stdio 传输适配器
│   │   ├── sse.ts            # SSE 传输适配器
│   │   └── http.ts           # Streamable HTTP 适配器
│   ├── server/
│   │   └── unified-server.ts # 统一 MCP 中继服务
│   ├── web/
│   │   ├── index.ts          # Express 管理服务
│   │   ├── auth.ts           # JWT 认证
│   │   └── routes.ts         # 管理 API 路由
│   └── cli/
│       └── index.ts          # Commander CLI
├── public/
│   ├── index.html            # Web 前端
│   ├── style.css             # 样式
│   └── app.js                # 前端逻辑
└── data/
    ├── config.json           # 持久化配置
    └── tool-calls.jsonl      # 调用日志
```

## CLI 命令

```bash
# 添加 MCP 资源
mcpmanager add <name> --protocol stdio --command "node" --args "server.js"
mcpmanager add <name> --protocol http --url "http://host:port/mcp"
mcpmanager add <name> --protocol sse --url "http://host:port/sse"

# 列出所有 MCP
mcpmanager list

# 启用/禁用 MCP
mcpmanager enable <id>
mcpmanager disable <id>

# 删除 MCP
mcpmanager remove <id>

# 查看工具列表
mcpmanager tools [id]

# 屏蔽工具（正则匹配）
mcpmanager block <id> --pattern "debug_.*"

# 移除屏蔽
mcpmanager unblock <id> --pattern "debug_.*"

# 启动服务
mcpmanager start --port 3100 --relay-port 3101
```

## 管理 API

所有 `/api/*` 路径需要 `Authorization: Bearer <token>` 请求头。

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/auth/login` | 登录获取 token |
| PUT | `/api/auth/password` | 修改登录密码 |
| GET | `/api/mcps` | 列出所有 MCP 资源 |
| POST | `/api/mcps` | 添加 MCP 资源 |
| DELETE | `/api/mcps/:id` | 删除 MCP 资源 |
| POST | `/api/mcps/:id/toggle` | 启用/禁用 MCP |
| GET | `/api/mcps/:id/tools` | 查看 MCP 工具列表 |
| POST | `/api/mcps/:id/refresh` | 刷新 MCP 工具列表 |
| PUT | `/api/mcps/:id/tools/toggle` | 批量禁用/启用工具 |
| PUT | `/api/mcps/:id/filter` | 更新工具过滤规则 |
| GET | `/api/relay` | 中继状态与管理工具 |
| PUT | `/api/relay/config` | 更新中继配置 |
| POST | `/api/relay/start` | 启动中继 |
| POST | `/api/relay/stop` | 停止中继 |
| GET | `/api/logs` | 查询调用日志 |
| POST | `/api/logs/clear` | 清空日志 |
| GET | `/api/logs/config` | 获取日志配置 |
| PUT | `/api/logs/config` | 更新日志配置 |

## 统一中继管理工具

对外暴露的 MCP Server 提供以下管理接口（所有以 `relay_` 为前缀）：

| 工具名 | 说明 |
|--------|------|
| `relay_list_mcps` | 列出所有已启用的下游 MCP |
| `relay_add_mcp` | 动态接入下游 MCP |
| `relay_remove_mcp` | 删除下游 MCP |
| `relay_enable_mcp` | 启用下游 MCP |
| `relay_disable_mcp` | 禁用下游 MCP |
| `relay_refresh_tools` | 刷新工具列表 |
| `relay_list_tools` | 列出指定 MCP 的可用工具 |
| `relay_use_tool` | 调用下游 MCP 的工具 |

## 配置持久化

所有配置存储在 `data/config.json`，包含 MCP 资源列表、中继设置、认证信息和日志配置。程序启动时自动加载，配置变更即时写入。