内容
# mcp-manager
监控和恢复连接到 Claude 的 MCP 服务器 - 无需触及设置文件或重启 Claude。
**这是什么？** MCP 服务器是 Claude 等 AI 助手可以调用的外部工具。它们可能会崩溃、挂起或失去连接 - 当它们发生这种情况时，您的助手会无声无息地失去功能。mcp-manager 监控所有服务器，自动重启失败的服务器，并为您的助手提供工具来诊断问题，而无需离开对话。
---
## 安装
```sh
claude mcp add mcp-manager npx @waycraft/mcp-manager
```
或手动添加到 `~/.claude/mcp.json`（全局）或 `.claude/mcp.json`（项目级别）：
```json
{
"mcpServers": {
"mcp-manager": {
"command": "npx",
"args": ["@waycraft/mcp-manager"]
}
}
}
```
---
## 其他编辑器
<details>
<summary><strong>Cursor</strong></summary>
将以下内容添加到项目根目录的 `.cursor/mcp.json`（或全局的 `~/.cursor/mcp.json`）：
```json
{
"mcpServers": {
"mcp-manager": {
"command": "npx",
"args": ["@waycraft/mcp-manager"]
}
}
}
```
</details>
<details>
<summary><strong>VS Code (Copilot)</strong></summary>
将以下内容添加到项目根目录的 `.vscode/mcp.json`：
```json
{
"servers": {
"mcp-manager": {
"command": "npx",
"args": ["@waycraft/mcp-manager"]
}
}
}
```
</details>
<details>
<summary><strong>Windsurf</strong></summary>
将以下内容添加到 `~/.codeium/windsurf/mcp_config.json`：
```json
{
"mcpServers": {
"mcp-manager": {
"command": "npx",
"args": ["@waycraft/mcp-manager"]
}
}
}
```
</details>
---
## 功能
当 MCP 服务器断开、波动或无法重启时，通常需要离开对话来检查日志或编辑配置文件。mcp-manager 将每个连接服务器的实时状态、磁盘配置、重启控制和事件历史记录公开为 MCP 工具，Claude 可以直接调用。
---
## 工具
### `mcp_status`
返回每个 MCP 服务器的实时连接状态 - 名称、状态（已连接 / 已断开 / 降级 / 失败）、延迟、上次看到的时间、重启次数和任何当前错误。首先在感觉有问题时使用此工具。
### `mcp_config`
返回每个 MCP 服务器的磁盘配置 - 确切的启动命令、配置文件路径和配置范围（项目、用户设置或全局）。**与 `mcp_status` 区分开来：** 状态是实时运行时状态（它是否正在运行？）；配置是磁盘上的设置（如何启动？）。当您需要验证命令路径、检查正在使用的 Node 版本或了解哪个设置文件控制服务器时，请使用此工具。
### `mcp_restart`
按名称重启特定的服务器。**如果服务器已经健康，则跳过** - 使用 `force: true` 无论健康状态如何都重启。默认情况下，健康服务器不会受到干扰。
**参数：**
- `name` - 服务器名称（与 `mcp_status` 中显示的名称完全一致）
- `force` - （可选）设置为 `true` 以重启，即使服务器当前处于健康状态
### `mcp_restart_all`
重启所有当前不健康的服务器。健康服务器将被跳过。返回重启了什么和保留了什么的摘要。
### `mcp_history`
返回特定服务器的时间戳事件日志 - 连接、断开和重启事件。断开事件包括进程退出详细信息和服务器崩溃时最后的 stderr 输出，这样您就可以看到它实际打印了什么。
**参数：**
- `name` - 要检查的服务器名称
---
## 典型工作流程
```
感觉有问题
→ mcp_status # 查找哪个服务器已断开或降级
→ mcp_restart name # 尝试重启
→ 仍然失败？
→ mcp_history name # 读取崩溃时的 stderr 输出
→ mcp_config # 验证启动命令和文件路径是否正确
→ 修复根本原因，再次重启
```
---
## 搭配使用
**[session-continuity](https://www.npmjs.com/package/session-continuity)** - 如果 session-continuity 在会话过程中断开，mcp-manager 会在不离开对话的情况下重启它。不会丢失上下文。
```bash
claude mcp add session-continuity npx session-continuity
```
**[@waycraft/waypoint-mcp](https://www.npmjs.com/package/@waycraft/waypoint-mcp)** - 如果 waypoint 在构建周期期间断开，mcp-manager 会立即将其恢复。
```bash
claude mcp add waypoint npx @waycraft/waypoint-mcp
```
---
## 故障排除
**"Cannot find module" 或 ENOENT 错误**
服务器的启动命令指向一个不存在的文件。检查您的 MCP 配置中的路径 - 常见原因：软件包未安装（`npm install`）、项目移动后路径错误，或 `npx` 无法解析软件包。
**服务器每隔几秒重启然后停止**
mcp-manager 尝试 3 次，延迟 5 秒 → 15 秒 → 45 秒，然后将服务器标记为失败。检查 `mcp_history` 中的 stderr 输出。如果错误不可恢复（缺少模块、权限被拒绝），它会立即停止。
**"Port already in use"（EADDRINUSE）**
另一个进程正在使用相同的端口。使用 `lsof -i :PORT` 查找它并停止它，或在服务器的配置中更改端口。
**服务器显示“connected”但工具不工作**
服务器正在运行，但可能无法正确响应工具调用。尝试 `mcp_restart --force` 以重启甚至健康的服务器。
**配置更改未生效**
mcp-manager 在手动重启（`mcp_restart`）时从磁盘重新读取配置。如果您更改了配置文件，请重启受影响的服务器。
---
## 安全说明
**环境变量：** mcp-manager 将父进程的环境变量传递给启动的 MCP 服务器（标准的 Node.js 行为）。如果您的 MCP 服务器需要特定的环境变量（API 密钥、令牌），请在父进程或服务器的 `env` 配置中设置它们。
**仪表盘：** 仪表盘在 `127.0.0.1:3131`（仅限 localhost）上运行，无身份验证。要完全禁用它，请在 `mcp-manager.config.json` 中设置 `dashboardPort: 0`。
---
## Waycraft MCP 套件的一部分
mcp-manager 是为协同工作而设计的四种 MCP 工具之一：
- **[mcp-manager](https://github.com/100615056/mcp-manager)** - 监控和恢复 MCP 服务器
- **[session-continuity](https://github.com/100615056/session-continuity)** - 跨会话的持久内存
- **[waypoint-mcp](https://github.com/100615056/waypoint-mcp)** - 有指导的工程工作流程（目标 → 交付）
- **[prism](https://github.com/100615056/prism-mcp)** - 基于角色的测试和批评
---
## 反馈和讨论
某些功能不工作，某个服务器 mcp-manager 处理不当，或者您觉得有用的功能？
→ [GitHub Discussions](https://github.com/100615056/mcp-manager/discussions)
---
## 许可证
[MIT](LICENSE)
