unifi-mcp: Skill for Claude Code

API Endpoint and Serializer Authoring (apps/api)

A. Adding a Resource or Action Endpoint

1. Classify the endpoint type

• Resource endpoint (GET /v1/sites/{id}/cameras): implies the resource exists; return HTTP 409 when the required product is absent.
• Action endpoint: advisory; always return HTTP 200 with a capability_not_available envelope when the capability is missing — never 404 or 409 for action endpoints.

2. Wire cursor-based pagination

Use Cursor and paginate() from apps/api/src/unifi_api/services/pagination.py:

from unifi_api.services.pagination import Cursor, InvalidCursor, paginate

cursor = Cursor.decode(cursor_str) if cursor_str else None
page, next_cursor = paginate(items, cursor=cursor, limit=limit, key_fn=key_fn)

• Cursor encodes {last_id, last_ts} as Base64 — survives new inserts; offset/page-number pagination does not.
• Default limit 50, max 200. Expose cursor as an opaque query-string param.

3. Apply the dependency rule

apps/api/ MUST only import from unifi-core. Never import unifi-mcp-shared inside apps/api/ — it couples the REST server to MCP protocol concerns.

4. Wire ManagerFactory

ManagerFactory lives in apps/api/src/unifi_api/services/managers.py. It caches one manager per (controller_id, product) pair behind asyncio locks:

manager = await factory.get_connection_manager(session, controller_id, product)

• product_kinds in the DB row is a comma-separated string. The factory splits it and raises UnknownProduct if the product isn't listed — so set product_kinds accurately when registering a controller.
• Each concurrency scope (request) shares the cached manager instance; no per-request teardown.

---

B. Phase 5A Advanced Routing Patterns

Capability-aware dispatch

When two products expose identically-named endpoint families (e.g., both Network and Protect expose /events), dispatch at request time by consulting controller.product_kinds. Route to the correct manager based on which products are active — avoids collisions without duplicate routes.