@coffeerunhobby/mcp-ha-connect 1.5.3 → 1.5.5

package/AGENTS.md

@@ -0,0 +1,411 @@
+# mcp-ha-connect -- Codex Agent
+
+## Identity & Scope
+
+This agent owns the **mcp-ha-connect MCP server** — a Model Context Protocol server for
+Home Assistant, TP-Link Omada, and Local AI integration.
+
+**Repo:** `github.com/coffeerunhobby/mcp-ha-connect`
+**npm:** `@coffeerunhobby/mcp-ha-connect`
+**Docker:** `ghcr.io/coffeerunhobby/mcp-ha-connect`
+**Live endpoint:** Cloudflare domain → NAS Docker port 3000 (domain in NAS `.env`)
+
+**Working directory:** `C:\workspace\mcp` — this is the canonical copy.
+`W:\mcp-homeassistant` is a stale export at v0.8.0 — ignore it.
+
+---
+
+## Stack
+
+- **Runtime:** Node.js 20+ (dev machine uses nvm)
+- **Language:** TypeScript, compiled to `dist/` via `tsc`
+- **MCP SDK:** `@modelcontextprotocol/sdk`
+- **Transport:** Streamable HTTP (port 3000, path `/mcp`)
+- **Auth:** JWT bearer tokens with RBAC permission system
+- **Plugins:** Home Assistant · TP-Link Omada SDN · Local AI (Ollama/OpenAI-compat)
+- **Tests:** Vitest (829 unit tests) + integration tests in `tests/integration/`
+- **Container:** Alpine Node image, deployed on Synology NAS via Docker Compose
+
+---
+
+## Infrastructure
+
+| Resource | Address | Notes |
+|---|---|---|
+| **MCP server** | `mcpserver.10.0.0.18.nip.io:3000` | NAS Docker container |
+| **Home Assistant** | `homeassistant.10.0.0.19.nip.io:8123` | |
+| **Omada controller** | `omada.10.0.0.18.nip.io:8043` | HTTPS, self-signed cert |
+| **Ollama** | `ollama.10.0.0.17.nip.io:11434` | model `phi4:14b` |
+| **n8n** | `n8n.10.0.0.18.nip.io:5678` | also exposed via Cloudflare |
+| **NAS Docker path** | `/volume1/docker/mcp-ha-connect/` | compose.yaml + .env |
+| **Cloudflare** | proxies public domain → NAS port 3000 | domain stored in `.env` |
+
+---
+
+## Secrets & Credentials
+
+All secrets live in the NAS `.env` file and as **Windows User environment variables**.
+Never store token values in source files, commit messages, or this file.
+
+| Variable | Purpose |
+|---|---|
+| `NPM_MCP_HA_TOKEN` | npm Granular token for publishing |
+| `GHCR_TOKEN` | GitHub PAT with `write:packages` scope |
+
+### Retrieve for use
+
+```powershell
+$npmToken  = [Environment]::GetEnvironmentVariable('NPM_MCP_HA_TOKEN', 'User')
+$ghcrToken = [Environment]::GetEnvironmentVariable('GHCR_TOKEN', 'User')
+```
+
+### npm token requirements
+
+The npm token must be **Granular type** with:
+- Scope `@coffeerunhobby` → **Read and write** (scope-level, not per-package)
+- **Bypass two-factor authentication** ✅ checked
+
+Create at: npmjs.com → Access Tokens → Generate New Token → Granular Access Token
+
+**Critical:** Never run `npm logout` — it revokes the token server-side and deletes it
+from npmjs.com. If the token disappears from the web UI, that's why.
+
+---
+
+## Release Process
+
+### 1. Pre-flight
+
+```powershell
+cd C:\workspace\mcp
+npm test          # all tests must pass
+npm run build     # must compile clean
+npm run lint      # ZERO errors AND zero warnings (see Code Quality policy)
+```
+
+### 2. Version bump
+
+Update **both** files to the new version:
+- `package.json` → `"version": "X.Y.Z"`
+- `src/version.ts` → `export const VERSION = 'X.Y.Z';`
+
+Update `docs/CHANGELOG.md` with the new version section.
+
+### 3. Commit & tag
+
+```powershell
+git add .
+git commit -m "vX.Y.Z - <short description>"
+git tag vX.Y.Z
+git push origin main
+git push origin vX.Y.Z
+```
+
+Create the GitHub Release at:
+`https://github.com/coffeerunhobby/mcp-ha-connect/releases/new?tag=vX.Y.Z`
+
+### 4. npm publish
+
+**Preferred: interactive login (browser).** Granular tokens keep getting revoked, so the
+reliable path is an interactive `npm login`, which opens the browser for auth. The agent
+**cannot** complete this alone — it MUST ask the user to run/confirm the browser login,
+then publish together:
+
+```powershell
+cd C:\workspace\mcp
+npm login                  # opens browser — USER completes this, agent waits
+npm whoami                 # must print the account name, not 403
+npm publish --access public
+```
+
+**Do NOT run `npm logout`** afterward — it revokes any granular token server-side.
+
+> Agent rule: when a release reaches this step, STOP and hand off to the user — the
+> **user owns npm publish** and runs it themselves. They authenticate with a **passkey**
+> (WebAuthn), so the publish cannot be automated from the agent side and there is no
+> usable stored/granular token to fall back on. The agent's job at this step is:
+> 1. Get everything else release-ready (tag, GitHub Release, all gates green).
+> 2. Tell the user the package is ready to publish and let them run
+>    `npm publish --access public` (passkey prompt).
+> 3. Verify afterward with `npm view @coffeerunhobby/mcp-ha-connect version` /
+>    `dist-tags` — do NOT rely on `npm whoami` from the agent (it returns 401 because the
+>    agent has no session; that is expected, not a failure).
+> Do not attempt `npm login`/`npm publish` from the agent, and never fall back to a stored
+> token — confirmed (2026-06-09, v1.5.1) that the user handles this leg via passkey.
+
+### 5. Docker build & push
+
+Docker Desktop must be running.
+
+```powershell
+$ghcrToken = [Environment]::GetEnvironmentVariable('GHCR_TOKEN', 'User')
+$ghcrToken | docker login ghcr.io -u coffeerunhobby --password-stdin
+
+cd C:\workspace\mcp
+docker build --no-cache `
+  -t ghcr.io/coffeerunhobby/mcp-ha-connect:X.Y.Z `
+  -t ghcr.io/coffeerunhobby/mcp-ha-connect:latest .
+
+docker push ghcr.io/coffeerunhobby/mcp-ha-connect:X.Y.Z
+docker push ghcr.io/coffeerunhobby/mcp-ha-connect:latest
+```
+
+Use `docker build`, not `docker buildx build --platform`. The NAS is amd64 and a plain
+build on a Windows/amd64 host produces the correct image.
+
+### 6. Deploy to NAS
+
+```bash
+cd /volume1/docker/mcp-ha-connect
+docker compose pull && docker compose up -d
+docker compose logs --tail=30
+```
+
+---
+
+## NAS `.env` — critical settings
+
+```env
+MCP_HTTP_BIND_ADDR=0.0.0.0
+```
+
+Must be `0.0.0.0`, not `127.0.0.1`. Docker port mapping requires the server to listen on
+all interfaces inside the container — loopback only means Cloudflare gets a 502.
+
+```env
+MCP_HTTP_ALLOWED_ORIGINS=...,<cloudflare-domain>,https://<cloudflare-domain>
+```
+
+Must include both the bare hostname AND the `https://` form of the Cloudflare domain.
+The MCP SDK checks the `host` header (no protocol) for DNS rebinding protection AND
+the `origin` header (with protocol) for CORS.
+
+---
+
+## Omada SDN — known issues
+
+**After upgrading the Omada controller version**, the `OMADA_OMADAC_ID` changes.
+Error code `-44106` is returned for BOTH wrong credentials AND wrong `OMADA_OMADAC_ID` —
+the API does not distinguish between them.
+
+**To get the new Omada ID:**
+Omada web UI → Settings → Open API → click the eye icon → copy **Omada ID**.
+
+```bash
+sed -i 's/OMADA_OMADAC_ID=.*/OMADA_OMADAC_ID=<new-id>/' /volume1/docker/mcp-ha-connect/.env
+docker compose up -d
+```
+
+If Omada is unreachable or credentials are wrong, the server **gracefully degrades** —
+Omada tools are disabled but HA and AI keep working. Set `OMADA_PLUGIN_ENABLED=false`
+to disable Omada entirely while troubleshooting.
+
+**`OMADA_SITE_ID` is validated at startup against the live site list** (the controller is
+the source of truth; the env var is only a selector). If `OMADA_SITE_ID` is set but **not**
+present on the controller — a site id can drift after a controller migration, exactly like
+`OMADA_OMADAC_ID` — the **Omada plugin is disabled** at boot with a `logger.error` that
+names the bad value and lists the valid sites (HA + AI stay up). This turns the old failure
+mode (a silent default scoping every read to a dead site → later "user does not have
+permissions to access this site") into a loud, self-diagnosing startup error. Fix by setting
+`OMADA_SITE_ID` to one of the listed ids. Validation lives in `checkConfiguredSite()`
+(`src/omadaClient/site.ts`); a *valid* default still auto-resolves, so site-scoped reads need
+no explicit `siteId`.
+
+---
+
+## Code Quality — fix every error and warning
+
+**Always fix errors AND warnings. Never label something "pre-existing debt" and move on.**
+
+- `npm run lint`, `npm run build`, and `npm test` must all be **completely clean** —
+  zero errors, zero warnings — before a change is considered done.
+- If you touch a file (or a release surfaces lint output) and find existing errors or
+  warnings, they are now yours to fix. "It was already broken" is not an acceptable
+  reason to leave it.
+- **Exception — release timing:** do not cut a patch release *solely* to clean up lint.
+  If quality issues are found right after a release has shipped, fold the fixes into the
+  **next feature's** commit rather than churning a `vX.Y.(Z+1)`. Outstanding cleanup of
+  this kind is tracked in `.Codex/NEXT-SESSION.md` so it isn't forgotten.
+
+> No lint cleanup currently outstanding. (The former `Function`-type warnings in the
+> test mock helpers were resolved — `npm run lint --max-warnings=0` is clean as of v1.5.0.)
+
+---
+
+## Development
+
+```powershell
+cd C:\workspace\mcp
+npm run dev             # tsx watch with .env
+npm test                # vitest (excludes integration)
+npm run test:watch      # watch mode
+npm run lint            # eslint
+npm run build           # tsc compile to dist/
+npm run generate:jwt    # generate a test JWT token
+```
+
+### Integration tests (requires live .env)
+
+```powershell
+npm run test:integration
+```
+
+---
+
+## Live testing against the running server
+
+The dev machine can exercise the deployed MCP server two ways:
+
+1. **Connected `homeassistant` MCP in Codex Desktop** — this agent has the live server
+   wired in as an MCP connection, so HA/Omada tools can be invoked directly (no curl, no
+   manual token; the configured bearer is used). **Caveat:** the MCP client caches the tool
+   list at *connection time*. After flipping `MCP_TOOL_REGISTRATION_MODE` (eager ⇄ graph)
+   and redeploying, that cached list is **stale** — Codex Desktop must reconnect (restart)
+   before the new tool surface (`omada_browse`/`omada_read`, or the typed getters) shows up.
+   Until it reconnects, calling a tool the live server no longer registers will fail.
+
+2. **Direct `/mcp` curl** — generate a token with
+   `npm run generate:jwt -- --sub <user> --exp 1h` (signs with the local `.env`
+   `MCP_AUTH_SECRET`, which currently matches the NAS), then POST JSON-RPC to the server's
+   `/mcp` with headers `Authorization: Bearer <tok>`, `Content-Type: application/json`,
+   `Accept: application/json, text/event-stream`. Responses come back as SSE
+   (`data: {...}` lines). `tools/list` and `tools/call` work **without** an initialize
+   handshake in stateless mode. The reachable server address lives in
+   `.Codex/NEXT-SESSION.md` (gitignored — never put the real IP/domain here).
+
+Permissions are resolved **server-side** from the token's `sub` via `MCP_PERMISSIONS_CONFIG`
+(they are NOT carried in the token). Pick a `sub` whose mapped role has the bit you need —
+e.g. the ADMIN-gated `/security/threats` node needs a `sub` mapped to an ADMIN role. The NAS
+role map differs from the local `.env`, so don't assume `sub=admin` is actually ADMIN there.
+
+---
+
+## Never assume. Always verify.
+
+- **Cloudflare 502**: check the container is running (`docker compose ps`) and
+  `MCP_HTTP_BIND_ADDR=0.0.0.0` is set.
+- **MCP client connects but tools fail**: check `MCP_HTTP_ALLOWED_ORIGINS` includes
+  the Cloudflare domain in both bare and `https://` form.
+- **Codex Desktop shows "Server disconnected" but `/health` is 200**: the client's
+  mcp-remote auth header is malformed. A `"Authorization: Bearer ${MCP_AUTH_TOKEN}"`
+  placeholder does NOT expand on Windows (`cmd /c` uses `%VAR%`, mcp-remote doesn't
+  substitute `${VAR}`) → literal text is sent → server 401 → mcp-remote drops into a
+  failing OAuth flow. Fix: inline the literal JWT in `claude_desktop_config.json`'s
+  `--header` arg, and add `-y` to `npx` so first run doesn't hang. Verify the server
+  side first with a direct `curl` POST to `/mcp` carrying the token.
+- **npm publish returns 404 on PUT**: token likely has per-package scope instead of
+  scope-level access, or "Bypass 2FA" is not ticked. Delete token and recreate.
+- **Omada auth error -44106**: check `OMADA_OMADAC_ID` first, not just credentials —
+  this error code covers both cases.
+- **Before a release**: always run `npm test` and `npm run build` clean.
+- **On release, bump the version everywhere**: `package.json`, `src/version.ts`,
+  `docs/CHANGELOG.md`, AND `openapi.json` (`info.version`) — the last one drifts easily.
+
+---
+
+## Tool registration modes (`MCP_TOOL_REGISTRATION_MODE`)
+
+Implemented as a **resource-graph** mode for the Omada plugin (config parses the var;
+`config.toolRegistrationMode` threads through `createServer` → `registerAllTools` →
+`registerOmadaTools`). Values:
+
+- **`eager`** (default) — register every typed tool (~26 Omada tools). Today's behavior;
+  fully backwards-compatible.
+- **`graph`** — register only `omada_browse` + `omada_read` + the 5 typed write/action
+  tools. Reads collapse into a discoverable resource graph (`src/tools/omada/namespace.ts`
+  manifest + `src/tools/omada/graph.ts`), shrinking the tool-schema budget for low-context
+  models while still exposing every read endpoint.
+
+Design invariants (don't regress these):
+- **browse returns TYPES, not instances** — `omada_browse(path)` lists permission-filtered
+  child resource types + metadata (kind, permission, pagination, params). It never
+  enumerates MACs or calls the controller.
+- **read is per-path RBAC, fail-closed** — `omada_read` declares NO static tool permission;
+  each manifest node declares its own bit (most reads = QUERY; the `/security/*` subtree =
+  ADMIN). Unknown / container / under-privileged / missing-required-param paths all return a
+  clean error and never fetch.
+- **single-page pagination** — paginated nodes forward one page/pageSize to a single GET via
+  `OmadaClient.readResource()`; they never walk every page.
+- **graph is a complete superset of eager reads** — every eager read getter has a graph node,
+  including the ADMIN-gated IDS/IPS threat-management log at `/security/threats`. Its mandatory
+  epoch time-window is enforced via required `params.startTime`/`params.endTime` (epoch seconds),
+  validated by `omada_read` before any controller call.
+
+HA and AI plugins are unaffected (still eager). Writes stay typed + individually gated in
+both modes — generic write verbs were deliberately rejected (prompt-injection / hallucination
+surface).
+
+---
+
+## Security
+
+This server controls real devices (HA, Omada) and is exposed publicly via Cloudflare, so
+treat it as security-sensitive. A full audit (2026-06-07) with file/line findings is in
+`.Codex/NEXT-SESSION.md`; this section is the **durable policy** distilled from it.
+
+### Dependencies — update, don't rewrite
+
+- Runtime deps are intentionally tiny: `@modelcontextprotocol/sdk`, `ws`, `zod`.
+  **Do not hand-roll replacements** for these (or for transitive libs like `hono`,
+  `ajv`, `path-to-regexp`). A homegrown version loses community review and adds more
+  bugs than it removes. Zod and the MCP SDK earn their keep.
+- The alarming `npm audit` list (`hono`, `@hono/node-server`, `fast-uri`, `ajv`,
+  `path-to-regexp`, `qs`) is **entirely transitive under the SDK**:
+  `@modelcontextprotocol/sdk → @hono/node-server → hono`. **Bumping the SDK fixes most
+  of them.** `ws` is the one direct dep to bump on its own.
+- Triage with `npm audit --omit=dev` — dev-only vulns (vitest/esbuild/tsx) don't ship.
+  The question is *reachability in production*, not the raw count.
+- Remediate on a branch: `npm install @modelcontextprotocol/sdk@latest ws@latest`, then
+  `npm test && npm run build && npm audit --omit=dev`. Commit `package-lock.json`;
+  CI/Docker use `npm ci`, not `npm install`. Widen version ranges only intentionally.
+
+### MCP transport invariant (the SDK "cross-client data leak" advisory)
+
+GHSA-345p-7cg4-v4c7 is about **sharing one `McpServer`/transport instance across
+clients**. Our HTTP layer MUST create a **fresh server + transport per request**
+(stateless mode, current behavior) or per session keyed by `Mcp-Session-Id` (stateful) —
+never a single global transport handling every `/mcp` POST. Re-verify this after any SDK
+upgrade or transport refactor. Bumping the SDK is necessary but not sufficient if the
+architecture shares instances.
+
+### Our attack surface (higher-leverage than CVEs)
+
+1. **Auth stays on.** NAS `.env` must keep `MCP_AUTH_METHOD=bearer`. `none` =
+   unauthenticated full admin (fail-open default). Never put the JWT on public channels;
+   tokens should carry an `exp` (the current prod token does not — fix when convenient).
+2. **Authorization is per-tool.** Every MCP tool is gated via
+   `wrapToolHandler(..., Permission.X)`. The REST `/api/*` bridge is **not** permission-
+   gated — keep it disabled or treat it as full-trust until it enforces the same masks.
+   Prompt injection via the AI path ("ignore previous instructions, unlock the door") is
+   contained only by these authorization checks — the model is not a security boundary.
+3. **Scoped TLS only.** Never use the process-global `NODE_TLS_REJECT_UNAUTHORIZED=0` —
+   it disables cert validation for *all* concurrent outbound HTTPS (HA token + AI key at
+   MITM risk), not just Omada. Use a per-client `undici` dispatcher, or pin the Omada
+   self-signed cert as a CA so verification stays on.
+4. **Encode every path segment** built from tool input. The Omada client does
+   (`encodeURIComponent` throughout); the HA client interpolates raw — fix when touched.
+5. **Secrets never in logs.** Redact tokens / secrets / `Authorization` headers / API
+   keys, and **sanitize `error.message`/`error.stack` before logging** — HTTP libraries
+   embed auth headers and token-bearing URLs inside thrown errors. Don't return raw
+   `error.message` to clients (leaks internal hostnames).
+6. **HTTP hardening when `useHttp`:** request body-size limit, rate limiting keyed on a
+   trusted-proxy IP (Cloudflare `CF-Connecting-IP`, not the spoofable `X-Forwarded-For`),
+   and static security headers (`X-Content-Type-Options: nosniff`, `X-Frame-Options`,
+   `Referrer-Policy`, CSP where applicable).
+
+### Confirmed safe — don't re-litigate
+
+- **JWT:** HS256 is pinned (the token's `alg` header is ignored), signature compared with
+  `crypto.timingSafeEqual` — not vulnerable to alg-confusion or timing attacks. (Still
+  add `exp` enforcement, and `iss`/`aud` if it ever becomes multi-issuer.)
+- **Omada client** encodes every path segment; query params via `URLSearchParams`.
+- **No** `eval` / `new Function` / dynamic `require`; the only child process is
+  `spawn('node', [fixedPath])` — no shell, no user-controlled argv.
+- **No arbitrary-URL SSRF via tool args** — HA/Omada/AI base URLs come only from config.
+- **Git hygiene clean** — `.env` is never tracked; no hardcoded real secrets in src/tests.
+
+### Insecure defaults to flip when next touched
+
+`config.ts` defaults `MCP_AUTH_METHOD=none`; `.env.example` ships `none` +
+`HA_STRICT_SSL=false`; `docker-compose.yml` hardcodes `MCP_HTTP_ALLOWED_ORIGINS=*`.
+None of these reflect the (secure) live deployment — make the secure values the defaults.

package/Dockerfile

@@ -1,6 +1,6 @@
 # syntax=docker/dockerfile:1.7
 
-FROM node:25-alpine AS deps
+FROM node:26-alpine AS deps
 WORKDIR /app
 COPY package*.json ./
 # npm ci installs exactly from the committed package-lock.json (reproducible) and
@@ -8,13 +8,13 @@ COPY package*.json ./
 # above pulls in package-lock.json, so the lockfile is present in this stage.
 RUN npm ci
 
-FROM node:25-alpine AS build
+FROM node:26-alpine AS build
 WORKDIR /app
 COPY --from=deps /app/node_modules ./node_modules
 COPY . .
 RUN npm run build
 
-FROM node:25-alpine AS runtime
+FROM node:26-alpine AS runtime
 
 # OCI metadata labels
 LABEL org.opencontainers.image.title="MCP-HA-Connect"
@@ -27,7 +27,9 @@ LABEL org.opencontainers.image.licenses="MIT"
 
 WORKDIR /app
 ENV NODE_ENV=production
-RUN apk add --no-cache curl
+# apk upgrade: pick up Alpine security patches even when the node base tag lags
+# (the 2026-07 Trivy scan's 24 libssl/libcrypto CVEs were exactly this rot).
+RUN apk upgrade --no-cache && apk add --no-cache curl
 COPY package*.json ./
 # Reproducible prod-only install from the lockfile (drops devDependencies).
 RUN npm ci --omit=dev
@@ -37,4 +39,6 @@ COPY --from=build /app/dist ./dist
 # Built artifacts under /app are world-readable, so no chown is required; the
 # server listens on 3000 (>1024) which needs no privileged capability.
 USER node
-CMD ["node", "--experimental-quic", "dist/index.js"]
+# --experimental-quic was dropped 2026-07-10: nothing in src/ uses QUIC, and the
+# flag tied the image to a specific Node major (25, now EOL) for no benefit.
+CMD ["node", "dist/index.js"]

package/dist/omadaClient/network.js

@@ -75,7 +75,7 @@ export class NetworkOperations {
      */
     async getSsidList(wlanId, siteId) {
         if (!wlanId) {
-            throw new Error('A wlanId must be provided. Use getWlanGroupList to get available WLAN group IDs.');
+            throw new Error('A wlanId must be provided. Use omada_read at path /wifi/groups to get available WLAN group IDs.');
         }
         const resolvedSiteId = this.site.resolveSiteId(siteId);
         const path = this.buildPath(`/sites/${encodeURIComponent(resolvedSiteId)}/wireless-network/wlans/${encodeURIComponent(wlanId)}/ssids`);
@@ -90,10 +90,10 @@ export class NetworkOperations {
      */
     async getSsidDetail(wlanId, ssidId, siteId) {
         if (!wlanId) {
-            throw new Error('A wlanId must be provided. Use getWlanGroupList to get available WLAN group IDs.');
+            throw new Error('A wlanId must be provided. Use omada_read at path /wifi/groups to get available WLAN group IDs.');
         }
         if (!ssidId) {
-            throw new Error('An ssidId must be provided. Use getSsidList to get available SSID IDs.');
+            throw new Error('An ssidId must be provided. Use omada_read at path /wifi/ssids to get available SSID IDs.');
         }
         const resolvedSiteId = this.site.resolveSiteId(siteId);
         const path = this.buildPath(`/sites/${encodeURIComponent(resolvedSiteId)}/wireless-network/wlans/${encodeURIComponent(wlanId)}/ssids/${encodeURIComponent(ssidId)}`);

package/dist/omadaClient/network.js.map

@@ -1 +1 @@
-{"version":3,"file":"network.js","sourceRoot":"","sources":["../../src/omadaClient/network.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"network.js","sourceRoot":"","sources":["../../src/omadaClient/network.ts"],"names":[],"mappings":"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"}

package/dist/omadaClient/site.js

@@ -52,7 +52,7 @@ export class SiteOperations {
         if (this.defaultSiteId) {
             return this.defaultSiteId;
         }
-        throw new Error('A site id must be provided either in the environment or as a parameter.');
+        throw new Error('A site id must be provided either in the environment or as a parameter. Use omada_browse at path / to discover available sites and their IDs.');
     }
 }
 //# sourceMappingURL=site.js.map

package/dist/omadaClient/site.js.map

@@ -1 +1 @@
-{"version":3,"file":"site.js","sourceRoot":"","sources":["../../src/omadaClient/site.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,mBAAmB,CAC/B,gBAAoC,EACpC,KAAyB;IAEzB,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,gBAAgB,CAAC,EAAE,CAAC;QACnD,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,MAAM,SAAS,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,gCAAgC,CAAC;IAC7G,OAAO,kBAAkB,gBAAgB,mEAAmE,SAAS,GAAG,CAAC;AAC7H,CAAC;AAED;;GAEG;AACH,MAAM,OAAO,cAAc;IAEF;IACA;IACA;IAHrB,YACqB,OAAuB,EACvB,SAAmC,EACnC,aAAsB;QAFtB,YAAO,GAAP,OAAO,CAAgB;QACvB,cAAS,GAAT,SAAS,CAA0B;QACnC,kBAAa,GAAb,aAAa,CAAS;IACxC,CAAC;IAEJ;;OAEG;IACI,KAAK,CAAC,SAAS;QAClB,OAAO,MAAM,IAAI,CAAC,OAAO,CAAC,cAAc,CAAmB,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC;IACzF,CAAC;IAED;;;OAGG;IACI,aAAa,CAAC,MAAe;QAChC,IAAI,MAAM,EAAE,CAAC;YACT,OAAO,MAAM,CAAC;QAClB,CAAC;QAED,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACrB,OAAO,IAAI,CAAC,aAAa,CAAC;QAC9B,CAAC;QAED,MAAM,IAAI,KAAK,CAAC,yEAAyE,CAAC,CAAC;IAC/F,CAAC;CACJ"}
+{"version":3,"file":"site.js","sourceRoot":"","sources":["../../src/omadaClient/site.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,mBAAmB,CAC/B,gBAAoC,EACpC,KAAyB;IAEzB,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,gBAAgB,CAAC,EAAE,CAAC;QACnD,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,MAAM,SAAS,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,gCAAgC,CAAC;IAC7G,OAAO,kBAAkB,gBAAgB,mEAAmE,SAAS,GAAG,CAAC;AAC7H,CAAC;AAED;;GAEG;AACH,MAAM,OAAO,cAAc;IAEF;IACA;IACA;IAHrB,YACqB,OAAuB,EACvB,SAAmC,EACnC,aAAsB;QAFtB,YAAO,GAAP,OAAO,CAAgB;QACvB,cAAS,GAAT,SAAS,CAA0B;QACnC,kBAAa,GAAb,aAAa,CAAS;IACxC,CAAC;IAEJ;;OAEG;IACI,KAAK,CAAC,SAAS;QAClB,OAAO,MAAM,IAAI,CAAC,OAAO,CAAC,cAAc,CAAmB,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC;IACzF,CAAC;IAED;;;OAGG;IACI,aAAa,CAAC,MAAe;QAChC,IAAI,MAAM,EAAE,CAAC;YACT,OAAO,MAAM,CAAC;QAClB,CAAC;QAED,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACrB,OAAO,IAAI,CAAC,aAAa,CAAC;QAC9B,CAAC;QAED,MAAM,IAAI,KAAK,CAAC,+IAA+I,CAAC,CAAC;IACrK,CAAC;CACJ"}

package/dist/resources/index.js

@@ -55,7 +55,7 @@ export function registerAllResources(server, client) {
                     {
                         uri: uri.href,
                         mimeType: 'application/json',
-                        text: JSON.stringify({ error: 'Entity not found', entity_id: entityId }),
+                        text: JSON.stringify({ error: 'Entity not found', entity_id: entityId, hint: 'Use the searchEntities tool with a keyword to find the correct entity_id' }),
                     },
                 ],
             };
@@ -88,7 +88,7 @@ export function registerAllResources(server, client) {
                     {
                         uri: uri.href,
                         mimeType: 'application/json',
-                        text: JSON.stringify({ error: 'Entity not found', entity_id: entityId }),
+                        text: JSON.stringify({ error: 'Entity not found', entity_id: entityId, hint: 'Use the searchEntities tool with a keyword to find the correct entity_id' }),
                     },
                 ],
             };

package/dist/resources/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/resources/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/resources/index.ts"],"names":[],"mappings":"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"}

package/dist/tools/homeassistant/entityAction.js

@@ -9,7 +9,7 @@ export function registerEntityActionTool(server, client) {
     }, wrapToolHandler('entityAction', async ({ entity_id, action }) => {
         const domain = entity_id.split('.')[0];
         if (!domain) {
-            return toToolResult({ error: 'Invalid entity_id format' }, true);
+            return toToolResult({ error: 'Invalid entity_id format', hint: 'entity_id must be in domain.name format such as light.living_room — use the searchEntities tool to discover valid entity IDs' }, true);
         }
         const result = await client.callService({
             domain,

package/dist/tools/homeassistant/entityAction.js.map

@@ -1 +1 @@
-{"version":3,"file":"entityAction.js","sourceRoot":"","sources":["../../../src/tools/homeassistant/entityAction.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAK7F,MAAM,UAAU,wBAAwB,CAAC,MAAiB,EAAE,MAAgB;IAC1E,MAAM,CAAC,YAAY,CACjB,cAAc,EACd;QACE,WAAW,EAAE,qGAAqG;QAClH,WAAW,EAAE,kBAAkB,CAAC,KAAK;KACtC,EACD,eAAe,CAAC,cAAc,EAAE,KAAK,EAAE,EAAE,SAAS,EAAE,MAAM,EAAoB,EAAE,EAAE;QAChF,MAAM,MAAM,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACvC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,YAAY,CAAC,EAAE,KAAK,EAAE,0BAA0B,EAAE,EAAE,IAAI,CAAC,CAAC;QACnE,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC;YACtC,MAAM;YACN,OAAO,EAAE,MAAM;YACf,MAAM,EAAE,EAAE,SAAS,EAAE;SACtB,CAAC,CAAC;QACH,OAAO,YAAY,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;IACrF,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,CACvB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"entityAction.js","sourceRoot":"","sources":["../../../src/tools/homeassistant/entityAction.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAK7F,MAAM,UAAU,wBAAwB,CAAC,MAAiB,EAAE,MAAgB;IAC1E,MAAM,CAAC,YAAY,CACjB,cAAc,EACd;QACE,WAAW,EAAE,qGAAqG;QAClH,WAAW,EAAE,kBAAkB,CAAC,KAAK;KACtC,EACD,eAAe,CAAC,cAAc,EAAE,KAAK,EAAE,EAAE,SAAS,EAAE,MAAM,EAAoB,EAAE,EAAE;QAChF,MAAM,MAAM,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACvC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,YAAY,CAAC,EAAE,KAAK,EAAE,0BAA0B,EAAE,IAAI,EAAE,8HAA8H,EAAE,EAAE,IAAI,CAAC,CAAC;QACzM,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC;YACtC,MAAM;YACN,OAAO,EAAE,MAAM;YACf,MAAM,EAAE,EAAE,SAAS,EAAE;SACtB,CAAC,CAAC;QACH,OAAO,YAAY,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;IACrF,CAAC,EAAE,UAAU,CAAC,OAAO,CAAC,CACvB,CAAC;AACJ,CAAC"}

package/dist/tools/homeassistant/getState.js

@@ -9,7 +9,7 @@ export function registerGetStateTool(server, client) {
     }, wrapToolHandler('getState', async ({ entity_id }) => {
         const state = await client.getState(entity_id);
         if (!state) {
-            return toToolResult({ error: 'Entity not found', entity_id }, true);
+            return toToolResult({ error: 'Entity not found', entity_id, hint: 'Use the searchEntities tool with a keyword to find the correct entity_id' }, true);
         }
         return toToolResult(state);
     }, Permission.QUERY));

package/dist/tools/homeassistant/getState.js.map

@@ -1 +1 @@
-{"version":3,"file":"getState.js","sourceRoot":"","sources":["../../../src/tools/homeassistant/getState.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAEzF,MAAM,UAAU,oBAAoB,CAAC,MAAiB,EAAE,MAAgB;IACtE,MAAM,CAAC,YAAY,CACjB,UAAU,EACV;QACE,WAAW,EAAE,kDAAkD;QAC/D,WAAW,EAAE,cAAc,CAAC,KAAK;KAClC,EACD,eAAe,CAAC,UAAU,EAAE,KAAK,EAAE,EAAE,SAAS,EAAyB,EAAE,EAAE;QACzE,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;QAC/C,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,YAAY,CAAC,EAAE,KAAK,EAAE,kBAAkB,EAAE,SAAS,EAAE,EAAE,IAAI,CAAC,CAAC;QACtE,CAAC;QACD,OAAO,YAAY,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC,EAAE,UAAU,CAAC,KAAK,CAAC,CACrB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"getState.js","sourceRoot":"","sources":["../../../src/tools/homeassistant/getState.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAEzF,MAAM,UAAU,oBAAoB,CAAC,MAAiB,EAAE,MAAgB;IACtE,MAAM,CAAC,YAAY,CACjB,UAAU,EACV;QACE,WAAW,EAAE,kDAAkD;QAC/D,WAAW,EAAE,cAAc,CAAC,KAAK;KAClC,EACD,eAAe,CAAC,UAAU,EAAE,KAAK,EAAE,EAAE,SAAS,EAAyB,EAAE,EAAE;QACzE,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;QAC/C,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,YAAY,CAAC,EAAE,KAAK,EAAE,kBAAkB,EAAE,SAAS,EAAE,IAAI,EAAE,0EAA0E,EAAE,EAAE,IAAI,CAAC,CAAC;QACxJ,CAAC;QACD,OAAO,YAAY,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC,EAAE,UAAU,CAAC,KAAK,CAAC,CACrB,CAAC;AACJ,CAAC"}

package/dist/version.d.ts

@@ -2,4 +2,4 @@
  * Package version - hardcoded at build time for reliability
  * Keep in sync with package.json version
  */
-export declare const VERSION = "1.5.3";
+export declare const VERSION = "1.5.5";

package/dist/version.js

@@ -2,5 +2,5 @@
  * Package version - hardcoded at build time for reliability
  * Keep in sync with package.json version
  */
-export const VERSION = '1.5.3';
+export const VERSION = '1.5.5';
 //# sourceMappingURL=version.js.map

package/docs/CHANGELOG.md

@@ -1,3 +1,19 @@
+### 1.5.4
+**Improvement — actionable error hints so agents self-correct instead of stalling.**
+Not-found / invalid-input errors now carry a next-step pointer toward the tool that
+resolves them, cutting the retry loops and wrong guesses that waste round-trips:
+- `getState`, `entityAction`, and the `hass://entities/{id}` resources now return a
+  `hint` field on a missing/malformed `entity_id`, pointing at `searchEntities` (and the
+  required `domain.name` format).
+- Omada `resolveSiteId` with no site configured now hints to `omada_browse` at `/` to
+  discover available sites and their IDs.
+- Omada SSID getters with a missing `wlanId`/`ssidId` had stale tool references
+  (`getWlanGroupList`/`getSsidList`) corrected to the real graph-mode paths
+  (`omada_read /wifi/groups`, `omada_read /wifi/ssids`).
+
+Purely additive — no API, schema, or behavior changes; only the human/agent-readable
+error text gains guidance.
+
 ### 1.5.3
 **Fix — allow the `x-session-id` request header in CORS so Open WebUI tool calls work.**
 Open WebUI sends an `x-session-id` header on every OpenAPI tool call. The REST bridge's

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Home Assistant MCP Wrapper",
-    "version": "1.5.3",
+    "version": "1.5.5",
     "description": "REST endpoints that wrap MCP tools for Home Assistant integration. Raw JSON-RPC passthrough available at POST / for n8n compatibility."
   },
   "servers": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffeerunhobby/mcp-ha-connect",
-  "version": "1.5.3",
+  "version": "1.5.5",
   "description": "Smart home MCP server for Home Assistant plus Local AI integration",
   "type": "module",
   "main": "dist/index.js",

package/src/omadaClient/network.ts

@@ -85,7 +85,7 @@ export class NetworkOperations {
      */
     public async getSsidList(wlanId: string, siteId?: string): Promise<unknown[]> {
         if (!wlanId) {
-            throw new Error('A wlanId must be provided. Use getWlanGroupList to get available WLAN group IDs.');
+            throw new Error('A wlanId must be provided. Use omada_read at path /wifi/groups to get available WLAN group IDs.');
         }
 
         const resolvedSiteId = this.site.resolveSiteId(siteId);
@@ -102,10 +102,10 @@ export class NetworkOperations {
      */
     public async getSsidDetail(wlanId: string, ssidId: string, siteId?: string): Promise<unknown> {
         if (!wlanId) {
-            throw new Error('A wlanId must be provided. Use getWlanGroupList to get available WLAN group IDs.');
+            throw new Error('A wlanId must be provided. Use omada_read at path /wifi/groups to get available WLAN group IDs.');
         }
         if (!ssidId) {
-            throw new Error('An ssidId must be provided. Use getSsidList to get available SSID IDs.');
+            throw new Error('An ssidId must be provided. Use omada_read at path /wifi/ssids to get available SSID IDs.');
         }
 
         const resolvedSiteId = this.site.resolveSiteId(siteId);

package/src/omadaClient/site.ts

@@ -61,6 +61,6 @@ export class SiteOperations {
             return this.defaultSiteId;
         }
 
-        throw new Error('A site id must be provided either in the environment or as a parameter.');
+        throw new Error('A site id must be provided either in the environment or as a parameter. Use omada_browse at path / to discover available sites and their IDs.');
     }
 }

package/src/resources/index.ts

@@ -74,7 +74,7 @@ export function registerAllResources(server: McpServer, client: HaClient): void
             {
               uri: uri.href,
               mimeType: 'application/json',
-              text: JSON.stringify({ error: 'Entity not found', entity_id: entityId }),
+              text: JSON.stringify({ error: 'Entity not found', entity_id: entityId, hint: 'Use the searchEntities tool with a keyword to find the correct entity_id' }),
             },
           ],
         };
@@ -115,7 +115,7 @@ export function registerAllResources(server: McpServer, client: HaClient): void
             {
               uri: uri.href,
               mimeType: 'application/json',
-              text: JSON.stringify({ error: 'Entity not found', entity_id: entityId }),
+              text: JSON.stringify({ error: 'Entity not found', entity_id: entityId, hint: 'Use the searchEntities tool with a keyword to find the correct entity_id' }),
             },
           ],
         };

package/src/tools/homeassistant/entityAction.ts

@@ -19,7 +19,7 @@ export function registerEntityActionTool(server: McpServer, client: HaClient): v
     wrapToolHandler('entityAction', async ({ entity_id, action }: EntityActionArgs) => {
       const domain = entity_id.split('.')[0];
       if (!domain) {
-        return toToolResult({ error: 'Invalid entity_id format' }, true);
+        return toToolResult({ error: 'Invalid entity_id format', hint: 'entity_id must be in domain.name format such as light.living_room — use the searchEntities tool to discover valid entity IDs' }, true);
       }
       const result = await client.callService({
         domain,

package/src/tools/homeassistant/getState.ts

@@ -16,7 +16,7 @@ export function registerGetStateTool(server: McpServer, client: HaClient): void
     wrapToolHandler('getState', async ({ entity_id }: { entity_id: string }) => {
       const state = await client.getState(entity_id);
       if (!state) {
-        return toToolResult({ error: 'Entity not found', entity_id }, true);
+        return toToolResult({ error: 'Entity not found', entity_id, hint: 'Use the searchEntities tool with a keyword to find the correct entity_id' }, true);
       }
       return toToolResult(state);
     }, Permission.QUERY)

package/src/version.ts

@@ -2,4 +2,4 @@
  * Package version - hardcoded at build time for reliability
  * Keep in sync with package.json version
  */
-export const VERSION = '1.5.3';
+export const VERSION = '1.5.5';