Synapse RMCP

synapse-rmcp

通过 MCP 和 CLI 执行主机、Docker、Compose、SSH、日志、ZFS 和文件操作。

Synapse 是一个功能完全对等的 Rust 移植版本，源自 synapse-mcp，基于 rmcp 框架构建。

该服务提供两个 MCP 工具（flux 和 scout）以及对应的 CLI 命令，涵盖原 TypeScript 服务中的全部 59 项生产环境操作。

目录

• 命名
• 功能与边界
• 安装
• 快速入门
• 客户端配置
• 插件包
• 运行时接口
• MCP 工具参考
• CLI 参考
• 身份验证
• 安全与信任模型
• 分发约定
• 验证
• 部署
• 故障排除
• 工具与操作
• 已知的对等差异
• 配置
• 运行
• 架构
• 开发
• 文档
• 相关服务
• 许可证

命名

仓库名为 synapse-rmcp，Rust crate 名为 synapse，MCP 服务标识为 synapse，安装后的二进制文件名为 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，无需手动安装二进制文件：

npx -y @dinglebear/synapse --help
npx -y @dinglebear/synapse mcp

设置永久命令：

npm i -g @dinglebear/synapse
synapse --version

npm 包会在 postinstall 期间从 GitHub Releases 下载 synapse 二进制文件，使发布标签与 packages/synapse-rmcp/package.json 保持一致。

从源代码构建：

cargo build --release

生产镜像包含 Python 3 和官方 Docker CLI/Compose 插件，因为 Scout 的远程描述符包装器和 Flux 的 Compose 操作会调用这些运行时工具。镜像不包含 Docker 守护进程；Flux 使用已挂载的套接字或通过 SSH 转发的远程套接字。持久化应用数据在主机上位于 ~/.synapse，在容器中位于 /data。

快速入门

30 秒内完成初始设置：

npx -y @dinglebear/synapse mcp

然后为 MCP 客户端配置 stdio：

{
  "mcpServers": {
    "synapse": {
      "command": "npx",
      "args": ["-y", "synapse-rmcp", "mcp"]
    }
  }
}

先进行只读调用：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "scout",
    "arguments": {
      "action": "nodes"
    }
  }
}

客户端配置

本地 MCP 客户端首选使用 stdio：

{
  "mcpServers": {
    "synapse": {
      "command": "synapse",
      "args": ["mcp"]
    }
  }
}

Streamable HTTP 使用已配置主机和端口上的 /mcp：

{
  "mcpServers": {
    "synapse": {
      "url": "http://127.0.0.1:40080/mcp",
      "headers": {
        "Authorization": "Bearer ${SYNAPSE_MCP_TOKEN}"
      }
    }
  }
}

插件包

plugins/synapse/ 提供 Claude Code、Codex 和 Gemini CLI 清单，它们都指向同一个 HTTP MCP 端点和同一个共享技能。

这些包不包含生命周期钩子。连接到已运行的服务无需任何设置——清单会直接替换其中的 server_url 和 api_token。如果这台机器也要运行服务，请手动初始化一次：

synapse setup install                  # put/refresh the binary on PATH
synapse setup plugin-hook              # check, then repair on blocking failures
synapse setup plugin-hook --no-repair  # audit only; never mutates appdata

先导出相关的 SYNAPSE_* 变量（或将它们写入 ~/.synapse/.env）；plugins/README.md 列出了每个插件选项对应的变量。插件更新后，请重新运行 synapse setup install。

运行时接口

接口	状态	用途
MCP	必需	面向 Agent 的 flux 和 scout 工具
CLI	必需	面向运维人员的可脚本化等效接口
REST	兼容	为 59 个操作中的 14 个提供轻量级本地操作端点
Web	已提供	轻量级静态管理界面

MCP 工具参考

Synapse 提供两个 MCP 工具：

• flux：Docker 守护进程、容器、主机和 Compose 操作。
• scout：SSH／本地主机检查、文件系统读取、允许列表中的执行、多主机发送、文件传输、ZFS 和日志。

这两个工具都使用按操作分派的 JSON 结构：

{"name":"flux","arguments":{"action":"docker","subaction":"info"}}
{"name":"scout","arguments":{"action":"nodes"}}

下方的详细操作表是经过整理的 README 参考资料。生成的运行时 MCP 架构和 Rust 操作定义才是实时工具契约的准确信息来源。

CLI 参考

常用命令：

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 身份验证即可运行。重要变量：

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 只能在环回安全上下文中跳过提示。主机 protocol 具有权威性，省略时默认为 SSH；本地执行必须显式使用内置的 local 主机或 protocol: "local"。SSH 主机信任委托给 OpenSSH 的 known-hosts 行为；命令执行采用 execvp／argv 语义，不进行 shell 插值。scout beam 会遵守两端配置的读取根目录，阻止访问敏感路径和符号链接路径，并将每次传输限制在 64 MiB 以内。

scout exec 和 scout emit 仅接受以下 18 个类型化命令（位于 src/synapse/command_policy.rs 中的 ALLOWED_READ_COMMANDS）：

cat、head、tail、grep、rg、ls、tree、wc、uniq、diff、stat、 file、du、df、pwd、hostname、uptime、whoami

git 被有意排除在外，shell、解释器、网络客户端和修改型工具也不允许使用（EXEC_DENYLIST）。允许列表中没有 find 或 sort——请使用专用的 scout find 操作搜索文件系统。可以通过 execAllowlist 启用每台主机的自定义命令，但在注册类型化参数策略之前，这些命令会采用零参数策略。

