内容
# mcp-wrap
一个封装另一个 MCP 服务器的 MCP 服务器，提供管理其生命周期和观察其协议流量的工具。这使得 LLM（例如通过 Claude Code）可以停止、重建、重启和调用你的 MCP 服务器，而无需代理程序重新连接。
## 为什么
在开发带有 Claude Code 的 MCP 服务器时，LLM 可以编辑服务器的源代码，但无法重启 MCP 进程 — 该连接由代理程序管理。mcp-wrap 位于两者之间：Claude Code 连接到 mcp-wrap（保持运行），而 mcp-wrap 将实际服务器作为子进程管理。
```
Claude Code <--stdio--> mcp-wrap <--stdio--> 您的 MCP 服务器（子进程）
```
典型工作流程：
1. LLM 编辑服务器代码
2. 调用 `restart_server`（或 `stop_server` + 重建 + `start_server`）
3. 调用 `get_tools` / `list_resources` 以发现已公开的内容
4. 调用 `call_tool` / `read_resource` 以调用它
5. 使用 `get_server_stderr`、`get_notifications` 或 `wait_for` 以观察行为
## 安装
```bash
git clone https://github.com/megabytefisher/mcp-wrap.git
cd mcp-wrap
npm install
npm run build
```
## 使用
```
mcp-wrap <命令> [参数...]
```
mcp-wrap 将封装服务器的命令作为其参数。例如：
```bash
mcp-wrap node ./my-server/dist/index.js
mcp-wrap python my_server.py
mcp-wrap ./target/release/my-server --flag 值
```
### Claude Code 配置
添加到项目的 `.mcp.json` 中：
```json
{
"mcpServers": {
"my-server": {
"command": "node",
"args": ["/path/to/mcp-wrap/dist/index.js", "node", "/path/to/my-server/dist/index.js"]
}
}
}
```
或在 Claude Code 全局设置（`~/.claude/settings.json`）中：
```json
{
"mcpServers": {
"my-server": {
"command": "node",
"args": ["/path/to/mcp-wrap/dist/index.js", "node", "/path/to/my-server/dist/index.js"]
}
}
}
```
## 工具
### 生命周期
| 工具 | 描述 |
|------|-------------|
| `start_server` | 将封装的服务器作为子进程启动并连接到它 |
| `stop_server` | 停止封装的服务器并显示最近的 stderr |
| `restart_server` | 一步停止然后启动（用于重建后的便捷操作） |
### 工具代理
| 工具 | 描述 |
|------|-------------|
| `get_tools` | 列出封装服务器的工具及其输入模式 |
| `call_tool` | 按名称调用封装服务器上的工具并传递参数 |
`call_tool` 接受 `name`（字符串）和 `arguments`（对象，可选）。参数直接传递 — 无需双序列化。
### 资源代理
| 工具 | 描述 |
|------|-------------|
| `list_resources` | 列出封装服务器公开的具体资源 |
| `list_resource_templates` | 列出封装服务器公开的资源模板 |
| `read_resource` | 按 URI 读取资源 |
| `subscribe_resource` | 订阅资源 URI 的更新 |
| `unsubscribe_resource` | 取消订阅资源 URI 的更新 |
资源更新通知通过 `get_notifications`（或 `wait_for` 以处理竞争敏感的流程）到达。
### 可观察性
| 工具 | 描述 |
|------|-------------|
| `get_server_stderr` | 读取封装服务器捕获的 stderr。无参数时，以纯文本形式返回缓冲区并清除它。带有 `since_seq` 和/或 `regex` 时，以结构化的游标条目形式返回，而不清除。 |
| `get_notifications` | 读取服务器发起的 MCP 通知（`tools/list_changed`、`resources/updated`、`notifications/message` 等）。通过 `since_seq` / `next_seq` 游标。 |
| `wait_for` | 等待匹配事件到达或 `timeout_ms` 超时。条件：`notification`（按方法，可选 URI）、`stderr_match`（正则表达式）或 `resource_update`（`notifications/resources/updated` 的语法糖，针对 URI）。返回 `{ matched, elapsed_ms, payload? }`。 |
游标工具返回 `next_seq`；在下一次调用时，将其作为 `since_seq` 传递以分页。缓冲区有界 — 当条目被逐出时，`dropped` / `dropped_since_last_call` 非零。
### 协议日志（调试）
| 工具 | 描述 |
|------|-------------|
| `set_protocol_logging` | 切换原始 MCP 线级日志记录（默认关闭；详细） |
| `get_protocol_log` | 读取原始协议条目，同时启用日志记录。游标，具有可选的 `regex` 过滤器。 |
仅在调试线路级别问题时有用。默认禁用以保持缓冲区开销低。
## 工作原理
mcp-wrap 本身是一个使用 stdio 传输的 MCP 服务器。它使用 MCP SDK 的 `Client` 和 `StdioClientTransport` 连接到封装的服务器作为子进程。stderr、通知和（可选）原始协议流量被捕获到有界环缓冲区中。
当封装的服务器意外崩溃时，mcp-wrap 检测到断开连接并重置其状态 — 随后的工具调用返回一个清晰的“服务器未运行”错误，而不是挂起。每运行一次的缓冲区（stderr、通知、协议日志）在每次 `start_server` 时重置；协议记录的开启/关闭标志在重启之间保留。
## 许可证
MIT
