pebble-mcp 0.1.0__tar.gz

pebble_mcp-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.venv/

pebble_mcp-0.1.0/EMU-TESTING-SPEC.md

@@ -0,0 +1,84 @@
+# pebble-mcp — Emulator boot / manage / test-app tool spec
+
+What it takes to launch and drive a Pebble app in the emery emulator, distilled
+from doing it by hand across a full app build. This is the contract for the
+Tier-3 dev-loop tools that let an agent boot the emulator, install apps, drive
+them, and see the result. Honors TOOL-SURFACE.md.
+
+> **STATUS — implemented (2026-08-01).** The wiring "gap" this spec describes is
+> closed: all Tier-3 tools listed below are registered on the server
+> (`pebble_build`, `pebble_install`, `emu_start`, `emu_stop`, `emu_screenshot`,
+> `emu_input`, `emu_logs`, `flow_run`, `flow_validate`). The "Operational
+> knowledge to bake in" folklore is now infrastructure: button-press pacing
+> (`BUTTON_SETTLE_SEC`) and post-install settle (`POST_INSTALL_SETTLE_SEC`) are
+> baked into the flow driver and `emu_input`, so correctness no longer depends
+> on a flow author inserting waits. Kept as the design record. The two items
+> still deliberately unimplemented — auto kill+wipe recovery on *standalone* emu
+> tools (they surface a clear hint instead, to avoid destroying state the agent
+> may want), and hard serialization of the single emulator — are noted inline.
+
+## Current state (what exists vs. the gap)
+- `devloop.py` LIBRARY already has: `build()`, `install()` (kill+wipe-first),
+  `emu_start()`, `emu_stop(wipe=)`, `logs_capture()`, plus GCC-diagnostic parsing
+  and WEDGE_MARKERS.
+- `flow.py` LIBRARY already has the full driver: parse a flow spec, install, and
+  step through button/tap/wait/screenshot with wedge recovery.
+- MISSING in the library: `emu_screenshot()` and `emu_input()` (button/tap).
+- MISSING on the server: NONE of these are registered as MCP tools yet — the
+  server only exposes `capabilities()` + `pebble://platforms`. Wiring is the gap.
+
+## The launch/test loop (what "launch an app" actually requires)
+1. **Gate** on `capabilities().tier3_devloop` (pebble CLI on PATH, ~/.local/bin).
+   If absent, fail fast with the install hint — never a traceback.
+2. **Build** (optional): `pebble build` in a project dir → `build/<name>.pbw`.
+   Return structured diagnostics (already implemented).
+3. **Clean install**: `pebble kill` → `pebble wipe` → sleep ~3s →
+   `pebble install --emulator emery <pbw>`. The kill+wipe BEFORE install is
+   load-bearing — a persisted active app otherwise stays foreground and the new
+   app never launches. (Already baked into `install()`.)
+4. **Settle**: sleep ~6s after install for the app to fully render (some apps
+   load resources / animate).
+5. **Observe**: screenshot the current screen (native 200x228 PNG).
+6. **Drive**: send button/tap input, screenshot again, repeat.
+
+## Tools to add / wire (small surface, per TOOL-SURFACE.md)
+- `pebble_build(project_dir)` — wire `build()`. Structured errors.
+- `pebble_install(pbw_or_project)` — wire `install()` (kill+wipe baked in).
+- `emu_start()` / `emu_stop(wipe?)` — wire existing.
+- **`emu_screenshot()`** — NEW. `pebble screenshot --no-open <tmp>`; verify the
+  file is non-empty; return as an **MCP image content block** (agent sees it)
+  PLUS the saved path. This is the key tool for "testing".
+- **`emu_input(action, button?, duration_ms?)`** — NEW. Wraps
+  `pebble emu-button click <back|up|select|down>` (+ `--duration` for long-press)
+  and `pebble emu-tap`. Validate button against the enum.
+- `emu_logs(...)` — wire `logs_capture()` (bounded).
+- **`flow_run(flow_or_project)`** — wire `flow.py`'s `run_flow()`: install + step
+  a scripted flow, returning shots as image content + a contact sheet. This is
+  the one-call "test an app" payoff (roadmap C3).
+
+## Operational knowledge to BAKE IN (folklore → infrastructure)
+- **Button-press pacing:** the emery emulator DROPS TO THE WATCHFACE / desyncs on
+  rapid presses. `emu_input` must pace internally (~0.2-0.3s between presses) and
+  flow_run must space steps — never fire presses back-to-back.
+- **Wedge recovery:** output containing any WEDGE_MARKER ("not responding",
+  "no emulator", "failed to connect", "connection refused", "timed out") → the
+  emulator is wedged; run kill+wipe and retry the operation ONCE, then fail with
+  a clear message. (flow.py already does this; emu tools should too.)
+- **Screenshot capture is racy for animations:** a sub-second animation can't be
+  reliably sampled through screenshot latency. For animated content, expose an
+  optional per-frame step (or document capturing a slowed build) rather than
+  promising to catch a transient.
+- **Single emulator:** there is ONE QEMU instance. Serialize emulator-touching
+  tools (queue or fail clearly); never let two installs/screenshots interleave.
+- **Window vs headless:** launching surfaces a QEMU window on a local display
+  when one is available (the user can interact directly), and still screenshots
+  fine when headless. Don't assume either.
+- **Timings:** ~3s after wipe, ~6s after install, before the first screenshot.
+
+## Acceptance
+A fresh agent with the server configured can, in ≤ a few calls:
+1. build a project and report an actionable compile error,
+2. install it and SEE the launch screen (image content),
+3. press a button and see the screen change,
+4. run a multi-step flow and get back the screenshots + contact sheet —
+each degrading gracefully (named gate error) when the pebble CLI is absent.

