mcp-server-shieldtv 0.1.0__tar.gz

mcp_server_shieldtv-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nicholas E. Andrade
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_server_shieldtv-0.1.0/PKG-INFO

@@ -0,0 +1,573 @@
+Metadata-Version: 2.4
+Name: mcp-server-shieldtv
+Version: 0.1.0
+Summary: MCP server for NVIDIA Shield TV (Android TV Remote protocol v2) with a one-time pairing CLI
+Author: Nicholas E. Andrade
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/SDNick484/mcp-server-shieldtv
+Project-URL: Issues, https://github.com/SDNick484/mcp-server-shieldtv/issues
+Project-URL: Changelog, https://github.com/SDNick484/mcp-server-shieldtv/blob/main/CHANGELOG.md
+Keywords: mcp,mcp-server,nvidia-shield,shield-tv,android-tv,home-automation
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: androidtvremote2>=0.3.2
+Requires-Dist: zeroconf>=0.130
+Requires-Dist: typing_extensions>=4.7
+Requires-Dist: adb-shell[async]>=0.4.4
+Requires-Dist: pyjwt[crypto]>=2.10
+Requires-Dist: uvicorn>=0.31
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: anyio>=4; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Requires-Dist: httpx2; extra == "dev"
+Dynamic: license-file
+
+# mcp-server-shieldtv
+
+[![CI](https://github.com/SDNick484/mcp-server-shieldtv/actions/workflows/ci.yml/badge.svg)](https://github.com/SDNick484/mcp-server-shieldtv/actions/workflows/ci.yml)
+
+An [MCP](https://modelcontextprotocol.io) server for the **NVIDIA Shield TV**, built on the
+Android TV Remote protocol v2 (the same protocol the Google TV phone app uses). It lets an
+MCP client such as Claude press remote keys, launch apps, wake or sleep the Shield, and
+read its power state and foreground app.
+
+> **Status.** Pairing, `get_status`, keys, `launch_app`, `set_power` and the ADB tools were
+> verified on a real Shield (remote service 7.00) in 2026-10. The features added since
+> (pairing retries, reconnect and rediscovery hardening, dry run, `doctor`, resources and
+> prompts, HTTP, the Alpine service) are **verified against the simulator only**, a
+> wire-level fake that the real protocol library pairs and connects with.
+> [Verification status](#verification-status) lists every protocol assumption and whether a
+> Shield has confirmed it; [HARDWARE_VALIDATION.md](https://github.com/SDNick484/mcp-server-shieldtv/blob/main/HARDWARE_VALIDATION.md) is the checklist.
+
+It's one of four sibling servers with the same conventions (dry run, `doctor`, typed results,
+Streamable HTTP behind Cloudflare Access):
+[mcp-server-onkyo](https://github.com/SDNick484/mcp-server-onkyo),
+[mcp-server-harmony](https://github.com/SDNick484/mcp-server-harmony) and
+[mcp-server-sofabaton](https://github.com/SDNick484/mcp-server-sofabaton).
+
+This is not an official NVIDIA project, and NVIDIA publishes no MCP server for the Shield.
+
+## Why this protocol
+
+| | Remote protocol v2 (this project) | ADB |
+|---|---|---|
+| Setup | One-time pairing with an on-screen code | Enable *Network debugging* on the Shield |
+| Good for | D-pad, media keys, app launch, power/app state | Deep device inspection |
+| Risk if exposed to an LLM | Bounded: it can only press keys | High: `adb shell` is arbitrary code execution |
+
+Three optional ADB tools do what the remote protocol can't: `get_now_playing`,
+`get_remotes` and `reboot_shield`. They are off until you run `adb-setup`, and they run
+only fixed commands; the server never exposes a raw shell (see
+[ADB tools](#adb-tools-optional)).
+
+## Install
+
+```sh
+python -m venv ~/.venvs/shieldtv && . ~/.venvs/shieldtv/bin/activate
+pip install mcp-server-shieldtv
+```
+
+From source instead (for the newest code, or to run the tests):
+
+```sh
+git clone https://github.com/SDNick484/mcp-server-shieldtv.git && cd mcp-server-shieldtv
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]" && pytest
+```
+
+Requires Python 3.11+.
+
+## Pair with your Shield (once)
+
+The Shield and the machine running the server must be on the same network, and the
+machine must be able to reach the Shield on these ports:
+
+| Port | Used for |
+|---|---|
+| TCP 6466 | Remote control (every tool call) |
+| TCP 6467 | Pairing (only during `pair`) |
+| UDP 5353 (mDNS) | `discover`, and `pair` without `--host` |
+| TCP 5555 | ADB, only if you enable the ADB tools with `adb-setup` |
+
+A firewall, a guest network, or a separate IoT VLAN between the two will show up as
+"can't reach the Shield".
+
+```sh
+mcp-server-shieldtv discover            # optional: list Android TV devices via mDNS
+mcp-server-shieldtv pair                # finds the Shield, or: pair --host 192.168.1.50
+```
+
+A code appears on the TV; type it into the terminal. A typo, a rejected code or Cancel on
+the TV starts over with a new code (three tries). Pairing generates a client certificate
+and key under `~/.config/mcp-server-shieldtv/` (override with `SHIELDTV_CONFIG_DIR`) and
+saves the Shield's address, name and MAC in `config.json`. The MAC is how the server finds
+the Shield again if its address changes. Unusable old credentials are set aside
+(`cert.pem.broken`) and replaced. A running server notices a new pairing and reconnects
+with it; it doesn't need a restart.
+
+Then check everything between this machine and the Shield:
+
+```sh
+mcp-server-shieldtv doctor
+```
+
+```
+Shield 192.168.1.50
+   ok config    paired with SHIELD Android TV (MAC xx:xx:xx:xx:B2:C3) at x.x.x.50; credentials load and are private
+   ok tcp       ports 6466 and 6467 accept connections
+   ok identity  SHIELD Android TV, MAC xx:xx:xx:xx:B2:C3
+   ok session   NVIDIA SHIELD Android TV (remote service <version>); on, com.google.android.tvlauncher in front, ...
+```
+
+`doctor` checks each layer in order and stops at the first failure, saying what it means and
+which [HARDWARE_VALIDATION.md](https://github.com/SDNick484/mcp-server-shieldtv/blob/main/HARDWARE_VALIDATION.md) step covers it. It never presses a
+key, launches anything or pairs. Output is redacted (addresses, MACs) unless `--no-redact`.
+
+**Treat `cert.pem` and `key.pem` like a password.** Anyone who has them can control your
+Shield. The directory is created `0700` and the files `0600`, and `.gitignore` excludes
+them. To revoke access, remove the device from the Shield's settings and re-pair.
+
+WSL2 note: mDNS discovery needs mirrored networking (`networkingMode=mirrored` in
+`%UserProfile%\.wslconfig`, then `wsl --shutdown`). Otherwise pass `--host`.
+
+### ADB tools (optional)
+
+The remote protocol knows which app is in front, but not what it's playing, whether your
+Bluetooth remotes work, or how to reboot. ADB can do all three. To enable the ADB tools:
+
+1. On the Shield: Settings > Device Preferences > About, select **Build** seven times, then
+   Developer options > **Network debugging** on.
+2. Run `mcp-server-shieldtv adb-setup` (after `pair`). The TV asks "Allow USB debugging?":
+   tick "Always allow from this computer" and choose Allow.
+
+`adb-setup` creates its own ADB key (`adbkey`, `adbkey.pub`, `0600`) next to the pairing
+files and sets `"adb": true` in `config.json`. **The ADB key grants a shell on the Shield;
+guard it more carefully than the pairing files.** To revoke it, use Developer options >
+Revoke USB debugging authorizations.
+
+**`get_now_playing`** reports, checked on a real Shield: the app, title, subtitle (the artist for music,
+the channel for live TV), play state, and position. Live TV (YouTube TV, Sling) reports no
+position, since its "position" is an offset into the stream. Music played from YouTube Music
+shows up as the YouTube app. Duration and album aren't available this way. A title that
+contains ", " can rarely split wrong (the system prints title and artist joined by ", ").
+
+**`get_remotes`** lists Bluetooth remotes (a Harmony hub shows up as "Harmony Keyboard")
+(every paired input device, even ones that haven't connected since the Shield started)
+as `working`, `disconnected` (normal when not in use), or `stuck`: Bluetooth says it is
+connected, but Android never created its input device, so its buttons do nothing. This
+happened to both remotes on a real Shield after a reboot. The fix for a Harmony hub is to
+press Off and start the activity again.
+
+**`reboot_shield`** notes which remotes work, restarts the Shield, and waits until it has
+booted (about 35 seconds on a real Shield) plus 20 seconds for remotes that reconnect on
+their own. It reports any remote that came back stuck, with the fix, and any that worked
+before but hasn't reconnected yet. A Harmony hub doesn't reconnect until a button is
+pressed, so expect it to be listed that way; if it then does nothing, `get_remotes` says
+whether it's stuck. The whole call takes about a minute. It is marked destructive, so MCP
+clients ask before running it.
+
+## Use it with an MCP client
+
+```json
+{
+  "mcpServers": {
+    "shieldtv": { "command": "/path/to/mcp-server-shieldtv/.venv/bin/mcp-server-shieldtv" }
+  }
+}
+```
+
+For Claude Code: `claude mcp add shieldtv -- /path/to/.venv/bin/mcp-server-shieldtv`.
+
+### HTTP and Cloudflare Access
+
+To share one server between Claude Code, Claude Desktop and the mobile app, run it as a
+service and reach it through a Cloudflare Tunnel with Access in front:
+
+```sh
+CF_ACCESS_TEAM_DOMAIN=<team>.cloudflareaccess.com CF_ACCESS_AUD=<aud tag> \
+  mcp-server-shieldtv --http --public-host mcp.example.com      # 127.0.0.1:8712/shieldtv/mcp
+```
+
+| Flag | Variable | Default |
+|---|---|---|
+| `--bind` | `MCP_HTTP_BIND` | `127.0.0.1` |
+| `--port` | `MCP_HTTP_PORT` | `8712` (Onkyo 8711, Harmony 8713) |
+| `--path` | `MCP_HTTP_PATH` | `/shieldtv/mcp` |
+| `--public-host` | `MCP_PUBLIC_HOSTS` | none: only loopback Host headers pass |
+| | `CF_ACCESS_TEAM_DOMAIN`, `CF_ACCESS_AUD` | none: no Access checks |
+| | `MCP_ALLOWED_EMAILS` | anyone Access lets in |
+
+With Access configured, every request needs a valid `Cf-Access-Jwt-Assertion`: the signature
+(the team's published keys), audience, issuer, expiry, and the email allow-list if set.
+Anything else gets a plain 403. The server **refuses to start** on a non-loopback address
+without Access unless you pass `--insecure-no-auth` (for trusted-LAN testing only). It also
+checks `Host` and `Origin` (DNS-rebinding protection), including on `--bind 0.0.0.0`.
+`GET /healthz` answers without auth. `src/shieldtv_mcp/remote.py` is identical in all four
+servers.
+
+### As a service on Alpine (Proxmox LXC)
+
+```sh
+sh deploy/alpine/install.sh                      # as root; or: install.sh /path/to/checkout
+su -s /bin/sh mcp-shieldtv -c 'SHIELDTV_CONFIG_DIR=/var/lib/mcp-server-shieldtv \
+  /opt/mcp-server-shieldtv/venv/bin/mcp-server-shieldtv pair --host <shield ip>'
+vi /etc/mcp-server-shieldtv/env                  # HTTP and Access settings
+rc-update add mcp-server-shieldtv default && rc-service mcp-server-shieldtv start
+```
+
+| Path | Owner, mode | Holds |
+|---|---|---|
+| `/opt/mcp-server-shieldtv/venv` | root, 0755 | The code |
+| `/etc/mcp-server-shieldtv/env` | root:mcp-shieldtv, 0640 | HTTP and Access settings |
+| `/var/lib/mcp-server-shieldtv/` | mcp-shieldtv, 0700 (files 0600) | `cert.pem`, `key.pem`, `adbkey`, `config.json` |
+| `/var/log/mcp-server-shieldtv/server.log` | mcp-shieldtv, 0750 | Logs, redacted |
+| `/etc/init.d/mcp-server-shieldtv` | root, 0755 | OpenRC script (`supervise-daemon`, restarts on exit) |
+
+The credentials live in `/var/lib`, owned by the unprivileged `mcp-shieldtv` user, because
+they're the service's own: `pair` runs as that user, and the server rewrites `config.json`
+when the Shield moves. Every dependency has a musl wheel, so nothing compiles.
+`deploy/alpine/smoke-test.sh` runs the whole install in a `python:3.12-alpine` container
+against the simulator, and CI runs it on every push.
+To point it at a particular Shield without editing `config.json`, pass the host as an
+environment variable: `claude mcp add shieldtv -e SHIELDTV_HOST=192.168.1.50 -- ...`.
+That Shield must already be paired with the same credentials (`pair --host <ip>` once per
+Shield; note that `pair` also saves its host as the default in `config.json`).
+
+## Configuration
+
+| Setting | Default | What it does |
+|---|---|---|
+| `SHIELDTV_HOST` | *(from `config.json`)* | The Shield's IP address or hostname |
+| `SHIELDTV_CONFIG_DIR` | `$XDG_CONFIG_HOME/mcp-server-shieldtv` | Where the certificate, key and `config.json` live |
+| `XDG_CONFIG_HOME` | `~/.config` | Standard base directory, used when `SHIELDTV_CONFIG_DIR` is unset |
+| `SHIELDTV_DRY_RUN` | off | Read the Shield, send nothing that changes anything (`serve --dry-run`) |
+| `SHIELDTV_DEBUG` | off | Log the protocol traffic to stderr (`--debug`) |
+| `SHIELDTV_LOG_UNREDACTED` | off | Show LAN addresses and MACs in logs (`--no-redact`); keys and tokens stay hidden |
+
+`config.json` (written by `pair`, safe to edit by hand):
+
+| Key | What it does |
+|---|---|
+| `host` | The Shield's address, saved by `pair` (and updated if the Shield moves) |
+| `name`, `mac` | The Shield's name and MAC, read from its certificate by `pair` |
+| `apps` | Extra or overriding app names for `launch_app` (see below) |
+| `adb` | `true` once `adb-setup` succeeds; enables the ADB tools |
+| `port`, `pairing_port` | `6466` and `6467`; other values are for the simulator |
+
+Problems in `config.json` (invalid JSON, a bad app entry) are logged at startup and shown by
+`doctor`, and only the bad part is ignored.
+
+When the host is set in more than one place, the most specific wins: `pair --host`, then
+`SHIELDTV_HOST`, then `config.json`.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `get_status` | Reachability, power (`on`/`standby`), foreground app, volume (`null` when not reported), device info; while unreachable, `stale: true` with `as_of` and `error` |
+| `list_apps` | The app names `launch_app` accepts |
+| `send_key` | Press an allow-listed remote key, optionally repeated 1-10 times (see below) |
+| `launch_app` | Launch an allow-listed app by friendly name, and confirm it reached the foreground |
+| `set_power` | Wake (`on`) or sleep (`off`) using `WAKEUP`/`SLEEP`, not the `POWER` toggle |
+| `get_now_playing` | App, title, subtitle (artist or channel), play state and position. Needs `adb-setup` |
+| `get_remotes` | Each Bluetooth remote and whether it works, with a fix for stuck ones. Needs `adb-setup` |
+| `reboot_shield` | Restart the Shield, wait until it's back, then check the remotes. Needs `adb-setup` |
+
+Every tool returns structured content with a published output schema. The actions
+(`send_key`, `launch_app`, `set_power`, and `reboot_shield`'s first fields) return the same
+**ActionResult** shape as the sibling servers:
+
+```json
+{"shield": "SHIELD Android TV", "outcome": "done",
+ "detail": "Launched netflix (com.netflix.ninja is in the foreground)",
+ "sent": ["app_link https://www.netflix.com/title"], "warnings": []}
+```
+
+`outcome` is `done`, `unchanged` (e.g. `set_power off` while already in standby: nothing is
+sent) or `dry_run`. Failures are MCP errors with a sentence that says what to do.
+
+**Dry run** (`serve --dry-run`, `call --dry-run` or `SHIELDTV_DRY_RUN=1`) reads the Shield and
+validates every call as usual, but sends nothing; results say what would have been sent.
+
+### Resources and prompts
+
+Resources are context a client attaches (in Claude Code: `@shieldtv:shieldtv://apps`). Reading
+them sends nothing to the Shield.
+
+| Resource | What it holds |
+|---|---|
+| `shieldtv://apps` | The apps `launch_app` accepts: link, package, and whether each is a default or from `config.json` |
+| `shieldtv://keys` | The keys `send_key` accepts, and the ones left out on purpose, with why |
+
+Prompts are workflows you pick (in Claude Code: `/mcp__shieldtv__watch netflix`).
+
+| Prompt | Arguments | Does |
+|---|---|---|
+| `watch` | `app`, `what` | Wakes the Shield, opens the app, navigates with the D-pad while asking you what's on screen |
+| `remotes_not_working` | | Runs `get_remotes` and repeats its advice; doesn't reboot unless you ask |
+
+### Movie night across servers
+
+The servers don't know about each other: each works alone, and a client with several
+connected composes them. With all four connected, *"movie night in the theater: Plex on the
+Shield, receiver in Dolby Surround at 45"* becomes (tool names as of these versions):
+
+```
+harmony.start_activity   activity="Watch Shield"          # TV and receiver on, inputs switched
+shieldtv.launch_app      app="plex"
+onkyo.set_listening_mode receiver="Theater" mode="dolby-surround"
+onkyo.set_volume         receiver="Theater" level=45      # capped server-side if above the cap
+```
+
+What makes this safe to hand to a model is that limits live in each server, not in the
+prompt: only allow-listed keys and apps here, and the volume cap and never-guess-a-receiver
+rule in Onkyo.
+
+Allowed keys: `HOME`, `BACK`, `MENU`, `DPAD_UP`/`DOWN`/`LEFT`/`RIGHT`/`CENTER`,
+`MEDIA_PLAY_PAUSE`, `MEDIA_PLAY`, `MEDIA_PAUSE`, `MEDIA_STOP`, `MEDIA_NEXT`,
+`MEDIA_PREVIOUS`, `MEDIA_REWIND`, `MEDIA_FAST_FORWARD`, `VOLUME_UP`, `VOLUME_DOWN`,
+`VOLUME_MUTE`.
+
+### Apps
+
+Default apps, each checked on a real Shield: `youtube`, `youtube-tv`, `netflix`,
+`prime-video`, `disney+`, `hulu`, `plex`, `spotify`.
+
+Apps launch through **deep links**: https links, or an app's own scheme (`plex://`,
+`spotify:`) where the https link would go to a browser instead. On the Shield (remote service 7.x), a bare
+package name is sent as `market://launch?id=<package>`, which the Shield rejects and then
+drops the connection. `launch_app` waits for the app to reach the foreground (up to 10s)
+and returns an error that says what happened if it doesn't: the request was rejected, or it
+was accepted but nothing opened (the app isn't installed, or no app handles the link; the
+TV shows "You don't have an app that can do this").
+
+### Add your own apps
+
+Edit `~/.config/mcp-server-shieldtv/config.json`:
+
+```json
+{
+  "host": "192.168.1.50",
+  "apps": {
+    "crunchyroll": { "link": "https://www.crunchyroll.com", "package": "com.crunchyroll.crunchyroid" },
+    "example": "https://example.com/tv"
+  }
+}
+```
+
+An entry is either a link, or `{ "link", "package" }`. Adding the package is recommended:
+`launch_app` then confirms that exact app opened, and `get_status` shows the friendly name.
+Without it, any app other than the home screen coming to the front counts as success.
+Names are case-insensitive, and an entry with the same name as a default replaces it.
+Restart the server (or your MCP client) to pick up changes.
+
+**Finding the link and package:** open the app on the Shield, then call `get_status` (or ask
+"what app is open on the Shield?"); `current_app_package` is the package. For the link, try
+the service's website address (`https://www.<service>.com`). With ADB enabled, Android can
+tell you which app a link opens without launching anything:
+
+```sh
+adb shell cmd package query-activities --brief -a android.intent.action.VIEW \
+  -c android.intent.category.BROWSABLE -d 'https://tv.youtube.com'
+```
+
+A result of `com.google.android.tv.frameworkpackagestubs/.Stubs$BrowserStub` means "no app"
+(the TV shows "You don't have an app that can do this"). If the stub is listed alongside the
+app, the app usually still opens, but its own scheme (if it has one) avoids the ambiguity.
+
+## Safety design
+
+- **Keys are an allow-list.** The tool schema is an enum, and the client re-checks it.
+  `POWER`, `SEARCH` (starts voice capture), `SETTINGS`, `MUTE` (Android's *microphone*
+  mute), raw numeric key codes, and the library's `text:` typing are not available.
+- **Apps are an allow-list.** Only names in `list_apps` can be launched.
+- **No shell and no arbitrary key codes**, so a prompt-injected model has a small blast
+  radius. ADB is off by default. When enabled, the ADB tools take no arguments and run only
+  constant commands (`dumpsys media_session`, `dumpsys bluetooth_manager`, `dumpsys input`,
+  `getprop sys.boot_completed`, `/proc/uptime`), plus ADB's own reboot service. Code that
+  tries any other command is refused, so nothing the model writes reaches the Shield's shell.
+- **`reboot_shield` is the only tool marked destructive**: it interrupts playback, so
+  clients should confirm with you first.
+- **Credentials are private** (`0600`) and never logged. Logs go to stderr because stdout
+  belongs to the MCP transport.
+- Tools carry titles and MCP annotations (`readOnlyHint`, `destructiveHint`,
+  `idempotentHint`, `openWorldHint`) so clients can decide what needs confirmation.
+
+## Behavior notes
+
+- The server keeps **one long-lived connection** and caches pushed state. If the Shield is
+  asleep or offline at startup it retries in the background (1 s doubling to 60 s), and tool
+  calls return a clear "can't reach the Shield" message in the meantime. Each attempt is
+  bounded (15 s), so a Shield that accepts the connection but never starts a session can't
+  hang the server.
+- **While disconnected, `get_status` still shows the last known values**, marked
+  `stale: true`, with `as_of` (when they arrived) and `error` (why it isn't reachable).
+- **If the Shield moves to another address** (DHCP), after 60 s unreachable the server looks
+  for it over mDNS and checks each candidate's certificate for the MAC that `pair` saved. Only
+  an exact match is adopted, and saved to `config.json`. Any other device is never guessed at.
+- **If the Shield stops trusting the certificate** (unpaired on the TV, factory reset), the
+  error says to re-run `pair`, and the running server picks up the new pairing by itself.
+- Volume keys act on whatever the Shield is configured to control (the Shield itself, HDMI-CEC,
+  or IR), so results depend on your setup. When volume goes to a TV or receiver over CEC, the
+  Shield doesn't report a level, and `get_status` returns `volume: null`.
+
+## Troubleshooting
+
+The server's errors are written to be actionable, so the model will usually relay one of
+these:
+
+**"Not paired with a Shield yet."** No host or credentials were found. Run
+`mcp-server-shieldtv pair`. If you did pair, check that the server and `pair` use the same
+`SHIELDTV_CONFIG_DIR` (an MCP client may launch the server with a different environment).
+
+**"The Shield rejected our pairing."** The Shield no longer trusts this certificate,
+typically after a factory reset or after removing the device under the Shield's
+remote/connected-device settings. Run `pair` again; a running server reconnects by itself.
+
+**"Can't connect: the pairing files ... can't be used."** `cert.pem` or `key.pem` is
+damaged. Run `pair` again; it sets the old files aside.
+
+**"Can't reach the Shield at ..."** The server is paired but has no connection. The Shield
+may be asleep, rebooting, or off the network, its IP may have changed (a DHCP reservation
+helps), or TCP 6466 may be blocked (see the port table above). The server keeps retrying in
+the background, so the next call may succeed without a restart. If the address changed and
+`config.json` has the Shield's `mac` (saved by `pair` since this version), the server finds
+it again by itself; otherwise re-pair with the new address. `doctor` tells these cases apart.
+
+**"The connection to the Shield dropped; try again in a moment."** The connection closed
+during the command. The library reconnects on its own; retry.
+
+**"The Shield rejected the launch request ..."** The app entry is a bare package name (or a
+link the Shield refuses). Use an https link; see [Apps](#apps).
+
+**"The Shield accepted ..., but the foreground app didn't change"** The app is probably not
+installed, or nothing on the Shield handles that link. A very slow cold start can also do
+this; the next call then reports the app as already open.
+
+**`pair` says "No input to read the code from".** It was run without a terminal (for
+example through a tool that doesn't attach one). Run it in a regular terminal.
+
+**`discover` (or `pair` without `--host`) finds nothing.** mDNS doesn't cross most VLANs or
+guest networks, and on WSL2 it needs mirrored networking (see above). Pass `--host <ip>`;
+the Shield shows its IP in its network/about settings, and your router's client list has
+it too.
+
+Server logs (connection attempts, retries, auth failures) go to stderr, which most MCP
+clients save in their own logs. Running `mcp-server-shieldtv` in a terminal shows them
+directly; it waits for MCP messages on stdin, so stop it with Ctrl+C.
+
+## A session against the simulator
+
+`simulate` runs a **simulated Shield**: TLS on two ports, speaking Android TV Remote v2 the way
+androidtvremote2 does. The real library pairs and connects with it. Pair with it exactly as
+with a real one (the code "on the TV" is printed by the simulator), or pass `--paired`:
+
+```
+$ mcp-server-shieldtv simulate --config-dir /tmp/sim        # terminal 1
+  ...
+  The TV shows the pairing code: 3B26B3
+
+$ export SHIELDTV_CONFIG_DIR=/tmp/sim                         # terminal 2
+$ mcp-server-shieldtv pair --host 127.0.0.1
+Pairing with SHIELD Android TV (00:04:4B:A1:B2:C3). A code will appear on the TV screen.
+Enter the code shown on the TV: 3B26B3
+Paired and connected: NVIDIA SHIELD Android TV
+
+$ mcp-server-shieldtv call launch_app app=netflix
+{ "shield": "SHIELD Android TV", "outcome": "done",
+  "detail": "Launched netflix (com.netflix.ninja is in the foreground)",
+  "sent": ["app_link https://www.netflix.com/title"], "warnings": [] }
+
+$ mcp-server-shieldtv call set_power state=off
+{ ..., "outcome": "done", "detail": "The Shield is in standby", "sent": ["KEYCODE_SLEEP"] }
+
+$ mcp-server-shieldtv call set_power state=off
+{ ..., "outcome": "unchanged", "detail": "The Shield is already in standby", "sent": [] }
+
+$ mcp-server-shieldtv call launch_app app=hulu
+Error executing tool launch_app: The Shield accepted https://www.hulu.com/welcome, but the
+foreground app didn't change within 10s (still com.netflix.ninja). The app may not be
+installed, or no installed app handles that link; the TV may be showing an error. The Shield
+is in standby, which may be why: wake it with set_power first.
+```
+
+(Lines wrapped, some fields elided with `...`.) What the simulator does and where each behavior
+comes from (the library's client code, the owner's Shield, or invented for a test) is listed
+at the top of `src/shieldtv_mcp/sim/fake_shield.py`.
+
+## Development
+
+```sh
+pip install -e ".[dev]"
+pytest -q           # ~200 tests, ~15 s, no Shield needed
+ruff check . && ruff format --check .
+mypy                # strict type checking of src/
+```
+
+| Tests | Cover |
+|---|---|
+| `test_config.py` | Allow-lists (checked against the protocol's own key enum), settings, config problems |
+| `test_client.py` | Connection lifecycle and state against `FakeRemote`, a stand-in for the library |
+| `test_wire.py` | The real library against the simulated Shield: pairing (typo, rejection, Cancel, Shield gone), session, drops, garbled frames, sleep, stale state, unpairing, re-pair pickup, an address change (127.0.0.2 to .3) |
+| `test_tools.py`, `test_resources.py` | The MCP contract: schemas, annotations, ActionResults, errors, dry run, resources, prompts |
+| `test_adb.py` | ADB parsers on real dumpsys output; only constant commands reach the shell |
+| `test_tooling.py`, `test_cli.py` | `doctor`, `simulate`, `call`, argument parsing |
+| `test_http_tools.py`, `test_remote.py` | Streamable HTTP end to end; Access JWTs (valid, expired, wrong audience, wrong issuer, missing) with locally generated keys |
+| `test_stdio.py` | The installed entry point over stdio |
+| `test_assumptions.py` | Every assumption is cited by code, and listed here and in HARDWARE_VALIDATION.md |
+
+CI runs it all on Python 3.11-3.14, plus the Alpine smoke test.
+`npx @modelcontextprotocol/inspector mcp-server-shieldtv` browses tools, resources and prompts
+by hand. [docs/ADB_TOOLS.md](https://github.com/SDNick484/mcp-server-shieldtv/blob/main/docs/ADB_TOOLS.md) reviews the ADB tools and proposes read-only
+additions (design only).
+
+## Verification status
+
+Hardware-verified means seen on the owner's Shield (what was seen is in each assumption's
+`note` in `src/shieldtv_mcp/assumptions.py`). Simulator-only means the simulator implements
+it and nothing has confirmed it.
+
+| Assumption | Confidence | Status |
+|---|---|---|
+| `S-PAIRING` | high | hardware-verified |
+| `S-REMOTE-HANDSHAKE` | high | hardware-verified |
+| `S-TLS-REJECT` | medium | simulator-only |
+| `S-CERT-MAC` | medium | simulator-only |
+| `S-MDNS` | high | simulator-only |
+| `S-RECONNECT` | high | hardware-verified |
+| `S-SLEEP-CONNECTION` | medium | simulator-only |
+| `S-MARKET-REJECT` | high | hardware-verified |
+| `S-LINK-UNHANDLED` | high | hardware-verified |
+| `S-WAKE-ANY-KEY` | high | hardware-verified |
+| `S-CEC-VOLUME` | high | hardware-verified |
+| `S-APP-LINKS` | high | hardware-verified |
+| `S-DUMPSYS-MEDIA` | high | hardware-verified |
+| `S-LIVE-TV-PACKAGES` | medium | simulator-only |
+| `S-STUCK-REMOTES` | high | hardware-verified |
+| `S-REBOOT-TIME` | high | hardware-verified |
+
+`test_assumptions.py` fails if this table and `assumptions.py` disagree.
+
+## Roadmap
+
+- Hardware validation of this branch ([HARDWARE_VALIDATION.md](https://github.com/SDNick484/mcp-server-shieldtv/blob/main/HARDWARE_VALIDATION.md))
+- The ADB proposals in [docs/ADB_TOOLS.md](https://github.com/SDNick484/mcp-server-shieldtv/blob/main/docs/ADB_TOOLS.md), once their outputs are captured
+- Several Shields from one server, by name (as the sibling servers do)
+- Publish to PyPI and the MCP registry
+
+## License
+
+MIT. See [LICENSE](https://github.com/SDNick484/mcp-server-shieldtv/blob/main/LICENSE).