UniFi Discovery 与后端选择
当你还不清楚这个服务器暴露了哪些能力，或者你预期的某个工具不存在时，从这里开始。本技能集中的其他所有技能都假定你已做出这两个决定：由哪个后端应答，以及哪些工具实际已注册。
第 1 步：查明已注册的内容
服务器自身的能力清单是权威来源。可按以下优先顺序读取：
A2A agent card（HTTP 部署）
curl -s -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
http://127.0.0.1:3000/a2a/agent-card
该卡片在 skills 下列出每个已注册工具，并在 metadata 下汇总部署情况：
| 字段 | 说明 |
|---|---|
| metadata.toolCount | 本次部署注册了多少个工具 |
| metadata.readToolCount / writeToolCount / destructiveToolCount | 按风险层级划分的数量 |
| metadata.domains | 存在哪些能力域（network、protect、cloud 等） |
| metadata.apiType | 当前运行模式：local、cloud-v1 或 cloud-ea |
| metadata.readOnly | 是否过滤掉了变更类工具 |
| metadata.dryRun | 是否所有写操作都被强制转为预览 |
| metadata.fleet | 是否配置了 fleet 注册表 |
| metadata.apiModes | 本部署可支持的模式 |
同一卡片也通过 /.well-known/agent-card.json 提供，而 POST /a2a/discover 的发现清单会额外给出按域划分的工具清单：
curl -s -X POST -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
-H "Content-Type: application/json" -d '{}' \
http://127.0.0.1:3000/a2a/discover
直接使用 MCP 协议
# 列出服务器暴露的工具
npx @modelcontextprotocol/inspector unifi-mcp-server
仓库卡片
仓库根目录的 agent-card.json 是默认本地部署的参考卡片。它有助于快速了解完整工具面，但它只是参考：你的部署所暴露的可能更窄。应信任服务端返回的卡片，而非该文件。
第 2 步：选择后端
模式决定存在哪些工具。请求某个模式不提供的工具是最常见的失败原因。
| 模式 | 设置方式 | 可达范围 | 适用场景 |
|---|---|---|---|
| local | UNIFI_API_TYPE=local | 局域网内的控制台或网关 | 全部能力：设备、客户端、配置、防火墙、Protect |
| cloud-v1 | UNIFI_API_TYPE=cloud-v1 | UniFi 稳定的 v1 云 API | 仅站点和汇总统计 |
| cloud-ea | UNIFI_API_TYPE=cloud-ea | UniFi 抢先体验云 API | 仅站点和汇总统计 |
| fleet | 设置 DATABASE_URL，外加 UNIFI_API_TYPE | 同一服务器后端的多个控制器 | 多个控制器、单一端点 |
云模式没有按设备控制的能力。cloud-v1 或 cloud-ea 下不会注册任何客户端、设备、防火墙或 Protect 工具。如果任务需要更改设备，就需要 local 模式。
云模式确实会注册 Site Manager、connector、Mobility、InnerSpace 和 Carrier Fabric 工具，且这些工具需要 UNIFI_SITE_MANAGER_ENABLED=true 才能运行。
第 3 步：检查暴露配置
有三个设置会收窄服务器注册的工具。在假定某工具可用之前，先从卡片上读取它们。
| 设置 | 效果 | 你的应对 |
|---|---|---|
| UNIFI_PROFILE | 只注册该配置下的工具模块 | 工具缺失可能是配置原因，而非缺陷 |
| UNIFI_READ_ONLY=true | 不注册任何变更类工具 | 只有读工具可用；写工具是缺失，而非被拒绝 |
| UNIFI_DRY_RUN=true | 对每次写操作强制 dry_run=True | 每个变更都返回预览；不会发生任何改变 |
配置档有 minimal、protect、network、security、devices 和 system。minimal 是最小的有用集合。
第 4 步：确认服务器健康
# 存活检查：无需 token，不返回详细信息
curl -s http://127.0.0.1:3000/healthz
# 服务器自身的健康检查，通过工具面调用
# （作为工具调用：health_check）
health_check 报告服务器能否到达其控制器。在长时间读取或变更之前使用它，以便正确归因失败。
第 5 步：检查允许执行的操作
bearer token 的角色决定你可以运行什么。角色按权限升序排列：
| 角色 | 可运行 |
|---|---|
| viewer | 仅读工具 |
| operator | 读和写工具 |
| admin | 读、写及破坏性工具 |
| fleet-admin | 全部，包括 fleet 注册表和 token 工具 |
MCP_AUTH_TOKEN 条目可写成 <role>:<token>；裸 token 是紧急用途的 fleet-admin。客户端只发送 token 部分。
需要高于你角色的工具会以权限错误被拒绝，而非静默跳过。审计记录会指明所需的层级。
常见故障
| 现象 | 原因 | 处理方式 |
|---|---|---|
| 找不到工具 | 模式错误，或配置档不包含它 | 读取卡片中的 metadata.domains 和 apiType |
| 找不到工具，云模式 | 云模式没有按设备工具 | 使用 local 模式，或 Site Manager 工具 |
| 找不到工具，Site Manager | UNIFI_SITE_MANAGER_ENABLED 未开启 | 设为 true 并重启 |
| 缺少写工具 | UNIFI_READ_ONLY=true | 只读是服务器模式；请求将其关闭 |
| 写操作返回预览 | UNIFI_DRY_RUN=true | 预览即试运行；没有任何改变 |
| 权限被拒 | token 角色太低 | 检查角色；admin 覆盖破坏性工具 |
| 每次调用都无法到达控制器 | 控制台从该主机不可达 | 检查 UNIFI_LOCAL_HOST 以及 health_check 结果 |
安全
工具存在并不意味着你应该调用它。在做变更之前，先阅读该域对应的技能。
除非工具自身的 schema 要求，否则绝不要把凭据放入工具参数，也绝不要放入提示词、日志行或报告中。
卡片和发现清单是公开元数据。它们携带工具名称和 schema，而不携带控制器地址或凭据。