pebble_mcp-0.1.0/LAUNCH.md

@@ -0,0 +1,171 @@
+# Launch checklist — get pebble-mcp on PyPI
+
+Your follow-along working doc. The community page's TODO is the public
+overview; **this** is the granular execution list. Check boxes as you go.
+
+**Legend**
+- 🟢 **Claude does it** — just say "go" and I'll do it (you review after).
+- 🔵 **You do it** — needs your account, credentials, or a decision only you can make.
+- ⏱ rough time.
+
+**This weekend's goal: get fully publish-READY and kick the tires — not publish.**
+Publishing (Steps 5–6) waits until you've tested enough to feel confident. So the
+plan is: I make everything publish-ready *in place* (no repo carve-out yet, so your
+testing environment stays intact), and you spend the weekend actually using it
+(see "Kick the tires" below). Pull the trigger on PyPI whenever you're ready.
+
+---
+
+## Step 0 — Decisions · 🔵 · ✅ DONE
+
+- [x] **License: MIT.**
+- [x] **Package name: `pebble-mcp`** (confirmed available on PyPI).
+- [x] **Authorship: Daniel Bonomo <d.z.bonomo@gmail.com>.**
+
+---
+
+## Kick the tires this weekend — get a feel for it · 🔵 · ⏱ as long as it's fun
+
+Do this from your **second terminal** (the MCP-connected one). **Restart that
+instance first** so it picks up all 23 tools — it connected when the server had
+only one. Then just talk to Claude naturally; these are prompts to try, grouped by
+tier. Jot down anything that feels wrong — that's exactly the feedback Phase 3 needs.
+
+**Tier 1 · Store (works even with no emulator):**
+- [ ] "Search the Pebble store for weather watchfaces that run on my Time 2."
+- [ ] "Show me the most-loved watchfaces — which ones include weather?"
+- [ ] "Compare Hubble against another astronomy app: hearts, platforms, size."
+- [ ] "Download the Hubble pbw so we can try it."
+
+**Tier 2 · Design (the fun, visual one — works anywhere, even claude.ai):**
+- [ ] "What's the nearest Pebble color to #3b82f6? Is it legible on black?"
+- [ ] "Quantize this image to the Pebble 64-color palette." *(drop in a logo/photo)*
+- [ ] "Prep this image as a 25×25 launcher menu icon."
+- [ ] "Make me a swatch of the coach app's accent colors."
+- [ ] "Which font for a big clock numeral? Give me the characterRegex for `15:37`."
+- [ ] "Convert this SVG to PDC." *(try one with a curve — watch it refuse honestly)*
+
+**Tier 3 · Dev loop (uses your local `pebble` CLI):**
+- [ ] "Run a screenshot flow on hail-watch and show me the frames."
+- [ ] "Build coach-workout and tell me about any warnings."
+- [ ] "Install Hubble in the emulator and screenshot the moon screen."
+- [ ] "Screenshot whatever's on the emulator right now."
+
+**Resources (reference data the model can pull):**
+- [ ] "Read the pebble://colors resource — what are the role colors?"
+- [ ] "Show me the wire-format conventions from pebble-mcp."
+
+**Try to break it / find rough edges (this is the valuable part):**
+- [ ] Give a vague request ("make my watchface art Pebble-ready") and see if Claude
+      picks the right tool from the descriptions alone.
+- [ ] Feed junk: a corrupt image, a nonsense color, a 10,000-character search.
+- [ ] Note **any** moment Claude picks the wrong tool, an error message confuses
+      you, or you expected a tool that doesn't exist. Add it to
+      `pebble-mcp/TOOL-SURFACE.md` (your other terminal already started that doc).
+
+---
+
+## Step 0-decisions are done. The rest below is the ready-then-publish path.
+
+---
+
+## Step 1 — Make it publish-ready in place (decouple from the monorepo) · 🟢 · IN PROGRESS
+
+Doing this now, *without* carving out a separate repo yet — so your testing
+environment stays a single tree all weekend. The physical carve-out + GitHub push
+becomes a mechanical step at publish time (Step 5b), because after this the
+package has no monorepo coupling left.
+
+- [ ] 🟢 **Break the monorepo coupling:** `tests/test_flow.py` reads the flow
+      specs from `../tools/flows/`. Vendor those `.flow` files into the package
+      (`pebble_mcp/examples/flows/`) and repoint the test — verified by running
+      pytest on a copy of the package alone, outside the repo.
+- [ ] 🟢 Genericize the last coach/hail mentions in `tools_flow.py` / `devloop.py`
+      docstrings (public repo hygiene; safety wording stays).
+- [ ] 🟢 Confirm no personal leaks (`btf4e`, `dbonomo`, `/media/`, `trainer`).
+
+### Step 5b (deferred to publish day) — carve out & push · 🔵
+- [ ] Create the empty **public** GitHub repo `pebble-mcp` (no README/license — we
+      bring our own). Copy the now-self-contained `pebble-mcp/` dir into it; I'll
+      give you the exact `git init` + `remote add` + `push`.
+
+---
+
+## Step 2 — Packaging metadata · 🟢 · ⏱ 20 min
+
+- [ ] 🟢 Add the `LICENSE` file (once you've picked one in Step 0).
+- [ ] 🟢 Fill out `pyproject.toml`: `description`, `authors`, `license`,
+      `keywords`, `classifiers` (Python 3.13, MCP, License, OS), `readme`,
+      `requires-python = ">=3.13"`, and `[project.urls]` (Homepage / Repository
+      / Issues).
+- [ ] 🟢 Verify the build: `uv build` produces an sdist + wheel, and
+      `uvx --from ./dist/pebble_mcp-*.whl pebble-mcp` boots from the wheel alone.
+
+---
+
+## Step 3 — README · 🟢 · ⏱ 20 min
+
+- [ ] 🟢 Write `README.md`: one-paragraph what-it-is, the four tiers, the `uvx`
+      config snippet, a quickstart per host (Claude Code / Desktop), the
+      `capabilities()` note, license, and the "not affiliated with Core
+      Devices/Rebble" line.
+- [ ] 🟢 Embed the demo GIF from Step 4 at the top.
+
+---
+
+## Step 4 — The demo GIF · 🟢 (needs the local emulator) · ⏱ 20 min
+
+- [ ] 🟢 Run the Hubble store→screenshot flow through `flow_run` and assemble the
+      captured frames into an animated GIF. **This is the single most convincing
+      launch artifact** — it's what earns the retweet.
+- [ ] 🟢 Drop it in the repo (`docs/demo.gif`) and wire it into the README + the
+      community page.
+
+---
+
+## Step 5 — Release workflow, trusted publishing (no tokens) · 🟢 write / 🔵 configure · ⏱ 15 min
+
+- [ ] 🟢 Add `.github/workflows/release.yml` — builds on a `v*` tag and publishes
+      via `pypa/gh-action-pypi-publish` with `permissions: id-token: write` (OIDC,
+      so **no API token to store**).
+- [ ] 🔵 On PyPI: create an account if needed, verify email, **enable 2FA**.
+- [ ] 🔵 On PyPI → your account → *Publishing* → **Add a pending publisher** with:
+      PyPI project name `pebble-mcp`, owner `<your-github-user>`, repository
+      `pebble-mcp`, workflow `release.yml`, environment (leave blank or `pypi`).
+      *(This authorizes GitHub to publish without a password.)*
+
+---
+
+## Step 6 — Ship it · 🔵 tag / 🟢 verify · ⏱ 10 min
+
+- [ ] 🔵 `git tag v0.1.0 && git push origin v0.1.0` — this triggers the workflow,
+      which publishes to PyPI.
+- [ ] 🟢 Verify the real thing: `uvx pebble-mcp` from a clean directory boots and
+      `capabilities()` responds. (I'll walk the install as a stranger would.)
+- [ ] 🟢 Flip the community page + config snippets from "not yet on PyPI / local
+      checkout" to the live `uvx pebble-mcp` one-liner.
+
+---
+
+## Step 7 — Announce (in this order) · 🟢 draft / 🔵 post · ⏱ 30 min
+
+- [ ] 🔵 **Rebble Showcase forum thread** (forum.rebble.io) — the durable home
+      base. 🟢 I'll draft it (lead with the SVG→PDC + 64-color quantization hook).
+- [ ] 🔵 **X, tagging @ericmigi** — highest leverage; he's publicly wanted exactly
+      this. 🟢 I'll draft the post; the GIF is the payload.
+- [ ] 🔵 **Discord `#app-dev`** (rebble.io/discord) — cross-post the forum thread.
+      🟢 I'll draft the message.
+- [ ] 🔵 **GitHub `pebble/community-resources` PR** — adds pebble-mcp to the
+      official tools listing (permanent, low-effort). 🟢 I'll prep the branch +
+      the markdown file; you submit the PR.
+- [ ] Secondary / opportunistic: Show HN, r/pebble (check sidebar rules first),
+      and a demo slot if the monthly dev hangout lands near launch.
+
+---
+
+### Status
+Step 0 decisions are locked. Steps 1–4 (decouple, license, packaging, README, demo
+GIF) are being prepared **now, in place** — so by the time you're done testing,
+publishing is just: create the public repo (5b), configure the PyPI trusted
+publisher (5), and push a `v0.1.0` tag (6). No rush — pull that trigger only once
+the weekend's testing has you confident.

pebble_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Bonomo
+
+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.

pebble_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: pebble-mcp
+Version: 0.1.0
+Summary: MCP server for the Pebble smartwatch ecosystem: appstore search, a 64-color design toolkit, and the local dev loop (build, emulator, screenshot flows).
+Project-URL: Homepage, https://github.com/dzbonomo/pebble-mcp
+Project-URL: Repository, https://github.com/dzbonomo/pebble-mcp
+Project-URL: Issues, https://github.com/dzbonomo/pebble-mcp/issues
+Author-email: Daniel Bonomo <d.z.bonomo@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: mcp,model-context-protocol,pebble,rebble,watchface
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Requires-Python: >=3.13
+Requires-Dist: mcp>=1.9.0
+Requires-Dist: pillow>=10.0.0
+Provides-Extra: design
+Requires-Dist: pillow>=10.0.0; extra == 'design'
+Description-Content-Type: text/markdown
+
+# pebble-mcp
+
+<p align="center">
+  <img src="docs/demo.gif" alt="pebble-mcp downloading a store app and screenshotting it in the emulator" width="200">
+</p>
+
+An [MCP](https://modelcontextprotocol.io) server for the Pebble smartwatch
+ecosystem: appstore search, a 64-color design toolkit, and the local dev loop
+(build → emulator → screenshot flows) exposed as typed tools usable from any
+MCP host — Claude Code, Claude Desktop, claude.ai, or any other agent — not
+just a shell. The demo above is a single `flow_run`: it installs a real
+appstore app (Hubble) onto the emery emulator, drives the buttons, and captures
+each screen — all through MCP.
+
+## Install
+
+Once published to PyPI, no checkout is needed — `uvx` runs it on demand. Add
+this to your MCP host's config (e.g. a Claude Code `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "pebble-mcp": {
+      "command": "uvx",
+      "args": ["pebble-mcp"]
+    }
+  }
+}
+```
+
+To run from a local checkout instead (development, or before the PyPI release):
+
+```json
+{
+  "mcpServers": {
+    "pebble-mcp": {
+      "command": "uv",
+      "args": ["run", "--directory", "/absolute/path/to/pebble-mcp", "pebble-mcp"]
+    }
+  }
+}
+```
+
+### Quickstart (Claude Code)
+
+```bash
+# from PyPI (once published)
+claude mcp add pebble-mcp -- uvx pebble-mcp
+
+# or from a local checkout
+claude mcp add pebble-mcp -- uv run --directory /absolute/path/to/pebble-mcp pebble-mcp
+```
+
+Then, in a session, ask the agent to call `capabilities()` to see which tiers
+are live, or `store_search("weather")` to hit the appstore immediately.
+
+## Capability tiers
+
+The server registers tools in four tiers and probes the environment at startup,
+so an agent only ever sees the tools it can actually run.
+
+- **Tier 1 — Appstore** (pure HTTPS, no auth, always on):
+  `store_search`, `store_app`, `store_collection`, `store_category`,
+  `store_developer`, `store_compare`, `store_download_pbw`.
+- **Tier 2 — Design toolkit** (pure Python + Pillow):
+  `color_nearest`, `palette_swatch`, `image_quantize`, `image_prep`,
+  `font_plan`, `pdc_convert`. Pillow is a core dependency, so this tier is
+  normally always on; `capabilities()` still probes for it and degrades
+  gracefully if it is somehow absent.
+- **Tier 3 — Dev loop** (requires the `pebble` CLI on `PATH`):
+  `pebble_build`, `pebble_install`, `emu_start`, `emu_stop`,
+  `emu_screenshot`, `emu_input`, `emu_logs`, `flow_validate`, and the crown
+  jewel `flow_run` — run a gallery-style flow spec and get every screenshot
+  back as MCP images. These tools register only when `pebble` is found.
+- **Tier 4 — Authenticated** (requires `PEBBLE_API_TOKEN`; off by default):
+  reserved for token-gated, network-mutating operations (heart an app,
+  publish, timeline pins). Detected by `capabilities()`; opt-in only.
+
+Read-only reference is also exposed as MCP resources: `pebble://colors`,
+`pebble://fonts`, `pebble://platforms`, `pebble://wire-conventions`.
+
+### The `capabilities()` tier probe
+
+Call the `capabilities()` tool first. It reports which tiers are live in the
+running environment (`tier1_appstore`, `tier2_design`, `tier3_devloop`,
+`tier4_auth`) so an agent can plan its work instead of calling a tool that
+isn't wired up. Tier 1 is always true; the rest reflect Pillow, the `pebble`
+CLI, and `PEBBLE_API_TOKEN` respectively.
+
+## Development
+
+```bash
+uv sync            # install deps (+ dev group: pytest, ruff)
+uv run pytest      # run the test suite
+uv run ruff check  # lint
+```
+
+The `pebble_mcp/examples/flows/` directory holds sample flow specs (used by the
+tests and as living documentation of the flow format, including the
+`# SAFETY RULES (live-write hazards — DO NOT TRIGGER):` convention that flow
+authors should follow for any app with server-mutating screens).
+
+## License
+
+MIT — see [LICENSE](LICENSE). Copyright (c) 2026 Daniel Bonomo.
+
+---
+
+*Not affiliated with, endorsed by, or sponsored by Core Devices or Rebble.
+"Pebble" and related marks belong to their respective owners.*

