pebble-index-mcp

MCP bridge that exposes a local Obsidian vault and a Hermes Agent instance to the Pebble Index 01 smart ring's double-click MCP sandbox. Voice captures from the ring are routed by the Pebble app's cloud agent into this server's tools, and the answer comes back as a phone notification.

Architecture

[Index ring] → [Pebble app] → [Pebble cloud agent] → [this MCP server]
                                                        ├─ vault tools (local files)
                                                        ├─ ha_control → Home Assistant REST API
                                                        ├─ ha_announce → assist_satellite.announce
                                                        ├─ vinyl_lookup → vinyl catalog API
                                                        └─ ask_hermes → Hermes API server

• The server speaks MCP over Streamable HTTP (official mcp SDK, FastMCP).

• Every request must carry a bearer token; anything else gets 401.

• FastMCP's DNS-rebinding protection is on: allowed hosts are loopback plus anything listed in MCP_ALLOWED_HOSTS.

• The public exposure is a cloudflared tunnel to the loopback port; no cloud infrastructure is required beyond that.

Related MCP server: Obsidian MCP Server

Components

Tools

• vault_search(query, max_results=5) — case-insensitive text search; returns path: excerpt lines.

• vault_read(note_path, max_chars=1500) — reads the head of a note.

• vault_append(note_path, text) — appends a timestamped - HH:MM text line, creating the note if needed.

• ask_hermes(question) — forwards to the Hermes API server; 60s timeout with an honest acknowledgment on miss.

• ha_control(command) — smart-home commands: "living room lights on", "bedroom off", "toggle the hallway", "is the living room tv on". Resolves the entity against Home Assistant's state list (room groups win over individual fixtures; ambiguous matches return the candidates instead of guessing), calls the service, and polls the state readback so the confirmation reflects the NEW state. Domains: light, switch, fan, cover, media_player. Requires HASS_TOKEN. Milliseconds-to-seconds latency; never route smart-home commands through ask_hermes.

• ha_announce(message) — intercom: speaks message on every live assist_satellite device with a pre-announce chime. Offline satellites are skipped (HA returns 200 for announce even when the device is down, so the tool pre-filters). Requires HASS_TOKEN.

• ha_music(command) — music control: "play Spiritbox in the basement", "play the album Blue Rev in the kitchen", "stop the music in the living room". Routes to Music Assistant players (the media_player.*_2 entities) through Home Assistant's play_media service, verifies the cast started by polling the player's media_title, and falls back across artist/track/album interpretations when a search comes back empty. Room map and the no-room default (Voice PE) live in homeassistant.py. Requires HASS_TOKEN and a running Music Assistant with the Deezer provider.

• vinyl_lookup(command) — queries the operator's self-hosted vinyl catalog: owned-record search ("do I own Eternal Blue"), a dormancy-weighted random pick, or most-played records. Requires VINYL_URL.

• web_search(query, max_results=3) — live web search via the Exa API, composed into a short spoken answer by the configured model. Requires EXA_API_KEY.

Both answer tools wrap their result in the Pebble app's private coreSchema contract (_meta: {"coreSchema": 1} plus structuredContent carrying a Response semantic result). Without it, the app's completion notification shows the transcription of the question instead of the answer. If the compose step fails, web_search falls back to raw results (the notification then shows the question; the agent still answers in the feed).

Security

• Auth: static bearer token (MCP_BEARER_TOKEN), constant-time compared, required on every request. An empty token fails closed (all requests 401) and logs a warning at startup.

• Transport: TLS terminates at the tunnel edge; the origin listens on loopback only.

• Host validation: DNS-rebinding protection rejects requests whose Host header is not loopback or in MCP_ALLOWED_HOSTS.

• Path sandbox: vault tools resolve all paths and require them to stay inside the vault root; symlink escapes are rejected and file opens use O_NOFOLLOW on the final component. The sandbox guards against accidental and remote misuse; a hostile local process that races a parent-directory swap can still win (documented TOCTOU boundary — the vault is assumed to be a trusted single-user directory).

• Config is read once at import: rotating the bearer token or changing allowed hosts requires a service restart.

• Secrets: the Hermes API key and MCP token live in a 0600 env file outside this repo, never in code, logs, or commits.

• Privacy note: recordings routed through the double-click sandbox transit the Pebble app's cloud agent. Single-click captures stay on-device. Sensitive thoughts belong on single-click.

Configuration (env)

HERMES_API_URL accepts any OpenAI-compatible chat completions endpoint, so ask_hermes works against OpenRouter directly, Ollama, or any other compatible API — Hermes is just the default.

Development

python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest -v

Run locally: set the env vars above and python -m pebble_index_mcp.server.

Deployment

deploy/ contains a systemd user unit template and a cloudflared tunnel template (hostname and credentials filled in on the host, not in this repo). See docs/ring-checklist.md for the phone-side setup and test matrix.

License

MIT — see LICENSE.