用途:通过 MCP 服务器查询和管理 UniFi Network Controller,覆盖设备、客户端、防火墙、VPN、路由、WLAN、Traffic Flows 与统计等,共 209 个工具。依赖 network,无可选依赖。
主要能力:默认惰性加载,仅注册元工具。unifi_tool_index 按名称/描述发现工具,可用 category、search、include_schemas 过滤;unifi_execute 按名称调用任意工具;unifi_batch 并行运行多个工具;unifi_batch_status 查看异步批处理状态。流程为先索引再执行,多个独立查询用批处理更快。
安全模型:读操作始终可用,所有 list_、get_ 与查询工具无需特殊权限。变更操作受权限门控:默认启用防火墙策略、端口转发、流量路由、QoS 规则、VPN 客户端、ACL 规则、凭证、用户组;默认禁用高风险项:网络、WLAN、设备、客户端、路由、VPN 服务器;删除操作默认禁用。权限错误会提示需设置的环境变量,格式为 UNIFI_POLICY_NETWORK_<CATEGORY>_<ACTION>=true,其中 CATEGORY 用服务器配置键(如 CLIENT_GROUPS、FIREWALL_POLICIES、OON_POLICIES),而非 tools_manifest.json 中的简写。每次变更采用预览后确认:默认调用返回预览,带 confirm=true 才执行,应先预览并展示给用户。
响应格式:返回 success/data、success/error 或 requires_confirmation/preview,需先检查 success。网络/WLAN 与 VPN 状态写入后会回读,并报告 mutation_applied、partial_success、persisted_fields、unchanged_fields、dropped_fields、coerced_fields 及写入后详情。已满足的空操作字段出现在 unchanged_fields,不使失败写入变为部分成功;失败写入不一定是回滚,重试前应检查这些字段。
限制:敏感字段默认脱敏为 REDACTED,包括 WLAN 口令(x_passphrase)、VPN 私钥/预共享密钥、整个 VPN 配置块、SNMP community 字符串、SNMPv3 密码、设备 SSH 凭据;原始值由进程策略控制(UNIFI_NETWORK_REDACT_SENSITIVE_FIELDS=false 或全局 UNIFI_REDACT_SENSITIVE_FIELDS=false),不由工具参数控制。更新时只发送要更改的字段,保持密钥不变则省略,切勿回传 REDACTED。报告须包含覆盖与限制部分,说明各来源状态、时间窗口/时区、过滤器、返回计数、分页与失败调用;计数仅指已检索记录,除非确认完整。不可用、部分或受限数据不得声称完整覆盖或整体健康。需区分观察、假设与身份,凭据事件只标识记录账户而非实际使用者。