skills.rest
sirkirby
sirkirbyCOMMUNITY
Explore all skills by this author →
Website𝕏@sirkirbyGitHub

myco:unifi-client-data-correctness

Enforces five correctness patterns for UniFi client data retrieval across Pydantic models and GraphQL types.

777|101|Updated Apr 21, 2025
Search Tags:#Pydantic#network management#fallback logic#data correctness#graphqL#uniFi#API Integration
One-click install
npx skills add https://github.com/sirkirby/unifi-network-mcp --skill myco-unifi-client-data-correctness
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: myco:unifi-client-data-correctness
Source: https://github.com/sirkirby/unifi-network-mcp/tree/main/.agents/skills/unifi-client-data-correctness
Command: npx skills add https://github.com/sirkirby/unifi-network-mcp --skill myco-unifi-client-data-correctness

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

UniFi controller APIs return inconsistent client data across endpoints and firmware versions, causing silent data corruption: lost user-assigned names, all clients misreported as offline, and transient endpoint errors making offline clients unfindable. This Skill encodes five verified correctness patterns that prevent these bugs when modifying client data retrieval code in the unifi-mcp monorepo.

Core Features & Use Cases

  • Endpoint Selection Rules: Mandates /stat/sta as the primary source for live clients and /rest/user only for offline or historical records, with a comparison table of the 85-field coverage gap.
  • Field Mapping Correctness: Preserves name and hostname as independent fields and derives online status via an _is_online() uptime-field fallback when is_online is absent from payloads.
  • Resilient Fallback and Merge Logic: Requires try/except fallback chains that never re-raise transient read errors, and dual-source merging where live /stat/sta data wins on overlapping keys.
  • Use Case: When fixing a bug where unifi_list_clients shows all devices offline, apply Procedure 3 to replace direct is_online checks with the _is_online() helper across all three model factories and the GraphQL layer, then verify with the live smoke test.

Quick Start

Apply this skill whenever modifying or debugging UniFi client data retrieval code in clients.py, client_manager.py, or the GraphQL client types.

Frequently Asked Questions about myco:unifi-client-data-correctness

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix UniFi clients showing as offline when they are connected?▼

Replace direct is_online field checks with an _is_online() helper that falls back to uptime fields like _uptime_by_uap and uptime. The is_online field is absent from /stat/sta payloads on many firmware versions, so reading it directly marks all active clients offline.

What is the difference between the UniFi /stat/sta and /rest/user endpoints?▼

/stat/sta returns live client connections with 92+ fields including signal, uptime, and traffic data, while /rest/user returns historical snapshots with only about 7 basic fields. Use /stat/sta as the primary source and /rest/user only for offline clients or transient failures.

Why does my UniFi client data lose the user-assigned device name?▼

The bug comes from collapsing fields with an or fallback like raw.get("hostname") or raw.get("name"), which discards the name alias when both differ. Return name and hostname as independent fields in all model factories and GraphQL types.

Should UniFi API fallback logic apply to write operations?▼

No, the fallback chain applies only to read paths like client lookups. Write operations such as block, unblock, and rename must fail fast, since silently falling back on a mutation failure could mask real errors or cause inconsistent controller state.

How do I merge UniFi client data from two endpoints correctly?▼

Merge with {**user_raw, **active_raw} so /stat/sta live data wins on overlapping keys like ip, while /rest/user supplies stable user-table fields like _id and fixed_ip. Reversing the order lets stale last-known values overwrite current live data.

Related Skills

Explore More Software Engineering Skills→
NCLGISANCLGISA

unifi-network

Manage Ubiquiti UniFi Network Controller infrastructure via its REST API.

Official
Advanced
labluplablup
672

bai-cli

Tests and verifies Backend.AI REST API endpoints using the v2 ./bai CLI command reference.

Official
Intermediate
agno-agiagno-agi
41.6k

system-info

Collect system information and emit JSON with OS, Python, and hostname fields.

Official
Basic
automatedigitalautomatedigital
1

mcporter

Manage MCP servers via a unified command-line interface with JSON output.

Official
Intermediate