rustunifimcp

rustunifimcp

面向 UniFi Network 的企业级 MCP 服务——精选工具、范围受限的访问权限、经审计的变更控制
mechub 项目——自主可控的网络安全自动化

非官方社区项目。 这是一个独立的社区项目，不声称与 Ubiquiti Inc. 有任何关联，也不代表其认可本项目。产品名称和商标仅用于标识本软件可互操作的系统。

---

rustunifimcp 是 mechub MCP 服务系列中面向 UniFi Network 的成员。它 为 UniFi 提供的功能，正如 rustjunosmcp 为 Junos 提供的功能，以及 rustpanosmcp 为 PAN-OS 提供的功能：在某个供应商的管理 API 上构建精选、范围受限且经审计的 MCP 接口。

它以 mecmcp-native 方式构建——完全不包含本地身份验证、传输、审计、 策略、清单或变更控制代码。所有这些都由共享的 Rust 基础库 mecmcp 提供。此处编写的内容仅包括 UniFi 资源模型、 工具接口和工作流，不包含其他内容。

UniFi 是该系列中首个完全没有候选配置的供应商——没有暂存区、没有提交，也没有设备端验证。Junos 和 PAN-OS 支持候选配置/提交；Proxmox 和 Security Director 则具有可将审批与之关联的服务端任务语义。UniFi 只有针对实时配置的即时 REST 写入，没有其他机制，因此它将真正检验 mecmcp-changeset 能否泛化到创建它的两家供应商之外。

状态

维护者的基础设施上每天都在使用（alpha）。对旧版服务的依赖已退役。

rustunifimcp v0.6.6 通过 TLS 从两台生产来宾机提供完整功能，包括读取、工作流、运维操作和变更控制：LXC 981 处于实验室模式，LXC 982 受双人控制。 unifi-mcp-legacy 注册项已移除；现在没有任何请求会再路由到 Python 服务。

LXC 980 本身未作任何改动，仍在运行。 它被标记为 notmechub;protected，而且我们从未获准修改它：退役依赖项并不意味着要对这台来宾机采取操作。它仍可作为回滚途径——重新添加其注册项即可恢复旧功能；停止或销毁它是由其所有者另行决定的事项。

来宾机	角色	端点
981 prod-unifimcp	日常使用的实验室来宾机，--lab-mode，TLS	https://prod-unifimcp.example.org:30033/mcp
982 prod-unifi2mcp	日常使用的实验室来宾机，双人控制，TLS	https://prod-unifi2mcp.example.org:30033/mcp
622 test-twoperson-unifi	测试环境，双人控制	http://test-twoperson-unifi.example.org:30033/mcp
623 test-labmode-unifi	测试环境，--lab-mode	http://test-labmode-unifi.example.org:30033/mcp

与旧版功能的对照记录在 docs/PARITY-AUDIT.md：在使用窗口内的 33 个旧版工具中，31 个已实现，并通过实时控制器验证；1 个已实现但尚未验证（execute_port_action，可通过 unifi_device_action action=port_action 调用——仅支持 PoE 电源循环，需启用 --allow-direct-commit，且未在实时环境中测试，因为这会中断正在使用的交换机端口）；另有 1 个已接受的缺口（set_device_port_overrides——在 10.5.67 上没有经过验证的写入路径）。

文档	内容
PLAN.md	阶段顺序及两次切换，一目了然
docs/HOW-TO-SETUP-LXC.md	如何从零开始构建 rustunifimcp Proxmox LXC
docs/HOW-TO-SETUP-DOCKER.md	如何在 Docker 中运行 rustunifimcp，包括双人控制和实验室模式
docs/superpowers/specs/2026-08-26-rustunifimcp-cutover-design.md	构建与切换设计：部署拓扑、控制器信任、阶段详情及风险
docs/superpowers/specs/2026-07-24-rustunifimcp-design.md	原始设计——对工具功能范围、API 标记和变更控制适配仍具有权威性

支持的最低控制器版本

支持的最低版本：UniFi Network Application 10.5.67 / UniFi OS Server 5.1.37

此服务要求 UniFi Network 控制器至少运行 10.5.67 版本（Network Application）或 5.1.37 版本（UniFi OS Server）。这些版本包含本项目依赖的 2026 年 CVSS 10 安全修复（SAB-062、SAB-064、SAB-066/067），可确保安全的 API 访问。

已在 rustunifimcp 测试环境和测试固件集上验证最低版本。若在较旧的控制器版本上运行，可能会遇到端点缺失或未处理的 API 演进问题。

替代的项目

家庭实验室运行的是 enuno/unifi-mcp-server（Python / FastMCP）。它是一个功能强大的 API 客户端，但有两个问题，而本项目正是为了解决这些问题。

工具泛滥。 它通过反射自动注册 src/tools/ 中的每个公共异步函数——37 个模块中的 205 个函数，最终变成大约 270 个 MCP 工具。没人选择了这个数量。rustunifimcp 的目标是 22 个：基于资源枚举的类型化读取原语、变更控制生命周期、范围明确的运维操作，以及四个名副其实的工作流。22 个工具都能端到端完成实际工作——没有任何工具只是挂名，却在每次调用时都拒绝执行或返回空结果。

