mcp-server-pixelcade 0.1.0__py3-none-any.whl

mcp_server_pixelcade-0.1.0.dist-info/METADATA

@@ -0,0 +1,321 @@
+Metadata-Version: 2.4
+Name: mcp-server-pixelcade
+Version: 0.1.0
+Summary: MCP server for Pixelcade LED marquees and Pixelcade Pulse lighting, via the pixelweb REST API
+Author: Nicholas E. Andrade
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/SDNick484/mcp-server-pixelcade
+Project-URL: Issues, https://github.com/SDNick484/mcp-server-pixelcade/issues
+Project-URL: Changelog, https://github.com/SDNick484/mcp-server-pixelcade/blob/main/CHANGELOG.md
+Keywords: mcp,mcp-server,pixelcade,arcade,batocera,led-marquee
+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 :: Games/Entertainment :: Arcade
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyjwt[crypto]>=2.10
+Requires-Dist: uvicorn>=0.31
+Requires-Dist: typing_extensions>=4.7
+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"
+Dynamic: license-file
+
+# mcp-server-pixelcade
+
+An [MCP](https://modelcontextprotocol.io) server for **[Pixelcade](https://pixelcade.org) LED marquees**
+and **Pixelcade Pulse** lighting (WS2812B strips, speaker rings and matrices on a V2 board). It lets an
+MCP client such as Claude show game and system marquees, scroll text, run arcade-themed clocks and other
+widgets, and drive Pulse lighting effects.
+
+> **Status: early, tested on hardware except Pulse.** On a real V2 board (pixelweb 8.0.17, Batocera 43)
+> every marquee, text, widget and frontend tool has been checked, plus dry run; Pulse waits for strips. See
+> [HARDWARE_VALIDATION.md](https://github.com/SDNick484/mcp-server-pixelcade/blob/main/HARDWARE_VALIDATION.md) and the [verification table](#verification-status).
+
+This is not an official Pixelcade project.
+
+## How it works
+
+The Pixelcade installer runs **pixelweb**, a small HTTP listener, on the arcade host (on Batocera:
+`/userdata/system/pixelcade/pixelweb`, port 8080, started from `/userdata/system/custom.sh`). Pixelweb
+drives the marquee over USB and exposes a [REST API](https://pixelcade.org/developers). This server is a
+typed, allow-listed client for that API, so it can run anywhere that can reach the arcade on TCP 8080:
+your desktop, a laptop, or a homelab VM. Clients reach it over stdio, or over Streamable HTTP as a
+service behind Cloudflare Access ([Service and Cloudflare](#service-and-cloudflare)).
+
+```
+MCP client ──stdio──▶ mcp-server-pixelcade ──HTTP :8080──▶ pixelweb (Batocera) ──USB──▶ V2 board ─▶ LED panels
+                                                                                              └──▶ Pulse strips
+```
+
+## Install
+
+```sh
+python -m venv ~/.venvs/pixelcade && . ~/.venvs/pixelcade/bin/activate
+pip install mcp-server-pixelcade
+```
+
+From source instead (for the newest code, or to run the tests):
+
+```sh
+git clone https://github.com/SDNick484/mcp-server-pixelcade.git && cd mcp-server-pixelcade
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]" && pytest
+```
+
+Requires Python 3.11+. Then check that pixelweb answers:
+
+```sh
+PIXELCADE_URL=192.168.1.20 mcp-server-pixelcade doctor
+```
+
+`doctor` checks each layer (TCP, `/info`, the frontend's current game, Pulse) and, when one fails, says
+what to try and which [HARDWARE_VALIDATION.md](https://github.com/SDNick484/mcp-server-pixelcade/blob/main/HARDWARE_VALIDATION.md) step covers it. It changes nothing
+on the marquee. It ends with the [assumptions](#verification-status) that hardware contradicted (listed; the code
+no longer relies on them) and a count of those not yet confirmed; `doctor --verbose` lists those too, and
+`doctor --json` always includes both lists.
+
+### Trying it without the arcade
+
+```sh
+mcp-server-pixelcade simulate --write-config /tmp/pxsim     # a fake pixelweb; prints every request it gets
+export PIXELCADE_CONFIG_DIR=/tmp/pxsim                      # in another terminal
+mcp-server-pixelcade doctor
+mcp-server-pixelcade call show_text text="GAME NIGHT" color=cyan   # one tool call, as the model makes it
+mcp-server-pixelcade call --dry-run blank_display                  # reports the GET it would send
+```
+
+### On Alpine (e.g. a Proxmox LXC)
+
+`deploy/alpine/` installs it on an always-on Alpine machine on the same LAN as the arcade, in the
+sibling servers' `deploy/alpine/` layout so they can share an LXC: a venv in `/opt/mcp-server-pixelcade`,
+a `mcp-pixelcade` system user, every setting in `/etc/mcp-server-pixelcade/env`, an OpenRC service
+(`/etc/init.d/mcp-server-pixelcade`), and `mcp-server-pixelcade` on `PATH`, which runs as that user with
+those settings, for `doctor` and `call` from a shell.
+
+```sh
+git clone https://github.com/SDNick484/mcp-server-pixelcade.git && cd mcp-server-pixelcade
+sh deploy/alpine/install.sh                                # as root; re-run to upgrade
+vim /etc/mcp-server-pixelcade/env                          # PIXELCADE_URL=<the arcade's IP>
+mcp-server-pixelcade doctor
+mcp-server-pixelcade call show_text text="GAME NIGHT" color=cyan
+rc-update add mcp-server-pixelcade default && rc-service mcp-server-pixelcade start
+```
+
+A variable set in your shell beats the env file, so one-off overrides work as usual
+(`PIXELCADE_DRY_RUN=1 mcp-server-pixelcade call ...`). mcp-server-batocera's
+`deploy/alpine/setup-arcade.sh` installs both arcade servers in a Proxmox container in one go, and
+enables and restarts both services. CI runs `deploy/alpine/smoke-test.sh` in a stock
+`python:3.12-alpine` container: install, upgrade, the test suite on musl, `doctor` and `call` through the
+command on `PATH` against the simulator, and the OpenRC service (as its user, an MCP call over HTTP,
+Access settings from the env file).
+
+### Service and Cloudflare
+
+The service runs `/opt/mcp-server-pixelcade/run.sh serve --http` under `supervise-daemon` (restarted if
+it exits) as `mcp-pixelcade`, logging to `/var/log/mcp-server-pixelcade/server.log`. The HTTP transport
+is `remote.py`, shared byte for byte with the sibling servers through
+[mcp-server-shared](https://github.com/SDNick484/mcp-server-shared). Its settings are the `MCP_HTTP_*`,
+`MCP_PUBLIC_HOSTS` and `CF_ACCESS_*` lines in `/etc/mcp-server-pixelcade/env`:
+
+| Flag | Variable | Default |
+| --- | --- | --- |
+| `--bind` | `MCP_HTTP_BIND` | `127.0.0.1` |
+| `--port` | `MCP_HTTP_PORT` | `8718` (the siblings use 8711 to 8716, Batocera 8717) |
+| `--path` | `MCP_HTTP_PATH` | `/pixelcade/mcp` |
+| `--public-host` | `MCP_PUBLIC_HOSTS` | none: only loopback Host headers pass |
+| | `CF_ACCESS_TEAM_DOMAIN`, `CF_ACCESS_AUD` | none: serves only this machine |
+| | `MCP_ALLOWED_EMAILS` | anyone Access lets in |
+
+With Access configured, every request needs a valid Access assertion, checked here: signature (Access's
+published keys), the application's audience tag, issuer, expiry, and the email allow-list if set; anything
+else gets a plain 403. Without Access it serves only the machine it runs on: it won't listen on anything
+but loopback, won't start with a `--public-host`, and answers 403 to anything a tunnel or proxy forwarded
+(`--insecure-no-auth` turns that off for a short trusted-LAN test; don't run the service with it).
+
+To use it as a connector, with cloudflared running on the same machine (keep the `127.0.0.1` bind):
+
+1. **Tunnel route:** a public hostname, say `mcp.example.com`, path `pixelcade/*`, to
+   `http://localhost:8718`. Several servers can share the hostname, one path each.
+2. **Access application** (self-hosted) covering that hostname and path, with a policy for who may use it
+   and Managed OAuth turned on, so Claude's connector can sign in through Access. Note its AUD tag.
+3. **The env file:** `MCP_PUBLIC_HOSTS=mcp.example.com`, `CF_ACCESS_TEAM_DOMAIN=<team>.cloudflareaccess.com`,
+   `CF_ACCESS_AUD=<the AUD tag>`, then `rc-service mcp-server-pixelcade restart`.
+4. **The connector:** `https://mcp.example.com/pixelcade/mcp`.
+
+`GET /healthz` answers without auth, for monitoring. Details are in `src/pixelcade_mcp/remote.py`.
+
+## Use it with an MCP client
+
+```json
+{
+  "mcpServers": {
+    "pixelcade": {
+      "command": "/path/to/mcp-server-pixelcade/.venv/bin/mcp-server-pixelcade",
+      "env": { "PIXELCADE_URL": "192.168.1.50" }
+    }
+  }
+}
+```
+
+For Claude Code: `claude mcp add pixelcade -e PIXELCADE_URL=192.168.1.50 -- /path/to/.venv/bin/mcp-server-pixelcade`.
+
+Running as a service behind Cloudflare Access instead, add `https://<your host>/pixelcade/mcp` as a
+connector ([Service and Cloudflare](#service-and-cloudflare)).
+
+## Configuration
+
+| Setting                          | Default                               | What it does                                                   |
+| -------------------------------- | ------------------------------------- | -------------------------------------------------------------- |
+| `PIXELCADE_URL`                  | `http://batocera.local:8080`          | Where pixelweb listens. A bare host or IP gets `http://` and `:8080` |
+| `PIXELCADE_PULSE_MAX_BRIGHTNESS` | `128`                                 | Highest Pulse brightness/intensity the model may set (0-255)   |
+| `PIXELCADE_TIMEOUT`              | `10`                                  | Seconds to wait for pixelweb (1-60)                            |
+| `PIXELCADE_CONFIG_DIR`           | `$XDG_CONFIG_HOME/mcp-server-pixelcade` | Where an optional `config.json` lives                        |
+| `PIXELCADE_NAME`                 | pixelweb's URL                        | How results name the marquee                                   |
+| `PIXELCADE_DRY_RUN`              | off                                   | Read pixelweb, change nothing (`serve --dry-run`)              |
+| `PIXELCADE_LOG_UNREDACTED`       | off                                   | Show LAN addresses in logs (`--no-redact`); secrets stay hidden |
+| `PIXELCADE_DEBUG`                | off                                   | Debug logging (`--debug`)                                      |
+
+`config.json` can hold the same settings as `url`, `pulse_max_brightness`, `timeout_s`, `name` and `dry_run`; environment
+variables win. `.local` names need mDNS, which usually doesn't cross VLANs or work in WSL2 without
+mirrored networking. A DHCP reservation plus the IP address is the dependable choice.
+
+## Tools
+
+All tools use the `pixelcade_` prefix to eliminate namespace collisions with sibling MCP servers in multi-server agent environments. The CLI supports shorthand names (`call show_text` resolves to `pixelcade_show_text`).
+
+| Tool                             | What it does                                                                                   |
+| -------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `pixelcade_get_status`           | Reachability, hardware/firmware/software versions, the frontend's selected game, Pulse state   |
+| `pixelcade_list_artwork`         | The marquees in one folder (a system, `console`, `animations`, `user`): names, still/animated |
+| `pixelcade_list_pulse_effects`   | Pulse effect names by category, per-game/per-system name patterns, and zone names              |
+| `pixelcade_show_game_marquee`    | A game's marquee by system + ROM name; still/animated choice, optional queueing and fallback text |
+| `pixelcade_show_console_marquee` | A system marquee, e.g. `snes`                                                                   |
+| `pixelcade_show_current_game`    | Put back the marquee for the game selected in EmulationStation                                  |
+| `pixelcade_show_default_marquee` | Pixelcade's default marquee (needs pixelweb 8.0.14+)                                            |
+| `pixelcade_show_text`            | Scrolling or fixed text: color, speed, loops, 1/2/4 lines, blink, left-justify                  |
+| `pixelcade_play_animation`       | One of Pixelcade's built-in animations                                                         |
+| `pixelcade_show_widget`          | Clock (19 arcade themes), weather, stocks, sports scores, or the attract-mode playlist          |
+| `pixelcade_stop_widgets`         | Stop widgets/attract mode and return to arcade mode                                            |
+| `pixelcade_blank_display`        | Black screen                                                                                   |
+| `pixelcade_pulse_effect`         | Run an effect on a Pulse zone (`rainbow`, `fire`, `mame_pacman`, …) with colors, speed, loops   |
+| `pixelcade_pulse_fill`           | Solid color on a zone                                                                          |
+| `pixelcade_pulse_clear`          | Turn off one zone, or all LEDs                                                                 |
+| `pixelcade_set_pulse_brightness` | Overall Pulse brightness, up to the server's cap                                               |
+
+**The frontend drives the marquee too.** EmulationStation's Pixelcade hooks call pixelweb whenever you
+scroll to a system or game, and every game launch calls `/attract/stop`. So whatever the model shows
+lasts until the next frontend event. `show_current_game` restores the frontend's marquee, and
+`show_default_marquee` shows the default one.
+
+**Locks.** `show_widget(lock=true)` sends `?nointerrupt`, which Pixelcade documents as preventing
+interruption by *other API calls*, this server's included, until `stop_widgets` or a game launch.
+Pixelcade's Batocera screensaver hooks do the same: the screensaver starts attract mode with
+`?nointerrupt` and ends it with `/attract/stop`. So while the screensaver runs, marquee calls succeed
+but change nothing (PX-ATTRACT-LOCK); `stop_widgets` releases the lock.
+
+**Pixelcade 8.x.** Pixelweb 8 is mostly about Sidekick companion displays; the API this server uses is
+unchanged. It adds `/defaultmarquee` (8.0.14, PX-DEFAULT-MARQUEE), and a companion-app setting to show
+static PNG marquees only, which may override `show_game_marquee(animation="animated")`. `doctor` shows
+the pixelweb version and notes when it's too old for `show_default_marquee`.
+
+**Names:** `system` is the Batocera ROM folder name (`mame`, `fbneo`, `snes`, …) and `rom` is the file
+name without its extension (`pacman`, `Super Mario World (USA)`), the same values Batocera's own hook
+scripts send.
+
+Every tool that changes the display returns the same structured result as the sibling servers:
+
+```json
+{ "pixelcade": "Arcade marquee", "outcome": "done", "detail": "Showing the text",
+  "sent": ["GET /text?t=GAME%20NIGHT&c=cyan"], "warnings": [] }
+```
+
+`outcome` is `done` or `dry_run`; `sent` is the exact GET (or, in a dry run, the one it would send).
+
+## Safety design
+
+- **Namespace isolation.** Every tool is prefixed with `pixelcade_` to eliminate collision with other MCP servers in multi-server configurations.
+- **Hardware Rate Limiting.** Commands are regulated via TokenBucket rate limiters:
+  - USB serial queue protection (burst 6, refill 2/s) prevents buffer overruns on the V2 board.
+  - High-draw Pulse LED protection (burst 3, refill 0.5/s) prevents thermal and current overload.
+- **Network topology & PII masking.** Network URLs and IP addresses are masked (e.g. `http://x.x.x.50:8080`) in tool outputs, logs, and error messages via `mcp_shared.logsafe`.
+- **A fixed set of endpoints.** Paths are built in `server.py` from constants plus validated arguments.
+  Pixelweb also serves `/quit`, `/reboot`, `/shutdown`, `/arcade/write` (writes the marquee's SD card),
+  `/upload`, `/settings`, `/update/*` and `/ledstrip/numpixels`; none are reachable through this server.
+- **Arguments can't become other URLs.** Each model-supplied path value must be a single segment (no
+  `/`, `\`, `.`/`..` or control characters) and is then percent-encoded, `/` included. Zones, colors,
+  tickers and team codes are validated; effect names must match a strict pattern.
+- **A Pulse brightness cap**, 128 by default. Each WS2812B LED can draw 60 mA at full white, and Pixelcade
+  warns that powering more than about 40 LEDs from the V2 board without an external 5V supply (with a
+  common ground) can overload it. Raise `PIXELCADE_PULSE_MAX_BRIGHTNESS` once your strips have their own
+  supply. The firmware's own thermal throttling (55/60/65 °C) is a backstop, not a plan.
+- **Pixelweb has no authentication**, so anything on your LAN can already call every endpoint. Keep port
+  8080 off the internet. Over HTTP, this server is the gate: Access assertions are checked on every
+  request, and without Access it serves only its own machine ([Service and Cloudflare](#service-and-cloudflare)).
+- Tools carry titles and MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`,
+  `openWorldHint`). Nothing is marked destructive: every display change is undone by the next one.
+- Structured XML docstrings (`<use_case>` and `<important_notes>`) guide models on tool preconditions, display lifetimes, and routing.
+- Errors are actionable ("pixelweb isn't answering at …", "Can't resolve batocera.local; set
+  PIXELCADE_URL to the IP"), and logs go to stderr because stdout belongs to the MCP transport.
+
+## Verification status
+
+Every pixelweb behavior the code relies on is listed in `src/pixelcade_mcp/assumptions.py`, with its
+source and how sure we are; the code cites each id where it depends on it, and
+[HARDWARE_VALIDATION.md](https://github.com/SDNick484/mcp-server-pixelcade/blob/main/HARDWARE_VALIDATION.md) has the step that confirms it. *high* means documented
+and used the same way by Pixelcade's own scripts; *medium* means documented only; *low* means our own
+guess. Hardware results so far are from pixelweb 8.0.17 on a V2 board (2026-10-22).
+
+| Assumption | Confidence | Status |
+|---|---|---|
+| `PX-GET-API` | high | hardware-verified |
+| `PX-INFO` | medium | hardware-verified |
+| `PX-CURRENTGAME` | medium | hardware-verified |
+| `PX-LISTS` | low | hardware-contradicted |
+| `PX-IMAGES-LIST` | high | hardware-verified |
+| `PX-REPLIES` | low | hardware-verified |
+| `PX-TEXT` | medium | hardware-verified |
+| `PX-QUEUE` | medium | hardware-verified |
+| `PX-HOLD` | medium | hardware-verified |
+| `PX-FRONTEND` | high | hardware-verified |
+| `PX-WIDGETS` | medium | hardware-verified |
+| `PX-ATTRACT-LOCK` | medium | hardware-verified |
+| `PX-DEFAULT-MARQUEE` | low | hardware-verified |
+| `PX-ZONES` | medium | simulator-only |
+| `PX-BRIGHTNESS` | medium | simulator-only |
+| `PX-POWER` | high | simulator-only |
+
+## Not yet included
+
+- Pulse **batch zone control**, **MAX7219** 7-segment/dot-matrix displays, and **mini LCD** (`/ministats`)
+  endpoints, which Pixelcade documents but this server doesn't wrap yet.
+- Editing the attract-mode playlist, and OAuth-backed widgets (Spotify, Plex, YouTube, Google Calendar).
+- Uploading custom artwork (`/upload`): useful, but it writes files on the arcade, so it should be opt-in.
+
+## Development
+
+```sh
+pip install -e ".[dev]"
+pytest              # validators, HTTP client, tools via an in-process MCP client, dry run, faults, CLI, stdio, HTTP + Access
+ruff check . && ruff format --check .
+mypy                # strict
+```
+
+Tests run against the wire-level fake pixelweb (`sim/fake_pixelweb.py`), which records each request's raw
+path, so the exact percent-encoding on the wire is asserted. To poke at the tools interactively:
+`npx @modelcontextprotocol/inspector mcp-server-pixelcade`.
+
+## License
+
+MIT. See [LICENSE](https://github.com/SDNick484/mcp-server-pixelcade/blob/main/LICENSE).

mcp_server_pixelcade-0.1.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+mcp_server_pixelcade-0.1.0.dist-info/licenses/LICENSE,sha256=UaFe7iKAtdvNfrhH4lJ-v0InFSbjZGMZ4dLXeVf7o8g,1076
+pixelcade_mcp/__init__.py,sha256=sM7Bai9XZ5pYv9JptQHjckyOIviVkdaN2LkOhmAU6Ng,318
+pixelcade_mcp/assumptions.py,sha256=b5HuqWkxZUqOqyfgmO2Bramh8SLowvZpV7zs7n7hq2A,13001
+pixelcade_mcp/cli.py,sha256=310N-OfdlzEXGj4JuP8S3Dw6D1QaIEq8Ri3a_s7u7TI,8886
+pixelcade_mcp/client.py,sha256=tScf43_hi4tSPlAqEmc7zgEJ-KWC3zHyRRaWS13cGEU,15045
+pixelcade_mcp/config.py,sha256=T3Mig3bMKXBkGs0XRmqTjC7inebRcVfbcx0alXnYYPc,10164
+pixelcade_mcp/doctor.py,sha256=tDxvDr39gqF9w27fjoRiCkyUE2lp3YEX1aU41JW66aE,7755
+pixelcade_mcp/effects.py,sha256=7XirNdfQwKgm9avoCfoJ33hEY0C_aKgAicEG1nZIBG0,4941
+pixelcade_mcp/limits.py,sha256=Gf0t_qp2B31Ch_Lrm9Lnx_BPxfn5L8bZfhL-g8gm5qE,1445
+pixelcade_mcp/logsafe.py,sha256=QuCitdXqckrLQSzb-V0R2pxFhLyqMhPSKQq7s3R97mI,15892
+pixelcade_mcp/lookup.py,sha256=TmP8Abg5drIKTzHZ928YJ8Sa1qSDmvymEhwnSQpun6s,2235
+pixelcade_mcp/ratelimit.py,sha256=aIhy8CAPMxJdEdlMvFCjUT8jElFKvb0QcrR8zxAB6Ps,9840
+pixelcade_mcp/registry.py,sha256=9JIwD7hYao7m6PWJXZDAiGQfd8dfGWIfruuAJYNFsUw,7027
+pixelcade_mcp/remote.py,sha256=v7d4C9Phz11hc9XsORMJ7VY-GO2GMrdfaa_gEU8b7s8,23958
+pixelcade_mcp/server.py,sha256=__2GRoSNayYdcbBPytvK8tYMFCyVYZZ1CJuPEh3hiR0,38556
+pixelcade_mcp/tasks.py,sha256=FttB8XI_evXjIJUyWz7rtjENQVhgTS6ZcbEB5v-crkc,7815
+pixelcade_mcp/tools.py,sha256=TlMObSXFMZst3ssGBrSwtS3WpjbAV0ngKfU5mnajWNU,1363
+pixelcade_mcp/sim/__init__.py,sha256=rtOXDNhwRl-DCbt4Lsf5qtLLJiqeNzty6tOrXZFP-vI,73
+pixelcade_mcp/sim/fake_pixelweb.py,sha256=nBo0JKWUN-dURNnLuXpTMULupY2GBHFXF4h7Biv83zQ,11285
+mcp_server_pixelcade-0.1.0.dist-info/METADATA,sha256=Mj2_pg3bY4LzjIA80X3MrYVsyg_6IH74vZwrzu59duI,19939
+mcp_server_pixelcade-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+mcp_server_pixelcade-0.1.0.dist-info/entry_points.txt,sha256=JEzBzxrdGTjJqTtd7LPVuDAi6mXCYUNvU2Z02ANg8cQ,64
+mcp_server_pixelcade-0.1.0.dist-info/top_level.txt,sha256=SOemg7JeEEDlB5WlfRr3YAYDmPk96CNPrLLKYPvGEZI,14
+mcp_server_pixelcade-0.1.0.dist-info/RECORD,,

mcp_server_pixelcade-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mcp_server_pixelcade-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-server-pixelcade = pixelcade_mcp.cli:main

mcp_server_pixelcade-0.1.0.dist-info/licenses/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_pixelcade-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pixelcade_mcp

pixelcade_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""MCP server for Pixelcade LED marquees (and Pixelcade Pulse lighting) via the pixelweb REST API."""
+
+# The one place the version lives: pyproject.toml reads it from here. Bump it for every release, since pip
+# keeps an installed copy whose version matches, even when the code under it changed.
+__version__ = "0.1.0"

pixelcade_mcp/assumptions.py

@@ -0,0 +1,230 @@
+"""Every pixelweb behavior this server relies on, and whether hardware has confirmed it.
+
+The same scheme as the sibling servers: each claim has an id that the code cites
+where it depends on it (``# ASSUMPTION PX-QUEUE``), that a test cites, that
+HARDWARE_VALIDATION.md cites in the step confirming it, that the README's
+verification table lists, and that ``mcp-server-pixelcade doctor`` prints while
+it's unconfirmed. tests/test_assumptions.py fails if they drift apart.
+
+Sources, read 2026-10: Pixelcade's API reference (pixelcade.org/developers), the
+Pulse page (pixelcade.org/pulse), the release notes (pixelcade.org/release-notes,
+through pixelweb 8.0.17), and Pixelcade's own Batocera hook scripts
+(github.com/alinke/pixelcade-linux, batocera/scripts/). Nothing has been seen on
+the owner's marquee yet. To record a result, set ``status`` to
+"hardware-verified" (or "hardware-contradicted"), say what you saw in ``note``.
+
+Confidence is about the *claim*, judged from its source:
+  high   - documented, and used the same way by Pixelcade's own scripts
+  medium - documented, but not used by anything we can read
+  low    - our own guess; the simulator implements it but nothing confirms it
+"""
+
+from __future__ import annotations
+
+from .registry import Assumption, Confidence, Status, by_id
+from .registry import contradicted as _contradicted
+from .registry import unverified as _unverified
+
+# Confidence and Status are re-exported (no_implicit_reexport): callers may need the literal types.
+__all__ = ["ASSUMPTIONS", "BY_ID", "Assumption", "Confidence", "Status", "contradicted", "unverified"]
+
+DOCS = "pixelcade.org/developers"
+SCRIPTS = "pixelcade-linux batocera/scripts"
+RELEASES = "pixelcade.org/release-notes"
+SEEN = "Seen 2026-10-22 on a V2 LED (firmware PIXR0023), pixelweb 8.0.17 on Batocera 43, from a Proxmox LXC: "
+
+
+ASSUMPTIONS: tuple[Assumption, ...] = (
+    Assumption(
+        "PX-GET-API",
+        "Every control is an HTTP GET on port 8080; options are query parameters, some of them bare flags "
+        "(?nogif, ?nointerrupt), and spaces in ROM names are sent as %20.",
+        f"{DOCS}; {SCRIPTS} (rawurlencode, curl)",
+        "high",
+        status="hardware-verified",
+        note=SEEN + "the marquee for 'Super Mario World 2 - Yoshi's Island (USA)' showed, sent as ...%20Yoshi%27s"
+        "%20Island%20%28USA%29; flags like ?nogif and scroll=false work. pixelweb matches artwork by exact name: "
+        "the ROM's '(USA) (Rev 1)' found nothing, so the default marquee showed.",
+    ),
+    Assumption(
+        "PX-INFO",
+        "/info returns JSON with type, resolution, v2board, firmwareVersion, softwareVersion, hasLEDStripSupport, "
+        "ledStrip, ledStripBrightness and ledStripNumPixels.",
+        f"{DOCS} (Device Information example)",
+        "medium",
+        status="hardware-verified",
+        note=SEEN + "every field present, plus many more: platform, arcadeFrontend 'Batocera', ledActive, "
+        "noAnimatedMarquees (the 8.x 'static PNG marquees only' setting, now in get_status), sidekick, "
+        "sidekick-ids, sidekick-models, sidekickOnly, centerMatrixResolution, isMiSTer, vestaboard*.",
+    ),
+    Assumption(
+        "PX-CURRENTGAME",
+        "/currentgame returns the last game or system marquee shown, by anyone (the frontend's hooks, the "
+        "screensaver, this server), as 'system%rom', or 'system%' after a system marquee; text and animations "
+        "don't change it. (The game-selected hook's comment says 'system,rom'.)",
+        f"{SCRIPTS} game-selected; {DOCS}; hardware",
+        "medium",
+        status="hardware-verified",
+        note=SEEN + "'neogeo%eightman' ('%', not a comma). It followed every marquee: scrolling gave "
+        "genesis%Old-Towers; show_text and play_animation left it; show_console_marquee snes made it 'snes%'; "
+        "show_game_marquee galaga made it mame%galaga. The claim used to say it was the frontend's selection; "
+        "it isn't, so the server remembers the frontend's itself (server._Marquees); in one session, Galaga "
+        "then show_current_game restored the frontend's gba/SpaceTwins. During the random-video "
+        "screensaver it changed with each video (mystwaru, eightman, circusc), so "
+        "the screensaver's game-selected events update it even while attract mode holds the marquee: after the "
+        "screensaver, it names the last video's game, not the user's selection.",
+    ),
+    Assumption(
+        "PX-LISTS",
+        "/arcade/list, /still/list and /animations/list return a list of names.",
+        DOCS,
+        "low",
+        status="hardware-contradicted",
+        note=SEEN + "all three answer 404 (so do the documented /list/image/<system>, /list/image/all and "
+        "/list/video, which may be LCD-only). list_artwork uses PX-IMAGES-LIST instead.",
+    ),
+    Assumption(
+        "PX-IMAGES-LIST",
+        'POST /api/images/list with the JSON body {"name": "<folder>"} lists /userdata/system/pixelcade/<folder> '
+        "as [{name, system, urlPath, imagePath}], name being a file name; a missing folder answers 400 (plain text "
+        "'open <path>: no such file or directory'), and an empty name answers null.",
+        "pixelweb's own web page (its artwork browser's script); checked on hardware",
+        "high",
+        status="hardware-verified",
+        note=SEEN + "mame: 12,415 files (10,291 PNG, 2,124 GIF; 2 MB of JSON in 0.07 s); animations: 702 PNG; "
+        "console, user and system folders too; 'still' has no folder. The one POST this server sends: a read. "
+        "Undocumented, so a pixelweb update could change it.",
+    ),
+    Assumption(
+        "PX-REPLIES",
+        'Controls answer 200 with an empty body (/defaultmarquee: {"status": "ok"}), even when the '
+        "artwork is missing; an endpoint this pixelweb doesn't have answers 404 '404 page not found'.",
+        "pixelweb is a Go net/http server; hardware",
+        "low",
+        status="hardware-verified",
+        note=SEEN + "every control call answered 200 with nothing in the body; /arcade/stream/mame/nosuchgame "
+        "answered 200 too, so a reply can't say whether artwork exists (list_artwork can). The claim used to "
+        "say 'a short body'.",
+    ),
+    Assumption(
+        "PX-TEXT",
+        "/text takes the message in t=, with line breaks as the literal two characters \\n, plus c=, s=, l=, "
+        "scroll=, lines=, blink= and left=.",
+        DOCS,
+        "medium",
+        status="hardware-verified",
+        note=SEEN + "color, two fixed lines from a literal \\n (sent %5Cn), blink on 'PLAYER 1', and four "
+        "left-justified lines all showed as documented. blink's 9-character limit is from the docs, not tried.",
+    ),
+    Assumption(
+        "PX-QUEUE",
+        "A call with l=N (N >= 1) joins a queue; a call without l interrupts and clears it. Queued calls from "
+        "scripts carry event=FEScroll.",
+        DOCS,
+        "medium",
+        status="hardware-verified",
+        note=SEEN + "a marquee queued with l=5&event=FEScroll played for about 5 s, then text queued with l=1 "
+        "scrolled once; blank_display (no l) interrupted.",
+    ),
+    Assumption(
+        "PX-HOLD",
+        "l=-1, documented as 'infinite until next command', shows text once and then the marquee goes blank; "
+        "l=99999 holds it until interrupted, and a plain call followed by the same call with l=99999 shows it "
+        "at once (the plain call interrupts and clears the queue) and holds it.",
+        f"{DOCS} (Looping & Queue System); hardware",
+        "medium",
+        status="hardware-verified",
+        note=SEEN + "text?t=HELLO&l=-1 showed once, then blank; HOLD ONE with l=99999 replaced Galaga and stayed; "
+        "the plain-then-l=99999 pair showed at once and stayed, and a long message sent the same way kept "
+        "scrolling for 30 s; scroll=false text stayed. Short text doesn't scroll (it fits). Held text stayed "
+        "until scrolling in the frontend replaced it. Not yet seen: the pair while the frontend's own l=99999 "
+        "game marquee holds the queue.",
+    ),
+    Assumption(
+        "PX-FRONTEND",
+        "EmulationStation's hooks call /console/stream/<system>/?event=FEScroll and "
+        "/arcade/stream/<system>/<rom>?event=FEScroll as you scroll (game-selected skips the call when the game "
+        "matches /currentgame), and /attract/stop then a queued marquee (l=99999&event=GameStart) on every game "
+        "launch, so whatever this server shows lasts until the next frontend event.",
+        f"{SCRIPTS} system-selected, game-selected, game-start",
+        "high",
+        status="hardware-verified",
+        note=SEEN + "scrolling in the frontend replaced held text; launching a game (through mcp-server-batocera) "
+        "ended a locked clock and showed the game's marquee. Hook scripts from pixelcade-linux (2026-06).",
+    ),
+    Assumption(
+        "PX-WIDGETS",
+        "/clock (clockType=, 12h=), /weather (location=), /stocks (tickers=), /sports[/<league>] (teams=) and "
+        "/attract show widgets; ?nointerrupt locks one in place (PX-ATTRACT-LOCK); /attract/stop ends them.",
+        DOCS,
+        "medium",
+        status="hardware-verified",
+        note=SEEN + "Galaga and Pac-Man clocks (12h=false too), weather (saved location and a ZIP), a stock ticker "
+        "and NFL scores all rendered, with no settings beyond the install. ?nointerrupt and /attract: step 5.",
+    ),
+    Assumption(
+        "PX-ATTRACT-LOCK",
+        "?nointerrupt locks the marquee: other API calls, this server's included, don't change it until "
+        "/attract/stop. Pixelcade's Batocera screensaver-start hook calls /attract?nointerrupt and "
+        "screensaver-stop calls /attract/stop, so while the cabinet's screensaver runs, the marquee shows the "
+        "attract playlist and ignores both the screensaver's game-selected events and this server.",
+        f"{DOCS} (attract mode: 'prevents interruption by other API calls'); {SCRIPTS} screensaver-start, "
+        "screensaver-stop",
+        "medium",
+        status="hardware-verified",
+        note=SEEN + "a clock shown with lock=true stayed through frontend scrolling, and show_text over it "
+        "answered 200 but didn't show. During the random-video screensaver the marquee stayed in attract mode, "
+        "didn't follow the videos and ignored show_text; after stop_widgets it followed the videos. Unknown: "
+        "whether queued (l=N) calls wait for the lock, and whether Pulse calls are locked too.",
+    ),
+    Assumption(
+        "PX-DEFAULT-MARQUEE",
+        "pixelweb 8.0.14 and later have GET /defaultmarquee, which shows the default marquee "
+        "(console/default-marquee.png) on the LED and LCD when called with no parameters; older versions answer 404.",
+        f"{RELEASES} (8.0.14); {DOCS} (default marquee path)",
+        "low",
+        status="hardware-verified",
+        note=SEEN + 'GET /defaultmarquee answered 200 {"status": "ok"} and showed the Batocera marquee (this '
+        "install's default). Only in the release notes, not the API reference; how it interacts with the queue "
+        "and the attract lock isn't known.",
+    ),
+    Assumption(
+        "PX-ZONES",
+        "Pulse zones are named (left_strip, right_strip, ...) or numbered 0-35; effects are "
+        "/ledstrip/zone/<z>/effect/<name>, fills /ledstrip/zone/<z>/flood, but clearing one zone is "
+        "/ledstrip/<z>/clear (no zone/ segment).",
+        f"{DOCS} (Pulse API)",
+        "medium",
+        note="The clear path's missing zone/ segment may be a documentation typo; check it first.",
+    ),
+    Assumption(
+        "PX-BRIGHTNESS",
+        "/ledstrip/brightness/<0-255> sets the strips' brightness and /ledstrip/getbrightness reads it back "
+        "from the board.",
+        f"{DOCS} (Pulse API)",
+        "medium",
+        note="Documented; needs strips connected to check. Seen 2026-10-22 with strips configured in pixelweb "
+        "(ledStrip true, 50 LEDs) but none connected: /ledstrip/getbrightness never answered (30 s), so get_status "
+        "and doctor wait only PULSE_STATUS_TIMEOUT_S (2 s) and report pulse.responding false.",
+    ),
+    Assumption(
+        "PX-POWER",
+        "Each WS2812B LED draws up to 60 mA at full white, and the V2 board can power only about 40 LEDs "
+        "itself; more needs an external 5 V supply with a common ground. Hence the default brightness cap of 128.",
+        "pixelcade.org/pulse (Powering and Safety)",
+        "high",
+        note="Pixelcade's own guidance. The cap is a safety margin, not a measured limit.",
+    ),
+)
+
+BY_ID = by_id(ASSUMPTIONS)
+
+
+def unverified() -> list[Assumption]:
+    """Not checked on hardware yet: the code relies on them on the strength of docs or source alone."""
+    return _unverified(ASSUMPTIONS)
+
+
+def contradicted() -> list[Assumption]:
+    """Checked on hardware and found wrong: the code no longer relies on them (see each ``note``)."""
+    return _contradicted(ASSUMPTIONS)