unifi-mcp: Skill for Claude Code

Implementing New UniFi Resource Types End-to-End

This unified skill covers the complete flow for adding a new UniFi resource type from manager implementation through API exposure. Both manager/tool layer (apps/{package}/) and API layer (apps/api/) must be implemented together for a complete resource.

Prerequisites

• Understand which package owns the resource (network, protect, access).
• Know whether the resource's GET-by-ID endpoint returns 405 (Step 2A).
• Have a live controller available for validation output in PR description.
• Dependency rule: apps/api/ may only import from unifi-core, never unifi-mcp-shared.
• V2 API identifier hazard: Understand the difference between UniFi V2 ObjectID (_id) and Integration UUID semantics before implementing cross-controller queries.

---

Part 1: Manager/Tool Layer (apps/{package}/)

Step 1 — Create Manager Class

File: packages/unifi-core/src/unifi_core/<server>/managers/{resource}_manager.py

Reference packages/unifi-core/src/unifi_core/network/managers/dns_manager.py as the golden pattern. Key naming conventions: method names use the full resource name (e.g., list_dns_records, get_dns_record, create_dns_record). The class constructor takes a ConnectionManager directly — not a raw HTTP client. The @lru_cache factory function lives in the app's runtime module and takes no arguments:

from functools import lru_cache
from unifi_core.network.managers.dns_manager import DnsManager

@lru_cache
def get_dns_manager() -> DnsManager:
    return DnsManager(get_connection_manager())

Step 2 — Check for 405 Endpoints and V2 Response Shapes

2A: 405 resources (DNS, AP groups, ACL rules, filtering rules) implement get_{resource} via list-and-filter rather than a direct GET-by-ID HTTP call:

async def get_dns_record(self, record_id: str) -> dict:
    records = await self.list_dns_records()
    for record in records:
        if record.get("_id") == record_id:
            return record
    raise UniFiNotFoundError(...)