Content
# 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).
MCP Store