Model Context Protocol server for TP-Link Omada SDN controllers
8 tools with solid naming (verb_noun pattern) and comprehensive descriptions (avg 180 chars, well above 10-char minimum). All tools have input schemas with type definitions. However, parameter descriptions are inconsistent: some params lack descriptions entirely (e.g., 'confirm' in set_radio_channel has no description visible in schema), and output schemas are not formally documented. Error handling is present but generic. No tool annotations (readOnlyHint/destructiveHint) despite clear risk levels. The write tool (set_radio_channel) has good guard documentation but lacks confirmation-request pattern in the schema itself.
List active alerts on a site. The pagination envelope is confirmed against real hardware; the shape of an individual alert row is NOT (no alert was active during verification) - each entry includes a best-effort module/level/content/time guess AND the untouched `raw` row, so nothing is lost if the guess is wrong. See docs/api-notes.md. Requires legacy login (OMADA_USER/OMADA_PASS) - no Open API equivalent has been verified against real hardware yet.
List Insight/known clients on a site: mac, name, download/upload (bytes), duration_seconds, last_seen_ms, guest/wireless flags, vid (VLAN), and block/manager flags. This is the controller's "Insight" view (historical + known clients), not just currently-associated ones. Requires legacy login (OMADA_USER/OMADA_PASS) - no Open API equivalent has been verified against real hardware yet.
Get the Omada controller's own identity: controller_version, omadac_id, configured. Unauthenticated (GET /api/info) - works regardless of which auth mode this server is configured with.
Get the richest available detail for one device by MAC address (any common separator - colon, hyphen, Cisco-dotted, or bare - is accepted and normalized). Legacy auth: full detail (ssidOverrides, lanPortSettings, ledSetting, ...) for AP/EAP devices via /eaps/{MAC}; other device types fall back to their grid/devices summary row (no richer verified endpoint yet - see README). Open API auth: the matching (reduced-field) row from the device list. The normalized fields (see list_devices) are included, plus the complete raw response under `raw` so nothing the controller returned is lost.
Output schemas not formally documented. Tool descriptions mention what is returned (e.g., 'normalized to one consistent shape', 'raw response under `raw`') but JSON Schema output definitions are absent from visible code. LLMs cannot plan downstream calls without knowing response structure.
Parameter descriptions incomplete or missing. 'confirm' parameter in set_radio_channel lacks description in visible schema. 'site_id' descriptions are identical across tools but could be more specific about auto-selection behavior. Parameter type constraints (e.g., MAC address format, channel number range) mentioned in prose descriptions but not in JSON Schema pattern/minimum/maximum fields.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 62 | <=2025-11-25 | v2 |
Per-AP WiFi summary: 2.4GHz/5GHz channel (parsed from the controller's irregularly-formatted actualChannel string), client counts per band, and radio utilization. One entry per AP on the site, or just the one matching `mac` if given. Requires legacy login (OMADA_USER/OMADA_PASS) - the Open API device list has no per-radio fields at all (confirmed against real hardware; see README's auth x endpoint matrix).
List devices on a site, normalized to one consistent shape regardless of auth mode (see formatting.normalize_device): connected, uptime_seconds, per-radio wifi_2g/wifi_5g channel info, and every raw field this package knows how to normalize - fields unavailable in the active auth mode are present as null rather than omitted, so a caller never has to branch on auth mode. `site_id` defaults to OMADA_SITE_ID, or auto-selects if the controller manages exactly one site (legacy auth only).
List sites managed by this controller: id + name. Requires legacy login (OMADA_USER/OMADA_PASS) - see README's auth x endpoint matrix for why the Open API path can't serve this in v0.1.
Set the radio channel for a device's 2.4GHz or 5GHz band. This is a guarded write operation - see guard.py's module docstring for the full write-guard model (central allowlist, read-only gate via OMADA_ALLOW_WRITE, confirm/preview, empirical re-read verification, and an audit journal).
No tool annotations (readOnlyHint/destructiveHint/idempotentHint) despite clear risk levels. set_radio_channel is marked WRITE but schema lacks destructiveHint. All read tools lack readOnlyHint. Current MCP spec (2026-07-28) supports these annotations for agent safety.
Confirmation pattern not enforced in schema for destructive write. set_radio_channel accepts 'confirm' boolean but description does not explicitly state that confirm=false returns a preview without applying changes. This should be formalized as a Multi Round-Trip Request (result 'input_required') or clearer schema documentation.
Error handling guidance minimal. Descriptions mention auth requirements and fallback behavior but do not guide LLM on recovery steps (e.g., 'If legacy auth fails, try Open API auth' or 'If site_id not found, call list_sites first'). Error responses from code are generic OmadaMCPError without actionable next steps.