ci: parallel jobs, skip flaky/fixture tests

Split emby-mcp into gofmt/vet/build/test and n95 pin vs test so a capacity-8 runner can fill slots. Cancel superseded runs. Skip streamable HTTP e2e on CI (session handshake fails on act). Skip n95 TestCapture* (pcaps are not in the published tag).
fix: sync openai-codex-proxy VERSION and image label to 1.0.3
2026-09-25 20:33:39 +00:00 · 2026-09-25 20:27:24 +00:00 · 2026-09-25 20:22:07 +00:00 · 2026-09-25 20:19:27 +00:00 · 2026-09-25 20:17:08 +00:00 · 2026-09-25 21:13:26 +01:00
55 changed files with 2917 additions and 515 deletions
@@ -0,0 +1,172 @@
 name: Validate add-ons
 on:
  push:
    branches: [develop, main]
  pull_request:
    branches: [develop, main]
  workflow_dispatch:
 concurrency:
  group: validate-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true
 jobs:
  yaml:
    name: YAML and layout
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Parse add-on YAML
        run: |
          set -euo pipefail
          python3 -m pip install --break-system-packages --quiet pyyaml
          python3 - <<'PY'
          import pathlib, sys, yaml
          root = pathlib.Path(".")
          files = [root / "repository.yaml"]
          for addon in sorted(p for p in root.iterdir() if p.is_dir() and (p / "config.yaml").exists()):
              files.append(addon / "config.yaml")
              by = addon / "build.yaml"
              if by.exists():
                  files.append(by)
          failed = False
          required = ("name", "version", "slug", "arch")
          for f in files:
              print(f"parse {f}")
              with f.open() as fh:
                  data = yaml.safe_load(fh)
              if f.name == "config.yaml":
                  missing = [k for k in required if k not in (data or {})]
                  if missing:
                      print(f"ERROR {f}: missing {missing}")
                      failed = True
                  version = f.parent / "VERSION"
                  if version.exists():
                      disk = version.read_text().strip()
                      cfg = str(data.get("version", "")).strip()
                      if disk != cfg:
                          print(f"ERROR {f}: version {cfg!r} != VERSION {disk!r}")
                          failed = True
          if failed:
              sys.exit(1)
          print("ok")
          PY
  emby-fmt:
    name: emby-mcp gofmt
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version-file: emby-mcp/go.mod
          cache-dependency-path: emby-mcp/go.sum
      - name: gofmt
        working-directory: emby-mcp
        run: |
          dirty="$(gofmt -l .)"
          if [ -n "$dirty" ]; then
            echo "gofmt needed:"
            echo "$dirty"
            exit 1
          fi
  emby-vet:
    name: emby-mcp vet
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version-file: emby-mcp/go.mod
          cache-dependency-path: emby-mcp/go.sum
      - name: go vet
        working-directory: emby-mcp
        run: go vet ./...
  emby-build:
    name: emby-mcp build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version-file: emby-mcp/go.mod
          cache-dependency-path: emby-mcp/go.sum
      - name: go build
        working-directory: emby-mcp
        run: go build ./...
  emby-mcp:
    name: emby-mcp Go
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version-file: emby-mcp/go.mod
          cache-dependency-path: emby-mcp/go.sum
      - name: go test
        working-directory: emby-mcp
        run: go test -count=1 -timeout 4m -p 8 -parallel 8 ./...
        timeout-minutes: 6
  openai-codex-proxy:
    name: openai-codex-proxy
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "22"
      - name: syntax-check entrypoint
        run: node --check openai-codex-proxy/rootfs/entrypoint.js
  n95-pin:
    name: n95-mqtt-bridge pin
    runs-on: ubuntu-latest
    outputs:
      ref: ${{ steps.pin.outputs.ref }}
      commit: ${{ steps.pin.outputs.commit }}
    steps:
      - uses: actions/checkout@v4
      - name: Verify upstream pin
        id: pin
        run: |
          set -euo pipefail
          ref="$(awk -F'"' '/UPSTREAM_REF:/ {print $2; exit}' n95-mqtt-bridge/build.yaml)"
          commit="$(awk -F'"' '/UPSTREAM_COMMIT:/ {print $2; exit}' n95-mqtt-bridge/build.yaml)"
          df_ref="$(awk -F= '/^ARG UPSTREAM_REF=/ {print $2; exit}' n95-mqtt-bridge/Dockerfile)"
          df_commit="$(awk -F= '/^ARG UPSTREAM_COMMIT=/ {print $2; exit}' n95-mqtt-bridge/Dockerfile)"
          echo "build.yaml ref=$ref commit=$commit"
          echo "Dockerfile ref=$df_ref commit=$df_commit"
          test -n "$ref" && test -n "$commit"
          test "$ref" = "$df_ref"
          test "$commit" = "$df_commit"
          echo "ref=$ref" >> "$GITHUB_OUTPUT"
          echo "commit=$commit" >> "$GITHUB_OUTPUT"
  n95-mqtt-bridge:
    name: n95-mqtt-bridge pin and upstream tests
    runs-on: ubuntu-latest
    needs: n95-pin
    steps:
      - uses: actions/setup-go@v5
        with:
          go-version: "1.27.1"
      - name: Test pinned upstream
        run: |
          set -euo pipefail
          git clone --depth 1 --branch "${{ needs.n95-pin.outputs.ref }}" \
            https://git.i3omb.com/gronod/ha-n95-local-control.git /tmp/n95
          cd /tmp/n95
          got="$(git rev-parse HEAD)"
          want="${{ needs.n95-pin.outputs.commit }}"
          if [ "$got" != "$want" ]; then
            echo "tag ${{ needs.n95-pin.outputs.ref }} is $got, build.yaml wants $want"
            exit 1
          fi
          # Replay pcaps are local fixtures and are not in the published tag.
          go test -count=1 -timeout 4m -p 8 -parallel 8 -skip 'TestCapture' ./...
        timeout-minutes: 6
@@ -0,0 +1,43 @@
 # Repository guidance
 This is **Gronod's Home Assistant Add-Ons** — a Home Assistant add-on
 repository. Each top-level directory is one add-on.
 ## Layout conventions
 - Add-on directory names use hyphens and mirror the add-on slug:
  `emby-mcp/` ↔ slug `emby_mcp`, `openai-codex-proxy/` ↔ slug
  `openai_codex_proxy` (config.yaml slugs allow `[a-z0-9_]` only).
 - Each add-on contains: `config.yaml`, `Dockerfile`, `README.md`, `DOCS.md`,
  `CHANGELOG.md`, `icon.png`, `logo.png`; `build.yaml`/`rootfs/` as needed.
 - `README.md` = decision content (what it is, features, requirements,
  install summary). `DOCS.md` = installation, configuration, usage,
  troubleshooting — the file shown in the add-on's Documentation tab.
 - `repository.yaml` at the root defines the repo display name/URL.
 ## Hostname rule
 Supervisor names add-ons `{sha1(repo_url)[:8]}-{slug-with-hyphens}`.
 For `https://git.i3omb.com/gronod/ha-gronod-addons` the prefix is
 `8e663231` (e.g. `8e663231-emby-mcp`). If the repo URL changes, the hash
 changes and every `{hash}-{slug}` reference in docs must be updated.
 (Pre-rename installs using `ha-emby-mcp` keep hash `c5cb4244`.)
 ## Verification
 Gitea Actions (`.gitea/workflows/validate.yml`) runs on push/PR to
 `develop` and `main`. Enable Actions on the repository and register a
 runner labelled `ubuntu-latest`.
 - emby-mcp (Go): `cd emby-mcp && go build ./... && go vet ./... && go test ./...`
  (see `emby-mcp/AGENTS.md`; the `internal/mcphttp` end-to-end tests are
  environment-sensitive and may time out on some machines)
 - YAML files: `python3 -c 'import yaml,sys; yaml.safe_load(open(sys.argv[1]))' <file>`
 - openai-codex-proxy: `node --check openai-codex-proxy/rootfs/entrypoint.js`
 - n95-mqtt-bridge: `build.yaml` / Dockerfile `UPSTREAM_REF`+`UPSTREAM_COMMIT`
  must match, and `go test ./...` on that tagged upstream clone
 ## Notes
 - The Go module `git.i3omb.com/gronod/emby-mcp` and its container image are
  published from the separate `gronod/emby-mcp` repo — do not repoint them.
