@coffeerunhobby/mcp-ha-connect 2.2.1 → 2.3.1

package/.github/workflows/ci.yml

@@ -1,193 +0,0 @@
-name: CI
-
-# Advisory only. This workflow REPORTS a pass/fail status on commits and PRs.
-# It does NOT block commits, pushes, or merges. The code builds, publishes, and
-# deploys with zero dependency on this file — delete it and nothing breaks.
-# (Blocking only happens if you separately enable branch-protection in the
-#  GitHub web UI, which is off by default and intentionally not set here.)
-
-on:
-  push:
-    branches: [main, dev]
-    # Version tags trigger the full gate + auto-create the GitHub Release (see
-    # the `release` job) — v1.5.4 sat tag-only for two weeks because the manual
-    # `gh release create` step kept getting skipped.
-    tags: ['v*']
-  pull_request:
-    branches: [main, dev]
-  # Lets you re-run it by hand from the Actions tab.
-  workflow_dispatch:
-
-# If you push twice quickly, cancel the older run instead of stacking them.
-concurrency:
-  group: ci-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  build-test-lint:
-    runs-on: ubuntu-latest
-
-    strategy:
-      # Don't kill the Node 22 run just because Node 20 failed (or vice-versa) —
-      # we want to see both results.
-      fail-fast: false
-      matrix:
-        # The LTS lines we support (package.json engines: ">=20"). 24.x is the
-        # Docker image's actual runtime (since v1.5.6); 26 is the next LTS (2026-10).
-        node-version: ['20.x', '22.x', '24.x', '26.x']
-
-    name: node ${{ matrix.node-version }}
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v7
-
-      - name: Set up Node ${{ matrix.node-version }}
-        uses: actions/setup-node@v7
-        with:
-          node-version: ${{ matrix.node-version }}
-          cache: npm
-
-      # Install deps from the lockfile (reproducible; same command Docker uses; never
-      # edits the lockfile). RECURRING TRAP: `npm ci` fails here if the lockfile was
-      # regenerated on Windows — that OMITS linux-only optional deps (@emnapi/*) and
-      # the Linux install rejects it. FIX: regenerate the lockfile on Linux / in the
-      # node:24-alpine build image (docker run … npm install --package-lock-only),
-      # never `npm install` on Windows.
-      - name: Install dependencies (npm ci — fails on a Windows-drifted lockfile)
-        run: npm ci
-
-      # 1. Compile cleanly (tsc -> dist/). Catches type errors.
-      - name: Build
-        run: npm run build
-
-      # 2. Lint src + tests. CLAUDE.md policy: zero errors AND zero warnings.
-      #    --max-warnings=0 makes a warning fail the job, matching that policy.
-      - name: Lint
-        run: npm run lint -- --max-warnings=0
-
-      # 3. Version-sync gate. Fails if package.json / src/version.ts / openapi.json
-      #    disagree on the version — the exact drift CLAUDE.md warns about.
-      - name: Version sync
-        run: npm run check:sync
-
-      # 4. Unit tests WITH coverage gate. test:coverage excludes tests/integration/**
-      #    (those need a live .env CI must never have) and enforces the regression
-      #    floor in vitest.config.ts — a coverage DROP fails the build.
-      - name: Test + coverage gate
-        run: npm run test:coverage
-
-  docker-smoke:
-    # Boot-test the ACTUAL image: build it, point it at a mock Home Assistant,
-    # and require /health to answer. Motivation: v1.5.5 shipped without ever
-    # having been run — its first boot was in production on the NAS (where the
-    # node:26 base then failed its first fetch). A release must never again be
-    # the image's first boot.
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v7
-
-      - name: Build image
-        run: docker build -t mcp-smoke:ci .
-
-      - name: Boot against a mock HA and assert /health
-        run: |
-          set -eu
-          docker network create smoke
-          # Mock HA: 200 {"message":"API running."} — the same body the real
-          # /api/ startup check (checkApi) expects.
-          docker run -d --name mockha --network smoke node:24-alpine \
-            node -e 'require("http").createServer((q,s)=>{s.writeHead(200,{"Content-Type":"application/json"});s.end(JSON.stringify({message:"API running."}))}).listen(8123,()=>console.log("mock HA up"))'
-          # HA_STRICT_SSL=false mirrors the REAL NAS config — the exact combination
-          # (http HA + strictSsl=false) that crash-looped v1.5.5 on a node:26 base
-          # (npm-undici-6 dispatcher passed to Node's built-in fetch -> "invalid
-          # onError method" -> "fetch failed"). The smoke must boot with it forever.
-          docker run -d --name mcp --network smoke \
-            -e MCP_SERVER_USE_HTTP=true \
-            -e MCP_HTTP_PORT=3000 -e MCP_HTTP_BIND_ADDR=0.0.0.0 \
-            -e MCP_HTTP_ENABLE_HEALTHCHECK=true -e MCP_HTTP_HEALTHCHECK_PATH=/health \
-            -e MCP_AUTH_METHOD=bearer -e MCP_AUTH_SECRET=ci-smoke-dummy-secret-0123456789 \
-            -e HA_PLUGIN_ENABLED=true -e HA_URL=http://mockha:8123 -e HA_TOKEN=ci-dummy \
-            -e HA_STRICT_SSL=false \
-            -e AI_PLUGIN_ENABLED=false -e OMADA_PLUGIN_ENABLED=false \
-            mcp-smoke:ci
-          for i in $(seq 1 15); do
-            if docker run --rm --network smoke curlimages/curl:latest -sf http://mcp:3000/health >/dev/null 2>&1; then
-              echo "smoke OK: image boots, startup HA check passes, /health answers"
-              exit 0
-            fi
-            sleep 2
-          done
-          echo "SMOKE FAILED — container logs:"
-          docker logs mcp
-          exit 1
-
-  publish-npm:
-    # Tokenless npm publish via OIDC trusted publishing (one-time npmjs.com config:
-    # package Settings -> Trusted Publisher -> GitHub Actions, this repo + ci.yml).
-    # Replaces the bypass-2FA granular token: npm is restricting those from Aug 2026
-    # and banning direct publish ~Jan 2027 (github.blog changelog 2026-07-08), and
-    # ours expires 2026-09-12 anyway. --provenance attests the package to this run.
-    # dist/ is GITIGNORED (built, not committed) — this job MUST npm ci + build, or
-    # the published tarball ships without the compiled code.
-    if: startsWith(github.ref, 'refs/tags/v')
-    needs: [build-test-lint, docker-smoke]
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      id-token: write   # the OIDC credential — this IS the auth, no secret anywhere
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v7
-
-      - name: Set up Node
-        uses: actions/setup-node@v7
-        with:
-          node-version: '24.x'
-          registry-url: 'https://registry.npmjs.org'
-
-      - name: Install + build (dist/ is gitignored — the tarball needs it compiled)
-        run: |
-          npm ci
-          npm run build
-          test -f dist/index.js || { echo "FATAL: build produced no dist/index.js"; exit 1; }
-
-      - name: Publish (tag must match package version; idempotent if already published)
-        run: |
-          set -eu
-          PKG=$(node -p "require('./package.json').name")
-          VER=$(node -p "require('./package.json').version")
-          if [ "v$VER" != "$GITHUB_REF_NAME" ]; then
-            echo "FATAL: tag $GITHUB_REF_NAME != package.json version $VER (check:sync covers files, this covers the tag)"
-            exit 1
-          fi
-          if npm view "$PKG@$VER" version >/dev/null 2>&1; then
-            echo "$PKG@$VER already on the registry — skipping (idempotent)"
-          else
-            npm publish --provenance --access public
-          fi
-          # Belt-and-braces: the tarball npm just packed must contain the entrypoint.
-          npm pack --dry-run 2>&1 | grep -q 'dist/index.js' || { echo "FATAL: packed tarball missing dist/index.js"; exit 1; }
-
-  release:
-    # Auto-create the GitHub Release when a `v*` tag passes BOTH gates above —
-    # the test matrix AND the image boot-test. Notes are auto-generated from the
-    # commits since the previous release; polish them in the web UI afterwards
-    # if the release deserves prose.
-    # Idempotent: if the Release already exists (created by hand), this no-ops.
-    if: startsWith(github.ref, 'refs/tags/v')
-    needs: [build-test-lint, docker-smoke]
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v7
-
-      - name: Create GitHub Release
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          gh release view "$GITHUB_REF_NAME" >/dev/null 2>&1 || \
-            gh release create "$GITHUB_REF_NAME" --latest --generate-notes --title "$GITHUB_REF_NAME"

