omada-controller-mcp

# omada A collection of network analysis tools for the home lab. The repository is a single monorepo that currently houses the **Omada Controller MCP server** — a Model Context Protocol server for inspecting, diagnosing, RF scanning, and optimizing EAPs (access points) on a self-hosted TP-Link Omada Controller. ## Tools ### Omada Controller MCP server Lets AI agents query the Omada Controller API (device inventory, client roaming/disconnect timelines, AP health, RF scans) and optimize Wi-Fi in a change-measure-validate loop, with an allow-list API firewall and dry-run safety. Includes an interactive setup wizard and two agent skills: `device-network-dossier` for per-device behavior analysis and `wifi-site-audit` for whole-site Wi-Fi audits with scorecards and a prioritized improvement plan. > See [omada-mcp-server/README.md](omada-mcp-server/README.md) for setup, > usage, and the setup wizard. ### How it works: OpenAPI → tools, filtered by an allow list The controller exposes its full REST API as an **OpenAPI document** (`openapi.json`, or a live URL). At startup the server loads that document and generates one **MCP tool per endpoint** with FastMCP, so the tool set always matches the controller's actual API version — no hand-maintained wrappers, and the same code adapts to different controller versions and firmware as their schemas evolve. Two mechanisms keep the surface small and cheap: 1. **Allow list.** Only endpoints matching the configured patterns become tools. Each route is either a safe, read-only diagnostic operation or a deliberately scoped mutation that should run with the `MCP_DRY_RUN` guardrail. This is the firewall that keeps the agent away from sensitive areas (switch/gateway management, vouchers, VPN configs, user accounts). 2. **Description sanitization.** Every tool/parameter description is cleaned before it is handed to the model: HTML tags are stripped, whitespace is normalized, and the controller's trailing boilerplate (permission lists, error-code tables) is removed. Regex `pattern` hints that are not valid ECMA-262 are dropped so LLM providers accept the generated schemas. Why both matter: exposing the whole API would generate on the order of a thousand tools, each with verbose descriptions — a massive amount of context pushed into every conversation, costing tokens on each request and distracting the model. Filtering to the handful of EAP/diagnostics routes and slimming their descriptions keeps the toolset to a few dozen tools with crisp help text, cutting token consumption by roughly an order of magnitude. The allow list is defined in `omada-mcp-server/wlanoptimization.txt` (or via `ALLOWED_ENDPOINTS` inline, falling back to built-in defaults). It uses `fnmatch` wildcards, one pattern per line, `#` for comments. The shipped file is trimmed for Wi-Fi/EAP work. Because it is just patterns, you can swap in a different surface without touching code — for example, a switch-management allow list: ``` # Switch / port management variant /openapi/v1/{omadacId}/sites/{siteId}/switches* /openapi/v1/{omadacId}/sites/{siteId}/ports* /openapi/v1/{omadacId}/sites/{siteId}/switch-qos* /openapi/v1/{omadacId}/sites/{siteId}/stacks* ``` Point `ALLOWED_ENDPOINTS_FILE` at that file and restart the server to trade the EAP toolset for a switch toolset. ### `mcp.sh` Quick lifecycle control for the MCP server: ```bash ./mcp.sh start # start the server detached (setsid), log to omada_mcp.log ./mcp.sh stop # gracefully stop the server (SIGTERM), force-kill after 8s if needed ``` Requires the project's `.venv` to be set up (run the setup wizard first). ## Layout ``` mcp.sh # start/stop the MCP server omada-mcp-server/ # the MCP server itself (see its README) scripts/setup_omada.py # interactive setup wizard skills/device-network-dossier/ # per-device network dossier skill skills/wifi-site-audit/ # whole-site Wi-Fi audit skill specs/ # design documents ``` ## Contributing All code, documentation, and specs in this repository must be written in English. Python is the runtime for the MCP server (see the server README for its conventions).