内容
# synapse-rmcp
Rust MCP 和 CLI 服务器，用于本地 Synapse 工作流 —— 一个使用 Rust 和 [rmcp](https://github.com/modelcontextprotocol/rust-sdk) 框架实现的 [synapse-mcp](https://github.com/jmagar/synapse-mcp) 的完全等价移植版。
服务器暴露了两个 MCP 工具（`flux` 和 `scout`）以及等效的 CLI 命令，涵盖了原始 TypeScript 服务器的所有 59 个生产操作。
## npm / npx
无需手动二进制安装即可运行 stdio MCP 服务器或 CLI：
```bash
npx -y synapse-rmcp --help
```
MCP 客户端可以使用相同的启动器：
```json
{
"mcpServers": {
"synapse2": {
"command": "npx",
"args": ["-y", "synapse-rmcp"]
}
}
}
```
npm 包在 `postinstall` 期间从 GitHub Releases 下载 `synapse` 二进制文件，并保持发布标签与 `packages/synapse-rmcp/package.json` 对齐。
在 rmcp 家族中，命名遵循 `repo=<service>-rmcp`、`npm=<service>-rmcp` 和 `CLI=r<service>`。Synapse 是一个例外：npm 包是 `synapse-rmcp`，但安装的 CLI 和二进制别名仍为 `synapse`。
## Surfaces
| Surface | 状态 | 目的 |
| --- | ---: | --- |
| MCP | Required | 面向代理的 `flux` 和 `scout` 工具 |
| CLI | Required | 可脚本化的等价表面 |
| REST | Present | 薄本地操作端点 |
| Web | Present | 轻量级静态管理外壳 |
## 工具和操作
### `flux` — Docker 基础设施管理
#### `flux docker` — Docker 守护进程操作（9 个操作）
| 子操作 | 范围 | 描述 |
| --- | --- | --- |
| `info` | `synapse:read` | Docker 守护进程信息 |
| `df` | `synapse:read` | Docker 磁盘使用情况 |
| `images` | `synapse:read` | 列出 Docker 镜像；`dangling_only` 过滤未标记的镜像 |
| `networks` | `synapse:read` | 列出 Docker 网络 |
| `volumes` | `synapse:read` | 列出 Docker 卷 |
| `pull` | `synapse:write` | 拉取 Docker 镜像；需要 `host`、`image` |
| `build` | `synapse:write` | 构建 Docker 镜像；需要 `host`、`context`、`tag`；可选 `dockerfile`、`no_cache` |
| `rmi` | `synapse:write` | 删除 Docker 镜像；需要 `host`、`image`、`force=true` |
| `prune` | `synapse:write` | 删除未使用的资源；需要 `host`、`prune_target`、`force=true` |
#### `flux container` — 容器生命周期 + 检查（14 个操作）
| 子操作 | 范围 | 描述 |
| --- | --- | --- |
| `list` | `synapse:read` | 列出容器；可选 `state`、`name_filter`、`image_filter`、`label_filter` |
| `inspect` | `synapse:read` | 详细的容器信息；需要 `container_id`；可选 `summary` |
| `logs` | `synapse:read` | 容器日志；需要 `container_id`；可选 `lines`、`since`、`until`、`grep`、`stream` |
| `stats` | `synapse:read` | 资源使用情况统计；可选 `container_id` |
| `top` | `synapse:read` | 显示运行的进程；需要 `container_id` |
| `search` | `synapse:read` | 按名称/镜像/标签进行全文搜索；需要 `query` |
| `start` | `synapse:write` | 启动停止的容器；需要 `container_id` |
| `stop` | `synapse:write` | 停止正在运行的容器（破坏性）；需要 `container_id` |
| `restart` | `synapse:write` | 重启容器；需要 `container_id` |
| `pause` | `synapse:write` | 暂停正在运行的容器；需要 `container_id` |
| `resume` | `synapse:write` | 恢复暂停的容器；需要 `container_id` |
| `pull` | `synapse:write` | 为容器拉取最新的镜像；需要 `container_id` |
| `recreate` | `synapse:write` | 使用镜像拉取重新创建容器（破坏性）；需要 `container_id`；可选 `pull`（默认为 true） |
| `exec` | `synapse:write` | 在容器内执行命令（破坏性，execvp）；需要 `container_id`、`command` 数组 |
#### `flux host` — 主机检查（9 个操作）
| 子操作 | 范围 | 描述 |
| --- | --- | --- |
| `status` | `synapse:read` | 检查主机上的 Docker 连接性 |
| `info` | `synapse:read` | 操作系统、内核、架构 |
| `uptime` | `synapse:read` | 系统运行时间 |
| `resources` | `synapse:read` | CPU、内存、磁盘使用情况 |
| `services` | `synapse:read` | systemd 服务状态；需要 `host`；可选 `state`、`service` |
| `network` | `synapse:read` | 网络接口 |
| `mounts` | `synapse:read` | 安装的文件系统；需要 `host` |
| `ports` | `synapse:read` | 端口映射；需要 `host`；可选 `protocol`、`limit`、`offset` |
| `doctor` | `synapse:read` | 诊断检查；需要 `host`；可选 `checks`（逗号分隔） |
#### `flux compose` — Docker Compose 项目管理（10 个操作）
| 子操作 | 范围 | 描述 |
| --- | --- | --- |
| `list` | `synapse:read` | 列出所有 Docker Compose 项目；需要 `host` |
| `status` | `synapse:read` | 获取项目服务状态；需要 `host`、`project`；可选 `service` |
| `up` | `synapse:write` | 启动 compose 项目；需要 `host`、`project` |
| `down` | `synapse:write` | 停止 compose 项目（破坏性）；需要 `host`、`project`；可选 `remove_volumes`、`force` |
| `restart` | `synapse:write` | 重启 compose 项目（破坏性）；需要 `host`、`project` |
| `recreate` | `synapse:write` | 重新创建 compose 容器（破坏性）；需要 `host`、`project` |
| `logs` | `synapse:read` | 获取项目日志；需要 `host`、`project`；可选 `service`、`lines`、`since` |
| `build` | `synapse:write` | 构建 compose 项目镜像；需要 `host`、`project`；可选 `service` |
| `pull` | `synapse:write` | 拉取 compose 项目镜像；需要 `host`、`project`；可选 `service` |
| `refresh` | `synapse:read` | 刷新 compose 项目缓存；需要 `host` |
#### `flux help` — 自动生成的 flux 文档
| 操作 | 范围 | 描述 |
| --- | --- | --- |
| `help` | public | 返回 flux 操作参考；可选 `topic`（例如 `"container:list"`）、`format`（`markdown`\|`json`） |
---
### `scout` — SSH/本地主机检查
#### Scout 简单操作（9 个操作）
| 操作 | 范围 | 描述 |
| --- | --- | --- |
| `nodes` | `synapse:read` | 列出所有配置的 SSH 主机 |
| `peek` | `synapse:read` | 读取文件或目录列表；需要 `host`、`path`；可选 `tree`、`depth` |
| `find` | `synapse:read` | 按 glob 查找文件；需要 `host`、`path`、`pattern`；可选 `depth`、`limit` |
| `ps` | `synapse:read` | 列出进程；需要 `host`；可选 `sort`（`cpu`\|`mem`\|`pid`\|`time`）、`grep`、`user`、`limit` |
| `df` | `synapse:read` | 磁盘使用情况；需要 `host`；可选 `path` |
| `delta` | `synapse:read` | 比较文件或内容；需要 `source_host`、`source_path`；然后是 `target_host`+`target_path` 或 `content` |
| `exec` | `synapse:write` | 执行允许的命令（破坏性，execvp）；需要 `host`、`command`；可选 `path`、`args`、`timeout_secs` |
| `emit` | `synapse:write` | 多主机执行（破坏性）；需要 `targets` 数组、`command`；可选 `args`、`timeout_secs` |
| `beam` | `synapse:write` | 主机之间文件传输（破坏性）；需要 `source_host`、`source_path`、`dest_host`、`dest_path` |
#### `scout zfs` — ZFS 检查（3 个子操作）
| 子操作 | 范围 | 描述 |
| --- | --- | --- |
| `pools` | `synapse:read` | 列出 ZFS 池；需要 `host`；可选 `pool` 名称过滤器 |
| `datasets` | `synapse:read` | 列出 ZFS 数据集；需要 `host`；可选 `pool`、`dataset_type`、`recursive` |
| `snapshots` | `synapse:read` | 列出 ZFS 快照；需要 `host`；可选 `pool`、`dataset`、`limit` |
#### `scout logs` — 日志检索（4 个子操作）
| 子操作 | 范围 | 描述 |
| --- | --- | --- |
| `syslog` | `synapse:read` | 读取 `/var/log/syslog`（回退到 `/var/log/messages`）；需要 `host`；可选 `lines`、`grep` |
| `journal` | `synapse:read` | 读取 systemd 日志；需要 `host`；可选 `lines`、`unit`、`priority`、`since`、`until`、`grep` |
| `dmesg` | `synapse:read` | 读取内核环缓冲区；需要 `host`；可选 `lines`、`grep` |
| `auth` | `synapse:read` | 读取 `/var/log/auth.log`（回退到 `/var/log/secure`）；需要 `host`；可选 `lines`、`grep` |
#### `scout help` — 自动生成的 scout 文档
| 操作 | 范围 | 描述 |
| --- | --- | --- |
| `help` | public | 返回 scout 操作参考；可选 `topic`（例如 `"zfs:pools"`）、`format`（`markdown`\|`json`） |
## 已知对等差距
`synapse2` 实现 **操作级对等** 与 `synapse-mcp` — 所有 59 个生产操作从 `synapse-mcp/docs/INVENTORY.md` 实现。但是，以下功能从原始 TypeScript 服务器 **尚未移植**:
### 未移植
| 功能 | 描述 |
| --- | --- |
| `claude/channel` 通知 | 原始转发 Docker 事件和日志尾部作为 `notifications/claude/channel` MCP 通知。在 Rust 中没有等效功能。 |
| 模板 MCP 资源 | 原始公开 `synapse://hosts/{host}`、`synapse://hosts/{host}/stacks`、`synapse://stacks`、`synapse://stacks/{host}/{stack}`、`synapse://stacks/{host}/{stack}/env`、`synapse://containers/{host}`、`synapse://containers/{host}/{id}`。Rust 公开模式资源、`synapse://hosts`、`synapse://compose/projects` 和帮助资源。 |
| 根 SSH 登录门 | 原始门控 `sshUser=root` 通过诱导，除非 `SYNAPSE_ALLOW_ROOT_LOGIN=true`。Rust 有破坏性操作诱导但无根登录门。 |
| TOFU 指纹存储 | 原始将指纹持久化到 `~/.config/synapse/known_hosts.json` 并拒绝更改的指纹。Rust 使用严格的 OpenSSH `known_hosts` 和通配符警告 — 不同的操作员行为。 |
| `SYNAPSE_EXCLUDE_HOSTS` | 原始环境变量以排除主机从舰队发现，在 Rust 中不存在。 |
| `SYNAPSE_MCP_ALLOW_YOLO` | 原始“跳过所有确认门”模式。Rust 有 `SYNAPSE_MCP_ALLOW_DESTRUCTIVE`（每个重启覆盖，环回仅限），这不相同。 |
| `SYNAPSE_DEBUG_ERRORS` | 原始选择加入模式，返回完整的内部错误详细信息。Rust 始终清理内部工具错误。 |
| `git` 在 exec 允许列表中 | 原始包括 `git` 在 `ALLOWED_READ_COMMANDS` 中带有标志守卫。Rust 故意排除 `git`。 |
## 配置
```bash
SYNAPSE_MCP_HOST=127.0.0.1
SYNAPSE_MCP_PORT=40080
SYNAPSE_MCP_TOKEN=change-me
```
关键环境变量：
| 变量 | 默认值 | 描述 |
| --- | ---: | --- |
| `SYNAPSE_MCP_HOST` | `127.0.0.1` | HTTP 传输的绑定主机。 |
| `SYNAPSE_MCP_PORT` | `40080` | HTTP 传输的绑定端口。 |
| `SYNAPSE_MCP_TOKEN` | 未设置 | 身份验证的静态承载令牌。 |
| `SYNAPSE_MCP_NO_AUTH` | `false` | 仅用于环回开发禁用身份验证。 |
| `SYNAPSE_NOAUTH` | `false` | 非环回部署的受信任网关无身份验证模式。 |
| `SYNAPSE_MCP_ALLOW_DESTRUCTIVE` | `false` | 跳过破坏性操作确认提示（仅限环回）。 |
| `SYNAPSE_MCP_MAX_CONCURRENCY` | `50` | `/mcp` 和 `/v1/synapse2` 上同时进行的请求的最大数量。超出请求被排队，不被拒绝。设置为 `0` 以禁用。`/health` 和 `/status` 豁免。 |
参见 `.env.example` 获取完整变量列表，`docs/CONFIG.md` 获取身份验证配置详情。
## 运行
```bash
# 启动 MCP 服务器（stdio 传输）
cargo run -- mcp
# 启动 HTTP 服务器
cargo run -- serve
# CLI 示例
cargo run -- flux docker info
cargo run -- flux container list
cargo run -- flux compose list --host myhost
cargo run -- scout nodes
cargo run -- scout exec --host myhost --command hostname
cargo run -- scout zfs pools --host myhost
cargo run -- scout logs journal --host myhost --unit docker
```
MCP 示例：
```json
{"name":"flux","arguments":{"action":"docker","subaction":"info"}}
{"name":"flux","arguments":{"action":"container","subaction":"list","state":"running"}}
{"name":"flux","arguments":{"action":"compose","subaction":"status","host":"myhost","project":"mystack"}}
{"name":"scout","arguments":{"action":"nodes"}}
{"name":"scout","arguments":{"action":"exec","host":"myhost","command":"hostname"}}
{"name":"scout","arguments":{"action":"zfs","subaction":"pools","host":"myhost"}}
{"name":"scout","arguments":{"action":"logs","subaction":"journal","host":"myhost","unit":"docker"}}
```
## 架构
```text
FluxService (src/flux_service/) Docker/container/compose/host ops
ScoutService (src/scout_service/) SSH/exec/fs/zfs/logs ops
↓ via SynapseService facade (src/app.rs)
MCP shims (src/mcp/tools.rs) tool args → service → Value
CLI shim (src/cli.rs) argv → service → stdout
REST layer (src/api.rs) POST /v1/synapse2 → service → JSON
```
## 开发
```bash
cargo fmt --check
cargo test
cargo clippy -- -D warnings
cargo build --release
just dev # serve with no auth (loopback, dev mode)
just test # cargo test
just lint # clippy
just fmt # cargo fmt
```
有用的文档：
- `docs/API.md` 获取完整的工具合约
- `docs/CONFIG.md` 获取环境和身份验证信息
- `docs/QUICKSTART.md` 获取本地烟雾测试
- `plugins/synapse2/skills/synapse2/SKILL.md` 获取代理使用指南
- `tests/parity.rs` 获取针对 synapse-mcp INVENTORY 的自动对等验证