pebble_mcp-0.1.0/README.md

@@ -0,0 +1,110 @@
+# pebble-mcp
+
+<p align="center">
+  <img src="docs/demo.gif" alt="pebble-mcp downloading a store app and screenshotting it in the emulator" width="200">
+</p>
+
+An [MCP](https://modelcontextprotocol.io) server for the Pebble smartwatch
+ecosystem: appstore search, a 64-color design toolkit, and the local dev loop
+(build → emulator → screenshot flows) exposed as typed tools usable from any
+MCP host — Claude Code, Claude Desktop, claude.ai, or any other agent — not
+just a shell. The demo above is a single `flow_run`: it installs a real
+appstore app (Hubble) onto the emery emulator, drives the buttons, and captures
+each screen — all through MCP.
+
+## Install
+
+Once published to PyPI, no checkout is needed — `uvx` runs it on demand. Add
+this to your MCP host's config (e.g. a Claude Code `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "pebble-mcp": {
+      "command": "uvx",
+      "args": ["pebble-mcp"]
+    }
+  }
+}
+```
+
+To run from a local checkout instead (development, or before the PyPI release):
+
+```json
+{
+  "mcpServers": {
+    "pebble-mcp": {
+      "command": "uv",
+      "args": ["run", "--directory", "/absolute/path/to/pebble-mcp", "pebble-mcp"]
+    }
+  }
+}
+```
+
+### Quickstart (Claude Code)
+
+```bash
+# from PyPI (once published)
+claude mcp add pebble-mcp -- uvx pebble-mcp
+
+# or from a local checkout
+claude mcp add pebble-mcp -- uv run --directory /absolute/path/to/pebble-mcp pebble-mcp
+```
+
+Then, in a session, ask the agent to call `capabilities()` to see which tiers
+are live, or `store_search("weather")` to hit the appstore immediately.
+
+## Capability tiers
+
+The server registers tools in four tiers and probes the environment at startup,
+so an agent only ever sees the tools it can actually run.
+
+- **Tier 1 — Appstore** (pure HTTPS, no auth, always on):
+  `store_search`, `store_app`, `store_collection`, `store_category`,
+  `store_developer`, `store_compare`, `store_download_pbw`.
+- **Tier 2 — Design toolkit** (pure Python + Pillow):
+  `color_nearest`, `palette_swatch`, `image_quantize`, `image_prep`,
+  `font_plan`, `pdc_convert`. Pillow is a core dependency, so this tier is
+  normally always on; `capabilities()` still probes for it and degrades
+  gracefully if it is somehow absent.
+- **Tier 3 — Dev loop** (requires the `pebble` CLI on `PATH`):
+  `pebble_build`, `pebble_install`, `emu_start`, `emu_stop`,
+  `emu_screenshot`, `emu_input`, `emu_logs`, `flow_validate`, and the crown
+  jewel `flow_run` — run a gallery-style flow spec and get every screenshot
+  back as MCP images. These tools register only when `pebble` is found.
+- **Tier 4 — Authenticated** (requires `PEBBLE_API_TOKEN`; off by default):
+  reserved for token-gated, network-mutating operations (heart an app,
+  publish, timeline pins). Detected by `capabilities()`; opt-in only.
+
+Read-only reference is also exposed as MCP resources: `pebble://colors`,
+`pebble://fonts`, `pebble://platforms`, `pebble://wire-conventions`.
+
+### The `capabilities()` tier probe
+
+Call the `capabilities()` tool first. It reports which tiers are live in the
+running environment (`tier1_appstore`, `tier2_design`, `tier3_devloop`,
+`tier4_auth`) so an agent can plan its work instead of calling a tool that
+isn't wired up. Tier 1 is always true; the rest reflect Pillow, the `pebble`
+CLI, and `PEBBLE_API_TOKEN` respectively.
+
+## Development
+
+```bash
+uv sync            # install deps (+ dev group: pytest, ruff)
+uv run pytest      # run the test suite
+uv run ruff check  # lint
+```
+
+The `pebble_mcp/examples/flows/` directory holds sample flow specs (used by the
+tests and as living documentation of the flow format, including the
+`# SAFETY RULES (live-write hazards — DO NOT TRIGGER):` convention that flow
+authors should follow for any app with server-mutating screens).
+
+## License
+
+MIT — see [LICENSE](LICENSE). Copyright (c) 2026 Daniel Bonomo.
+
+---
+
+*Not affiliated with, endorsed by, or sponsored by Core Devices or Rebble.
+"Pebble" and related marks belong to their respective owners.*