package/AGENTS.md

@@ -1,389 +0,0 @@
-# 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:** v2 split packages — `@modelcontextprotocol/server` + `@modelcontextprotocol/node` (Node HTTP transport); `@modelcontextprotocol/client` is dev-only (tests)
-- **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 (1064 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
-
-Server secrets live in the NAS `.env` file. The one release secret — the GHCR push token
-(a GitHub classic PAT with `write:packages`, used for the Docker push in step 5) — lives only
-in the maintainer's password manager. Never store it as an environment variable, in a file, in
-a commit, in chat, or in this file; fetch it at push time and pipe it to `docker login
---password-stdin`.
-
-### npm publishing needs no token
-
-npm publish is done by CI via **OIDC trusted publishing** (see Release Process step 4) —
-there is no npm token to store, rotate, or revoke. Publishing is configured at
-npmjs.com → package Settings → **Trusted Publisher** → GitHub Actions (this repo +
-`ci.yml`), not via a token.
-
----
-
-## 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 — AUTOMATED by CI (do NOT publish by hand)
-
-**The `v*` tag you pushed in step 3 already publishes npm.** `.github/workflows/ci.yml`
-has a `publish-npm` job that fires on `refs/tags/v*` and publishes via **OIDC trusted
-publishing** — tokenless, `--provenance`, no `npm login`. It is **idempotent** (skips if
-`pkg@version` is already on the registry) and it re-runs `npm ci && npm run build`
-because `dist/` is gitignored. The same tag also runs a `release` job that auto-creates
-the GitHub Release (idempotent — a manual `gh release create` just no-ops).
-
-> Agent rule: **do NOT run `npm publish`/`npm login`.** Just push the tag, then verify:
-> ```powershell
-> gh run list --limit 3          # publish-npm + release jobs green on the v tag
-> npm view @coffeerunhobby/mcp-ha-connect version   # shows the new version
-> ```
-> `npm whoami` from the agent returns 401 (no session) — expected, not a failure.
-
-### 5. Docker build & push — via WSL (NO Docker Desktop)
-
-**Docker Desktop is not used on this box.** The working engine is **Docker CE inside
-WSL2 Ubuntu-24.04**. CI's `docker-smoke` job only *boot-tests* the image — it does
-**not** push to GHCR, so this push is the one genuinely manual release leg.
-
-```powershell
-# GHCR login — token fetched from the maintainer's password manager at push time and piped
-# over stdin (never a command-line arg or env var). WSL keeps the login for the push below.
-<token from password manager> | wsl -d Ubuntu-24.04 -- bash -lc "docker login ghcr.io -u coffeerunhobby --password-stdin"
-
-# Build (repo is /mnt/c/workspace/mcp inside WSL) + push both tags
-wsl -d Ubuntu-24.04 -- bash -lc "cd /mnt/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 ."
-wsl -d Ubuntu-24.04 -- bash -lc "docker push ghcr.io/coffeerunhobby/mcp-ha-connect:X.Y.Z && docker push ghcr.io/coffeerunhobby/mcp-ha-connect:latest"
-```
-
-WSL2 is amd64 = the NAS arch, so a plain `docker build` (not `buildx --platform`)
-produces the correct image.
-
-### 6. Deploy to NAS
-
-The compose file pulls `ghcr.io/coffeerunhobby/mcp-ha-connect:latest`. On the NAS:
-
-```bash
-cd /volume1/docker/mcp-ha-connect
-docker compose pull mcp-ha-connect && docker compose up -d mcp-ha-connect
-docker compose logs --tail=30
-```
-
-Verify: `curl https://<cloudflare-domain>/openapi.json` → `info.version` is the new
-version, and `curl https://<cloudflare-domain>/health` → `{"status":"healthy"}`.
-
----
-
-## 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 version not updating after a tag push**: check the `publish-npm` CI job on the
-  tag (`gh run list`) — publishing is OIDC via CI, never manual (see Release step 4).
-- **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/server`, `@modelcontextprotocol/node`,
-  `undici`, `ws`, `zod` (^4.2 — SDK v2 requires it). Since v2.0.0 (SDK v2) the whole production tree
-  is **8 packages** (was 95 with SDK v1, which dragged in Express/cors/cross-spawn/ajv).
-  **Do not hand-roll replacements** for these (or for transitive libs like `hono`). A homegrown version loses community review and adds more
-  bugs than it removes. Zod and the MCP SDK earn their keep.
-- Transitive advisories now can only come from `hono`/`@hono/node-server` (via
-  `@modelcontextprotocol/node`) or `@modelcontextprotocol/core`. **Bumping the SDK packages
-  fixes most of them.** `ws` and `undici` are direct deps to bump on their 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/server@latest @modelcontextprotocol/node@latest ws@latest undici@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)`, and the REST `/api/*` bridge enforces the same
-   RBAC masks per route (`requiredPermissionFor` in the chat-face dispatcher).
-   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,50 +0,0 @@
-# syntax=docker/dockerfile:1.7
-
-FROM node:24-alpine AS deps
-WORKDIR /app
-COPY package*.json ./
-# npm ci installs exactly from the committed package-lock.json (reproducible) and
-# fails if package.json and the lockfile have drifted. The `package*.json` COPY
-# above pulls in package-lock.json, so the lockfile is present in this stage.
-RUN npm ci
-
-FROM node:24-alpine AS build
-WORKDIR /app
-COPY --from=deps /app/node_modules ./node_modules
-COPY . .
-RUN npm run build
-
-FROM node:24-alpine AS runtime
-
-# OCI metadata labels
-LABEL org.opencontainers.image.title="MCP-HA-Connect"
-LABEL org.opencontainers.image.description="MCP server for Home Assistant + TP-Link Omada + Local AI integration"
-LABEL org.opencontainers.image.authors="Coffee Run Hobby"
-LABEL org.opencontainers.image.url="https://github.com/coffeerunhobby/mcp-ha-connect"
-LABEL org.opencontainers.image.source="https://github.com/coffeerunhobby/mcp-ha-connect"
-LABEL org.opencontainers.image.documentation="https://github.com/coffeerunhobby/mcp-ha-connect#readme"
-LABEL org.opencontainers.image.licenses="MIT"
-
-WORKDIR /app
-ENV NODE_ENV=production
-# 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), then
-# strip the package managers from the runtime image: nothing invokes npm/yarn after
-# this line, and the npm CLI's vendored deps were the only Trivy findings left on
-# v1.5.5 (undici 6.26.0 inside /usr/local/lib/node_modules/npm).
-RUN npm ci --omit=dev && \
-    rm -rf /usr/local/lib/node_modules /usr/local/bin/npm /usr/local/bin/npx \
-           /usr/local/bin/corepack /opt/yarn* /usr/local/bin/yarn /usr/local/bin/yarnpkg \
-           /root/.npm
-COPY --from=build /app/dist ./dist
-
-# M10: drop root. The official node image ships a non-root `node` user (uid 1000).
-# 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
-# --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/docker-compose.yml

@@ -1,23 +0,0 @@
-services:
-  mcp-ha-connect:
-    build: .
-    container_name: mcp-ha-connect
-    restart: unless-stopped
-    ports:
-      - "3000:3000"
-    extra_hosts:
-      - "host.docker.internal:host-gateway"
-    env_file:
-      - .env
-    environment:
-      # Bind all interfaces inside the container so Docker's port map works.
-      - MCP_HTTP_BIND_ADDR=0.0.0.0
-      # M1: do NOT hard-code a wildcard origin here. Set MCP_HTTP_ALLOWED_ORIGINS
-      # in .env to the exact public origin(s) — e.g. your Cloudflare domain in
-      # both bare-host and https:// form — so DNS-rebinding/CORS protection works.
-    healthcheck:
-      test: ["CMD", "wget", "-q", "--spider", "http://localhost:3000/health"]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-      start_period: 10s