分发契约

发布标识的准确信息来源是 Cargo.toml、.release-please-manifest.json、packages/synapse-rmcp/package.json、发布制品和 server.json 中一致的版本。

分发／版本不变量：

• npm 包会下载匹配的 GitHub Release 二进制文件。
• 安装后的二进制文件仍名为 synapse。
• server.json 必须指向 ghcr.io/dinglebear-ai/synapse:<version>。
• 当市场根据 git 状态派生标识时，插件清单应保持无版本号。
• 生成的文档和架构必须来自受源代码控制的生成输入；经过整理的 README／文档应指向准确的源文件，以提供详细信息。

验证

just validate-plugin          # plugin manifests, MCP config, monitors, skills
npm --prefix packages/synapse-rmcp run check
cargo fmt --check
cargo check
cargo test
git diff --check

部署

如需运行持久的挂载 HTTP 服务：

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 known_hosts、mux/socket 是否可用，以及从 Synapse 外部能否连接主机。

工具和操作

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/本地主机检查

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/Compose 根目录下

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）

已知的功能对齐差距

synapse 与 synapse-mcp 在操作层面实现了功能对齐——synapse-mcp/docs/INVENTORY.md 中列出的全部 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。
Root SSH 登录门控	原版会通过征询确认来限制 sshUser=root，除非设置了 SYNAPSE_ALLOW_ROOT_LOGIN=true。Rust 版本有破坏性操作的征询确认，但没有 Root 登录门控。
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 版本始终会对内部工具错误进行清理。
exec 允许列表中的 git	原版在 ALLOWED_READ_COMMANDS 中包含 git，并设置了标志保护。Rust 版本有意排除 git。

配置

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	unset	用于身份验证的静态 bearer token。
SYNAPSE_MCP_NO_AUTH	false	仅在回环地址开发时禁用身份验证。
SYNAPSE_NOAUTH	false	将身份验证/授权委托给隔离的可信上游网关。
SYNAPSE_MCP_ALLOW_DESTRUCTIVE	false	跳过破坏性操作的确认提示（仅限回环地址）。
SYNAPSE_MCP_MAX_CONCURRENCY	50	同时处理中的操作请求数上限。超出限制的请求会收到 HTTP 429 响应及 Retry-After。设为 0 可禁用此限制。公共探测、OAuth 发现和静态资源不受并发限制。
SYNAPSE_MCP_PUBLIC_URL	unset	OAuth 公共 URL；除回环地址开发外，必须使用 HTTPS。
SYNAPSE_HOSTS_CONFIG	unset	内联主机拓扑。省略主机协议时默认使用 SSH；本地执行需要设置 protocol: "local"。

完整变量列表请参阅 .env.example，配置详情请参阅 docs/CONFIG.md，传输、路径、传输操作、容器和 CI 运行器的信任边界请参阅 docs/SECURITY.md。

运行

# Start MCP server (stdio transport)
cargo run -- mcp

# Start HTTP server
cargo run -- serve

# CLI examples
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 示例：

{"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"}}

架构

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/synapse → service → JSON

开发

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
• Agent 使用指南见 plugins/synapse/skills/synapse/SKILL.md
• 与 synapse-mcp INVENTORY 的自动化功能对齐验证见 tests/parity.rs

文档

此 README 旨在帮助初次使用者快速了解项目，并概览可执行的操作。 权威文档和代码分布如下：

• docs/API.md：精选操作契约参考。
• docs/MCP_SCHEMA.md：MCP 架构形式和预期变更。
• docs/CONFIG.md：环境和身份验证策略。
• docs/QUICKSTART.md：本地冒烟测试。
• docs/PLUGINS.md 和 plugins/synapse/skills/synapse/SKILL.md：Agent 和市场用法。
• docs/generated/openapi.json：生成的 OpenAPI 输出。
• src/flux_service/、src/scout_service/ 和 src/mcp/：运行时权威源代码。

相关服务

• runifi - UniFi 控制器 REST API 桥接服务。
• rtailscale - 用于设备、用户和 tailnet 操作的 Tailscale API 桥接服务。
• unraid / runraid - 用于 NAS 和服务器管理的 Unraid GraphQL 桥接服务。
• rapprise - 面向多种投递后端的 Apprise 通知分发桥接服务。
• rgotify - 用于发送通知、消息、应用和客户端的 Gotify 推送通知桥接服务。
• rarcane - 用于容器及相关资源的 Arcane Docker 管理桥接服务。
• yarr - 面向 Sonarr、Radarr、Prowlarr、Plex 及相关服务的媒体栈桥接服务。
• rytdl - 媒体下载和元数据工作流服务。
• cortex - Syslog 和家庭实验室日志聚合 MCP 服务。
• axon - RAG、爬取、抓取、提取和语义搜索项目。
• labby - 家庭实验室控制平面和 Labby 网关项目。
• lumen - 本地语义代码搜索 MCP 服务。
• nugs - 用于本地 Agent 工作流的项目/软件包管理助手。
• agentcast - Agent 对话记录和活动发布项目。
• soma - 用于构建由提供方支持的新服务的 RMCP 脚手架/运行时模板。

许可证

本项目中由 Dinglebear 编写的原创部分依据 AGPL-3.0-only 授权。对于需要 AGPL 之外许可条款的组织，可提供单独的商业许可。第三方材料仍遵循其原始许可证。请参阅 LICENSING.md。