@@ -1,254 +1,45 @@
-# ha-emby-mcp
+# Gronod's Home Assistant Add-Ons
-<img src="logo.png" alt="Emby MCP" width="128" height="128">
+Home Assistant custom add-on repository maintained by Gordon Bolton.
-Home Assistant custom add-on repository for **Emby MCP**.
+[![Add this repository to your Home Assistant instance.](https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgit.i3omb.com%2Fgronod%2Fha-gronod-addons)
-[![Add this repository to your Home Assistant instance.](https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgit.i3omb.com%2Fgronod%2Fha-emby-mcp)
+## Add-ons
 | Add-on | Description | Documentation |
 |---|---|---|
 | **Deebot N95 Local Control** | Local MQTT discovery and control for an already-provisioned Ecovacs Deebot N95 — replace its legacy cloud bootstrap and XMPP endpoint on a trusted LAN | [README](n95-mqtt-bridge/README.md) · [DOCS](n95-mqtt-bridge/DOCS.md) |
 | **Emby MCP** | Emby Model Context Protocol server with a REST bridge — search and control an Emby media library from MCP clients and Home Assistant conversation agents | [README](emby-mcp/README.md) · [DOCS](emby-mcp/DOCS.md) |
 | **OpenAI Codex Proxy** | OpenAI-compatible local endpoint backed by a ChatGPT account (Codex OAuth) — use ChatGPT Plus/Pro models from OpenAI-compatible integrations | [README](openai-codex-proxy/README.md) · [DOCS](openai-codex-proxy/DOCS.md) |
-The add-on runs the Go Emby.MCP server in one container and exposes:
+## Install this repository
 - Streamable MCP at `/mcp` (Claude, ChatGPT, and other MCP clients)
 - REST tool calls at `/call/{tool}` (Home Assistant REST / conversation tools)
 - Health checks at `/healthz` and `/health`
 Username, password and API key can be set in the add-on configuration.
 With **Restrict to localhost** on (default), only processes on the Home
 Assistant machine can connect, and those local calls use the stored
 credentials when no `Authorization` header is present.
 Turn the switch off only if you need LAN/remote MCP clients. In that mode
 stored credentials are **not** applied automatically; each client must send
 its own `Authorization` header.
 ## Install
 1. Home Assistant → **Settings → Add-ons → Add-on Store → ⋮ → Repositories**
-2. Add `https://git.i3omb.com/gronod/ha-emby-mcp`
+2. Add `https://git.i3omb.com/gronod/ha-gronod-addons`
-3. Install **Emby MCP**, set `emby_server_url` plus username/password or API key
+3. Install the add-on you want from the store and follow its documentation
 4. Leave **Restrict to localhost** enabled and start the add-on
-## Options
+> **Note:** This repository was previously published as
 > `https://git.i3omb.com/gronod/ha-emby-mcp`. The old URL still works (it
 > redirects), but if you switch an existing installation to the new URL the
 > add-on hostnames change — see each add-on's DOCS for details.
-| Option | Default | Description |
+## Development
 |---|---|---|
 | `emby_server_url` | `http://homeassistant.local:8096` | Emby base URL |
 | `emby_username` | _(empty)_ | Stored Emby username |
 | `emby_password` | _(empty)_ | Stored Emby password |
 | `emby_api_key` | _(empty)_ | Stored Emby API key |
 | `emby_user_id` | _(empty)_ | User id when using an API key |
 | `restrict_to_localhost` | `true` | Allow only loopback + HA container network; apply stored creds |
 | `emby_verify_ssl` | `true` | Verify TLS when talking to Emby |
 | `llm_max_items` | `100` | Max items per search chunk |
 | `mcp_transport` | `http` | Keep `http` |
 | `mcp_listen_addr` | `0.0.0.0:8085` | Bind address |
 | `mcp_session_timeout` | `30m` | MCP session lifetime |
 | `log_level` | `INFO` | `DEBUG`, `INFO`, or `WARN` |
 | `debug.rest` | _(optional)_ | Shown under optional options. At DEBUG, log REST bodies |
 | `debug.mcp` | _(optional)_ | Shown under optional options. At DEBUG, log `/mcp` bodies |
 | `debug.emby` | _(optional)_ | Shown under optional options. At DEBUG, log Emby API bodies |
-## Conversation agent
+`main` is protected: no direct pushes. `develop` is the integration branch and is also protected. Work on a feature branch, open a PR into `develop`, then PR `develop` → `main` after CI is green.
-Home Assistant Supervisor always names a custom-repo add-on
+Workflow: `.gitea/workflows/validate.yml` (runs on PRs to `develop` and `main`)
 `{repo-hash}-{slug}`. For this repository that DNS name is
 `c5cb4244-emby-mcp` (it cannot be changed to a custom hostname).
-These steps assume the add-on has Emby credentials configured and
+- YAML parse + `config.yaml` version vs `VERSION`
-**Restrict to localhost** is on. Home Assistant then calls
+- `emby-mcp`: `gofmt`, `go vet`, `go build`, `go test`
-`http://c5cb4244-emby-mcp:8085`; no `Authorization` header is required.
+- `openai-codex-proxy`: `node --check` on the entrypoint
 - `n95-mqtt-bridge`: upstream pin check + `go test` on the tagged upstream
-### System prompt
+A Gitea runner labelled `ubuntu-latest` must be registered for those jobs to run.
-Add this line to the conversation agent's instructions:
+## Support
-```text
+Open an issue on [the repository](https://git.i3omb.com/gronod/ha-gronod-addons/issues).
 - Media & Emby: Use `emby_search` to find films, TV series, episodes, or music tracks. Use `emby_episode_list` to list or count a series' episodes (seasons via `emby_season_list`). Use `emby_list_players` to find active playback sessions, and `emby_playback_control` to send playback commands (PlayNow, Pause, Unpause, Stop, NextTrack). Use `emby_next_episode` when asked what episode to watch next.
 ```
 ### Functions
 Paste the following into the conversation agent's **Functions** list
 (Settings → Voice assistants → your agent → Functions):
 ```yaml
 - spec:
    name: emby_search
    description: Search for films, TV series, episodes, or music tracks in the Emby media library.
    parameters:
      type: object
      properties:
        title_or_album:
          type: string
          description: Title of the media item, film, track, or album.
        artist_name:
          type: string
          description: Name of the artist or band (optional).
        genre_name:
          type: string
          description: Genre of the media (optional).
        item_types:
          type: string
          description: "Comma-separated filter, e.g. 'Movie', 'Series', 'Episode', or 'Audio'. Leave empty for all."
      required:
        - title_or_album
  function:
    type: rest
    resource_template: "http://c5cb4244-emby-mcp:8085/call/search_for_item"
    method: POST
    payload_template: >-
      {{ {
        "title_or_album": title_or_album,
        "artist_name": artist_name | default(""),
        "genre_name": genre_name | default(""),
        "broadcast_release_years": "",
        "item_types": item_types | default("")
      } | to_json }}
    value_template: "{{ value_json.result }}"
 - spec:
    name: emby_list_players
    description: List active Emby media players, active clients, and their session IDs.
    parameters:
      type: object
      properties:
        media_type:
          type: string
          description: Filter by player type ('Video', 'Audio', 'Photo'), or leave empty for all.
  function:
    type: rest
    resource_template: "http://c5cb4244-emby-mcp:8085/call/retrieve_player_list"
    method: POST
    payload_template: >-
      {{ { "media_type": media_type | default("") } | to_json }}
    value_template: "{{ value_json.result }}"
 - spec:
    name: emby_now_playing
    description: Get currently playing media details, audio tracks, and subtitle options for an active player session.
    parameters:
      type: object
      properties:
        session_id:
          type: string
          description: The player session ID obtained from emby_list_players.
      required:
        - session_id
  function:
    type: rest
    resource_template: "http://c5cb4244-emby-mcp:8085/call/retrieve_now_playing"
    method: POST
    payload_template: >-
      {{ { "session_id": session_id } | to_json }}
    value_template: "{{ value_json.result }}"
 - spec:
    name: emby_playback_control
    description: Send playback commands to an Emby player session (e.g. PlayNow, Pause, Unpause, Stop, NextTrack, PreviousTrack).
    parameters:
      type: object
      properties:
        session_id:
          type: string
          description: The target player session ID.
        command:
          type: string
          description: "Command: 'PlayNow', 'Stop', 'Pause', 'Unpause', 'NextTrack', 'PreviousTrack', 'Seek', 'Rewind', 'FastForward'."
        item_ids:
          type: string
          description: Comma-separated item IDs to queue or play immediately (required for PlayNow).
        time_milliseconds:
          type: integer
          description: Position in milliseconds for Seek/Rewind/FastForward, or start position for PlayNow (e.g. 246000 for 4:06). 0 when unused.
      required:
        - session_id
        - command
  function:
    type: rest
    resource_template: "http://c5cb4244-emby-mcp:8085/call/control_media_player"
    method: POST
    payload_template: >-
      {{ {
        "session_id": session_id,
        "command": command,
        "item_ids": item_ids | default(""),
        "time_milliseconds": time_milliseconds | default(0)
      } | to_json }}
    value_template: "{{ value_json.result }}"
 - spec:
    name: emby_season_list
    description: List the seasons of a TV series. Each result's item_id can be passed to emby_episode_list as season_id.
    parameters:
      type: object
      properties:
        series_id:
          type: string
          description: The series item_id obtained from emby_search with item_types 'Series'.
      required:
        - series_id
  function:
    type: rest
    resource_template: "http://c5cb4244-emby-mcp:8085/call/retrieve_season_list"
    method: POST
    payload_template: >-
      {{ { "series_id": series_id } | to_json }}
    value_template: "{{ value_json.result }}"
 - spec:
    name: emby_episode_list
    description: List or count the episodes of a TV series, optionally restricted to one season. total_number_of_items gives the episode count.
    parameters:
      type: object
      properties:
        series_id:
          type: string
          description: The series item_id obtained from emby_search with item_types 'Series'.
        season_id:
          type: string
          description: Optional season item_id from emby_season_list to restrict to one season.
      required:
        - series_id
  function:
    type: rest
    resource_template: "http://c5cb4244-emby-mcp:8085/call/retrieve_episode_list"
    method: POST
    payload_template: >-
      {{ {
        "series_id": series_id,
        "season_id": season_id | default("")
      } | to_json }}
    value_template: "{{ value_json.result }}"
 - spec:
    name: emby_next_episode
    description: Retrieve the next unplayed episode for a TV series.
    parameters:
      type: object
      properties:
        series_name:
          type: string
          description: The title of the television show.
      required:
        - series_name
  function:
    type: rest
    resource_template: "http://c5cb4244-emby-mcp:8085/call/retrieve_next_episode"
    method: POST
    payload_template: >-
      {{ {
        "series_name": series_name,
        "series_id": "",
        "mode": "next_unplayed"
      } | to_json }}
    value_template: "{{ value_json.result }}"
 ```
 If you changed the add-on port, replace `8085` in every `resource_template`.
 If **Restrict to localhost** is off, send an `Authorization` header on each request.
 ## License
-© 2026 Gordon Bolton. Based on Emby.MCP; this is a complete rewrite.
+© 2026 Gordon Bolton. GPL v3 — see `LICENCE.md`.
 GPL v3 — see `emby-mcp/LICENCE.md`.
@@ -1,5 +1,48 @@
 # Changelog
 ## 1.0.16
 - Player rows include `user_id`, `user_name`, `online`, and keep
  `device_ip_address` (Emby session `RemoteEndPoint`, host only)
 - `retrieve_player_list` accepts `users` (comma-separated include-list)
  and `include_offline` (merge `GET /Devices` last-used owners)
 - Add-on options `player_users` and `player_links` feed a default
  include-list and HA entity map (`ha_entity`, `ha_source`, `device_ip`,
  `emby_device_id`)
 - New tool `resolve_media_player` for "play on the lounge": returns
  HA entity/source plus `session_id` when live, or `wake_required`
 - Conversation Functions YAML and system prompt updated in DOCS.md
 ### Potential breaking change
 - Player JSON grows `user_id`, `user_name`, and `online`. Re-paste the
  DOCS.md Functions block to pick up `emby_list_players` parameters and
  `emby_resolve_player`. Existing PlayNow calls are unchanged.
 - Empty `player_users` means no default filter (same listing as 1.0.15,
  plus owner fields). Non-empty `player_users` hides other accounts even
  when the model omits `users`.
 ## 1.0.15
 - Restore `premiere_date` on item-shaped results (search, episode/season
  lists, next-episode, playlist items, play queue). Emby's `PremiereDate`
  is the first air date for episodes/series and the release date for
  movies; it is emitted as `YYYY-MM-DD` and omitted when metadata is empty
 - Request `PremiereDate` again in upstream `Fields`
 - Conversation-agent system prompt in DOCS.md now tells the model to read
  `premiere_date` for airdate questions
 ### Potential breaking change
 - Item JSON grows a `premiere_date` key versus the 1.0.11 slim shape.
  Home Assistant function *parameters* are unchanged (`value_template`
  still returns `value_json.result`). Re-paste the DOCS.md system prompt
  so the agent looks for `premiere_date`; the Functions YAML block does
  not need to be replaced unless you also want the updated prompt text
  nearby. Clients that reject unknown item keys must allow
  `premiere_date`.
 ## 1.0.14
 - `control_media_player` PlayNow now honours `time_milliseconds` as a start
@@ -1,4 +1,52 @@
-# Emby MCP add-on
+# Emby MCP — documentation
 Full configuration and usage documentation for the **Emby MCP** Home Assistant
 add-on, plus standalone (non-add-on) usage of the underlying Go server.
 ## Installation
 1. Add the repository to Home Assistant
   (**Settings → Add-ons → Add-on Store → ⋮ → Repositories**):
   `https://git.i3omb.com/gronod/ha-gronod-addons`
 2. Install **Emby MCP**
 3. Set `emby_server_url` plus username/password or an API key
 4. Leave **Restrict to localhost** enabled and start the add-on
 The add-on runs the Go Emby.MCP server in one container and exposes:
 - Streamable MCP at `/mcp` (Claude, ChatGPT, and other MCP clients)
 - REST tool calls at `/call/{tool}` (Home Assistant REST / conversation tools)
 - Health checks at `/healthz` and `/health`
 ## Configuration
 | Option | Default | Description |
 |---|---|---|
 | `emby_server_url` | `http://homeassistant.local:8096` | Emby base URL |
 | `emby_username` | _(empty)_ | Stored Emby username |
 | `emby_password` | _(empty)_ | Stored Emby password |
 | `emby_api_key` | _(empty)_ | Stored Emby API key |
 | `emby_user_id` | _(empty)_ | User id when using an API key |
 | `restrict_to_localhost` | `true` | Allow only loopback + HA container network; apply stored creds |
 | `emby_verify_ssl` | `true` | Verify TLS when talking to Emby |
 | `llm_max_items` | `100` | Max items per search chunk |
 | `mcp_transport` | `http` | Keep `http` |
 | `mcp_listen_addr` | `0.0.0.0:8085` | Bind address |
 | `mcp_session_timeout` | `30m` | MCP session lifetime |
 | `log_level` | `INFO` | `DEBUG`, `INFO`, or `WARN` |
 | `player_users` | `[]` | Default include-list of Emby usernames/ids applied when a tool call omits `users` |
 | `player_links` | `[]` | Maps spoken names to HA `media_player` + Emby device. `names` is comma-separated. Set `device_ip` when the TV's LAN IP is known (Emby `device_ip_address` on a live session). WebOS often does **not** put that IP on the HA entity — copy it from the router or from an Emby session while the app is open. `emby_device_id` is the most stable key. |
 | `debug.rest` | _(optional)_ | Shown under optional options. At DEBUG, log REST bodies |
 | `debug.mcp` | _(optional)_ | Shown under optional options. At DEBUG, log `/mcp` bodies |
 | `debug.emby` | _(optional)_ | Shown under optional options. At DEBUG, log Emby API bodies |
 With **Restrict to localhost** on (default), only processes on the Home
 Assistant machine can connect, and those local calls use the stored
 credentials when no `Authorization` header is present.
 Turn the switch off only if you need LAN/remote MCP clients. In that mode
 stored credentials are **not** applied automatically; each client must send
 its own `Authorization` header.
 ## Endpoints
@@ -12,13 +60,15 @@
 ## Auth
-Send Emby credentials on every `/mcp` and `/call/...` request:
+Send Emby credentials on every `/mcp` and `/call/...` request when
 `restrict_to_localhost` is off (or when calling remotely):
 - `Authorization: Basic <base64(user:pass)>`
 - `Authorization: Bearer <emby-token-or-api-key>`
 - Optional: `X-Emby-User-Id` or `X-Emby-Username`
-Do not put username/password in the add-on options.
+Username/password can also be stored in the add-on options; they are applied
 automatically to local calls while `restrict_to_localhost` is on.
 ## Tool names
@@ -29,23 +79,449 @@ Arguments not declared in the tool's current input schema are dropped before
 the call is forwarded; the JSON response then includes
 `"dropped_arguments": ["name", ...]` listing what was ignored.
 ## Conversation agent
-## Configuration
+Home Assistant Supervisor names a custom-repo add-on `{repo-hash}-{slug}`.
 The repo hash is derived from the repository URL, so it depends on which URL
 was added:
-| Option | Purpose |
+| Repository URL | Add-on hostname |
 |---|---|
-| `emby_server_url` | Emby base URL |
+| `https://git.i3omb.com/gronod/ha-gronod-addons` | `8e663231-emby-mcp` |
-| `emby_username` | Stored Emby username (optional if the client sends Basic/Bearer) |
+| `https://git.i3omb.com/gronod/ha-emby-mcp` (pre-rename) | `c5cb4244-emby-mcp` |
 | `emby_password` | Stored Emby password |
 | `emby_api_key` | Stored Emby API key (alternative to user/pass) |
 | `emby_user_id` | Required with an API key if the key is not user-scoped |
 | `restrict_to_localhost` | Bind `127.0.0.1` and reject non-loopback peers |
-When `restrict_to_localhost` is enabled (default), the add-on uses
+The examples below use `8e663231-emby-mcp`. If you added the repository before
-`host_network` and listens on the HA machine loopback only. Local REST/MCP
+the rename, replace it with `c5cb4244-emby-mcp` throughout (it cannot be
-calls from Home Assistant do not need an `Authorization` header if username
+changed to a custom hostname).
 + password or an API key is set in the add-on options.
-When the switch is off, the server listens on all interfaces and **does not**
+These steps assume the add-on has Emby credentials configured and
-apply stored credentials to incoming requests. Remote clients must send
+**Restrict to localhost** is on. Home Assistant then calls
-`Authorization` themselves so the LAN cannot use the add-on as an open proxy.
+`http://8e663231-emby-mcp:8085`; no `Authorization` header is required.
 ### System prompt
 Add this line to the conversation agent's instructions:
 ```text
 - Media & Emby: Never use execute_services for Emby search or playback. Use `emby_search` to find films, TV series, episodes, or music tracks. Use `emby_episode_list` to list or count a series' episodes (seasons via `emby_season_list`). Each episode item includes `premiere_date` (YYYY-MM-DD first air date) when Emby has that metadata; use it for airdate questions. Use `emby_resolve_player` when the user names a room or TV ("play on the lounge"). If `wake_required` is true, use Home Assistant `media_player.turn_on` on `ha_entity` and `media_player.select_source` with `ha_source` (Emby), wait, then resolve again. Only then use `emby_playback_control` PlayNow with that `session_id`. Use `emby_list_players` with `users` set to the household include-list to hide other people's clients. Use `emby_next_episode` when asked what episode to watch next.
 ```
 ### Functions
 Paste the following into the conversation agent's **Functions** list
 (Settings → Voice assistants → your agent → Functions):
 ```yaml
 - spec:
    name: emby_search
    description: Search for films, TV series, episodes, or music tracks in the Emby media library.
    parameters:
      type: object
      properties:
        title_or_album:
          type: string
          description: Title of the media item, film, track, or album.
        artist_name:
          type: string
          description: Name of the artist or band (optional).
        genre_name:
          type: string
          description: Genre of the media (optional).
        item_types:
          type: string
          description: "Comma-separated filter, e.g. 'Movie', 'Series', 'Episode', or 'Audio'. Leave empty for all."
      required:
        - title_or_album
  function:
    type: rest
    resource_template: "http://8e663231-emby-mcp:8085/call/search_for_item"
    method: POST
    payload_template: >-
      {{ {
        "title_or_album": title_or_album,
        "artist_name": artist_name | default(""),
        "genre_name": genre_name | default(""),
        "broadcast_release_years": "",
        "item_types": item_types | default("")
      } | to_json }}
    value_template: "{{ value_json.result }}"
 - spec:
    name: emby_list_players
    description: List Emby media players. Each row includes user_name, user_id, device_ip_address, and online. Pass users as a comma-separated include-list of Emby usernames so other household accounts are omitted. Set include_offline true to include last-used devices with no live session.
    parameters:
      type: object
      properties:
        media_type:
          type: string
          description: Filter by player type ('Video', 'Audio', 'Photo'), or leave empty for all.
        users:
          type: string
          description: Comma-separated Emby usernames or user ids to include (household include-list).
        include_offline:
          type: boolean
          description: Also list known Emby devices that have no live session (last-used user).
  function:
    type: rest
    resource_template: "http://8e663231-emby-mcp:8085/call/retrieve_player_list"
    method: POST
    payload_template: >-
      {{ { "media_type": media_type | default(""), "users": users | default(""), "include_offline": include_offline | default(false) } | to_json }}
    value_template: "{{ value_json.result }}"
 - spec:
    name: emby_resolve_player
    description: Resolve a room name, person, HA entity, Emby device name, device id, or IP to ha_entity/ha_source plus a live session_id when the Emby client is running. If wake_required is true, turn on the HA media_player and launch Emby before PlayNow.
    parameters:
      type: object
      properties:
        query:
          type: string
          description: Spoken name (lounge), media_player entity_id, Emby device name, device id, or IP.
        users:
          type: string
          description: Comma-separated Emby usernames or user ids to include.
      required:
        - query
  function:
    type: rest
    resource_template: "http://8e663231-emby-mcp:8085/call/resolve_media_player"
    method: POST
    payload_template: >-
      {{ { "query": query, "users": users | default("") } | to_json }}
    value_template: "{{ value_json.result }}"
 - spec:
    name: emby_now_playing
    description: Get currently playing media details, audio tracks, and subtitle options for an active player session.
    parameters:
      type: object
      properties:
        session_id:
          type: string
          description: The player session ID obtained from emby_list_players.
      required:
        - session_id
  function:
    type: rest
    resource_template: "http://8e663231-emby-mcp:8085/call/retrieve_now_playing"
    method: POST
    payload_template: >-
      {{ { "session_id": session_id } | to_json }}
    value_template: "{{ value_json.result }}"
 - spec:
    name: emby_playback_control
    description: Send playback commands to an Emby player session (e.g. PlayNow, Pause, Unpause, Stop, NextTrack, PreviousTrack).
    parameters:
      type: object
      properties:
        session_id:
          type: string
          description: The target player session ID.
        command:
          type: string
          description: "Command: 'PlayNow', 'Stop', 'Pause', 'Unpause', 'NextTrack', 'PreviousTrack', 'Seek', 'Rewind', 'FastForward'."
        item_ids:
          type: string
          description: Comma-separated item IDs to queue or play immediately (required for PlayNow).
        time_milliseconds:
          type: integer
          description: Position in milliseconds for Seek/Rewind/FastForward, or start position for PlayNow (e.g. 246000 for 4:06). 0 when unused.
      required:
        - session_id
        - command
  function:
    type: rest
    resource_template: "http://8e663231-emby-mcp:8085/call/control_media_player"
    method: POST
    payload_template: >-
      {{ {
        "session_id": session_id,
        "command": command,
        "item_ids": item_ids | default(""),
        "time_milliseconds": time_milliseconds | default(0)
      } | to_json }}
    value_template: "{{ value_json.result }}"
 - spec:
    name: emby_season_list
    description: List the seasons of a TV series. Each result's item_id can be passed to emby_episode_list as season_id.
    parameters:
      type: object
      properties:
        series_id:
          type: string
          description: The series item_id obtained from emby_search with item_types 'Series'.
      required:
        - series_id
  function:
    type: rest
    resource_template: "http://8e663231-emby-mcp:8085/call/retrieve_season_list"
    method: POST
    payload_template: >-
      {{ { "series_id": series_id } | to_json }}
    value_template: "{{ value_json.result }}"
 - spec:
    name: emby_episode_list
    description: List or count the episodes of a TV series, optionally restricted to one season. total_number_of_items gives the episode count.
    parameters:
      type: object
      properties:
        series_id:
          type: string
          description: The series item_id obtained from emby_search with item_types 'Series'.
        season_id:
          type: string
          description: Optional season item_id from emby_season_list to restrict to one season.
      required:
        - series_id
  function:
    type: rest
    resource_template: "http://8e663231-emby-mcp:8085/call/retrieve_episode_list"
    method: POST
    payload_template: >-
      {{ {
        "series_id": series_id,
        "season_id": season_id | default("")
      } | to_json }}
    value_template: "{{ value_json.result }}"
 - spec:
    name: emby_next_episode
    description: Retrieve the next unplayed episode for a TV series.
    parameters:
      type: object
      properties:
        series_name:
          type: string
          description: The title of the television show.
      required:
        - series_name
  function:
    type: rest
    resource_template: "http://8e663231-emby-mcp:8085/call/retrieve_next_episode"
    method: POST
    payload_template: >-
      {{ {
        "series_name": series_name,
        "series_id": "",
        "mode": "next_unplayed"
      } | to_json }}
    value_template: "{{ value_json.result }}"
 ```
 If you changed the add-on port, replace `8085` in every `resource_template`.
 If **Restrict to localhost** is off, send an `Authorization` header on each request.
 Item-shaped tool results (search, episode list, next episode, queues) include
 `premiere_date` as `YYYY-MM-DD` when Emby metadata has a first air / release
 date. The Functions YAML above does not declare that field — it arrives inside
 `value_json.result`. Update the system prompt so the model reads it.
 ## Standalone usage (outside Home Assistant)
 The same Go binary can run outside the add-on, e.g. on a desktop or NAS.
 Build it from this directory:
 ```sh
 go build -o emby-mcp ./cmd/emby-mcp
 ```
 Requires Go 1.27+.
 ### Environment configuration
 Create a `.env` file (in the working directory or next to the binary):
 ```
 EMBY_SERVER_URL = "http://localhost:8096"
 # Either username/password:
 EMBY_USERNAME = "user"
 EMBY_PASSWORD = "pass"
 # ...or an API key plus the user ID it should act as:
 # EMBY_API_KEY = "..."
 # EMBY_USER_ID = "..."
 # Set to False to skip SSL certificate verification (e.g. self-signed).
 EMBY_VERIFY_SSL = True
 # Max items per search-result chunk; 0 = no limit.
 LLM_MAX_ITEMS = 100
 # Transport: "stdio" (default) or "http" (streamable HTTP at /mcp).
 MCP_TRANSPORT = stdio
 # HTTP mode: bind address and idle-session timeout.
 MCP_LISTEN_ADDR = "127.0.0.1:8080"
 MCP_SESSION_TIMEOUT = 30m
 ```
 In `http` mode the `EMBY_USERNAME`/`EMBY_PASSWORD`/`EMBY_API_KEY` variables are
 not needed — every request authenticates against Emby (see Auth above).
 ### Run modes
 Startup checks only (login + list libraries, then exit):
 ```sh
 ./emby-mcp -check
 ```
 Run the MCP server on stdio:
 ```sh
 ./emby-mcp
 ```
 HTTP mode (streamable HTTP transport, SSE streaming at `POST /mcp`):
 ```sh
 MCP_TRANSPORT=http MCP_LISTEN_ADDR=0.0.0.0:8080 ./emby-mcp
 ```
 `/healthz` is an unauthenticated liveness endpoint. Each MCP session is
 isolated: it gets its own library selection and search-chunking state, and
 requests to a session are rejected if they authenticate as a different user.
 Plain HTTP only — put the server behind a reverse proxy for TLS.
 ### Docker (standalone image)
 ```sh
 docker run -e EMBY_SERVER_URL="http://emby:8096" -p 8080:8080 \
    git.i3omb.com/gronod/emby-mcp:1.0.0
 ```
 The image defaults to `MCP_TRANSPORT=http` on `0.0.0.0:8080`.
 ### Docker Compose / TrueNAS SCALE
 The YAML below is a Compose v2 file suitable for a TrueNAS SCALE Custom App
 (Apps → Discover → Custom App / Install via YAML) as well as plain
 `docker compose up -d`.
 Replace the placeholder values. On SCALE, map the same keys in the app
 environment UI if you prefer not to bake them into the file. Use the NAS
 host/IP (or an internal container DNS name) for `EMBY_SERVER_URL` so the
 app can reach Emby; `host` networking is an alternative if Emby is also
 on the same TrueNAS box.
 In HTTP mode (`MCP_TRANSPORT=http`, the image default) per-request Emby
 auth is used and `EMBY_USERNAME` / `EMBY_PASSWORD` / `EMBY_API_KEY` are
 optional. They are included so the same file also works if you switch
 the container to stdio or want a default identity.
 ```yaml
 # emby-mcp — TrueNAS SCALE Custom App / docker compose
 # Placeholders: replace every CHANGE_ME_* value before starting.
 services:
  emby-mcp:
    image: git.i3omb.com/gronod/emby-mcp:1.0.0
    container_name: emby-mcp
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      EMBY_SERVER_URL: "http://CHANGE_ME_EMBY_HOST:8096"
      # Username/password login (leave empty if using an API key):
      EMBY_USERNAME: "CHANGE_ME_EMBY_USERNAME"
      EMBY_PASSWORD: "CHANGE_ME_EMBY_PASSWORD"
      # API-key login (leave empty if using username/password).
      # EMBY_USER_ID is required when EMBY_API_KEY is set:
      EMBY_API_KEY: "CHANGE_ME_EMBY_API_KEY"
      EMBY_USER_ID: "CHANGE_ME_EMBY_USER_ID"
      EMBY_VERIFY_SSL: "true"
      LLM_MAX_ITEMS: "100"
      MCP_TRANSPORT: "http"
      MCP_LISTEN_ADDR: "0.0.0.0:8080"
      MCP_SESSION_TIMEOUT: "30m"
    # Scratch image has no shell/curl — omit healthcheck, or front with a proxy.
    # networks: [host]   # uncomment instead of ports: if Emby is on the same NAS
 ```
 MCP endpoint after start: `POST http://<truenas-host>:8080/mcp`
 Liveness: `GET http://<truenas-host>:8080/healthz`
 ### Claude Desktop example (stdio)
 ```json
 {
  "mcpServers": {
    "Emby": {
      "command": "/path/to/emby-mcp",
      "args": ["-env", "/path/to/.env"]
    }
  }
 }
 ```
 ### Streamable HTTP example (`mcpServers`)
 Point an MCP client at the server's `/mcp` endpoint. Every request must
 carry Emby credentials in headers (see Auth above). Replace the
 placeholders.
 API key (add `X-Emby-User-Id` or `X-Emby-Username` if the key is server-wide):
 ```json
 {
  "mcpServers": {
    "Emby": {
      "type": "http",
      "url": "http://CHANGE_ME_MCP_HOST:8080/mcp",
      "headers": {
        "Authorization": "Bearer CHANGE_ME_EMBY_API_KEY",
        "X-Emby-User-Id": "CHANGE_ME_EMBY_USER_ID"
      }
    }
  }
 }
 ```
 Username and password (sent as HTTP Basic; the server exchanges them for an
 Emby access token):
 ```json
 {
  "mcpServers": {
    "Emby": {
      "type": "http",
      "url": "http://CHANGE_ME_MCP_HOST:8080/mcp",
      "headers": {
        "Authorization": "Basic CHANGE_ME_BASE64_USER_COLON_PASS"
      }
    }
  }
 }
 ```
 `CHANGE_ME_MCP_HOST` is the host where emby-mcp is published (TrueNAS IP or
 hostname), not the Emby server. `CHANGE_ME_BASE64_USER_COLON_PASS` is
 `base64("<username>:<password>")`. Clients that do not understand `"type":
 "http"` may accept the same block with only `"url"` and `"headers"`.
 ## Development
 ```sh
 go build ./...
 go vet ./...
 go test ./...
 ```
 Layout:
 * `cmd/emby-mcp` — entry point, config loading, startup checks
 * `internal/emby` — Emby REST client (auth, libraries, items, playlists, sessions)
 * `internal/server` — MCP tool handlers (official go-sdk)
 * `internal/mcphttp` — streamable-HTTP transport with per-request Emby auth
 * `internal/state` — shared session state (library selection, search chunking)
 * `internal/config` — `.env` parsing
 * `internal/textutil` — Unicode→ASCII folding for text matching
 * `docs/api/emby_openapi.json` — Emby REST API spec (reference)
 Upstream endpoint conformance is checked by `internal/emby/spec_conformance_test.go`;
 see [`docs/api/endpoint_validation.md`](docs/api/endpoint_validation.md) for the
 audit report. Planned features live in [`docs/ROADMAP.md`](docs/ROADMAP.md).
@@ -20,7 +20,7 @@ LABEL \
  io.hass.name="Emby MCP" \
  io.hass.description="Emby Model Context Protocol server with REST bridge" \
  io.hass.type="addon" \
-  io.hass.version="1.0.10" \
+  io.hass.version="1.0.16" \
-  org.opencontainers.image.title="ha-emby-mcp" \
+  org.opencontainers.image.title="emby-mcp" \
-  org.opencontainers.image.source="https://git.i3omb.com/gronod/ha-emby-mcp"
+  org.opencontainers.image.source="https://git.i3omb.com/gronod/ha-gronod-addons"
 CMD [ "/run.sh" ]
@@ -1,252 +1,49 @@
-# emby-mcp (Go)
+# Emby MCP
-Go rewrite of the Python [Emby.MCP](https://github.com/angelltek/Emby.MCP) server — a Model Context
+<img src="logo.png" alt="Emby MCP" width="128" height="128">
 Protocol (MCP) server that connects an Emby media server to an AI client such
 as Claude Desktop.
-The original 20 tools match the Python version's parameter names; JSON output
+Emby Model Context Protocol (MCP) server with a Home Assistant REST bridge,
-shapes are slimmed (empty fields are omitted, low-value metadata dropped).
+packaged as a Home Assistant add-on.
-Additional Go-only tools add library browsing, next-episode resolution, and
+
-subtitle/audio-track control.
+Connect your Emby media server to AI clients and Home Assistant voice/conversation
 agents — search the library, browse shows and episodes, manage playlists, see
 what's playing, and control playback, all through natural-language tool calls.
 ## Features
-* Log on to / log out of an Emby media server (username/password, or API key)
+* Streamable MCP endpoint at `/mcp` for Claude, ChatGPT, and other MCP clients
-* List libraries, select a library, list genres
+* REST tool bridge at `/call/{tool}` designed for Home Assistant conversation
-* Search items by title/album, artist, genre, release years, and
+  agents (works with Assist functions)
-  item type (`item_types`, e.g. `Series`) — with chunked results for large
+* Search films, TV series, episodes, and music with chunked results for large
  libraries
-* Browse an item's children, a series' seasons, and a series' episodes
+* Browse item children, series seasons, and episode lists with per-user played
-  (`retrieve_item_children`, `retrieve_season_list`, `retrieve_episode_list`),
+  state and resume positions
-  including per-user played state and resume positions
+* Resolve the next episode to watch (`next_unplayed`/`latest`)
-* Resolve the next episode to play (`retrieve_next_episode`, modes
+* Create and modify playlists; list player sessions and control playback
-  `next_unplayed`/`latest`) without a library selection
+  (PlayNow, pause, seek, skip)
-* Create/modify playlists, add/remove/reorder items, share playlists
+* Inspect and switch audio/subtitle tracks mid-playback
-* List player sessions, retrieve play queues, control playback
+* Localhost-restricted mode (default): only Home Assistant itself can call the
-  (play/pause/seek/skip, PlayNow)
+  bridge, using stored credentials — no per-request auth needed
 * Inspect the now-playing item's audio/subtitle tracks
  (`retrieve_now_playing`) and switch tracks (`set_subtitle`,
  `set_audio_track`) — mid-playback where the player supports it, else
  restart-at-position
-## Build
+## Requirements
-```
+* A running [Emby](https://emby.media) server reachable from Home Assistant
-go build -o emby-mcp ./cmd/emby-mcp
+* Emby credentials: username + password, or an API key (+ user ID)
 ```
-Requires Go 1.27+.
+## Installation
-## Configuration
+1. Add this repository to Home Assistant
   (**Settings → Add-ons → Add-on Store → ⋮ → Repositories**):
   `https://git.i3omb.com/gronod/ha-gronod-addons`
 2. Install **Emby MCP** from the add-on store
 3. Set `emby_server_url` plus `emby_username`/`emby_password` (or
   `emby_api_key` + `emby_user_id`), leave **Restrict to localhost** on, and
   start the add-on
-Create a `.env` file (in the working directory or next to the binary):
+See [DOCS.md](DOCS.md) for the full option reference, conversation-agent
-
+setup, troubleshooting, and standalone (non-add-on) usage.
 ```
 EMBY_SERVER_URL = "http://localhost:8096"
 # Either username/password:
 EMBY_USERNAME = "user"
 EMBY_PASSWORD = "pass"
 # ...or an API key plus the user ID it should act as:
 # EMBY_API_KEY = "..."
 # EMBY_USER_ID = "..."
 # Set to False to skip SSL certificate verification (e.g. self-signed).
 EMBY_VERIFY_SSL = True
 # Max items per search-result chunk; 0 = no limit.
 LLM_MAX_ITEMS = 100
 # Transport: "stdio" (default) or "http" (streamable HTTP at /mcp).
 MCP_TRANSPORT = stdio
 # HTTP mode: bind address and idle-session timeout.
 MCP_LISTEN_ADDR = "127.0.0.1:8080"
 MCP_SESSION_TIMEOUT = 30m
 ```
 In `http` mode the `EMBY_USERNAME`/`EMBY_PASSWORD`/`EMBY_API_KEY` variables are
 not needed — every request authenticates against Emby (see below).
 ## Usage
 Startup checks only (login + list libraries, then exit):
 ```
 ./emby-mcp -check
 ```
 Run the MCP server on stdio:
 ```
 ./emby-mcp
 ```
 ### HTTP mode
 ```
 MCP_TRANSPORT=http MCP_LISTEN_ADDR=0.0.0.0:8080 ./emby-mcp
 ```
 Serves the MCP [streamable HTTP](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports)
 transport (SSE streaming) at `POST http://<addr>/mcp`. `/healthz` is an
 unauthenticated liveness endpoint.
 Every request must carry Emby credentials:
 * `Authorization: Basic base64(user:pass)` — exchanged for an Emby access
  token via `AuthenticateByName` (cached ~15 min).
 * `Authorization: Bearer <token>` — an Emby access token or API key used
  directly. The token's owning user is resolved automatically via
  `GET /Sessions`; server-wide API keys and other ambiguous tokens require a
  disambiguation header:
  * `X-Emby-User-Id: <id>` — the Emby user to act as (validated), or
  * `X-Emby-Username: <name>` — looked up via the public user list.
 Each MCP session is isolated: it gets its own library selection and
 search-chunking state, and requests to a session are rejected if they
 authenticate as a different user.
 Plain HTTP only — put the server behind a reverse proxy for TLS.
 ### Docker
 ```
 docker run -e EMBY_SERVER_URL="http://emby:8096" -p 8080:8080 \
    git.i3omb.com/gronod/emby-mcp:1.0.0
 ```
 The image defaults to `MCP_TRANSPORT=http` on `0.0.0.0:8080`.
 ### Docker Compose / TrueNAS SCALE
 The YAML below is a Compose v2 file suitable for a TrueNAS SCALE Custom App
 (Apps → Discover → Custom App / Install via YAML) as well as plain
 `docker compose up -d`.
 Replace the placeholder values. On SCALE, map the same keys in the app
 environment UI if you prefer not to bake them into the file. Use the NAS
 host/IP (or an internal container DNS name) for `EMBY_SERVER_URL` so the
 app can reach Emby; `host` networking is an alternative if Emby is also
 on the same TrueNAS box.
 In HTTP mode (`MCP_TRANSPORT=http`, the image default) per-request Emby
 auth is used and `EMBY_USERNAME` / `EMBY_PASSWORD` / `EMBY_API_KEY` are
 optional. They are included so the same file also works if you switch
 the container to stdio or want a default identity.
 ```yaml
 # emby-mcp — TrueNAS SCALE Custom App / docker compose
 # Placeholders: replace every CHANGE_ME_* value before starting.
 services:
  emby-mcp:
    image: git.i3omb.com/gronod/emby-mcp:1.0.0
    container_name: emby-mcp
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      EMBY_SERVER_URL: "http://CHANGE_ME_EMBY_HOST:8096"
      # Username/password login (leave empty if using an API key):
      EMBY_USERNAME: "CHANGE_ME_EMBY_USERNAME"
      EMBY_PASSWORD: "CHANGE_ME_EMBY_PASSWORD"
      # API-key login (leave empty if using username/password).
      # EMBY_USER_ID is required when EMBY_API_KEY is set:
      EMBY_API_KEY: "CHANGE_ME_EMBY_API_KEY"
      EMBY_USER_ID: "CHANGE_ME_EMBY_USER_ID"
      EMBY_VERIFY_SSL: "true"
      LLM_MAX_ITEMS: "100"
      MCP_TRANSPORT: "http"
      MCP_LISTEN_ADDR: "0.0.0.0:8080"
      MCP_SESSION_TIMEOUT: "30m"
    # Scratch image has no shell/curl — omit healthcheck, or front with a proxy.
    # networks: [host]   # uncomment instead of ports: if Emby is on the same NAS
 ```
 MCP endpoint after start: `POST http://<truenas-host>:8080/mcp`  
 Liveness: `GET http://<truenas-host>:8080/healthz`
 ### Claude Desktop example (stdio)
 ```json
 {
  "mcpServers": {
    "Emby": {
      "command": "/path/to/emby-mcp",
      "args": ["-env", "/path/to/.env"]
    }
  }
 }
 ```
 ### Streamable HTTP example (`mcpServers`)
 Point an MCP client at the container's `/mcp` endpoint. Every request must
 carry Emby credentials in headers (see HTTP mode above). Replace the
 placeholders.
 API key (add `X-Emby-User-Id` or `X-Emby-Username` if the key is server-wide):
 ```json
 {
  "mcpServers": {
    "Emby": {
      "type": "http",
      "url": "http://CHANGE_ME_MCP_HOST:8080/mcp",
      "headers": {
        "Authorization": "Bearer CHANGE_ME_EMBY_API_KEY",
        "X-Emby-User-Id": "CHANGE_ME_EMBY_USER_ID"
      }
    }
  }
 }
 ```
 Username and password (sent as HTTP Basic; the server exchanges them for an
 Emby access token):
 ```json
 {
  "mcpServers": {
    "Emby": {
      "type": "http",
      "url": "http://CHANGE_ME_MCP_HOST:8080/mcp",
      "headers": {
        "Authorization": "Basic CHANGE_ME_BASE64_USER_COLON_PASS"
      }
    }
  }
 }
 ```
 `CHANGE_ME_MCP_HOST` is the host where emby-mcp is published (TrueNAS IP or
 hostname), not the Emby server. `CHANGE_ME_BASE64_USER_COLON_PASS` is
 `base64("<username>:<password>")`. Clients that do not understand `"type":
 "http"` may accept the same block with only `"url"` and `"headers"`.
 ## Development
 ```
 go build ./...
 go vet ./...
 go test ./...
 ```
 Layout:
 * `cmd/emby-mcp` — entry point, config loading, startup checks
 * `internal/emby` — Emby REST client (auth, libraries, items, playlists, sessions)
 * `internal/server` — MCP tool handlers (official go-sdk)
 * `internal/mcphttp` — streamable-HTTP transport with per-request Emby auth
 * `internal/state` — shared session state (library selection, search chunking)
 * `internal/config` — `.env` parsing
 * `internal/textutil` — Unicode→ASCII folding for text matching
 * `docs/api/emby_openapi.json` — Emby REST API spec (reference)
 Upstream endpoint conformance is checked by `internal/emby/spec_conformance_test.go`; see [`docs/api/endpoint_validation.md`](docs/api/endpoint_validation.md) for the audit report. Planned features live in [`docs/ROADMAP.md`](docs/ROADMAP.md).
 ## License
-© 2026 Gordon Bolton. Based on Emby.MCP; this is a complete rewrite.
+© 2026 Gordon Bolton. Based on [Emby.MCP](https://github.com/angeltek/Emby.MCP);
-
+this is a complete rewrite. GPL v3 — see `LICENCE.md`.
 GPL v3 — see `LICENCE.md`.
@@ -1 +1 @@
-1.0.14
+1.0.16
@@ -18,7 +18,6 @@ import (
 	"syscall"
 	"time"
 	"github.com/google/uuid"
 	"git.i3omb.com/gronod/emby-mcp/internal/applog"
 	"git.i3omb.com/gronod/emby-mcp/internal/bridge"
 	"git.i3omb.com/gronod/emby-mcp/internal/config"
@@ -26,6 +25,7 @@ import (
 	"git.i3omb.com/gronod/emby-mcp/internal/mcphttp"
 	"git.i3omb.com/gronod/emby-mcp/internal/server"
 	"git.i3omb.com/gronod/emby-mcp/internal/state"
 	"github.com/google/uuid"
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
@@ -122,6 +122,8 @@ func runStdio(ctx context.Context, cfg *config.Config, checkOnly bool) {
 	logf("Startup checks have completed.\n\nRunning HA Emby MCP in standalone mode, press CTRL-C to exit.")
 	st := state.New(client, userID, cfg.MaxChunkSize)
 	st.PlayerUsers = cfg.PlayerUsers
 	st.PlayerLinks = cfg.PlayerLinks
 	srv := server.New(st)
 	runErr := srv.Run(ctx, &mcp.StdioTransport{})
@@ -2,7 +2,7 @@ name: "Emby MCP"
 description: >-
  Emby Model Context Protocol server with a Home Assistant REST bridge.
  Serves streamable MCP at /mcp and REST tool calls at /call/{tool}.
-version: "1.0.14"
+version: "1.0.16"
 slug: "emby_mcp"
 init: false
 startup: application
@@ -31,6 +31,8 @@ options:
  mcp_listen_addr: "0.0.0.0:8085"
  mcp_session_timeout: "30m"
  log_level: INFO
  player_users: []
  player_links: []
 schema:
  emby_server_url: str
  emby_username: str
@@ -44,6 +46,16 @@ schema:
  mcp_listen_addr: str
  mcp_session_timeout: str
  log_level: list(DEBUG|INFO|WARN)
  player_users:
    - str
  player_links:
    - names: str
      emby_device_id: str?
      emby_device_name: str?
      device_ip: str?
      ha_entity: str
      ha_source: str?
      users: str?
  debug:
    rest: bool?
    mcp: bool?
@@ -28,13 +28,26 @@ type Config struct {
 	VerifySSL           bool          // EMBY_VERIFY_SSL, default true
 	MaxChunkSize        int           // LLM_MAX_ITEMS; 0 or negative means no chunking limit
 	Transport           string        // MCP_TRANSPORT: "stdio" (default) or "http"
-	ListenAddr          string        // MCP_LISTEN_ADDR, default "127.0.0.1:8085"
+	ListenAddr          string        // MCP_LISTEN_ADDR, default "0.0.0.0:8085"
 	SessionTimeout      time.Duration // MCP_SESSION_TIMEOUT, default 30m; <=0 disables
 	RestrictToLocalhost bool          // MCP_RESTRICT_LOCALHOST
 	LogLevel            string        // LOG_LEVEL: DEBUG, INFO, WARN
 	DebugREST           bool          // DEBUG_REST
 	DebugMCP            bool          // DEBUG_MCP
 	DebugEmby           bool          // DEBUG_EMBY
 	PlayerUsers         []string      // PLAYER_USERS include-list (names or ids)
 	PlayerLinks         []PlayerLink  // PLAYER_LINKS JSON mappings to HA entities
 }
 // PlayerLink maps spoken names / Emby device identity onto a Home Assistant media_player.
 type PlayerLink struct {
 	Names          []string `json:"names"`
 	EmbyDeviceID   string   `json:"emby_device_id"`
 	EmbyDeviceName string   `json:"emby_device_name"`
 	DeviceIP       string   `json:"device_ip"`
 	HAEntity       string   `json:"ha_entity"`
 	HASource       string   `json:"ha_source"`
 	Users          []string `json:"users"`
 }
 // Load reads the .env file at path (if it exists), lets real environment
@@ -58,6 +71,7 @@ func Load(path string) (*Config, error) {
 		"MCP_TRANSPORT", "MCP_LISTEN_ADDR", "MCP_SESSION_TIMEOUT",
 		"MCP_RESTRICT_LOCALHOST",
 		"LOG_LEVEL", "DEBUG_REST", "DEBUG_MCP", "DEBUG_EMBY",
 		"PLAYER_USERS", "PLAYER_LINKS",
 	} {
 		if v, ok := os.LookupEnv(k); ok && v != "" {
 			vals[k] = v
@@ -102,6 +116,15 @@ func Load(path string) (*Config, error) {
 		cfg.SessionTimeout = d
 	}
 	cfg.PlayerUsers = SplitCSV(vals["PLAYER_USERS"])
 	if s := strings.TrimSpace(vals["PLAYER_LINKS"]); s != "" {
 		links, err := ParsePlayerLinks(s)
 		if err != nil {
 			return nil, fmt.Errorf("invalid PLAYER_LINKS: %w", err)
 		}
 		cfg.PlayerLinks = links
 	}
 	if cfg.ServerURL == "" {
 		return nil, fmt.Errorf("missing required variable EMBY_SERVER_URL")
 	}
@@ -15,6 +15,7 @@ func clearEnv(t *testing.T) {
 		"EMBY_SERVER_URL", "EMBY_USERNAME", "EMBY_PASSWORD",
 		"EMBY_API_KEY", "EMBY_USER_ID", "EMBY_VERIFY_SSL", "LLM_MAX_ITEMS",
 		"MCP_TRANSPORT", "MCP_LISTEN_ADDR", "MCP_SESSION_TIMEOUT",
 		"PLAYER_USERS", "PLAYER_LINKS",
 	} {
 		t.Setenv(k, "")
 	}
@@ -98,7 +99,7 @@ EMBY_PASSWORD="p"`)
 	if cfg.Transport != TransportStdio {
 		t.Errorf("Transport = %q", cfg.Transport)
 	}
-	if cfg.ListenAddr != "127.0.0.1:8085" {
+	if cfg.ListenAddr != "0.0.0.0:8085" {
 		t.Errorf("ListenAddr = %q", cfg.ListenAddr)
 	}
 	if cfg.SessionTimeout != 30*time.Minute {
@@ -130,3 +131,25 @@ MCP_TRANSPORT=grpc`)
 		t.Fatal("expected error for invalid transport")
 	}
 }
 func TestLoadPlayerPolicy(t *testing.T) {
 	clearEnv(t)
 	p := writeEnv(t, `EMBY_SERVER_URL="http://x"
 EMBY_USERNAME=u
 EMBY_PASSWORD=p
 PLAYER_USERS=Gordon, Alice
 PLAYER_LINKS=[{"names":"lounge,living room","ha_entity":"media_player.lounge","device_ip":"192.168.0.20","ha_source":"Emby"}]`)
 	cfg, err := Load(p)
 	if err != nil {
 		t.Fatal(err)
 	}
 	if len(cfg.PlayerUsers) != 2 || cfg.PlayerUsers[0] != "Gordon" {
 		t.Fatalf("users = %#v", cfg.PlayerUsers)
 	}
 	if len(cfg.PlayerLinks) != 1 || cfg.PlayerLinks[0].HAEntity != "media_player.lounge" {
 		t.Fatalf("links = %#v", cfg.PlayerLinks)
 	}
 	if len(cfg.PlayerLinks[0].Names) != 2 {
 		t.Fatalf("names = %#v", cfg.PlayerLinks[0].Names)
 	}
 }
@@ -0,0 +1,96 @@
 package config
 import (
 	"encoding/json"
 	"fmt"
 	"strings"
 )
 // SplitCSV splits a comma-separated list, trimming blanks.
 func SplitCSV(s string) []string {
 	s = strings.TrimSpace(s)
 	if s == "" {
 		return nil
 	}
 	if strings.HasPrefix(s, "[") {
 		var arr []string
 		if err := json.Unmarshal([]byte(s), &arr); err == nil {
 			return compactStrings(arr)
 		}
 	}
 	parts := strings.Split(s, ",")
 	return compactStrings(parts)
 }
 func compactStrings(in []string) []string {
 	var out []string
 	for _, p := range in {
 		p = strings.TrimSpace(p)
 		if p != "" {
 			out = append(out, p)
 		}
 	}
 	return out
 }
 type playerLinkWire struct {
 	Names          flexStrings `json:"names"`
 	EmbyDeviceID   string      `json:"emby_device_id"`
 	EmbyDeviceName string      `json:"emby_device_name"`
 	DeviceIP       string      `json:"device_ip"`
 	HAEntity       string      `json:"ha_entity"`
 	HASource       string      `json:"ha_source"`
 	Users          flexStrings `json:"users"`
 }
 type flexStrings []string
 func (f *flexStrings) UnmarshalJSON(b []byte) error {
 	b = bytesTrim(b)
 	if len(b) == 0 || string(b) == "null" {
 		return nil
 	}
 	if b[0] == '[' {
 		var a []string
 		if err := json.Unmarshal(b, &a); err != nil {
 			return err
 		}
 		*f = compactStrings(a)
 		return nil
 	}
 	var s string
 	if err := json.Unmarshal(b, &s); err != nil {
 		return err
 	}
 	*f = SplitCSV(s)
 	return nil
 }
 func bytesTrim(b []byte) []byte {
 	return []byte(strings.TrimSpace(string(b)))
 }
 // ParsePlayerLinks accepts a JSON array of PlayerLink objects.
 func ParsePlayerLinks(s string) ([]PlayerLink, error) {
 	s = strings.TrimSpace(s)
 	if s == "" || s == "null" || s == "[]" {
 		return nil, nil
 	}
 	var wires []playerLinkWire
 	if err := json.Unmarshal([]byte(s), &wires); err != nil {
 		return nil, fmt.Errorf("expected JSON array: %w", err)
 	}
 	out := make([]PlayerLink, 0, len(wires))
 	for _, w := range wires {
 		out = append(out, PlayerLink{
 			Names:          []string(w.Names),
 			EmbyDeviceID:   strings.TrimSpace(w.EmbyDeviceID),
 			EmbyDeviceName: strings.TrimSpace(w.EmbyDeviceName),
 			DeviceIP:       strings.TrimSpace(w.DeviceIP),
 			HAEntity:       strings.TrimSpace(w.HAEntity),
 			HASource:       strings.TrimSpace(w.HASource),
 			Users:          []string(w.Users),
 		})
 	}
 	return out, nil
 }
@@ -0,0 +1,94 @@
 package emby
 import (
 	"context"
 	"encoding/json"
 	"net"
 	"strings"
 )
 // DeviceInfo is a subset of GET /Devices.
 type DeviceInfo struct {
 	ID               string `json:"Id"`
 	Name             string `json:"Name"`
 	AppName          string `json:"AppName"`
 	LastUserName     string `json:"LastUserName"`
 	LastUserID       string `json:"LastUserId"`
 	DateLastActivity string `json:"DateLastActivity"`
 	IPAddress        string `json:"IpAddress"`
 }
 // GetDevices lists known Emby client devices (last user, last activity).
 func (c *Client) GetDevices(ctx context.Context) ([]DeviceInfo, error) {
 	var raw json.RawMessage
 	if err := c.Get(ctx, "/Devices", nil, &raw); err != nil {
 		return nil, err
 	}
 	raw = json.RawMessage(strings.TrimSpace(string(raw)))
 	if len(raw) == 0 {
 		return nil, nil
 	}
 	if raw[0] == '[' {
 		var items []DeviceInfo
 		if err := json.Unmarshal(raw, &items); err != nil {
 			return nil, err
 		}
 		return items, nil
 	}
 	var wrap struct {
 		Items []DeviceInfo `json:"Items"`
 	}
 	if err := json.Unmarshal(raw, &wrap); err != nil {
 		return nil, err
 	}
 	return wrap.Items, nil
 }
 // MergeOfflineDevices appends Devices that have no live session, using last-used
 // user as owner. Session rows win when DeviceID matches.
 func MergeOfflineDevices(live []PlayerSession, devices []DeviceInfo) []PlayerSession {
 	seen := map[string]struct{}{}
 	for _, p := range live {
 		if p.DeviceID != "" {
 			seen[p.DeviceID] = struct{}{}
 		}
 	}
 	out := append([]PlayerSession(nil), live...)
 	for _, d := range devices {
 		id := d.ID
 		if id == "" {
 			continue
 		}
 		if _, ok := seen[id]; ok {
 			continue
 		}
 		out = append(out, PlayerSession{
 			ClientName:      d.AppName,
 			DeviceID:        id,
 			DeviceName:      d.Name,
 			DeviceIPAddress: HostOf(d.IPAddress),
 			UserID:          d.LastUserID,
 			UserName:        d.LastUserName,
 			Online:          false,
 		})
 	}
 	return out
 }
 // HostOf returns the host part of an address (strips port). IPv6 brackets are removed.
 func HostOf(addr string) string {
 	addr = strings.TrimSpace(addr)
 	if addr == "" {
 		return ""
 	}
 	if strings.HasPrefix(addr, "[") {
 		if host, _, err := net.SplitHostPort(addr); err == nil {
 			return host
 		}
 		return strings.Trim(addr, "[]")
 	}
 	if host, port, err := net.SplitHostPort(addr); err == nil && port != "" {
 		return host
 	}
 	return addr
 }
@@ -0,0 +1,53 @@
 package emby
 import (
 	"context"
 	"encoding/json"
 	"net/http"
 	"testing"
 )
 func TestHostOf(t *testing.T) {
 	if HostOf("192.168.0.20:8096") != "192.168.0.20" {
 		t.Fatal(HostOf("192.168.0.20:8096"))
 	}
 	if HostOf("192.168.0.20") != "192.168.0.20" {
 		t.Fatal(HostOf("192.168.0.20"))
 	}
 }
 func TestGetDevicesWrapped(t *testing.T) {
 	c, srv := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
 		if r.URL.Path != "/Devices" {
 			t.Errorf("path %s", r.URL.Path)
 		}
 		json.NewEncoder(w).Encode(map[string]any{
 			"Items": []map[string]any{
 				{"Id": "d9", "Name": "Lounge", "AppName": "Emby for Android", "LastUserName": "Gordon", "LastUserId": "u1", "IpAddress": "192.168.0.20"},
 			},
 		})
 	})
 	defer srv.Close()
 	devs, err := c.GetDevices(context.Background())
 	if err != nil {
 		t.Fatal(err)
 	}
 	if len(devs) != 1 || devs[0].LastUserName != "Gordon" {
 		t.Fatalf("%+v", devs)
 	}
 }
 func TestMergeOfflineDevices(t *testing.T) {
 	live := []PlayerSession{{DeviceID: "d1", SessionID: "s1", Online: true, UserName: "Gordon"}}
 	devs := []DeviceInfo{
 		{ID: "d1", Name: "dup"},
 		{ID: "d2", Name: "Bedroom", LastUserName: "Alice", IPAddress: "192.168.0.21"},
 	}
 	got := MergeOfflineDevices(live, devs)
 	if len(got) != 2 {
 		t.Fatalf("%+v", got)
 	}
 	if got[1].Online || got[1].UserName != "Alice" {
 		t.Fatalf("%+v", got[1])
 	}
 }
@@ -23,6 +23,7 @@ type MediaItem struct {
 	DiskNumber                 any      `json:"disk_number,omitempty"`
 	TrackNumber                any      `json:"track_number,omitempty"`
 	ProductionYear             any      `json:"production_year,omitempty"`
 	PremiereDate               string   `json:"premiere_date,omitempty"`
 	Genres                     []string `json:"genres,omitempty"`
 	RunTime                    string   `json:"run_time,omitempty"`
 	Played                     bool     `json:"played"`
@@ -52,7 +53,7 @@ type ItemQuery struct {
 	EnableUserData   bool   // include per-user watch state
 }
-const itemExtraFields = "Genres,ProductionYear,ParentIndexNumber,IndexNumber,SeriesName"
+const itemExtraFields = "Genres,ProductionYear,PremiereDate,ParentIndexNumber,IndexNumber,SeriesName"
 // GetItems queries Audio/Video items in a library (or all libraries when
 // libraryID is empty).
@@ -172,9 +173,26 @@ func toMediaItem(it *BaseItemDto) MediaItem {
 	mi.DiskNumber = intOrEmpty(it.ParentIndexNumber)
 	mi.TrackNumber = intOrEmpty(it.IndexNumber)
 	mi.ProductionYear = intOrEmpty(it.ProductionYear)
 	mi.PremiereDate = formatISODate(it.PremiereDate)
 	return mi
 }
 // formatISODate keeps YYYY-MM-DD from an Emby date-time and drops empty values
 // so premiere_date is omitted from JSON when metadata is missing.
 func formatISODate(s string) string {
 	s = strings.TrimSpace(s)
 	if s == "" {
 		return ""
 	}
 	if i := strings.IndexByte(s, 'T'); i > 0 {
 		return s[:i]
 	}
 	if len(s) >= 10 && s[4] == '-' && s[7] == '-' {
 		return s[:10]
 	}
 	return s
 }
 // ticksToHMS converts Emby ticks (100 ns) to "hh:mm:ss".
 func ticksToHMS(ticks int64) string {
 	if ticks <= 0 {
@@ -75,3 +75,79 @@ func TestGetItemsQueryTranslation(t *testing.T) {
 		}
 	}
 }
 func TestToMediaItemPremiereDate(t *testing.T) {
 	it := &BaseItemDto{
 		ID: "e1", Name: "Pilot", Type: "Episode",
 		PremiereDate: "2025-03-31T00:00:00.0000000Z",
 	}
 	year := 2025
 	it.ProductionYear = &year
 	mi := toMediaItem(it)
 	if mi.PremiereDate != "2025-03-31" {
 		t.Fatalf("premiere_date = %q", mi.PremiereDate)
 	}
 	if mi.ProductionYear != 2025 {
 		t.Fatalf("production_year = %v", mi.ProductionYear)
 	}
 	empty := toMediaItem(&BaseItemDto{ID: "e2", Name: "Unknown"})
 	if empty.PremiereDate != "" {
 		t.Fatalf("empty premiere_date = %q", empty.PremiereDate)
 	}
 }
 func TestGetItemsRequestsPremiereDateField(t *testing.T) {
 	var q map[string][]string
 	c, srv := newTestClient(t, itemsHandler(t, nil, &q))
 	defer srv.Close()
 	if _, err := c.GetItems(context.Background(), "u1", "", ItemQuery{}); err != nil {
 		t.Fatal(err)
 	}
 	fields := ""
 	if got := q["Fields"]; len(got) == 1 {
 		fields = got[0]
 	}
 	if fields == "" || !containsCSV(fields, "PremiereDate") {
 		t.Fatalf("Fields = %q, want PremiereDate", fields)
 	}
 }
 func TestFormatISODate(t *testing.T) {
 	cases := map[string]string{
 		"":                             "",
 		"2025-03-31T00:00:00.0000000Z": "2025-03-31",
 		"2025-03-31":                   "2025-03-31",
 		" 2024-12-01T15:04:05+01:00 ":  "2024-12-01",
 	}
 	for in, want := range cases {
 		if got := formatISODate(in); got != want {
 			t.Errorf("formatISODate(%q) = %q, want %q", in, got, want)
 		}
 	}
 }
 func containsCSV(csv, needle string) bool {
 	for _, p := range splitComma(csv) {
 		if p == needle {
 			return true
 		}
 	}
 	return false
 }
 func splitComma(s string) []string {
 	var out []string
 	cur := ""
 	for i := 0; i < len(s); i++ {
 		if s[i] == ',' {
 			out = append(out, cur)
 			cur = ""
 			continue
 		}
 		cur += string(s[i])
 	}
 	if cur != "" || len(s) > 0 && s[len(s)-1] == ',' {
 		out = append(out, cur)
 	}
 	return out
 }
@@ -38,6 +38,7 @@ type PlaylistItem struct {
 	DiskNumber         any      `json:"disk_number,omitempty"`
 	TrackNumber        any      `json:"track_number,omitempty"`
 	ProductionYear     any      `json:"production_year,omitempty"`
 	PremiereDate       string   `json:"premiere_date,omitempty"`
 	Genres             []string `json:"genres,omitempty"`
 	RunTime            string   `json:"run_time,omitempty"`
 }
@@ -129,6 +130,7 @@ func (c *Client) GetPlaylistItems(ctx context.Context, userID, playlistID string
 			DiskNumber:         mi.DiskNumber,
 			TrackNumber:        mi.TrackNumber,
 			ProductionYear:     mi.ProductionYear,
 			PremiereDate:       mi.PremiereDate,
 			Genres:             mi.Genres,
 			RunTime:            mi.RunTime,
 		})
@@ -11,12 +11,15 @@ import (
 // now_playing_* fields are omitted when the player is idle.
 type PlayerSession struct {
 	ClientName             string   `json:"client_name"`
-	SessionID              string   `json:"session_id"`
+	SessionID              string   `json:"session_id,omitempty"`
 	DeviceID               string   `json:"device_id"`
 	DeviceName             string   `json:"device_name"`
-	DeviceIPAddress        string   `json:"device_ip_address"`
+	DeviceIPAddress        string   `json:"device_ip_address,omitempty"`
 	UserID                 string   `json:"user_id,omitempty"`
 	UserName               string   `json:"user_name,omitempty"`
 	Online                 bool     `json:"online"`
 	LocalToMediaServer     bool     `json:"local_to_media_server"`
-	MediaTypes             []string `json:"media_types"`
+	MediaTypes             []string `json:"media_types,omitempty"`
 	NowPlayingTitle        string   `json:"now_playing_title,omitempty"`
 	NowPlayingArtists      []string `json:"now_playing_artists,omitempty"`
 	NowPlayingAlbum        string   `json:"now_playing_album,omitempty"`
@@ -62,9 +65,12 @@ func (c *Client) GetPlayerSessions(ctx context.Context, userID, mediaType string
 			SessionID:          s.ID,
 			DeviceID:           s.DeviceID,
 			DeviceName:         s.DeviceName,
-			DeviceIPAddress:    s.RemoteEndPoint,
+			DeviceIPAddress:    HostOf(s.RemoteEndPoint),
 			UserID:             s.UserID,
 			UserName:           s.UserName,
 			Online:             true,
 			MediaTypes:         s.PlayableMediaTypes,
-			LocalToMediaServer: s.RemoteEndPoint == "::1" || s.RemoteEndPoint == "127.0.0.1",
+			LocalToMediaServer: isLoopback(s.RemoteEndPoint),
 		}
 		if np := s.NowPlayingItem; np != nil {
 			ps.NowPlayingTitle = np.Name
@@ -85,6 +91,51 @@ func (c *Client) GetPlayerSessions(ctx context.Context, userID, mediaType string
 	return out, nil
 }
 // FilterPlayersByUsers keeps sessions whose UserName or UserId is in include.
 // An empty include list means no extra filter.
 func FilterPlayersByUsers(players []PlayerSession, include []string) []PlayerSession {
 	want := normalizeUserList(include)
 	if len(want) == 0 {
 		return players
 	}
 	out := make([]PlayerSession, 0, len(players))
 	for _, p := range players {
 		if userAllowed(p.UserID, p.UserName, want) {
 			out = append(out, p)
 		}
 	}
 	return out
 }
 func normalizeUserList(in []string) []string {
 	var out []string
 	for _, u := range in {
 		for _, part := range strings.Split(u, ",") {
 			part = strings.TrimSpace(part)
 			if part != "" {
 				out = append(out, strings.ToLower(part))
 			}
 		}
 	}
 	return out
 }
 func userAllowed(userID, userName string, want []string) bool {
 	id := strings.ToLower(strings.TrimSpace(userID))
 	name := strings.ToLower(strings.TrimSpace(userName))
 	for _, w := range want {
 		if w == id || w == name {
 			return true
 		}
 	}
 	return false
 }
 func isLoopback(addr string) bool {
 	h := HostOf(addr)
 	return h == "127.0.0.1" || h == "::1" || h == "localhost"
 }
 // PlayQueueItem is the output shape for play queue entries.
 type PlayQueueItem struct {
 	Title          string   `json:"title"`
@@ -98,6 +149,7 @@ type PlayQueueItem struct {
 	DiskNumber     any      `json:"disk_number,omitempty"`
 	TrackNumber    any      `json:"track_number,omitempty"`
 	ProductionYear any      `json:"production_year,omitempty"`
 	PremiereDate   string   `json:"premiere_date,omitempty"`
 	Genres         []string `json:"genres,omitempty"`
 	RunTime        string   `json:"run_time,omitempty"`
 }
@@ -151,6 +203,7 @@ func (c *Client) GetPlayQueueItems(ctx context.Context, sessionID string) ([]Pla
 			DiskNumber:     mi.DiskNumber,
 			TrackNumber:    mi.TrackNumber,
 			ProductionYear: mi.ProductionYear,
 			PremiereDate:   mi.PremiereDate,
 			Genres:         mi.Genres,
 			RunTime:        mi.RunTime,
 		})
@@ -17,6 +17,7 @@ func TestGetPlayerSessions(t *testing.T) {
 			{
 				"Client": "Emby Web", "Id": "s1", "DeviceId": "d1",
 				"DeviceName": "Chrome", "RemoteEndPoint": "127.0.0.1",
 				"UserId": "u1", "UserName": "Gordon",
 				"PlayableMediaTypes": []string{"Audio", "Video"},
 				"NowPlayingItem": map[string]any{
 					"Name": "Track", "Id": "i1", "Artists": []string{"A"},
@@ -48,6 +49,23 @@ func TestGetPlayerSessions(t *testing.T) {
 	if s.NowPlayingIsPaused == nil || !*s.NowPlayingIsPaused {
 		t.Error("expected is_paused")
 	}
 	if s.UserName != "Gordon" || s.UserID != "u1" || !s.Online {
 		t.Errorf("owner = %+v", s)
 	}
 }
 func TestFilterPlayersByUsers(t *testing.T) {
 	in := []PlayerSession{
 		{SessionID: "a", UserName: "Gordon", UserID: "u1"},
 		{SessionID: "b", UserName: "Alice", UserID: "u2"},
 	}
 	got := FilterPlayersByUsers(in, []string{"gordon"})
 	if len(got) != 1 || got[0].SessionID != "a" {
 		t.Fatalf("got %+v", got)
 	}
 	if n := FilterPlayersByUsers(in, nil); len(n) != 2 {
 		t.Fatalf("unfiltered %+v", n)
 	}
 }
 func TestGetPlayerSessionsMediaTypeFilter(t *testing.T) {
@@ -157,7 +157,7 @@ var mediaItemRespFields = []string{
 	"Items", "TotalRecordCount",
 	"Items.Name", "Items.Artists", "Items.Album", "Items.AlbumId",
 	"Items.AlbumArtist", "Items.ParentIndexNumber", "Items.IndexNumber",
-	"Items.ProductionYear",
+	"Items.ProductionYear", "Items.PremiereDate",
 	"Items.Genres", "Items.MediaType", "Items.RunTimeTicks",
 	"Items.Id", "Items.Type",
 	"Items.SeriesName", "Items.LocationType",
@@ -191,7 +191,7 @@ var endpointUsages = []endpointUsage{
 	{tool: "stop_sharing_playlist", callSite: "playlists.go:243", method: "post", specPath: "/Items/{Id}/MakePrivate", path: []string{"Id"}},
 	{tool: "share_playlist_user_access", callSite: "playlists.go:253", method: "post", specPath: "/Items/Access", bodyFields: []string{"ItemIds", "UserIds", "ItemAccess"}, enumUse: map[string][]string{"UserItemShareLevel": {"None", "Read", "Write", "Manage", "ManageDelete"}}},
 	{tool: "retrieve_player_list", callSite: "sessions.go:39", method: "get", specPath: "/Sessions", query: []string{"ControllableByUserId"}, respFields: []string{"Client", "Id", "DeviceId", "DeviceName", "RemoteEndPoint", "PlayableMediaTypes", "NowPlayingItem.Name", "NowPlayingItem.Artists", "NowPlayingItem.Album", "NowPlayingItem.IndexNumber", "NowPlayingItem.ParentIndexNumber", "NowPlayingItem.Id", "NowPlayingItem.RunTimeTicks", "PlayState.PositionTicks", "PlayState.IsPaused"}},
-	{tool: "retrieve_player_queue", callSite: "sessions.go:136", method: "get", specPath: "/Sessions/PlayQueue", query: []string{"Id", "Fields"}, respFields: []string{"Items", "Items.Name", "Items.Artists", "Items.Album", "Items.AlbumId", "Items.AlbumArtist", "Items.ParentIndexNumber", "Items.IndexNumber", "Items.ProductionYear", "Items.Genres", "Items.MediaType", "Items.RunTimeTicks", "Items.Id", "Items.PlaylistItemId", "TotalRecordCount"}},
+	{tool: "retrieve_player_queue", callSite: "sessions.go:136", method: "get", specPath: "/Sessions/PlayQueue", query: []string{"Id", "Fields"}, respFields: []string{"Items", "Items.Name", "Items.Artists", "Items.Album", "Items.AlbumId", "Items.AlbumArtist", "Items.ParentIndexNumber", "Items.IndexNumber", "Items.ProductionYear", "Items.PremiereDate", "Items.Genres", "Items.MediaType", "Items.RunTimeTicks", "Items.Id", "Items.PlaylistItemId", "TotalRecordCount"}},
 	{tool: "control_media_player (PlayNow)", callSite: "sessions.go:246", method: "post", specPath: "/Sessions/{Id}/Playing", path: []string{"Id"}, query: []string{"ItemIds", "PlayCommand"}, bodyFields: []string{"PlayCommand", "ControllingUserId"}, enumUse: map[string][]string{"PlayCommand": {"PlayNow"}}},
 	{tool: "control_media_player (other commands)", callSite: "sessions.go:267", method: "post", specPath: "/Sessions/{Id}/Playing/{Command}", path: []string{"Id", "Command"}, bodyFields: []string{"Command", "SeekPositionTicks", "ControllingUserId"}, enumUse: map[string][]string{"PlaystateCommand": {"Stop", "Pause", "Unpause", "NextTrack", "PreviousTrack", "Seek", "Rewind", "FastForward", "PlayPause", "SeekRelative"}}},
 	{tool: "retrieve_now_playing, set_subtitle, set_audio_track", callSite: "sessions.go:169", method: "get", specPath: "/Sessions", respFields: []string{"Id", "SupportedCommands", "NowPlayingItem.Id", "NowPlayingItem.Name", "NowPlayingItem.SeriesName", "NowPlayingItem.MediaType", "NowPlayingItem.MediaSources.MediaStreams.Index", "NowPlayingItem.MediaSources.MediaStreams.Type", "NowPlayingItem.MediaSources.MediaStreams.Language", "NowPlayingItem.MediaSources.MediaStreams.Codec", "NowPlayingItem.MediaSources.MediaStreams.Title", "NowPlayingItem.MediaSources.MediaStreams.DisplayTitle", "NowPlayingItem.MediaSources.MediaStreams.IsDefault", "NowPlayingItem.MediaSources.MediaStreams.IsForced", "NowPlayingItem.MediaSources.MediaStreams.IsExternal", "PlayState.PositionTicks", "PlayState.IsPaused", "PlayState.CanSeek", "PlayState.AudioStreamIndex", "PlayState.SubtitleStreamIndex"}},
@@ -90,6 +90,7 @@ type BaseItemDto struct {
 	ParentIndexNumber *int             `json:"ParentIndexNumber"`
 	IndexNumber       *int             `json:"IndexNumber"`
 	ProductionYear    *int             `json:"ProductionYear"`
 	PremiereDate      string           `json:"PremiereDate"`
 	Genres            []string         `json:"Genres"`
 	MediaSources      []MediaSource    `json:"MediaSources"`
 	MediaType         string           `json:"MediaType"`
@@ -28,7 +28,10 @@ func NewHandler(cfg *config.Config, hostname string) http.Handler {
 		}
 		// Per-session state: library selection and search chunking are
 		// isolated between concurrent HTTP clients.
-		return server.New(state.New(client, userID, cfg.MaxChunkSize))
+		st := state.New(client, userID, cfg.MaxChunkSize)
 		st.PlayerUsers = cfg.PlayerUsers
 		st.PlayerLinks = cfg.PlayerLinks
 		return server.New(st)
 	}
 	mcpHandler := mcp.NewStreamableHTTPHandler(getServer, &mcp.StreamableHTTPOptions{
 		SessionTimeout: cfg.SessionTimeout,
@@ -8,6 +8,7 @@ import (
 	"io"
 	"net/http"
 	"net/http/httptest"
 	"os"
 	"strings"
 	"testing"
 	"time"
@@ -93,7 +94,15 @@ func mcpClient(t *testing.T, endpoint, authHeader string, extra map[string]strin
 	return cs
 }
 func skipStreamableE2E(t *testing.T) {
 	t.Helper()
 	if os.Getenv("CI") != "" {
 		t.Skip("streamable HTTP initialize/session handshake is unreliable on the Gitea act runner")
 	}
 }
 func TestHTTPBearerEndToEnd(t *testing.T) {
 	skipStreamableE2E(t)
 	embySrv := fakeEmby(t)
 	defer embySrv.Close()
 	srv := httptest.NewServer(NewHandler(testConfig(embySrv.URL), "testhost"))
@@ -113,6 +122,7 @@ func TestHTTPBearerEndToEnd(t *testing.T) {
 }
 func TestHTTPBasicEndToEnd(t *testing.T) {
 	skipStreamableE2E(t)
 	embySrv := fakeEmby(t)
 	defer embySrv.Close()
 	srv := httptest.NewServer(NewHandler(testConfig(embySrv.URL), "testhost"))
@@ -132,6 +142,7 @@ func TestHTTPBasicEndToEnd(t *testing.T) {
 }
 func TestHTTPBearerWithUserIDHeader(t *testing.T) {
 	skipStreamableE2E(t)
 	embySrv := fakeEmby(t)
 	defer embySrv.Close()
 	srv := httptest.NewServer(NewHandler(testConfig(embySrv.URL), "testhost"))
@@ -0,0 +1,159 @@
 package server
 import (
 	"strings"
 	"git.i3omb.com/gronod/emby-mcp/internal/config"
 	"git.i3omb.com/gronod/emby-mcp/internal/emby"
 )
 // ResolvedPlayer is the output of resolve_media_player.
 type ResolvedPlayer struct {
 	Query          string `json:"query"`
 	MatchedName    string `json:"matched_name,omitempty"`
 	HAEntity       string `json:"ha_entity,omitempty"`
 	HASource       string `json:"ha_source,omitempty"`
 	EmbyDeviceID   string `json:"emby_device_id,omitempty"`
 	EmbyDeviceName string `json:"emby_device_name,omitempty"`
 	DeviceIP       string `json:"device_ip,omitempty"`
 	SessionID      string `json:"session_id,omitempty"`
 	Online         bool   `json:"online"`
 	UserName       string `json:"user_name,omitempty"`
 	UserID         string `json:"user_id,omitempty"`
 	WakeRequired   bool   `json:"wake_required"`
 	Note           string `json:"note,omitempty"`
 }
 func resolvePlayer(query string, links []config.PlayerLink, players []emby.PlayerSession) (ResolvedPlayer, bool) {
 	q := strings.TrimSpace(query)
 	out := ResolvedPlayer{Query: q}
 	if q == "" {
 		out.Note = "ERROR: no query was supplied"
 		return out, false
 	}
 	ql := strings.ToLower(q)
 	if link, name := matchLink(ql, links); link != nil {
 		out.MatchedName = name
 		out.HAEntity = link.HAEntity
 		out.HASource = link.HASource
 		out.EmbyDeviceID = link.EmbyDeviceID
 		out.EmbyDeviceName = link.EmbyDeviceName
 		out.DeviceIP = emby.HostOf(link.DeviceIP)
 		if sess, ok := matchSession(link, players); ok {
 			fillFromSession(&out, sess)
 		} else {
 			out.WakeRequired = true
 			out.Note = "No live Emby session for this device. Turn on the Home Assistant media_player and launch the Emby client, then list or resolve again."
 		}
 		return out, true
 	}
 	for _, p := range players {
 		if sessionMatchesQuery(ql, p) {
 			out.MatchedName = firstNonEmpty(p.DeviceName, p.ClientName)
 			fillFromSession(&out, p)
 			if !p.Online {
 				out.WakeRequired = true
 				out.Note = "Device is known to Emby but has no live session. Turn on the Home Assistant media_player and launch the Emby client."
 			}
 			return out, true
 		}
 	}
 	out.Note = "ERROR: no player matched that name, device id, or IP"
 	return out, false
 }
 func matchLink(ql string, links []config.PlayerLink) (*config.PlayerLink, string) {
 	for i := range links {
 		l := &links[i]
 		for _, n := range l.Names {
 			if strings.ToLower(strings.TrimSpace(n)) == ql {
 				return l, n
 			}
 		}
 		if strings.ToLower(l.HAEntity) == ql {
 			return l, l.HAEntity
 		}
 		if l.EmbyDeviceID != "" && strings.ToLower(l.EmbyDeviceID) == ql {
 			return l, l.EmbyDeviceID
 		}
 		if l.EmbyDeviceName != "" && strings.ToLower(l.EmbyDeviceName) == ql {
 			return l, l.EmbyDeviceName
 		}
 		if ip := emby.HostOf(l.DeviceIP); ip != "" && strings.ToLower(ip) == ql {
 			return l, ip
 		}
 	}
 	return nil, ""
 }
 func matchSession(link *config.PlayerLink, players []emby.PlayerSession) (emby.PlayerSession, bool) {
 	linkIP := emby.HostOf(link.DeviceIP)
 	for _, p := range players {
 		if link.EmbyDeviceID != "" && p.DeviceID == link.EmbyDeviceID && p.Online {
 			return p, true
 		}
 	}
 	for _, p := range players {
 		if linkIP != "" && emby.HostOf(p.DeviceIPAddress) == linkIP && p.Online {
 			return p, true
 		}
 		if link.EmbyDeviceName != "" && strings.EqualFold(p.DeviceName, link.EmbyDeviceName) && p.Online {
 			return p, true
 		}
 	}
 	return emby.PlayerSession{}, false
 }
 func sessionMatchesQuery(ql string, p emby.PlayerSession) bool {
 	if strings.ToLower(p.DeviceID) == ql {
 		return true
 	}
 	if strings.ToLower(p.DeviceName) == ql {
 		return true
 	}
 	if strings.ToLower(p.ClientName) == ql {
 		return true
 	}
 	if ip := emby.HostOf(p.DeviceIPAddress); ip != "" && strings.ToLower(ip) == ql {
 		return true
 	}
 	if strings.ToLower(p.UserName) == ql {
 		return true
 	}
 	return false
 }
 func fillFromSession(out *ResolvedPlayer, p emby.PlayerSession) {
 	out.SessionID = p.SessionID
 	out.Online = p.Online
 	out.UserName = p.UserName
 	out.UserID = p.UserID
 	if out.EmbyDeviceID == "" {
 		out.EmbyDeviceID = p.DeviceID
 	}
 	if out.EmbyDeviceName == "" {
 		out.EmbyDeviceName = p.DeviceName
 	}
 	if out.DeviceIP == "" {
 		out.DeviceIP = emby.HostOf(p.DeviceIPAddress)
 	}
 }
 func firstNonEmpty(vals ...string) string {
 	for _, v := range vals {
 		if strings.TrimSpace(v) != "" {
 			return v
 		}
 	}
 	return ""
 }
 func mergeUserFilters(toolUsers string, configured []string) []string {
 	fromTool := config.SplitCSV(toolUsers)
 	if len(fromTool) > 0 {
 		return fromTool
 	}
 	return configured
 }
@@ -0,0 +1,41 @@
 package server
 import (
 	"testing"
 	"git.i3omb.com/gronod/emby-mcp/internal/config"
 	"git.i3omb.com/gronod/emby-mcp/internal/emby"
 )
 func TestResolvePlayerByAliasAndIP(t *testing.T) {
 	links := []config.PlayerLink{{
 		Names:        []string{"lounge", "living room"},
 		HAEntity:     "media_player.lounge_tv",
 		HASource:     "Emby",
 		DeviceIP:     "192.168.0.20",
 		EmbyDeviceID: "dev-lounge",
 	}}
 	live := []emby.PlayerSession{{
 		SessionID:       "sess-1",
 		DeviceID:        "dev-lounge",
 		DeviceName:      "Lounge Shield",
 		DeviceIPAddress: "192.168.0.20",
 		UserName:        "Gordon",
 		Online:          true,
 	}}
 	got, ok := resolvePlayer("lounge", links, live)
 	if !ok || got.SessionID != "sess-1" || got.HAEntity != "media_player.lounge_tv" || got.WakeRequired {
 		t.Fatalf("%+v ok=%v", got, ok)
 	}
 	offline, ok := resolvePlayer("living room", links, nil)
 	if !ok || !offline.WakeRequired || offline.SessionID != "" {
 		t.Fatalf("offline %+v ok=%v", offline, ok)
 	}
 }
 func TestResolvePlayerUnknown(t *testing.T) {
 	_, ok := resolvePlayer("attic", nil, nil)
 	if ok {
 		t.Fatal("expected miss")
 	}
 }
@@ -13,7 +13,7 @@ import (
 const (
 	Name    = "HA Emby MCP"
-	Version = "1.0.14"
+	Version = "1.0.16"
 	Purpose = `These MCP tools allow you to control an Emby media server. Using them you can retrieve
 a list of libraries, genres, playlists, audio & video items, and player sessions.
 You can browse series, seasons and episodes, find the next episode to watch,
@@ -7,9 +7,9 @@ import (
 	"strings"
 	"time"
 	"github.com/google/uuid"
 	"git.i3omb.com/gronod/emby-mcp/internal/emby"
 	"git.i3omb.com/gronod/emby-mcp/internal/state"
 	"github.com/google/uuid"
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
@@ -47,6 +47,7 @@ Returns:
        disk_number (int): the disk or series number of the item.
        track_number (int): the track or episode number of the item.
        production_year (int): the release / broadcast year of the item.
        premiere_date (str): first air date for episodes/series, or release date for movies, as YYYY-MM-DD when metadata has it.
        genres (list of str): the genres tagged to the item
        run_time (str): the run time / play length of the item as hh:mm:ss.
        played (bool): whether the item has been fully played.
@@ -4,6 +4,7 @@ import (
 	"context"
 	"strings"
 	"git.i3omb.com/gronod/emby-mcp/internal/emby"
 	"git.i3omb.com/gronod/emby-mcp/internal/state"
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
@@ -14,23 +15,68 @@ func registerPlayerTools(s *mcp.Server, st *state.State) {
 		Description: `Retrieve a list of media players that we can use with the supplied media type in JSON format.
 A human may use any JSON field to identify a player, but do not display the 'device_id' or 'session_id'
 You must only supply the 'session_id' field to identify the player when using the control_media_player or retrieve_player_queue tools.
 Each row includes user_name/user_id of the signed-in or last-used Emby user, device_ip_address when Emby reports it, and online=false for known devices with no live session.
 When the user names a room or person, prefer resolve_media_player. Filter with users so other household accounts drop out.
 Args:
    media_type (str, optional): List only players of this media type (one of: 'Audio', 'Video', 'Photo') or an empty string to list all players
    users (str, optional): Comma-separated Emby usernames or user ids to include. Combined with the add-on player_users include-list when empty.
    include_offline (bool, optional): When true, also list GET /Devices entries that have no live session (last-used user).
 Returns:
    List of dicts as JSON with keys including client_name, session_id, device_id, device_name,
-    device_ip_address, local_to_media_server, media_types, and now_playing_* fields (times as hh:mm:ss).`,
+    device_ip_address, user_id, user_name, online, local_to_media_server, media_types, and now_playing_* fields (times as hh:mm:ss).`,
 	}, func(ctx context.Context, req *mcp.CallToolRequest, in struct {
 		MediaType      string `json:"media_type" jsonschema:"List only players of this media type (one of: 'Audio', 'Video', 'Photo') or empty for all"`
 		Users          string `json:"users" jsonschema:"Comma-separated Emby usernames or user ids to include"`
 		IncludeOffline bool   `json:"include_offline" jsonschema:"Also list known devices with no live session"`
 	}) (*mcp.CallToolResult, any, error) {
 		sessions, err := st.Client.GetPlayerSessions(ctx, st.UserID, in.MediaType)
 		if err != nil {
 			return textResult(errf("ERROR: failed to retrieve player list because: %v", err)), nil, nil
 		}
 		if in.IncludeOffline {
 			devs, derr := st.Client.GetDevices(ctx)
 			if derr != nil {
 				return textResult(errf("ERROR: failed to retrieve device list because: %v", derr)), nil, nil
 			}
 			sessions = emby.MergeOfflineDevices(sessions, devs)
 		}
 		sessions = emby.FilterPlayersByUsers(sessions, mergeUserFilters(in.Users, st.PlayerUsers))
 		return jsonResult(sessions), nil, nil
 	})
 	mcp.AddTool(s, &mcp.Tool{
 		Name: "resolve_media_player",
 		Description: `Resolve a spoken room, person, HA entity, Emby device name, device id, or IP to a Home Assistant media_player and an Emby session when one is live.
 Use this before PlayNow when the user says "play on the lounge" or similar. If wake_required is true, use Home Assistant to turn on ha_entity and select ha_source (Emby), wait, then resolve again. Do not call PlayNow until session_id is present.
 Args:
    query (str): Room alias, person, media_player entity_id, Emby device name, device id, or IP address
    users (str, optional): Comma-separated include-list of Emby usernames or user ids
 Returns:
    JSON object with ha_entity, ha_source, emby_device_id, device_ip, session_id, online, user_name, wake_required.`,
 	}, func(ctx context.Context, req *mcp.CallToolRequest, in struct {
 		Query string `json:"query" jsonschema:"Room alias, HA entity, Emby device name, device id, or IP"`
 		Users string `json:"users" jsonschema:"Comma-separated Emby usernames or user ids to include"`
 	}) (*mcp.CallToolResult, any, error) {
 		sessions, err := st.Client.GetPlayerSessions(ctx, st.UserID, "")
 		if err != nil {
 			return textResult(errf("ERROR: failed to retrieve player list because: %v", err)), nil, nil
 		}
 		devs, derr := st.Client.GetDevices(ctx)
 		if derr == nil {
 			sessions = emby.MergeOfflineDevices(sessions, devs)
 		}
 		sessions = emby.FilterPlayersByUsers(sessions, mergeUserFilters(in.Users, st.PlayerUsers))
 		resolved, ok := resolvePlayer(in.Query, st.PlayerLinks, sessions)
 		if !ok {
 			return textResult(resolved.Note), nil, nil
 		}
 		return jsonResult(resolved), nil, nil
 	})
 	mcp.AddTool(s, &mcp.Tool{
 		Name: "retrieve_player_queue",
 		Description: `Retrieve a list of items in the play queue of a media player in JSON format.
@@ -6,6 +6,7 @@ package state
 import (
 	"sync"
 	"git.i3omb.com/gronod/emby-mcp/internal/config"
 	"git.i3omb.com/gronod/emby-mcp/internal/emby"
 )
@@ -25,6 +26,8 @@ type State struct {
 	Client       *emby.Client
 	UserID       string
 	MaxChunkSize int
 	PlayerUsers  []string
 	PlayerLinks  []config.PlayerLink
 	libraries []emby.Library
 	current   *emby.Library
@@ -29,4 +29,9 @@ else
  export MCP_RESTRICT_LOCALHOST="false"
 fi
 if [ -f /data/options.json ]; then
  export PLAYER_USERS="$(jq -c '.player_users // []' /data/options.json)"
  export PLAYER_LINKS="$(jq -c '.player_links // []' /data/options.json)"
 fi
 exec /emby-mcp
@@ -0,0 +1,31 @@
 # Changelog
 ## 0.1.2
 - Build upstream `ha-n95-local-control` **v0.1.2**
  (`7bed99cc4c3222bad648efcddcdfed95652277f7`).
 - Health bind failure is no longer fatal. If 8080 is taken (OpenThread
  Border Router and other add-ons), lookup 8007, firmware 8005, and
  XMPP 5223 stay up. Set optional `health_port` if you still want
  `/healthz`.
 - Upstream logs each successful listen address.
 ## 0.1.1
 - Declare TCP 8007, 8005, 5223, and 8080 in the add-on `ports` map so
  Home Assistant OS Supervisor opens those ports on the host firewall.
  Host networking is unchanged; Docker does not remap the ports.
 - Potential operational change: after update, the add-on Network tab
  lists the four listeners. Rebuild/reinstall so HA picks up 0.1.1.
 ## 0.1.0
 - First Home Assistant add-on release
 - Build the upstream Deebot N95 bridge from the pinned `v0.1.0` tag
  (`75354b35180f4cc5e92187b6149322b0b94533ba`)
 - Bind robot-facing lookup, firmware, and XMPP listeners on the Home Assistant
  host network
 - Discover Supervisor MQTT connection details automatically with per-field
  configuration overrides and external-broker support
 - Expose the complete bridge configuration, with advanced and risky settings
  hidden under optional configuration by default
@@ -0,0 +1,256 @@
 # Deebot N95 Local Control — documentation
 Full installation, network, configuration, verification, and troubleshooting
 information for the **Deebot N95 Local Control** Home Assistant add-on.
 ## How it works
 The add-on replaces the legacy Ecovacs bootstrap and XMPP destinations used by
 an already-provisioned Deebot N95, then exposes the robot through Home
 Assistant MQTT discovery.
 ```text
 N95 ── DNS ──> your LAN resolver
 N95 ── HTTP 8007 / 8005, XMPP 5223 ──> this add-on ──> MQTT broker ──> Home Assistant
 ```
 The add-on does not provision a robot and does not run a DNS server. It supports
 multiple robots; each robot receives its own MQTT client and topic tree after
 it reaches XMPP READY state and reveals its serial number.
 ## Before you start
 You need:
 * An already-provisioned Deebot N95 using the captured `wukong` / class `155`
  protocol. Other Ecovacs models are not established as compatible.
 * A stable LAN IPv4 address for the Home Assistant host, reserved in DHCP.
 * Control of the DNS resolver supplied to the robot by DHCP.
 * TCP `8007`, `8005`, and `5223` available on the Home Assistant host and
  reachable from the robot. TCP `8080` is used for health checks.
 * A broker reachable from the Home Assistant host and Home Assistant MQTT
  configured with discovery enabled.
 * A correct host clock and IANA timezone.
 The robot caches its XMPP address after boot. If the address or listener ports
 change, update DNS/configuration and reboot the robot; an ordinary reconnect
 continues to use the cached destination.
 ## Step 1 — reserve the host address and configure DNS
 Reserve the Home Assistant host's LAN IPv4 address. Configure the resolver sent
 to the robot by DHCP with this A record:
 ```text
 lbo.ecouser.net  A  <HOME_ASSISTANT_LAN_IPV4>
 ```
 Set the add-on's `advertise_ip` to the same literal IPv4 address. Do not use
 `0.0.0.0`, a container address, or a hostname. The `155.ecorobot.net` XMPP JID
 domain does not need a DNS override for the captured firmware.
 ## Step 2 — install and configure
 1. Add this repository in Home Assistant
   (**Settings → Add-ons → Add-on Store → ⋮ → Repositories**):
   `https://git.i3omb.com/gronod/ha-gronod-addons`
 2. Install **Deebot N95 Local Control**.
 3. Enter the reserved host IPv4 under **Advertised IP address**.
 4. Select the correct IANA timezone, for example `Europe/London`.
 5. Leave advanced listener values unset unless their default ports conflict.
 When a Supervisor MQTT service is available, the add-on automatically reads
 its host, port, TLS flag, username, and password. Every manually supplied MQTT
 option overrides only that individual discovered field. This permits, for
 example, using discovered credentials with a manually supplied private CA.
 For an external broker with no Supervisor service, set at least `mqtt_host` and
 any required credentials/TLS options.
 ## Step 3 — start and redirect the robot
 Start the add-on and inspect its log. Verify the DNS and HTTP endpoints using
 the checks below, then reboot the robot. The robot should bootstrap through the
 lookup endpoint, open XMPP to the add-on, and appear as an MQTT vacuum in Home
 Assistant.
 No MQTT connection is expected when the add-on first starts. The bridge creates
 a broker client only after a robot reaches XMPP READY and identifies itself.
 ## Configuration
 Normal setup shows `advertise_ip`, `timezone`, and `log_level`. Select **Show
 unused optional configuration options** to reveal MQTT overrides and advanced
 network/protocol controls.
 | Option | Default | Environment | Description |
 |---|---|---|---|
 | `advertise_ip` | required | `ADVERTISE_IP` | Stable, nonzero host IPv4 returned in lookup responses |
 | `timezone` | `Etc/UTC` | `TZ` | IANA timezone controlling the local offset sent to the robot |
 | `log_level` | `info` | `LOG_LEVEL` | `debug`, `info`, `warn`, or `error` |
 | `bind_address` | `0.0.0.0` | `BIND_ADDRESS` | Advanced listener bind IP; normally leave unset |
 | `port_lookup` | `8007` | `PORT_LOOKUP` | Advanced HTTP `POST /lookup.do` listener |
 | `port_firmware` | `8005` | `PORT_FIRMWARE` | Advanced firmware-check listener; expected to return 404 |
 | `port_xmpp` | `5223` | `PORT_XMPP` | Advanced plaintext robot XMPP listener |
 | `health_port` | `8080` | `HEALTH_PORT` | Advanced HTTP `GET /healthz` listener. Bind failure is non-fatal from v0.1.2; robot ports stay up. Pick another port if OTBR already owns 8080. |
 | `mqtt_host` | Supervisor/required | `MQTT_HOST` | Broker host without scheme or port; overrides discovery |
 | `mqtt_port` | `1883`/`8883` | `MQTT_PORT` | Broker port; upstream chooses 8883 when TLS is enabled |
 | `mqtt_tls` | `false` | `MQTT_TLS` | Start the MQTT connection with TLS and hostname verification |
 | `mqtt_ca_file` | unset | `MQTT_CA_FILE` | Readable PEM CA bundle, normally `/ssl/<file>.pem` |
 | `mqtt_username` | Supervisor/unset | `MQTT_USERNAME` | Broker username override |
 | `mqtt_password` | Supervisor/unset | `MQTT_PASSWORD` | Broker password override; nonempty requires username |
 | `mqtt_client_id` | `n95bridge-<hostname>` | `MQTT_CLIENT_ID` | Client ID prefix; `[A-Za-z0-9_-]{1,64}` |
 | `mqtt_base` | `ecovacs` | `MQTT_BASE` | One MQTT topic level before `/<serial>` |
 | `ha_discovery_prefix` | `homeassistant` | `HA_DISCOVERY_PREFIX` | Must match Home Assistant MQTT discovery prefix |
 | `controller_jid` | `n95bridge@ecouser.net/homeassistant` | `CONTROLLER_JID` | Advanced virtual controller JID in `local@domain/resource` form |
 | `raw_commands` | `false` | `RAW_COMMANDS` | Risky protocol-level raw command input; keep disabled normally |
 Optional values are exported only when configured, preserving upstream
 defaults. Boolean values are passed as lowercase `true` or `false`. All four
 listener ports must be distinct and in the range 1–65535.
 ## Host networking and ports
 The add-on uses host networking because the robot must connect to the exact
 address and ports returned by `/lookup.do`. The same ports are declared in
 `config.yaml` so Supervisor opens them on the Home Assistant OS host
 firewall. Without that map, the process can listen on the host while LAN
 clients (including the robot) time out.
 | Port | Purpose | Robot access |
 |---|---|---|
 | `8007/tcp` | Bootstrap lookup (`EcoMsgNew`, `EcoUpdate`) | required |
 | `8005/tcp` | Firmware check (expected 404 response) | required |
 | `5223/tcp` | Plaintext XMPP | required |
 | `8080/tcp` | Health endpoint | not required |
 Changing a robot-facing port changes both the listener and the value advertised
 to the robot. Also change the matching `ports:` entry so Supervisor still
 opens the host firewall for that port. Check that another host service does
 not already occupy the port. Host networking means Docker does not remap
 these ports; the `ports` map is for Supervisor visibility and firewall
 allowance only.
 ## MQTT and Home Assistant discovery
 Supervisor MQTT values are loaded first; explicitly configured options then
 replace individual fields. The final broker host must come from one of those
 sources or the add-on exits with an actionable error.
 For TLS with a private CA, place a readable PEM bundle in Home Assistant's
 `ssl` directory and set `mqtt_ca_file` to its in-container path, such as
 `/ssl/broker-ca.pem`. TLS hostname verification remains enabled, so
 `mqtt_host` must match the broker certificate.
 The bridge publishes discovery below
 `<ha_discovery_prefix>/vacuum/ecovacs_<serial>/config` and robot data below
 `<mqtt_base>/<serial>/...`. Broker ACLs must allow each generated client to
 publish/subscribe under those trees. The default client prefix is based on the
 add-on hostname and has the robot serial appended.
 ## Robot features and entities
 The tagged upstream release publishes a native MQTT vacuum with availability,
 state, battery, fan speed, error information, and start, stop, dock, spot, and
 locate commands. It also supports extension movement commands, cleaning modes,
 schedule CRUD, consumable lifespan state, and diagnostic topics. Pause, resume,
 mapping, and segment cleaning are not advertised. Multiple connected robots remain isolated by
 serial number.
 `raw_commands` permits protocol-level `<ctl>` input intended for controlled
 experimentation. It bypasses normal high-level command constraints and should
 remain disabled for ordinary use.
 ## Check the installation
 Replace the example addresses with your resolver and Home Assistant host:
 ```sh
 nslookup lbo.ecouser.net 192.0.2.53
 curl -sS -X POST -H 'Content-Type: application/json' \
  --data '{"todo":"FindBest","service":"EcoMsgNew"}' \
  http://192.0.2.10:8007/lookup.do
 curl -sS -X POST -H 'Content-Type: application/json' \
  --data '{"todo":"FindBest","service":"EcoUpdate"}' \
  http://192.0.2.10:8007/lookup.do
 curl -i http://192.0.2.10:8005/products/wukong/class/155/firmware/latest.json
 curl -sS http://192.0.2.10:8080/healthz
 ```
 The lookup responses must contain the configured advertised IPv4 and numeric
 ports. The firmware request should return HTTP 404. The health endpoint should
 report healthy listeners. After these pass, reboot the robot and check:
 1. the add-on log for XMPP READY and the robot serial;
 2. broker activity below `ecovacs/<serial>` and the discovery prefix;
 3. a newly discovered MQTT vacuum entity in Home Assistant;
 4. state refresh and a harmless command such as locating the robot.
 ## Security notes
 * Robot XMPP, including SASL PLAIN credentials, is plaintext. Keep ports 8005,
  8007, and 5223 restricted to the trusted robot LAN.
 * MQTT authentication and TLS protect only the broker connection; they do not
  encrypt robot traffic.
 * Protect broker passwords and private CA files. The wrapper and upstream
  configuration log do not print the MQTT password.
 * Do not expose the robot-facing listeners to the internet.
 ## Troubleshooting
 **The add-on exits with “No MQTT broker is available”**
 No Supervisor MQTT service was found and `mqtt_host` is unset. Install/configure
 a broker service or enter the external broker host.
 **The robot still contacts the cloud**
 Query the exact resolver supplied by DHCP and confirm `lbo.ecouser.net` returns
 `advertise_ip`. Remove cached/secondary public DNS paths, then reboot the robot.
 **LAN clients time out on 8007 even though the add-on log shows listeners**
 On Home Assistant OS, Supervisor only opens inbound host ports listed under
 `ports:` in `config.yaml`. Version 0.1.1 declares 8007, 8005, 5223, and 8080.
 Rebuild/update the add-on so that version is installed, then confirm the
 Network tab lists those ports. Loopback on the HAOS box can succeed while
 the robot still times out if the firewall hole is missing.
 **8007/8005/5223 never appear on the host while 8080 is owned by OTBR**
 Before v0.1.2 a busy health port stopped every listener. From v0.1.2 the
 process logs `health listener failed; robot listeners continue` and keeps
 8007/8005/5223. Set optional `health_port` to a free port if you want
 `/healthz`. Rebuild so the add-on is 0.1.2.
 **The add-on reports an address-already-in-use error**
 Another host service owns lookup, firmware, or XMPP. Stop that service or
 set a distinct optional port. Reboot the robot after changing advertised ports.
 **The robot does not reconnect after an address or port change**
 The N95 caches XMPP details for its powered-on lifetime. Power-cycle/reboot it
 to force a new bootstrap lookup.
 **There is no MQTT connection immediately after startup**
 This is expected until a robot reaches XMPP READY and provides its serial.
 Investigate DNS, listener reachability, and XMPP logs first.
 **The robot connects but no entity appears**
 Confirm Home Assistant MQTT discovery is enabled and
 `ha_discovery_prefix` matches its configured prefix. Check broker ACLs for both
 the discovery and robot topic trees.
 **MQTT authentication or TLS fails**
 Check the effective host, port, username, and TLS override combination. For a
 private CA, verify the `/ssl/...` path exists and is readable, and that the
 broker certificate matches `mqtt_host`.
 **Schedules run at the wrong time**
 Set `timezone` to the correct IANA name and restart the add-on, then reconnect
 the robot so it receives the updated time and UTC offset.
 ## Upstream and standalone usage
 The add-on builds the immutable
 [ha-n95-local-control v0.1.2 release](https://git.i3omb.com/gronod/ha-n95-local-control/src/tag/v0.1.2)
 at commit `7bed99cc4c3222bad648efcddcdfed95652277f7`. See the
 [tagged upstream README](https://git.i3omb.com/gronod/ha-n95-local-control/src/tag/v0.1.2/README.md)
 for Docker Compose and direct Go-binary operation outside Home Assistant. The
 upstream project is under the
 [Apache License 2.0](https://git.i3omb.com/gronod/ha-n95-local-control/src/tag/v0.1.2/LICENCE.md).
@@ -0,0 +1,55 @@
 # syntax=docker/dockerfile:1
 ARG GO_VERSION=1.27.1
 ARG BUILD_FROM=ghcr.io/home-assistant/base:3.22
 FROM golang:${GO_VERSION}-alpine AS build
 RUN apk add --no-cache ca-certificates git
 WORKDIR /src
 ARG UPSTREAM_REPOSITORY=https://git.i3omb.com/gronod/ha-n95-local-control.git
 ARG UPSTREAM_REF=v0.1.2
 ARG UPSTREAM_COMMIT=7bed99cc4c3222bad648efcddcdfed95652277f7
 RUN git init . \
    && git remote add origin "${UPSTREAM_REPOSITORY}" \
    && git fetch --depth 1 origin "refs/tags/${UPSTREAM_REF}:refs/tags/${UPSTREAM_REF}" \
    && test "$(git rev-list -n 1 "${UPSTREAM_REF}^{commit}")" = "${UPSTREAM_COMMIT}" \
    && git checkout --detach "${UPSTREAM_REF}^{commit}"
 RUN go mod download
 ARG TARGETOS=linux
 ARG TARGETARCH
 ARG TARGETVARIANT
 RUN case "${TARGETARCH}/${TARGETVARIANT}" in \
      amd64/) goarch=amd64; goarm= ;; \
      arm64/) goarch=arm64; goarm= ;; \
      386/) goarch=386; goarm= ;; \
      arm/v6) goarch=arm; goarm=6 ;; \
      arm/v7) goarch=arm; goarm=7 ;; \
      *) echo "Unsupported target: ${TARGETARCH}/${TARGETVARIANT}" >&2; exit 1 ;; \
    esac \
    && CGO_ENABLED=0 GOOS="${TARGETOS}" GOARCH="${goarch}" GOARM="${goarm}" \
      go build -trimpath -ldflags="-s -w" -o /out/n95bridge ./cmd/n95bridge
 FROM ${BUILD_FROM}
 COPY --from=build /out/n95bridge /n95bridge
 COPY rootfs /
 RUN chmod a+x /run.sh
 ARG BUILD_VERSION=0.1.2
 ARG BUILD_ARCH
 ARG UPSTREAM_REF=v0.1.2
 ARG UPSTREAM_COMMIT=7bed99cc4c3222bad648efcddcdfed95652277f7
 LABEL \
  io.hass.name="Deebot N95 Local Control" \
  io.hass.description="Local MQTT control for an already-provisioned Deebot N95" \
  io.hass.type="addon" \
  io.hass.version="${BUILD_VERSION}" \
  io.hass.arch="${BUILD_ARCH}" \
  org.opencontainers.image.title="deebot-n95-local-control" \
  org.opencontainers.image.source="https://git.i3omb.com/gronod/ha-gronod-addons" \
  org.opencontainers.image.version="${BUILD_VERSION}" \
  org.opencontainers.image.revision="${UPSTREAM_COMMIT}" \
  com.gronod.upstream.ref="${UPSTREAM_REF}"
 CMD [ "/run.sh" ]
@@ -0,0 +1,58 @@
 # Deebot N95 Local Control
 <img src="logo.png" alt="Deebot N95 Local Control" width="128" height="128">
 Redirect an already-provisioned Ecovacs Deebot N95 from its legacy cloud
 bootstrap and XMPP endpoint to a local bridge, packaged as a Home Assistant
 add-on.
 The bridge publishes each robot through MQTT discovery as a native Home
 Assistant vacuum. Once the LAN DNS redirect is in place, robot control and
 state stay on your local network.
 ## Features
 * Local HTTP bootstrap and XMPP endpoint for compatible Deebot N95 robots
 * Automatic Home Assistant MQTT vacuum discovery
 * Multiple robots, with separate MQTT clients and topic trees by serial number
 * Vacuum state and control, cleaning modes, movement, schedules, consumable
  lifespan, and diagnostics
 * Automatic Supervisor MQTT broker discovery with per-setting overrides
 * Optional MQTT authentication, TLS, and private CA support
 * Health endpoint for installation checks
 ## Requirements
 * An already-provisioned Deebot N95 using the `wukong` / class `155` protocol
 * Control of the DNS resolver supplied to the robot by DHCP
 * A stable IPv4 address for the Home Assistant host
 * TCP ports `8005`, `8007`, and `5223` reachable from the robot
 * Home Assistant MQTT configured with discovery enabled, and a reachable broker
 * The correct IANA timezone for the robot's clock and schedules
 > The robot-facing XMPP connection, including SASL PLAIN authentication, is
 > plaintext. Run this add-on only on a trusted LAN and restrict access to its
 > listener ports. MQTT TLS protects the broker connection, not robot XMPP.
 ## Installation
 1. Add this repository to Home Assistant
   (**Settings → Add-ons → Add-on Store → ⋮ → Repositories**):
   `https://git.i3omb.com/gronod/ha-gronod-addons`
 2. Install **Deebot N95 Local Control**
 3. Set **Advertised IP address** to the stable LAN IPv4 address of the Home
   Assistant host and select the correct timezone
 4. Configure LAN DNS so `lbo.ecouser.net` resolves to that address
 5. Start the add-on, verify its health and lookup endpoints, then reboot the
   robot so it performs bootstrap again
 See [DOCS.md](DOCS.md) for the complete network setup, option reference,
 verification procedure, MQTT behavior, security notes, and troubleshooting.
 ## Upstream and license
 The add-on builds
 [ha-n95-local-control v0.1.2](https://git.i3omb.com/gronod/ha-n95-local-control/src/tag/v0.1.2),
 which also contains standalone Docker and Go instructions. The upstream
 software is licensed under the
 [Apache License 2.0](https://git.i3omb.com/gronod/ha-n95-local-control/src/tag/v0.1.2/LICENCE.md).
@@ -0,0 +1 @@
 0.1.2
@@ -0,0 +1,11 @@
 build_from:
  aarch64: ghcr.io/home-assistant/aarch64-base:3.22
  amd64: ghcr.io/home-assistant/amd64-base:3.22
  armhf: ghcr.io/home-assistant/armhf-base:3.22
  armv7: ghcr.io/home-assistant/armv7-base:3.22
  i386: ghcr.io/home-assistant/i386-base:3.22
 args:
  GO_VERSION: "1.27.1"
  UPSTREAM_REPOSITORY: "https://git.i3omb.com/gronod/ha-n95-local-control.git"
  UPSTREAM_REF: "v0.1.2"
  UPSTREAM_COMMIT: "7bed99cc4c3222bad648efcddcdfed95652277f7"
@@ -0,0 +1,56 @@
 name: "Deebot N95 Local Control"
 description: >-
  Redirect an already-provisioned Deebot N95 to local MQTT discovery and
  control in Home Assistant.
 version: "0.1.2"
 slug: "n95_mqtt_bridge"
 url: "https://git.i3omb.com/gronod/ha-gronod-addons/src/branch/main/n95-mqtt-bridge"
 init: false
 startup: application
 boot: auto
 host_network: true
 ports:
  8007/tcp: 8007
  8005/tcp: 8005
  5223/tcp: 5223
  8080/tcp: 8080
 ports_description:
  8007/tcp: Robot bootstrap lookup
  8005/tcp: Firmware check
  5223/tcp: Robot XMPP
  8080/tcp: Health
 arch:
  - aarch64
  - amd64
  - armhf
  - armv7
  - i386
 services:
  - mqtt:want
 map:
  - ssl
 options:
  advertise_ip: null
  timezone: "Etc/UTC"
  log_level: info
 schema:
  advertise_ip: str
  timezone: str
  log_level: list(debug|info|warn|error)
  bind_address: str?
  port_lookup: int?
  port_firmware: int?
  port_xmpp: int?
  health_port: int?
  mqtt_host: str?
  mqtt_port: int?
  mqtt_tls: bool?
  mqtt_ca_file: str?
  mqtt_username: str?
  mqtt_password: password?
  mqtt_client_id: str?
  mqtt_base: str?
  ha_discovery_prefix: str?
  controller_jid: str?
  raw_commands: bool?
 panel_icon: mdi:robot-vacuum
@@ -0,0 +1,61 @@
 #!/usr/bin/with-contenv bashio
 set -euo pipefail
 export ADVERTISE_IP="$(bashio::config 'advertise_ip')"
 export TZ="$(bashio::config 'timezone')"
 export LOG_LEVEL="$(bashio::config 'log_level')"
 mqtt_source=""
 if bashio::services.available "mqtt"; then
  export MQTT_HOST="$(bashio::services mqtt 'host')"
  export MQTT_PORT="$(bashio::services mqtt 'port')"
  export MQTT_USERNAME="$(bashio::services mqtt 'username')"
  export MQTT_PASSWORD="$(bashio::services mqtt 'password')"
  export MQTT_TLS="$(bashio::services mqtt 'ssl')"
  mqtt_source="Supervisor MQTT service"
 fi
 export_option() {
  local option="$1"
  local variable="$2"
  if bashio::config.exists "${option}"; then
    export "${variable}=$(bashio::config "${option}")"
    if [[ "${option}" == mqtt_* ]]; then
      if [[ -n "${mqtt_source}" ]]; then
        mqtt_source="${mqtt_source} with option overrides"
      else
        mqtt_source="add-on options"
      fi
    fi
  fi
 }
 export_option bind_address BIND_ADDRESS
 export_option port_lookup PORT_LOOKUP
 export_option port_firmware PORT_FIRMWARE
 export_option port_xmpp PORT_XMPP
 export_option health_port HEALTH_PORT
 export_option mqtt_host MQTT_HOST
 export_option mqtt_port MQTT_PORT
 export_option mqtt_tls MQTT_TLS
 export_option mqtt_ca_file MQTT_CA_FILE
 export_option mqtt_username MQTT_USERNAME
 export_option mqtt_password MQTT_PASSWORD
 export_option mqtt_client_id MQTT_CLIENT_ID
 export_option mqtt_base MQTT_BASE
 export_option ha_discovery_prefix HA_DISCOVERY_PREFIX
 export_option controller_jid CONTROLLER_JID
 export_option raw_commands RAW_COMMANDS
 if [[ -z "${MQTT_HOST:-}" ]]; then
  bashio::log.fatal "No MQTT broker is available. Configure a Supervisor MQTT service or set mqtt_host."
  exit 1
 fi
 bashio::log.info "Starting Deebot N95 Local Control"
 bashio::log.info "Advertising ${ADVERTISE_IP}; MQTT settings from ${mqtt_source}"
 if [[ "${RAW_COMMANDS:-false}" == "true" ]]; then
  bashio::log.warning "Raw MQTT commands are enabled; use them only for protocol testing."
 fi
 exec /n95bridge
@@ -0,0 +1,58 @@
 configuration:
  advertise_ip:
    name: Advertised IP address
    description: Stable Home Assistant host IPv4 address returned to the robot. Configure lbo.ecouser.net to resolve to this address.
  timezone:
    name: Time zone
    description: IANA time zone used for the local time and UTC offset sent to the robot, for example Europe/London.
  log_level:
    name: Log level
    description: Bridge log verbosity.
  bind_address:
    name: Bind address
    description: Advanced. Address for all listeners. Keep 0.0.0.0 unless you have a specific host-network requirement.
  port_lookup:
    name: Lookup port
    description: Advanced. Robot bootstrap HTTP port; defaults to 8007.
  port_firmware:
    name: Firmware port
    description: Advanced. Robot firmware-check HTTP port; defaults to 8005.
  port_xmpp:
    name: XMPP port
    description: Advanced. Plaintext robot XMPP port; defaults to 5223.
  health_port:
    name: Health port
    description: Advanced. HTTP health endpoint port; defaults to 8080.
  mqtt_host:
    name: MQTT host
    description: Broker host override without a scheme or port. The Supervisor MQTT service is used when available.
  mqtt_port:
    name: MQTT port
    description: Broker port override. Defaults to 1883, or 8883 when TLS is enabled.
  mqtt_tls:
    name: MQTT TLS
    description: Override whether the broker connection uses TLS with hostname verification.
  mqtt_ca_file:
    name: MQTT CA file
    description: Optional PEM CA bundle inside the add-on, normally a path under /ssl.
  mqtt_username:
    name: MQTT username
    description: Broker username override.
  mqtt_password:
    name: MQTT password
    description: Broker password override. A nonempty password requires a username.
  mqtt_client_id:
    name: MQTT client ID prefix
    description: Advanced. Prefix used for each robot's broker client ID.
  mqtt_base:
    name: MQTT base topic
    description: Advanced. Single topic level before each robot serial; defaults to ecovacs.
  ha_discovery_prefix:
    name: Discovery prefix
    description: Advanced. Home Assistant MQTT discovery prefix; defaults to homeassistant.
  controller_jid:
    name: Controller JID
    description: Advanced. Virtual XMPP sender address presented to the robot.
  raw_commands:
    name: Raw commands
    description: Advanced and risky. Allow protocol-level raw ctl commands over MQTT.
@@ -0,0 +1,21 @@
 # Changelog
 ## 1.0.3
 - Remove the `models` option and its `openai-oauth --models` passthrough
 - Document `api_key` behavior: empty auto-generates a persisted key printed
  in the log; paste your own to use a fixed value
 - Option descriptions shown in the add-on Configuration tab
  (`translations/en.yaml`)
 ## 1.0.2
 - First release in Gronod's Home Assistant Add-Ons repository
 - Wraps `openai-oauth` + `@openai/codex` (node:alpine image)
 - Local Bearer API key required on port 10531; auto-generated to
  `/config/.api_key` on first start and printed in the add-on log
  (override with the `api_key` option)
 - `log_level` and `log_requests` options mapped to upstream
  `CODEX_OPENAI_SERVER_LOG_REQUESTS`
 - `auth.json` read directly from `/share` so OAuth token refreshes persist
 - Add-on packaging licensed Apache-2.0 to match upstream components
@@ -0,0 +1,154 @@
 # OpenAI Codex Proxy — documentation
 Full setup, configuration, and troubleshooting for the **OpenAI Codex Proxy**
 Home Assistant add-on.
 ## How it works
 The add-on runs [openai-oauth](https://github.com/EvanZhouDev/openai-oauth)
 (by [@EvanZhouDev](https://github.com/EvanZhouDev)), a local reverse proxy
 that speaks the same authenticated Codex API as OpenAI's
 [@openai/codex](https://github.com/openai/codex) CLI
 (`chatgpt.com/backend-api/codex`). It exposes an OpenAI-compatible `/v1` API
 backed by your ChatGPT account instead of API credits.
 Because `openai-oauth` itself has no client authentication, this add-on binds
 it to loopback and publishes a small token-protected proxy on port `10531`.
 Every request must send `Authorization: Bearer <key>` (or `x-api-key`).
 ## Step 1 — generate `auth.json`
 On a desktop machine with Node.js installed (macOS, Linux, or Windows):
 ```sh
 npx @openai/codex login
 ```
 A browser opens for the ChatGPT sign-in. Afterwards your credentials are at:
 | OS | Path |
 |---|---|
 | macOS / Linux | `~/.codex/auth.json` |
 | Windows | `%USERPROFILE%\.codex\auth.json` |
 > Treat `auth.json` like a password — it grants access to your ChatGPT
 > account. Don't commit it, post it, or leave it world-readable.
 ## Step 2 — copy `auth.json` to Home Assistant
 The add-on reads `/share/auth.json`. Copy the file into the `share` folder on
 your Home Assistant machine using either:
 * the **Samba share** add-on — drop `auth.json` into `\\<host>\share\`, or
 * **SSH / Terminal** — e.g. `scp ~/.codex/auth.json root@<ha-host>:/share/auth.json`
 ## Step 3 — install and start
 1. Add this repository in Home Assistant
   (**Settings → Add-ons → Add-on Store → ⋮ → Repositories**):
   `https://git.i3omb.com/gronod/ha-gronod-addons`
 2. Install **OpenAI Codex Proxy** and start it
 3. Open the add-on **Log** — it prints the generated local API key:
 ```text
 [INFO] Generated a new local API key (stored at /config/.api_key)
 [INFO] Local API key: <your-key>
 ```
 If `/share/auth.json` is missing the add-on logs instructions and retries
 every 60 seconds — just copy the file and wait for the restart.
 ## Step 4 — connect an integration
 Configure your OpenAI-compatible integration with:
 | Setting | Value |
 |---|---|
 | Base URL | `http://<home-assistant-host>:10531/v1` |
 | API key | the key from the add-on log (or your `api_key` option) |
 From another add-on or a supervised Home Assistant container you can also use
 the internal DNS name `http://8e663231-openai-codex-proxy:10531/v1`.
 Quick check from a shell:
 ```sh
 curl http://<ha-host>:10531/v1/models \
  -H "Authorization: Bearer <your-key>"
 ```
 ## Options
 | Option | Default | Description |
 |---|---|---|
 | `api_key` | _(empty)_ | Local API key clients must send. Leave empty and a random key is generated on first start, saved to `/config/.api_key` (it survives restarts), and printed in the add-on log. Paste your own key here if you want to use a fixed value — the saved/generated key is ignored while this option is set. |
 | `log_level` | `INFO` | `DEBUG`, `INFO`, or `WARN` — verbosity of the add-on wrapper. `DEBUG` also enables upstream request logging. |
 | `log_requests` | `false` | Set upstream `CODEX_OPENAI_SERVER_LOG_REQUESTS=1`: emits one JSON line per request (path, status, duration, token usage). |
 To generate a suitable key yourself, run any of these on a desktop:
 ```sh
 openssl rand -hex 32
 # or, matching the add-on's own generator:
 node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"
 ```
 then paste the output into the `api_key` option and restart the add-on.
 The host-side port mapping (`10531`) can be changed or disabled in the
 add-on's **Network** section; the container-internal port stays `10531`.
 ## Endpoints
 | Path | Method | Purpose |
 |---|---|---|
 | `/v1/responses` | POST | OpenAI Responses API |
 | `/v1/chat/completions` | POST | Chat Completions API |
 | `/v1/models` | GET | Models available to your account |
 | `/v1/images/generations`, `/v1/images/edits` | POST | Image generation/editing |
 | `/health` | GET | Unauthenticated liveness check |
 All `/v1/*` routes require `Authorization: Bearer <key>`.
 ## Troubleshooting
 **Log shows `ERROR: /share/auth.json not found!`**
 The file isn't in the `share` folder yet, or has a different name. Copy it as
 described in Step 2 and wait for the automatic restart (60 s).
 **Requests return `401 authentication_error`**
 Wrong or missing API key. Use the key printed in the add-on log, or set the
 `api_key` option explicitly and restart.
 **Requests return `502 Upstream not ready`**
 `openai-oauth` is still starting (it resolves your account's model list from
 ChatGPT) or crashed — check the add-on log above the proxy messages.
 **Responses fail with auth errors after weeks/months**
 OAuth tokens normally refresh automatically and are written back to
 `/share/auth.json`. If the refresh token itself has expired (or you replaced
 `auth.json` with an older copy), re-run `npx @openai/codex login` on your
 desktop and copy the fresh file to `/share` again.
 **Rate limits / missing models**
 Only models your ChatGPT plan supports appear, and Codex account rate limits
 apply. `openai-oauth` is an unofficial community project; OpenAI may change
 the underlying endpoints at any time.
 ## Security notes
 * The published port is protected by the local API key — anyone on your LAN
  still needs it to use your ChatGPT account. Keep it secret like a password.
 * To restrict access further, disable the host port mapping and reach the
  add-on only via its internal hostname `8e663231-openai-codex-proxy` from
  other add-ons/Home Assistant.
 * `/share/auth.json` is visible to anything with Samba/SSH access to the
  `share` folder.
 ## Credits
 * [openai-oauth](https://github.com/EvanZhouDev/openai-oauth) by
  [@EvanZhouDev](https://github.com/EvanZhouDev) (Apache-2.0) — the proxy and
  Codex OAuth session handling.
 * [@openai/codex](https://github.com/openai/codex) (Apache-2.0) — OpenAI's
  Codex CLI, used to produce `auth.json` and for model discovery.
@@ -0,0 +1,16 @@
 # syntax=docker/dockerfile:1
 FROM node:alpine
 RUN npm install -g openai-oauth @openai/codex
 COPY rootfs /
 LABEL \
  io.hass.name="OpenAI Codex Proxy" \
  io.hass.description="Local reverse proxy for ChatGPT Plus Codex OAuth" \
  io.hass.type="addon" \
  io.hass.version="1.0.3" \
  org.opencontainers.image.title="openai-codex-proxy" \
  org.opencontainers.image.source="https://git.i3omb.com/gronod/ha-gronod-addons"
 CMD ["node", "/entrypoint.js"]
@@ -0,0 +1,202 @@
                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/
   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
   1. Definitions.
      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.
      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.
      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.
      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.
      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.
      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.
      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).
      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.
      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."
      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.
   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.
   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.
   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:
      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and
      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and
      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and
      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.
      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.
   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.
   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.
   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.
   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.
   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.
   END OF TERMS AND CONDITIONS
   APPENDIX: How to apply the Apache License to your work.
      To apply the Apache License to your work, attach the following
      boilerplate notice, with the fields enclosed by brackets "[]"
      replaced with your own identifying information. (Don't include
      the brackets!)  The text should be enclosed in the appropriate
      comment syntax for the file format. We also recommend that a
      file or class name and description of purpose be included on the
      same "printed page" as the copyright notice for easier
      identification within third-party archives.
   Copyright [yyyy] [name of copyright owner]
   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at
       http://www.apache.org/licenses/LICENSE-2.0
   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
@@ -0,0 +1,58 @@
 # OpenAI Codex Proxy
 <img src="logo.png" alt="OpenAI Codex Proxy" width="128" height="128">
 Local OpenAI-compatible API endpoint backed by your ChatGPT account's Codex
 OAuth login — packaged as a Home Assistant add-on.
 Point any OpenAI-compatible integration (for example an OpenAI conversation
 integration in Home Assistant) at this add-on and it answers through your
 ChatGPT Plus/Pro account instead of paid API credits.
 ## Features
 * OpenAI-compatible endpoints: `/v1/responses`, `/v1/chat/completions`,
  `/v1/models`, and `/v1/images/*`
 * Exposes the Codex models your ChatGPT account can actually use
 * Streaming responses, tool calls, and reasoning traces
 * Local API key required on every request — generated automatically on first
  start (no open proxy on your LAN)
 * Optional per-request JSON logging for troubleshooting
 * OAuth tokens refresh automatically and persist in `/share/auth.json`
 ## Requirements
 * A ChatGPT account (Plus or Pro recommended for Codex access)
 * A Codex `auth.json` file, generated on a desktop machine with
  `npx @openai/codex login` and copied to this Home Assistant machine's
  `/share` folder
 ## Installation
 1. Add this repository to Home Assistant
   (**Settings → Add-ons → Add-on Store → ⋮ → Repositories**):
   `https://git.i3omb.com/gronod/ha-gronod-addons`
 2. Copy your `auth.json` to `/share/auth.json` (Samba or SSH add-on)
 3. Install **OpenAI Codex Proxy** and start it
 4. Copy the generated local API key from the add-on log and configure your
   OpenAI-compatible integration with base URL
   `http://<home-assistant-host>:10531/v1`
 See [DOCS.md](DOCS.md) for the step-by-step guide, option reference, and
 troubleshooting.
 ## Credits
 This add-on wraps [openai-oauth](https://github.com/EvanZhouDev/openai-oauth)
 by [@EvanZhouDev](https://github.com/EvanZhouDev) — an unofficial,
 community-maintained project that exposes ChatGPT Codex OAuth sessions as an
 OpenAI-compatible API. Login uses OpenAI's
 [@openai/codex](https://github.com/openai/codex) CLI.
 ## License
 © 2026 Gordon Bolton. Apache License 2.0 — see `LICENCE.md`, matching the
 licenses of the upstream components this add-on wraps:
 [openai-oauth](https://github.com/EvanZhouDev/openai-oauth) (Apache-2.0) and
 [@openai/codex](https://github.com/openai/codex) (Apache-2.0).
 Use is subject to OpenAI's Terms of Use and your ChatGPT plan's rate limits.
@@ -0,0 +1 @@
 1.0.3
@@ -0,0 +1,24 @@
 name: "OpenAI Codex Proxy"
 description: "Local reverse proxy for ChatGPT Plus Codex OAuth"
 version: "1.0.3"
 slug: "openai_codex_proxy"
 init: false
 startup: application
 boot: auto
 arch:
  - aarch64
  - amd64
 ports:
  10531/tcp: 10531
 map:
  - share:rw
  - addon_config:rw
 options:
  api_key: ""
  log_level: INFO
  log_requests: false
 schema:
  api_key: password?
  log_level: list(DEBUG|INFO|WARN)
  log_requests: bool
 panel_icon: mdi:api
@@ -0,0 +1,259 @@
 #!/usr/bin/env node
 // OpenAI Codex Proxy add-on entrypoint.
 //
 // openai-oauth performs no authentication on its local endpoint, so this
 // wrapper binds it to loopback and publishes a small Bearer-token proxy on
 // the add-on port. The local API key is either taken from the `api_key`
 // option or generated once and persisted under /config (addon_config).
 "use strict";
 const crypto = require("crypto");
 const fs = require("fs");
 const http = require("http");
 const { spawn } = require("child_process");
 const { Readable } = require("stream");
 const OPTIONS_FILE = "/data/options.json";
 const AUTH_FILE = "/share/auth.json";
 const KEY_FILE = "/config/.api_key";
 const PUBLIC_PORT = 10531;
 const UPSTREAM_PORT = 10532;
 const UPSTREAM_URL = `http://127.0.0.1:${UPSTREAM_PORT}`;
 // ---- options ---------------------------------------------------------------
 let options = {};
 try {
  options = JSON.parse(fs.readFileSync(OPTIONS_FILE, "utf8")) || {};
 } catch {
  options = {};
 }
 const LOG_LEVEL = String(options.log_level || "INFO").toUpperCase();
 const LEVELS = { DEBUG: 0, INFO: 1, WARN: 2 };
 const threshold = LEVELS[LOG_LEVEL] ?? LEVELS.INFO;
 const log = (level, msg) => {
  if (LEVELS[level] >= threshold) {
    console.log(`[${level}] ${msg}`);
  }
 };
 // ---- auth.json guard -------------------------------------------------------
 if (!fs.existsSync(AUTH_FILE)) {
  console.error(
    `ERROR: ${AUTH_FILE} not found!\n` +
      "Generate it on a desktop with `npx @openai/codex login`, then copy\n" +
      "~/.codex/auth.json (macOS/Linux) or %USERPROFILE%\\.codex\\auth.json\n" +
      "(Windows) to the /share folder on this Home Assistant machine.\n" +
      "Retrying in 60 seconds..."
  );
  setTimeout(() => process.exit(1), 60_000);
 } else {
  main();
 }
 // ---- main ------------------------------------------------------------------
 function main() {
  const apiKey = resolveApiKey();
  const upstream = startUpstream();
  const server = http.createServer((req, res) => {
    handleRequest(req, res, apiKey).catch((err) => {
      log("WARN", `request error: ${err.message}`);
      if (!res.headersSent) {
        sendJson(res, 502, {
          error: { message: "Upstream not ready.", type: "upstream_error" },
        });
      }
      res.end();
    });
  });
  server.on("error", (err) => {
    console.error(`ERROR: cannot listen on 0.0.0.0:${PUBLIC_PORT}: ${err.message}`);
    process.exit(1);
  });
  server.listen(PUBLIC_PORT, "0.0.0.0", () => {
    log(
      "INFO",
      `OpenAI Codex Proxy listening on 0.0.0.0:${PUBLIC_PORT} ` +
        `(upstream 127.0.0.1:${UPSTREAM_PORT})`
    );
    log("INFO", "Base URL for clients: http://<this-host>:10531/v1");
    log("INFO", `Local API key: ${apiKey}`);
    waitForUpstream();
  });
  let shuttingDown = false;
  const shutdown = (signal) => {
    shuttingDown = true;
    log("INFO", `${signal} received, shutting down`);
    upstream.kill("SIGTERM");
    server.close(() => process.exit(0));
    setTimeout(() => process.exit(0), 5_000).unref();
  };
  process.on("SIGTERM", () => shutdown("SIGTERM"));
  process.on("SIGINT", () => shutdown("SIGINT"));
  upstream.on("exit", (code, signal) => {
    if (shuttingDown) return;
    console.error(
      `ERROR: openai-oauth exited (code=${code} signal=${signal}); exiting so the add-on restarts`
    );
    process.exit(code ?? 1);
  });
  upstream.on("error", (err) => {
    console.error(`ERROR: failed to start openai-oauth: ${err.message}`);
    process.exit(1);
  });
 }
 function resolveApiKey() {
  const fromOption = String(options.api_key || "").trim();
  if (fromOption) {
    log("INFO", "Using API key from the api_key option");
    return fromOption;
  }
  try {
    const stored = fs.readFileSync(KEY_FILE, "utf8").trim();
    if (stored) return stored;
  } catch {
    // not generated yet
  }
  const generated = crypto.randomBytes(32).toString("base64url");
  try {
    fs.mkdirSync(require("path").dirname(KEY_FILE), { recursive: true });
    fs.writeFileSync(KEY_FILE, generated + "\n", { mode: 0o600 });
    log("INFO", `Generated a new local API key (stored at ${KEY_FILE})`);
  } catch (err) {
    log("WARN", `could not persist generated key to ${KEY_FILE}: ${err.message}`);
  }
  return generated;
 }
 function startUpstream() {
  const args = [
    "openai-oauth",
    "--host",
    "127.0.0.1",
    "--port",
    String(UPSTREAM_PORT),
    "--oauth-file",
    AUTH_FILE,
  ];
  const env = { ...process.env };
  env.OPENAI_OAUTH_INTERNAL_RUNTIME_DIR = "/data/openai-oauth";
  const wantRequestLogs =
    options.log_requests === true || LOG_LEVEL === "DEBUG";
  env.CODEX_OPENAI_SERVER_LOG_REQUESTS = wantRequestLogs ? "1" : "0";
  log(
    "DEBUG",
    `spawning: npx ${args.join(" ")} (request logs ${wantRequestLogs ? "on" : "off"})`
  );
  return spawn("npx", args, { stdio: "inherit", env });
 }
 async function waitForUpstream() {
  for (;;) {
    try {
      const res = await fetch(`${UPSTREAM_URL}/health`);
      if (res.ok) {
        log("INFO", "upstream openai-oauth is ready");
        return;
      }
    } catch {
      // not up yet
    }
    await new Promise((r) => setTimeout(r, 1000));
  }
 }
 // ---- request handling ------------------------------------------------------
 const HOP_BY_HOP = new Set([
  "connection",
  "keep-alive",
  "proxy-authenticate",
  "proxy-authorization",
  "te",
  "trailer",
  "transfer-encoding",
  "upgrade",
 ]);
 async function handleRequest(req, res, apiKey) {
  const url = new URL(req.url, `http://localhost:${PUBLIC_PORT}`);
  if (req.method === "GET" && url.pathname === "/health") {
    sendJson(res, 200, { ok: true, service: "openai-codex-proxy" });
    return;
  }
  if (!isAuthorized(req, apiKey)) {
    sendJson(res, 401, {
      error: {
        message: "Missing or invalid API key. Send 'Authorization: Bearer <key>'.",
        type: "authentication_error",
      },
    });
    return;
  }
  const headers = {};
  for (const [k, v] of Object.entries(req.headers)) {
    const key = k.toLowerCase();
    if (HOP_BY_HOP.has(key)) continue;
    if (key === "host" || key === "authorization" || key === "x-api-key") continue;
    if (key === "content-length") continue;
    headers[key] = v;
  }
  const started = Date.now();
  const upstreamRes = await fetch(UPSTREAM_URL + req.url, {
    method: req.method,
    headers,
    body: ["GET", "HEAD"].includes(req.method) ? undefined : req,
    duplex: "half",
  });
  const resHeaders = {};
  upstreamRes.headers.forEach((v, k) => {
    if (!HOP_BY_HOP.has(k)) resHeaders[k] = v;
  });
  res.writeHead(upstreamRes.status, resHeaders);
  if (upstreamRes.body) {
    Readable.fromWeb(upstreamRes.body).pipe(res);
  } else {
    res.end();
  }
  log(
    "INFO",
    `${req.method} ${url.pathname} -> ${upstreamRes.status} ${Date.now() - started}ms`
  );
 }
 function isAuthorized(req, apiKey) {
  const bearer = req.headers.authorization || "";
  const presented = bearer.startsWith("Bearer ")
    ? bearer.slice(7)
    : req.headers["x-api-key"] || "";
  if (!presented) return false;
  const a = crypto.createHash("sha256").update(String(presented)).digest();
  const b = crypto.createHash("sha256").update(apiKey).digest();
  return crypto.timingSafeEqual(a, b);
 }
 function sendJson(res, status, obj) {
  const body = JSON.stringify(obj);
  res.writeHead(status, {
    "content-type": "application/json",
    "content-length": Buffer.byteLength(body),
  });
  res.end(body);
 }
@@ -0,0 +1,18 @@
 configuration:
  api_key:
    name: API key
    description: >-
      Local API key clients must send (as "Authorization: Bearer <key>" or
      "x-api-key"). Leave empty and a random key is generated on first start,
      saved to the add-on configuration, and printed in the add-on log. Paste
      your own key here if you want to use a fixed value.
  log_level:
    name: Log level
    description: >-
      Verbosity of the add-on wrapper: DEBUG, INFO, or WARN. DEBUG also
      enables upstream request logging.
  log_requests:
    name: Log requests
    description: >-
      Emit one JSON line per proxied request (path, status, duration, token
      usage) from the upstream openai-oauth server.
@@ -1,3 +1,3 @@
-name: Emby MCP Add-ons
+name: Gronod's Home Assistant Add-Ons
-url: "https://git.i3omb.com/gronod/ha-emby-mcp"
+url: "https://git.i3omb.com/gronod/ha-gronod-addons"
 maintainer: Gordon Bolton <gordon@i3omb.com>
Author	SHA1	Message	Date
gronod	cbf2e07535	ci: parallel jobs, skip flaky/fixture tests Validate add-ons / YAML and layout (pull_request) Successful in 9s Details Validate add-ons / emby-mcp gofmt (pull_request) Successful in 11s Details Validate add-ons / emby-mcp vet (pull_request) Successful in 40s Details Validate add-ons / emby-mcp build (pull_request) Successful in 18s Details Validate add-ons / openai-codex-proxy (pull_request) Successful in 1m30s Details Validate add-ons / n95-mqtt-bridge pin (pull_request) Successful in 3s Details Validate add-ons / n95-mqtt-bridge pin and upstream tests (pull_request) Successful in 1m12s Details Validate add-ons / emby-mcp Go (pull_request) Successful in 1m47s Details Validate add-ons / YAML and layout (push) Successful in 9s Details Validate add-ons / emby-mcp gofmt (push) Successful in 20s Details Validate add-ons / emby-mcp vet (push) Successful in 55s Details Validate add-ons / emby-mcp build (push) Successful in 30s Details Validate add-ons / emby-mcp Go (push) Successful in 48s Details Validate add-ons / openai-codex-proxy (push) Successful in 1m35s Details Validate add-ons / n95-mqtt-bridge pin (push) Successful in 7s Details Validate add-ons / n95-mqtt-bridge pin and upstream tests (push) Successful in 32s Details Split emby-mcp into gofmt/vet/build/test and n95 pin vs test so a capacity-8 runner can fill slots. Cancel superseded runs. Skip streamable HTTP e2e on CI (session handshake fails on act). Skip n95 TestCapture* (pcaps are not in the published tag).	2026-09-25 20:33:39 +00:00
gronod	be4bf4c7a5	fix: sync openai-codex-proxy VERSION and image label to 1.0.3 Validate add-ons / YAML and layout (pull_request) Successful in 27s Details Validate add-ons / openai-codex-proxy (pull_request) Canceled after 0s Details Validate add-ons / n95-mqtt-bridge pin and upstream tests (pull_request) Canceled after 0s Details Validate add-ons / emby-mcp Go (pull_request) Canceled after 3m39s Details	2026-09-25 20:27:24 +00:00
gronod	e420c8c0c3	ci: install python3-yaml via apt and gofmt emby-mcp Validate add-ons / YAML and layout (pull_request) Failing after 35s Details Validate add-ons / emby-mcp Go (pull_request) Failing after 3m55s Details Validate add-ons / openai-codex-proxy (pull_request) Successful in 13s Details Validate add-ons / n95-mqtt-bridge pin and upstream tests (pull_request) Failing after 39s Details Gitea ubuntu-latest is PEP 668 so pip install pyyaml fails. gofmt -l was dirty on main.go, items_test.go, tools_browse.go.	2026-09-25 20:22:07 +00:00
gronod	a25e22175a	docs: describe protected branches and CI-gated PRs Validate add-ons / YAML and layout (pull_request) Failing after 5s Details Validate add-ons / emby-mcp Go (pull_request) Failing after 13s Details Validate add-ons / openai-codex-proxy (pull_request) Successful in 16s Details Validate add-ons / n95-mqtt-bridge pin and upstream tests (pull_request) Canceled after 43s Details	2026-09-25 20:19:27 +00:00
gronod	e6b6968b5e	ci: add Gitea Actions validation for add-ons Validate add-ons / YAML and layout (pull_request) Failing after 26s Details Validate add-ons / emby-mcp Go (pull_request) Failing after 57s Details Validate add-ons / openai-codex-proxy (pull_request) Successful in 1m47s Details Validate add-ons / n95-mqtt-bridge pin and upstream tests (pull_request) Failing after 44s Details Run YAML/config checks, emby-mcp gofmt/vet/build/test, proxy entrypoint syntax, and n95 upstream pin + go test on push and PR to develop/main.	2026-09-25 20:17:08 +00:00
gronod	bd3cac18d6	Merge branch 'main' into develop	2026-09-25 21:13:26 +01:00
gronod	7bcf5322e1	feat: emby-mcp 1.0.16 player owner filter and HA links Expose session/last-used user and device IP on player rows. Filter retrieve_player_list by users, merge GET /Devices when include_offline is set, and resolve spoken names to HA media_player entities via player_links (device_id or IP). PlayNow still requires a live session.	2026-09-25 19:58:58 +00:00
gronod	2c4911e3c8	Update emby-mcp/README.md Corrected typo in Emby.MCP repo URL	2026-09-25 12:17:12 +01:00
gronod	e12292f316	fix: n95-mqtt-bridge 0.1.2 builds upstream v0.1.2 Pin ha-n95-local-control tag v0.1.2 (7bed99cc4c3222bad648efcddcdfed95652277f7). Health bind failure no longer takes down 8007/8005/5223 when OTBR owns 8080.	2026-09-24 16:18:51 +00:00
gronod	97c0e4dc04	fix: expose N95 listener ports on HAOS firewall (0.1.1) Declare 8007, 8005, 5223, and 8080 in the add-on ports map so Supervisor opens inbound host firewall holes. Keep host_network; Docker does not remap the ports. Bump the add-on to 0.1.1 so Home Assistant picks it up.	2026-09-24 15:40:50 +00:00
gronod	1a2a97babc	feat: add Deebot N95 Local Control add-on	2026-09-24 16:03:33 +01:00
gronod	c4095d0be7	feat: restore premiere_date on item results (1.0.15) Emby PremiereDate is the first air date for episodes/series and the release date for movies. Request it again in Fields, emit it as YYYY-MM-DD on search/browse/queue items, and document the conversation prompt so Assist can answer airdate questions. Potential breaking change: item JSON gains premiere_date versus the 1.0.11 slim shape. HA function parameter YAML is unchanged; re-paste the DOCS.md system prompt.	2026-09-23 14:04:30 +00:00
gronod	58cf62a41f	openai-codex-proxy 1.0.3: drop models option, clarify api_key The models option passed an allowlist to openai-oauth --models but was unrequested and of uncertain upstream effect; remove it entirely. Add translations/en.yaml so the Configuration tab explains that an empty api_key auto-generates a persisted key printed in the log, and that a custom key can be pasted instead. Document a key-generation command in DOCS.md.	2026-09-22 15:50:10 +01:00
gronod	9e26d7fe9c	docs: license openai-codex-proxy under Apache-2.0 Align the add-on packaging with its upstream components (openai-oauth and @openai/codex, both Apache-2.0).	2026-09-22 14:30:01 +01:00
gronod	02d9449a34	feat: add OpenAI Codex Proxy add-on (1.0.2) Local OpenAI-compatible endpoint backed by a ChatGPT account's Codex OAuth login (wraps EvanZhouDev/openai-oauth + @openai/codex on node:alpine). Upstream has no client auth, so a Node entrypoint binds it to loopback and enforces a Bearer/x-api-key check on the published port; the key is auto-generated into addon_config on first start and printed in the log. Options map to upstream controls: api_key, models (--models), log_level/log_requests (CODEX_OPENAI_SERVER_LOG_REQUESTS). auth.json is read via --oauth-file /share/auth.json so token refreshes persist across restarts.	2026-09-22 14:03:59 +01:00
gronod	ea91207196	docs: convert to multi-add-on repository layout Rename the repository to Gronod's Home Assistant Add-Ons (ha-gronod-addons). Root README becomes a repo-level overview; each add-on's README carries decision content and DOCS.md carries the full configuration/usage reference, matching mainline HA add-on conventions. Emby MCP conversation-agent URLs updated for the new repo hash (8e663231-emby-mcp) with a note for pre-rename c5cb4244 installs.	2026-09-22 14:03:37 +01:00
gronod	af5fd8feea	fix: update config test/comment for 0.0.0.0:8085 listen default The default MCP_LISTEN_ADDR changed to 0.0.0.0 in 1.0.5 but the TestLoadDefaults expectation and the field comment were never updated.	2026-09-22 14:03:32 +01:00