本资料是 UniFi MCP Server 中关于云端与多控制器舰队（Fleet）工具的开发说明，面向需要新增、修改或测试此类 MCP 工具的开发者。
一、用途与模块结构 云端工具调用 https://api.ui.com（Site Manager 与连接器代理），舰队代码让一个服务器服务多个控制器。资料给出各模块及工具数量：site_manager.py（16 个，如 list_all_sites_aggregated、get_isp_metrics、list_hosts）、connector.py（10 个）、integration_api.py（14 个）、sites.py（3 个）、mobility.py（8 个）、innerspace.py（6 个，只读）、carrier.py（11 个）。舰队工具在函数内部构建而非模块级定义，包括 list_controllers、select_controller、get_active_controller，以及 DATABASE_URL 存在时注册的管理工具（11 个）和只读舰队工具（fleet_health、fleet_sites、fleet_inventory、fleet_compare_versions、fleet_compare_sites、fleet_fanout）。
二、API 模式与门控 APIType 分为 local、cloud-v1、cloud-ea，代码默认为 cloud-ea。云端模式只注册 _CLOUD_TOOL_MODULES 列出的模块，并在云端模式下排除 get_site_statistics（其端点在云 API 返回 404），共 71 个工具（含 4 个舰队工具）；本地模式同时注册两组列表。Site Manager 系列工具需 UNIFI_SITE_MANAGER_ENABLED=true，mobility、innerspace、carrier 通过各自的 _require_cloud_api() 检查，connector 工具内联重复该检查。SiteManagerClient 使用 https://api.ui.com/v1/ 基址与 X-API-KEY 头；连接器调用走 connector/consoles/{console_id}/proxy/{network|protect}/{path}，并对 console_id 与 path 做严格校验（字符集、长度上限、拒绝 ?、#、%、\ 等），使调用方始终限定在代理前缀内。集成路径由 settings.get_integration_path() 给出。
三、按调用路由 路由发生在注册表包装器中。每个被路由工具带有关键字参数 controller。FleetRouter.resolve() 依次使用显式参数、select_controller 的会话选择、注册表默认值。注册两个及以上控制器时，写操作若会回退到默认值会抛出 ValidationError。工具通过 ControllerProfile.apply_to() 获得按控制器的 Settings，仅连接字段可不同，只读等安全开关保持进程级。select_controller 在无状态 HTTP 模式（MCP_STATELESS_HTTP）下被拒绝。
四、舰队基础设施 无 DATABASE_URL 时 EnvRegistry 只包含名为 default 的控制器；有则使用 PostgresRegistry，按刷新间隔或 Redis 变更事件更新，凭据以 UNIFI_FLEET_CREDENTIAL_KEY 加密。ClientPool 为每个控制器维护 HTTP 客户端、限流器与熔断器，上限由 UNIFI_FLEET_MAX_OPEN_CLIENTS 控制。限流按 UNIFI_RATE_LIMIT_REQUESTS/UNIFI_RATE_LIMIT_PERIOD，有 Redis 时跨副本共享窗口、云调用按 API key 共享，无 Redis 时按 UNIFI_FLEET_EXPECTED_REPLICAS 均分。ReadCache 需 UNIFI_CACHE_ENABLED 与显式 Redis 配置，仅缓存 CACHED_MODULES 中不含云模块的模块，被缓存工具增加 fresh 参数，非 dry-run 写操作清除该控制器缓存。worker 运行健康与同步任务，控制器按 rendezvous 哈希与 Redis 租约在 worker 间分配。fleet_fanout 只运行带 controller 参数的只读工具，每个控制器返回 {ok, data|error}，写操作永不 fan-out，受并发、超时与截止时间三个限制约束。配置 Redis 时，经验证的 Webhook 投递在本地处理后被发布到 unifi:webhooks:v1:events，消息带源实例 id。安装时 pyproject.toml 的 fleet extra 增加 redis、SQLAlchemy、asyncpg 与 alembic。
五、认证、角色与审计 网络传输在无认证时拒绝启动。MCP_AUTH_TOKEN 存放静态 bearer token；有数据库时 FleetTokenVerifier 校验以 umcp_ 开头、仅存 SHA-256 哈希的服务器签发令牌，可按角色、模块与控制器标签限制。角色分 viewer（读）、operator（读写）、admin（增加破坏性操作）、fleet-admin（全部）。stdio 调用者与 MCP_AUTH_TOKEN 调用者默认 fleet-admin，除非 UNIFI_STDIO_ROLE 降低。每次变更调用写入哈希链的尝试记录与结果记录，UNIFI_AUDIT_FAIL_CLOSED 开启时写入失败即拒绝调用，可用 python -m src.utils.audit_verify 验证日志。
六、写工具约定 签名包含 confirm 与 dry_run，函数先调用 validate_confirmation，在创建客户端前返回 dry-run 结果。DESTRUCTIVE_TOOLS 包含全部 8 个变更型连接器工具与 suspend_carrier_subscriber；Carrier 写操作影响面最大，须保持 confirm 门控。工具名含风险词需登记到 DESTRUCTIVE_TOOLS 或 RISKY_NAME_EXEMPTIONS，失败用例会给出提示；可用 UPDATE_TOOL_TIERS=1 pytest tests/unit/fleet/test_tiers.py 重新生成快照。
七、模型、响应与测试 模型位于 src/models/ 下，使用 populate_by_name=True、extra="allow" 与 camelCase 别名。列表工具返回 {count, data}，Integration API 列表另返回 offset、limit、totalCount；许多 site_manager 工具返回原始 dict 或 list。测试方面：工具测试 patch 客户端（配 site_manager_enabled=True 的 settings），客户端测试用 httpx.MockTransport，Redis 测试用 fakeredis，Postgres 测试用 pgserver 启动真实服务，make verify-fleet-scale 在本地跑 3 个副本与 2 个 worker。
八、注意事项与已知缺陷 新增设置必须同时写入 API.md 与 .env.example。Mobility、InnerSpace、Carrier Fabric 的规格快照在 scripts/，上游只托管当前版本，需要对比时保留旧快照。MCP resources 仍读取默认控制器而非路由目标。负载均衡后的有状态 HTTP 需按 mcp-session-id 做粘性路由。工具模块按基础 UNIFI_API_TYPE 一次性选择，混合舰队可设 UNIFI_MIXED_MODE=true 同时注册云与本地模块。已知缺陷：SiteManagerClient 硬编码基址，忽略 UNIFI_CLOUD_API_URL，也不使用连接池与限流器。