pebble_mcp-0.1.0/TOOL-SURFACE.md

@@ -0,0 +1,98 @@
+# pebble-mcp — Tool Surface Contract
+
+The usability contract for every MCP tool this server exposes. The requirements
+doc says *what* ships; this says *how it must feel*. A tool that violates this
+doc is not done, even if it works. Scope changes go through Fable + Dan.
+
+Guiding test for every design decision: **an agent that has never seen Pebble
+before reads only the tool list and schemas — can it do the task on the first
+call, and when it can't, does the error tell it what to do next?**
+
+## 1. Small surface, strong verbs
+
+- Target **≤ 15 tools total** across all tiers. Prefer one tool with a clear
+  argument over two near-duplicate tools. (Counter-example to avoid: separate
+  `store_faces` / `store_apps` — it's one `store_search` with a `type` arg.)
+- Every tool name is `noun_verb` or `noun` scoped by prefix: `store_*`,
+  `image_*`, `font_*`, `emu_*`, `pebble_*` (build/install), `flow_*`.
+- No tool exists just to expose a library function. If an agent wouldn't reach
+  for it while building or shipping a watchface, it doesn't get a tool.
+  Library ≠ surface.
+
+## 2. Descriptions and schemas are the product
+
+- Tool description: first sentence = what it does for the caller. Then when to
+  use it, then sharp edges. Written for a model, tuned like docs.
+- Every enum-ish argument IS an enum in the schema (platforms, buttons,
+  collection slugs, dither modes). Never "string, see docs".
+- Defaults encode expertise: `hardware="emery"`, sane limits, safe modes. A
+  zero-argument or one-argument call should do the obviously-right thing.
+  (Lesson from GymTracker: value on first call, never "configure elsewhere
+  first".)
+
+## 3. Returns: compact, structured, honest
+
+- **Context is the scarce resource.** List-shaped returns are trimmed
+  projections (id, title, author, hearts, one-line summary) — never the raw
+  App object. Full detail is a *by-id* lookup. Cap list returns (default
+  ~10, max ~50) and always include pagination state the agent can act on:
+  `{offset, returned, has_more}`.
+- Screenshots and swatches return as **MCP image content blocks** (the agent
+  sees them) *plus* the saved file path (the human keeps them). Both, always.
+- Numbers the store API lies about get fixed in the tool: hearts sorting is
+  client-side (`sort=hearts` is silently ignored upstream — measured, not
+  assumed). The tool's output order is the order it promises.
+- Anything cached carries `fetched_at`. Cached list tools accept
+  `refresh: bool = false`. Stale-on-network-failure returns data + a
+  `stale: true` flag, not an exception.
+
+## 4. Errors an agent can act on
+
+- Every failure path returns: what failed, why (upstream detail bounded to a
+  few hundred chars), and **the next move** ("run capabilities()", "the id
+  looks malformed — store ids are 24 hex chars", "emulator wedged; it was
+  kill+wiped, retry your call").
+- Tier-gated tools fail fast with the gate named: calling `pebble_build`
+  without the CLI returns the install hint, not a traceback.
+- No silent None. A lookup that finds nothing says so and echoes what it
+  looked for.
+
+## 5. Sharp edges stay inside the tool
+
+- `pebble_install` bakes in kill+wipe. `flow_run` bakes in wedge recovery
+  (one restart, then a structured failure). Agents never need to know the
+  folklore; that's the whole point of the server.
+- Emulator tools are serialized internally (one QEMU); a second concurrent
+  call queues or fails clearly — it never interleaves.
+- Log/output capture is always bounded (bytes and seconds) with the truncation
+  stated in the return.
+
+## 6. Safety and tiers
+
+- Tier 4 (authed) tools: mutating calls (`store_heart`, `pebble_publish`,
+  timeline pushes) require an explicit `confirm: true` argument and describe
+  exactly what will happen when called without it. Publish is a two-step
+  handshake, never one call.
+- `capabilities()` stays cheap, evaluated per-call, and is the single source
+  of truth the other tools' gate errors point at.
+- Nothing phones home; the only network calls are the ones the tool name
+  promises.
+
+## 7. Known upstream quirks (encode, don't rediscover)
+
+| Quirk | Tool-level answer |
+|---|---|
+| `sort=hearts` ignored by collection API | client-side sort, documented in description |
+| collection type is `apps`/`faces` (not `watchapps`) | enum hides the slug entirely |
+| `Page.total` absent | expose `has_more` from returned-vs-limit instead |
+| no text-search read endpoint mapped yet (A1 gap) | `store_search` is the #1 user verb — needs an endpoint or client-side scan; resolve before A2 ships |
+| watchapps need wipe-before-install to foreground | baked into `pebble_install` |
+
+## 8. Definition of slick (acceptance)
+
+A fresh agent session with only this server configured can, unprompted:
+1. name the top-5 most-loved emery faces (correct order, one call),
+2. build a broken project and report the *actionable* compiler error,
+3. run a 3-step flow and *show* the screenshots,
+4. explain why a Tier-4 tool call didn't run and what's needed to enable it —
+   each in ≤ 2 tool calls, no call returning > ~4 KB of text.