内容
# synapse-rmcp
Rust MCP 和 CLI 服务器，用于本地 Synapse 工作流 —— 一个用 Rust 实现的 [synapse-mcp](https://github.com/jmagar/synapse-mcp) 的完全等价移植版，使用 [rmcp](https://github.com/modelcontextprotocol/rust-sdk) 框架。
服务器暴露了两个 MCP 工具（`flux` 和 `scout`）以及等效的 CLI 命令，涵盖了原始 TypeScript 服务器的所有 59 个生产动作。
## 目录
- [命名](#命名)
- [功能和边界](#功能和边界)
- [安装](#安装)
- [快速入门](#快速入门)
- [客户端配置](#客户端配置)
- [运行时界面](#运行时界面)
- [MCP 工具参考](#mcp-工具参考)
- [CLI 参考](#cli-参考)
- [配置](#配置)
- [身份验证](#身份验证)
- [安全性和信任模型](#安全性和信任模型)
- [架构](#架构)
- [分发合约](#分发合约)
- [开发](#开发)
- [验证](#验证)
- [部署](#部署)
- [故障排除](#故障排除)
- [文档](#文档)
- [相关服务器](#相关服务器)
- [许可证](#许可证)
## 命名
存储库名为 `synapse-rmcp`，Rust crate 名为 `synapse2`，MCP 服务器标识为 `synapse2`，安装的二进制文件名为 `synapse`。npm 启动器包名为 `synapse-rmcp`。
在大多数 RMCP 家族中，命名遵循 `repo=<service>-rmcp`、`npm=<service>-rmcp` 和 `CLI=r<service>`。Synapse 是一个例外，因为它是较旧的 TypeScript `synapse-mcp` 项目的 Rust 端口，并保留了面向操作员的 `synapse` 二进制文件。
## 功能和边界
Synapse 通过两个 MCP 工具和等效的 CLI 提供本地 Docker、Compose、主机、SSH、日志、ZFS 和文件操作工作流：
- `flux` 管理 Docker 基础设施、容器、Compose 项目和主机检查。
- `scout` 处理 SSH/本地主机检查、安全文件读取、允许列表命令执行、ZFS 检查和日志检索。
- REST 仅作为子集动作的兼容性垫片存在。
- Web 界面是一个轻量级的静态管理外壳，而不是一个完整的管理仪表板。
**不适用于：** 任意 shell 访问、未经审计的远程修改或绕过主机 SSH 信任。破坏性 Docker/Compose/exec/文件传输操作需要明确的主机目标和确认策略。
MCP 调用者从不提供凭据、令牌、密钥或机密作为动作参数。令牌、OAuth 设置、主机拓扑、SSH 信任和允许列表存储在服务器端配置或本地 SSH 环境中。
## 安装
使用 npm 启动器进行 stdio MCP 或 CLI 访问，无需手动安装二进制文件：
```bash
npx -y synapse-rmcp --help
npx -y synapse-rmcp mcp
```
用于永久命令：
```bash
npm i -g synapse-rmcp
synapse --version
```
从源代码：
```bash
cargo build --release
```
## 快速入门
首屏 30 秒路径：
```bash
npx -y synapse-rmcp mcp
```
然后使用 stdio 配置 MCP 客户端：
```json
{
"mcpServers": {
"synapse": {
"command": "npx",
"args": ["-y", "synapse-rmcp", "mcp"]
}
}
}
```
以只读调用开始：
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "scout",
"arguments": {
"action": "nodes"
}
}
}
```
## 客户端配置
stdio 是本地 MCP 客户端的首选：
```json
{
"mcpServers": {
"synapse": {
"command": "synapse",
"args": ["mcp"]
}
}
}
```
可流式 HTTP 使用配置的主机和端口上的 `/mcp`：
```json
{
"mcpServers": {
"synapse": {
"url": "http://127.0.0.1:40080/mcp",
"headers": {
"Authorization": "Bearer ${SYNAPSE_MCP_TOKEN}"
}
}
}
}
```
## 运行时界面
| 界面 | 状态 | 目的 |
| --- | ---: | --- |
| MCP | 必需 | 面向代理的 `flux` 和 `scout` 工具 |
| CLI | 必需 | 操作员的脚本化对等面 |
| REST | 兼容性 | 薄的本地动作端点，适用于 14 个动作 |
| Web | 已存在 | 轻量级静态管理外壳 |
## MCP 工具参考
Synapse 暴露了两个 MCP 工具：
- `flux`：Docker 守护进程、容器、主机和 Compose 操作。
- `scout`：SSH/本地主机检查、文件系统读取、允许列表执行、多主机发出、文件束、ZFS 和日志。
两个工具都使用动作分派的 JSON 形状：
```json
{"name":"flux","arguments":{"action":"docker","subaction":"info"}}
{"name":"scout","arguments":{"action":"nodes"}}
```
下面的详细动作表是精选的 README 参考资料。生成的运行时 MCP 模式和 Rust 动作定义是实时工具合约的真相来源。
## CLI 参考
常用命令：
```bash
synapse flux docker info
synapse flux container list
synapse flux compose list --host myhost
synapse scout nodes
synapse scout exec --host myhost --command hostname
synapse scout zfs pools --host myhost
synapse scout logs journal --host myhost --unit docker
```
## 身份验证
挂载的 HTTP 支持 bearer 和 Google OAuth 模式。环回 stdio/本地开发可以在没有挂载 HTTP 身份验证的情况下运行。重要变量：
```bash
SYNAPSE_MCP_HOST=127.0.0.1
SYNAPSE_MCP_PORT=40080
SYNAPSE_MCP_TOKEN=change-me
SYNAPSE_MCP_AUTH_MODE=bearer
```
参见 [配置](#配置) 和 `docs/CONFIG.md` 以获取完整的身份验证矩阵。
## 安全性和信任模型
Synapse 将读取和写入范围（`synapse:read`、`synapse:write`）分开，并对破坏性操作使用确认门。`SYNAPSE_MCP_ALLOW_DESTRUCTIVE` 可以在环回安全上下文中跳过提示。SSH 主机信任委托给 OpenSSH 已知主机行为，命令执行使用 execvp/argv 语义而没有 shell 插值。
## 分发合约
发布身份的真相来源是 `Cargo.toml`、`.release-please-manifest.json`、`packages/synapse-rmcp/package.json`、发布工件和 `server.json` 中共享的版本。
分发/版本不变式：
- npm 包从 GitHub Releases 下载匹配的二进制文件。
- 安装的二进制文件仍为 `synapse`。
- `server.json` 必须指向 `ghcr.io/jmagar/synapse:<version>`。
- 插件清单在市场从 git 状态派生标识时保持无版本。
- 生成的文档和模式必须来自源代码控制的生成输入；精选的 README/文档应指向源代码真相文件以获取详细信息。
## 验证
```bash
python3 /home/jmagar/workspace/soma/scripts/check-readme-guide.py README.md
npm --prefix packages/synapse-rmcp run check
cargo fmt --check
cargo check
cargo test
git diff --check
```
## 部署
用于持久挂载的 HTTP 服务器：
```bash
SYNAPSE_MCP_HOST=0.0.0.0 \
SYNAPSE_MCP_PORT=40080 \
SYNAPSE_MCP_TOKEN=change-me \
synapse serve
```
在将端点暴露到环回之外之前使用 bearer 或 OAuth。生产 Docker/Compose 注释存在于 `docs/DEPLOYMENT.md` 和 `docs/DOCKER.md` 中；本地操作员用法可以保留在 stdio 上。
## 故障排除
- 来自 `/mcp` 的 `401` 或 `403`：检查 bearer/OAuth 设置和网关头。
- 没有主机出现：检查 `SYNAPSE_HOSTS_CONFIG`、`SYNAPSE_CONFIG_FILE` 和 `~/.ssh/config`。
- 拒绝破坏性操作：确认主机目标和确认策略。
- SSH 错误：验证 OpenSSH 已知主机、mux/套接字可用性和主机可达性（在 Synapse 之前）。
## npm / npx
在没有手动安装二进制文件的情况下运行 stdio MCP 服务器或 CLI：
```bash
npx -y synapse-rmcp --help
```
MCP 客户端可以使用相同的启动器：
```json
{
"mcpServers": {
"synapse": {
"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`。
## 界面
| 界面 | 状态 | 目的 |
| --- | ---: | --- |
| MCP | 必需 | 面向代理的 `flux` 和 `scout` 工具 |
| CLI | 必需 | 脚本化对等面 |
| REST | 已存在 | 薄的本地动作端点 |
| Web | 已存在 | 轻量级静态管理外壳 |
## 工具和动作
### `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` | 启动停止的容器；需要 `host`、`container_id` |
| `stop` | `synapse:write` | 停止运行的容器（破坏性）；需要 `host`、`container_id` |
| `restart` | `synapse:write` | 重启容器；需要 `host`、`container_id` |
| `pause` | `synapse:write` | 暂停运行的容器；需要 `host`、`container_id` |
| `resume` | `synapse:write` | 恢复暂停的容器；需要 `host`、`container_id` |
| `pull` | `synapse:write` | 为容器拉取最新的镜像；需要 `host`、`container_id` |
| `recreate` | `synapse:write` | 使用镜像拉取重新创建容器（破坏性）；需要 `host`、`container_id`；可选 `pull`（默认 true） |
| `exec` | `synapse:write` | 在容器内执行命令（破坏性，execvp）；需要 `host`、`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/本地主机检查
#### 简单动作（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` 的 **动作级别对等** — 所有 `synapse-mcp` 的 59 个生产动作都已实现。然而，原始 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`、`synapse://status` 和 `synapse://activity`。 |
| 根 SSH 登录门 | 原始功能通过诱导检查 `sshUser=root`，除非 `SYNAPSE_ALLOW_ROOT_LOGIN=true`。Rust 具有破坏性操作诱导，但没有根登录门。 |
| TOFU 指纹存储 | 原始功能将指纹持久化到 `~/.config/synapse/known_hosts.json`，并拒绝更改的指纹。Rust 使用严格的 OpenSSH `known_hosts` 和通配符警告 — 不同的操作员行为。 |
| `SYNAPSE_EXCLUDE_HOSTS` | 用于从群集发现中排除主机的原始 env 变量在 Rust 中不存在。 |
| `SYNAPSE_MCP_ALLOW_YOLO` | 原始的“跳过所有确认门”模式。Rust 具有 `SYNAPSE_MCP_ALLOW_DESTRUCTIVE`（每重新启动覆盖，环回仅限），这并不相同。 |
| `SYNAPSE_DEBUG_ERRORS` | 允许返回完整内部错误详细信息的原始选择加入模式。Rust 始终净化内部工具错误。 |
| `git` 在 exec 允许列表中 | 原始功能在 `ALLOWED_READ_COMMANDS` 中包含 `git`，带有标志守卫。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` 的最大并发请求数。超出请求将返回HTTP 429，并附带 `Retry-After`。设置为 `0` 以禁用。`/health`、`/ready` 和 `/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的自动化一致性验证。
## 文档
本README用于首次运行定位和高级操作发现。源文档和代码按以下方式分割：
- `docs/API.md` 整理的动作合约参考。
- `docs/MCP_SCHEMA.md` MCP模式形状和漂移期望。
- `docs/CONFIG.md` 环境和身份验证策略。
- `docs/QUICKSTART.md` 本地烟雾测试。
- `docs/PLUGINS.md` 和 `plugins/synapse2/skills/synapse2/SKILL.md` 代理和市场使用。
- `docs/generated/openapi.json` 生成的OpenAPI输出。
- `src/flux_service/`、`src/scout_service/` 和 `src/mcp/` 运行时源代码。
## 相关服务器
- `unifi-rmcp / rustifi` - UniFi控制器REST API桥接。
- `tailscale-rmcp / rustscale` - Tailscale设备、用户和tailnet操作API桥接。
- `unraid-rmcp / unrust` - Unraid GraphQL桥接，用于NAS和服务器管理。
- `apprise-rmcp` - Apprise通知分发桥接，适用于多种投递后端。
- `gotify-rmcp` - Gotify推送通知桥接，适用于发送、消息、应用和客户端。
- `arcane-rmcp` - Arcane Docker管理桥接，适用于容器和相关资源。
- `yarr-rmcp` - 媒体栈桥接，适用于Sonarr、Radarr、Prowlarr、Plex和相关服务。
- `ytdl-mcp` - 媒体下载和元数据工作流服务器。
- `cortex` - Syslog和家庭实验室日志聚合MCP服务器。
- `axon` - RAG、爬取、抓取、提取和语义搜索项目。
- `lab` - 家庭实验室控制平面和Labby网关项目。
- `lumen` - 本地语义代码搜索MCP服务器。
- `nugs` - 项目/包管理助手，用于本地代理工作流。
- `agentcast` - 代理转录和活动发布项目。
- `soma` - RMCP脚手架/运行时模板，用于新的提供者支持的服务器。
## 许可证
[MIT](LICENSE)
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器