SuperAPI AI 工具集

unifi-mcp-tool-builder

编程与开发

查看项目

更新于 11-02 01:23

技能介绍

用途

该技能用于指导开发者向现有的 UniFi MCP Server 添加新的 MCP 工具,扩展 UniFi Network Controller 相关功能,同时保持项目既有的质量标准。它不同于从零构建 MCP 服务器,重点在于在现有实现上做增量扩展。

项目背景

  • 现有工具:本地模式下 343 个 MCP 工具;实际数量以注册表报告为准,由 tests/unit/test_skill_tool_references.py 校验。
  • 测试门槛:单元测试套件为质量闸门,在仓库根目录运行 pytest tests/unit/ -q --cov=src --cov-fail-under=80,覆盖率门槛为 80%。
  • 架构:FastMCP + Pydantic v2 + async/await。
  • API 支持:本地网关(完整)、Cloud V1/EA(有限)。
  • 质量要求:最低 80% 测试覆盖率,必须采用 TDD。

主要流程

第一阶段:调研与规划

明确要暴露的 UniFi 功能/端点、所属 API 模式(local、cloud-v1、cloud-ea)、面向 AI 智能体的工作流,以及所属工具类别。项目工具类别包括:设备管理、客户端管理、网络配置、防火墙与安全、WiFi/SSID 管理、QoS 与流量、备份与恢复、站点管理、拓扑与监控。

随后阅读 docs/UNIFI_API.md(覆盖 UniFi Network v10.0.156+ 的已验证端点),并注意端点可用性、API 模式差异、响应格式与认证方式的不同。参考同类现有工具源码与测试,识别输入模型、响应格式、错误处理、写操作确认、dry-run、缓存等模式。

需特别注意:并非文档中列出的所有端点都真实存在。例如 ZBF 矩阵端点不存在(应改用 Firewall Policies v2),部分统计端点文档有但不可用,Cloud API 端点支持远少于本地网关。

最后输出实施计划:工具定义(命名遵循 {action}_{resource}、描述、参数、响应格式、错误场景)、数据模型、测试策略(建议 10–15 个以上单元测试,新代码覆盖率目标 85%+)与文档更新。

第二阶段:实现

按需在 src/models/{feature}.py 创建 Pydantic v2 模型,使用 model_config(而非 Config)、extra="forbid"、完整的 Field 描述与类型注解。

在 src/tools/{category}.py 实现工具。工具为普通 async 函数,模块中每个被 src/main.py 列出的公开 async def 都会成为工具,没有 @mcp.tool() 装饰器。每个工具必须声明 @read_tool 或 @write_tool(src/utils/tool_kind.py),否则注册失败;设置 UNIFI_READ_ONLY 时仅注册读工具。注册表会传入 settings 并从公开签名中隐藏。辅助函数以 _ 开头以免被注册。

写工具须包含 confirm 与 dry_run 参数,先调用 validate_confirmation(),并在发起任何请求前返回 dry-run 结果;可选更新参数默认 None;工具内不写审计代码(注册表包装器会审计每次写操作);错误使用 src/utils/exceptions.py 中的类型,不用会掩盖原因的宽泛 except。

路径应使用 Settings 辅助方法(get_integration_path、get_protect_integration_path、get_v2_api_path)或 UniFiClient 可转换的 /ea/sites/{site_id}/... 形式,禁止硬编码 /proxy/network/...。相关工具集技能(unifi-protect-tools、unifi-network-config-tools、unifi-security-tools、unifi-cloud-fleet-tools)列出各领域的路径与注意事项。

新模块需在 src/main.py 中导入并加入 LOCAL_TOOL_MODULES 或 CLOUD_TOOL_MODULES,以及相应 UNIFI_PROFILE 集合;通过 UPDATE_TOOL_TIERS=1 pytest tests/unit/fleet/test_tiers.py 重新生成风险分级快照;破坏性工具需使用 delete、remove 或 bulk_delete_ 前缀,或加入 DESTRUCTIVE_TOOLS(src/tool_registry.py);名称含风险词的写工具也需登记到 DESTRUCTIVE_TOOLS 或 RISKY_NAME_EXEMPTIONS。

代码质量:black、isort、ruff check --fix、mypy。

第三阶段:测试驱动开发

项目要求 TDD:先写失败测试,再实现至通过,然后重构,新代码覆盖率达 85%+。测试文件位于 tests/unit/tools/test_{module}_tools.py。文档给出 fixture、AsyncMock 客户端辅助函数及三个示例测试(仅发送变更字段、缺少 confirm 时拒绝、dry-run 不发请求)。

注意:asyncio_mode = auto,测试无需 asyncio 标记;--strict-markers 仅允许 integration 标记;mock 的 aexit 应返回假值,否则会吞掉异常。

覆盖场景包括:正常路径、写操作确认要求、dry-run、输入校验、错误处理(未找到、API 错误)、可选参数、边界情况(空结果、分页)、响应格式校验。

运行方式:pytest tests/unit/test_your_category.py -v,配合 --cov 与 --cov-report=term-missing/html 检查覆盖率。

第四阶段:文档

在 API.md 对应章节补充工具说明:描述、用途、参数、返回 JSON(含 dry-run 响应示例)、调用示例、错误处理(ValidationError、ResourceNotFoundError、APIError)、API 端点、支持的 API 模式。若属重要功能,更新 README.md 功能列表;在 CHANGELOG.md 的 Unreleased 下添加条目。

第五阶段:质量验证

运行完整单元测试与覆盖率检查,执行 black、isort、ruff、mypy、bandit 及 pre-commit;可用 uv run mcp dev src/main.py 启动 MCP Inspector 进行手动测试(原文此处内容不完整)。

适用场景

适用于已了解 UniFi MCP Server 代码库、需要按项目规范新增或扩展 MCP 工具的开发者。

限制

原文未说明该技能本身的安装方式、收费、价格与具体支持平台;API 端点可用性需以实际控制器验证,Cloud EA 支持有限。