unifi-network-mcp image: Dockerfile + Gitea Actions build workflow + README

2026-08-17 02:34:21 +00:00
commit 9255f72ddc
3 changed files with 211 additions and 0 deletions
@@ -0,0 +1,63 @@
+# unifi-network-mcp
+
+The [UniFi Network MCP server](https://github.com/sirkirby/unifi-mcp)
+(`unifi-network-mcp` on PyPI) packaged as a container image, built by Gitea
+Actions in this repo. Runs the server in streamable-HTTP mode so MCP clients
+(Hermes Agent) can call it over the network without carrying any controller
+credentials — `UNIFI_HOST` / `UNIFI_USERNAME` / `UNIFI_PASSWORD` live only in
+the deployed server's own Kubernetes secret.
+
+- **Image:** `gitea.williammiceli.systems/hermes/unifi-network-mcp`
+- **Consumed by:** `William/Kubernetes_Cluster0` → `cluster0 (Personal)/#active/#applications/ai-0 (Hermes Agent)/ai-0-3 (UniFi MCP)/`
+
+## Why this server
+
+Two active open-source UniFi MCP servers were evaluated:
+
+| | `unifi-network-mcp` (sirkirby/unifi-mcp) — chosen | `unifi-mcp-server` (enuno) |
+|---|---|---|
+| Activity | Very active (PyPI release every few days; 116 releases) | Slow (5 releases, last May 2026) |
+| Tools | 189 Network tools (stable), 15 categories incl. firewall, clients, devices, stats, VPN | ~130 tools across network areas, broader but less mature |
+| Auth model | Local controller login (username/password) | Local API key (`UNIFI_API_KEY`) |
+| HTTP transport | Native streamable-http + DNS-rebinding protection + Host allowlist | SSE/streamable-http, no caller auth |
+| Safety | Preview-then-confirm for all mutations; policy gates; secret redaction in responses | Standard |
+
+Local username/password login matches the UniFi controller's local-account
+model directly and is the simplest credential Will needs to create (one
+dedicated local admin/service account). The response redaction
+(Wi-Fi passphrases, VPN keys, API tokens → `***REDACTED***`) keeps controller
+secrets out of agent context by default.
+
+## Updates (fully automatic)
+
+The build workflow (`.gitea/workflows/build.yaml`) runs:
+
+1. **Weekly, Monday 06:00 UTC** — resolves the newest published
+   `unifi-network-mcp` version on PyPI; if no image exists for it yet, builds
+   and pushes `v<version>` (and `latest`). This lands ~7 hours before the
+   cluster0 image-update cron (Monday 13:00 UTC), which then bumps the
+   deployment's image tag exactly like any other app.
+2. **On push to `main`** — e.g. after bumping the Dockerfile's default
+   `UNIFI_NETWORK_MCP_VERSION` ARG.
+3. **Manual dispatch** — Actions → build → Run workflow, optionally with an
+   explicit version.
+
+Skips automatically when the resolved version is already published.
+Registry login uses a dedicated scoped PAT (`REGISTRY_TOKEN` repo Actions
+secret, `write:package`) — Gitea's container registry rejects scoped
+token requests from the Actions job token (upstream issue #23642).
+
+## Runtime configuration
+
+Set at deploy time by the Kubernetes manifests (never baked in):
+
+| Env | Purpose |
+|---|---|
+| `UNIFI_HOST` | Controller address (required — server refuses to start without it) |
+| `UNIFI_USERNAME` | Local controller admin/service account (from the server's own secret) |
+| `UNIFI_PASSWORD` | Password for that account (from the server's own secret) |
+| `UNIFI_VERIFY_SSL` | `false` (controller uses a self-signed certificate) |
+| `UNIFI_MCP_ALLOWED_HOSTS` | Trusted Host/Origin for the server's DNS-rebinding protection |
+
+Endpoints: `/mcp` (streamable HTTP; FastMCP default path). No `/health`
+endpoint upstream — Kubernetes probes use tcpSocket.