MCP 层缺乏安全防护。 它通过不带身份验证令牌、无作用域、无审计记录且无限流的纯 HTTP 进行监听。任何能够访问该端口的对象都能不受限制地写入控制器。rustunifimcp 则完整继承了 mecmcp 安全层。

工具目录

读取原语是 unifi_list_resources 和 unifi_get_resource 背后的精简接口。每种 kind 在到达模型之前，都会经过 rustunifimcp-core::redact 中记录的允许列表或扫描处理——详见下文的设计亮点。

工具	备注
unifi_list_resources	kind = station | device | network | wlan | port_profile | dhcp_reservation | firewall_policy | firewall_zone | firewall_group | firewall_rule | port_forward | static_route | traffic_route | radius_profile
unifi_get_resource	kind、id
unifi_query_stats	subject = site | device | station | wlan | flow | event，以及一个时间窗口
unifi_search	对站点、设备和站点进行全文搜索
unifi_list_sites

firewall_rule、port_forward 和 static_route（MEC-509）分别是旧版（非基于区域）的规则集、端口转发规则和静态路由——目前仅支持读取；无法通过 unifi_stage_change 写入这些内容。subject=event 可以访问控制器的事件日志。

unifi_backup_action（MEC-516）提供 list 和 trigger：list 返回控制器保留的备份，最多 100 条，并像其他列表型工具一样包含 truncated 标记；trigger 会启动一次新备份。 完全不提供 download 和 validate（MEC-505：已从操作枚举中移除，而非仅仅挂出后再拒绝）——这两项都需要传输原始 .unf 文件，而该服务目前尚不支持此操作。 restore 永久拒绝执行；恢复备份会覆盖整个配置，因此必须通过变更集生命周期进行。

使用 Docker 运行（stdio）

适合工具目录的 stdio 调用会将镜像的 HTTP CMD 替换为 --transport stdio。将 controllers.json（格式： packaging/examples/controllers.example.json） 和控制器 API 密钥文件放入 etc/，并为容器提供可写的 state/ 目录，用于存放变更集和审计 HMAC 密钥。两者都必须归镜像的 UID/GID 65532:65532 所有，文件权限设为 0600：

mkdir -p etc state
# etc/controllers.json  -> "api_key_file": "/etc/unifimcp/api.key"
# etc/api.key           -> the controller API key
sudo chown -R 65532:65532 etc state
sudo chmod 0700 etc state
sudo chmod 0600 etc/controllers.json etc/api.key

docker run --rm -i \
  -v "$PWD/etc:/etc/unifimcp:ro" \
  -v "$PWD/state:/var/lib/unifimcp" \
  ghcr.io/mechubsec/rustunifimcp:latest \
  --transport stdio

该服务在 MCP 注册表中的名称为 io.github.mechubsec/rustunifimcp，其条目运行的正是这条 stdio 命令。同一镜像也发布在 Docker Hub，地址为 docker.io/mechub/rustunifimcp。

stdio 不携带调用方身份，因此变更集审批和直接提交工具都会被拒绝；如需双人变更控制，请使用 docs/HOW-TO-SETUP-DOCKER.md 中的可流式 HTTP 配置。

设计亮点

三个 API 接口面，均有标注。 UniFi 支持的 Integration API 远比控制器实际能执行的操作受限，因此保留了私有的 /api/s/ 和 /v2/api/ 路由 — 但每个端点都会在代码中标注其标签，而且私有端点受 controllers.json 中按控制器设置的显式 allow_private_api 标志保护，而非令牌作用域限制。仅支持官方接口的部署是一种真正可运行的配置，不会因控制器升级而在不知情的情况下失效。

如实适配变更控制。 UniFi 没有候选配置，也没有提交操作。变更集生命周期通过客户端捕获变更前状态、本地验证、依次应用和尽力回滚来实现 — 工具说明也如实写明了这一点。批准 UniFi 变更集的操作员并不会获得提交确认语义，服务也不会假装如此。unifi_approve_change_set 需要人工审批者：服务会将调用者令牌中的 actor_type 传递给 mecmcp，而 mecmcp 会拒绝来自 agent 或未标注归属（stdio）的调用者的任何审批 — 只有 actor_type: human 才能审批。使用 rustunifimcp token add ... --actor-type human 为审批者签发令牌。actor_type 是操作员签发时自行声明的属性，并非由服务验证；如果将标记为 human 的令牌交给大模型 Agent，就会绕过这道限制。

多控制器。 控制器存储在清单注册表中，而非环境变量里，因此一个实例可以服务多个控制器，令牌也可以限定为其中的一部分。

HTTP 默认启用限流，而非开放访问。 默认会强制执行每 IP 和每令牌的请求速率、并发会话数以及请求体大小限制（LimitsConfig::default()）；每项限制也都有对应的 CLI 标志（参见 rustunifimcp --help），操作员无需分叉代码即可调整这些限制。始终会挂载无需身份验证的 /healthz（进程运行状态）和 /readyz（未配置依赖项检查，因此“就绪”状态与“运行”状态一致）。/metrics 默认关闭（--enable-metrics）；启用后，仅允许回环地址的调用者访问。

许可证

基于 MIT 许可。