vaultbeat-apple-health

# Vaultbeat Local MCP Server

**Your Apple Health data — sleep stages, cycle, HRV, resting heart rate, workouts, weight, VO₂ max, meals, lifts, notes — readable and writable by your own AI agent (Claude Code, Hermes, OpenClaw, anything MCP), end-to-end encrypted so that only your machine ever sees plaintext.** The [Vaultbeat](https://vaultbeat.app) iPhone app captures from HealthKit; this package is the local server that decrypts for the agent.

Technically: the local service program for Vaultbeat's encrypted health-data recipient flow.
Published externally as [`Fino-wind/vaultbeat-apple-health`](https://github.com/Fino-wind/vaultbeat-apple-health)
(public package name `vaultbeat-apple-health` since 0.6.2; `vaultbeat-mcp` and
`vaultbeat-mcp-local` remain back-compat console scripts). This directory is the source of truth — after any user-visible change here,
re-export the public repo and update its README tool table + the website `/mcp` page
(see CLAUDE.md "Sync duty").

It runs on the user's computer, generates the Curve25519 keypair used by the iOS app,
shows a QR binding payload, receives a one-time server token from the cloud API, and
then exposes decrypted health data — sleep, water, weight, cycle, activity, vitals —
through either a CLI or a stdio MCP server. Read-only: data is written by the iOS app.

## Commands

```bash
python -m pip install -e './mcp-local-server[qr]'
# try every read tool against synthetic data — no pairing, no cloud, no Apple Health
vaultbeat-apple-health --demo sleep --limit 5
vaultbeat-apple-health --demo doctor

vaultbeat-apple-health bind
vaultbeat-apple-health status

# read decrypted health data — every data subcommand accepts
# --owner <user-id prefix> to filter to one person (omitting it mixes
# both partners' records into one pool; aggregates become meaningless)
vaultbeat-apple-health sleep --limit 5 --owner a1a1        # sleep sessions + provenance
vaultbeat-apple-health sleep-detail --limit 1 --owner a1a1 # HR+RR+stage timeline
vaultbeat-apple-health water --limit 30 --owner a1a1       # water intake + daily average
vaultbeat-apple-health weight --limit 90 --owner b2b2      # weight trend (latest/avg/weekly rate)
vaultbeat-apple-health menstrual --limit 60 --owner b2b2   # menstrual cycle (sensitive)
vaultbeat-apple-health activity --limit 30 --owner a1a1    # daily activity rings
vaultbeat-apple-health resting-hr --limit 30 --owner a1a1  # resting heart rate
vaultbeat-apple-health workouts --limit 20 --owner a1a1    # workout records
vaultbeat-apple-health mindfulness --limit 30 --owner a1a1 # mindful minutes
vaultbeat-apple-health hrv --limit 30 --owner a1a1         # HRV / SDNN (hourly buckets by default; --granularity raw for per-sample)
vaultbeat-apple-health wrist-temp --limit 30 --owner a1a1  # sleeping wrist temperature
vaultbeat-apple-health symptoms --limit 30                 # symptom days (grouped by owner)
vaultbeat-apple-health notes --kind sleep --limit 30       # free-text day annotations

# run as an MCP server
vaultbeat-apple-health serve --transport stdio
vaultbeat-apple-health serve --transport http --host 127.0.0.1 --port 8000 --path /mcp
vaultbeat-apple-health --demo serve --transport stdio   # same synthetic dataset, wired into a client
```

`--demo` is a **global flag**, not a subcommand: it goes before the subcommand
(`vaultbeat-apple-health --demo sleep`), and `VAULTBEAT_DEMO=1` does the same thing. It serves a
deterministic synthetic dataset — the same records on every machine, every run — so demo
output can be pasted into a bug report as a shared baseline. Nothing is fetched and nothing
is decrypted; there is no private key involved at all. Every payload carries `demo_mode:
true` plus a `[SYNTHETIC DEMO DATA]` banner, the tool descriptions say so, and the server
lists itself as `Vaultbeat Health [DEMO — SYNTHETIC DATA]`, so demo output cannot pass for a
real export. **Read tools only** — the `log_*` write tools refuse, because writing needs a
real key and a real account, and a write that pretends to succeed is worse than one that says
it needs pairing. It applies to that one invocation and is never written to the config file.

`http` is a CLI alias for MCP's `streamable-http` transport.
The default transport remains `stdio` for local desktop MCP clients.

The config file defaults to `~/.tether/mcp-local/config.json` and is written with
`0600` permissions. It contains the cloud-issued server token and your **public**
key; do not commit or share it.

### Where the private key lives

Not in `config.json`. It is looked for in three places, in order:

1. **`VAULTBEAT_PRIVATE_KEY`** — read if set, never written back, for operators
   who inject it from systemd-creds / a vault / a KMS.
2. **The system keyring** — the normal case on a desktop.
3. **`~/.tether/mcp-local/identity.key`**, mode `0600` — the automatic fallback
   on a machine with no keyring backend at all.

Keeping it out of `config.json` is a boundary, not tidiness: the server token
alone can download your ciphertext but not read it, and the private key alone
has nothing to decrypt. `config.json` is the file people `cat` into bug reports.

> 🔴 **Never delete `config.json` to "start clean".** The private key is not in
> it, so deleting does not clear a bad key — it mints a brand-new identity, and
> every record already encrypted for the old one becomes permanently unreadable.
> If a command reports missing key material, the error names all three locations
> and what was found in each; read that before removing anything.

**Headless servers**: if the keyring is unreachable, do *not* set
`PYTHON_KEYRING_BACKEND` to the null backend. That backend accepts writes and
stores nothing; since 0.4.3 every keyring write is verified by reading it back,
so a null backend just lands the key in layer 3's `identity.key` file — the same
outcome as having no keyring, with a keyring you might have reached hidden behind
it. Either let layer 3 handle it (automatic when no backend exists) or, if a
D-Bus session exists but this process cannot see it, pass
`DBUS_SESSION_BUS_ADDRESS` through explicitly — `XDG_RUNTIME_DIR` on its own is
not enough.

> **`.tether`, not `.vaultbeat` — that is deliberate, do not "fix" it.** The app
> was renamed but this path is frozen at the pre-rename location, because the
> Keychain username embeds the resolved config path (`_keychain_username` in
> `store.py`). Moving the directory orphans the bound config *and* its
> private-key Keychain entry for every existing install. Until 2026-07-28 this
> README wrote `~/.vaultbeat/...`, which does not exist — so anyone who came here
> to destroy their credentials `rm -rf`'d an empty path, got no error, and left
> the real key in place.

When using HTTP transport, the server binds to `127.0.0.1:8000` and serves MCP at
`/mcp` by default, and requires a bearer token (see "Authenticating HTTP transport"
below). Binding a non-loopback address fails closed unless you pass both a token and
`--allow-remote`; always front a network-exposed server with TLS (a reverse proxy).

## Binding Flow

1. `vaultbeat-apple-health bind` generates a fresh `pollID` and prints a QR payload:
   `{"pollID":"...","publicKeyBase64":"...","serverName":"..."}`
2. The iOS app scans that payload and calls the `mcp-bind-local` Edge Function.
3. The local service polls the `mcp-poll-binding` Edge Function.
4. Once bound, the local config stores `serverID` and `serverToken`.
5. All read commands call the `mcp-sync` Edge Function, decrypt the returned envelopes
   locally, and return plaintext JSON. (All privileged routes are Supabase Edge
   Functions at `/functions/v1/<name>`.)

### Troubleshooting: `vaultbeat-apple-health doctor`

If binding or reads fail, run the self-diagnosis:

```bash
vaultbeat-apple-health doctor          # human-readable [OK]/[FAIL] checklist with hints
vaultbeat-apple-health doctor --json   # machine-readable, for agents
```

It checks, in order: config file → identity key (Keychain) → cloud reachability →
binding state → a real fetch-and-decrypt round trip, and prints a targeted hint for
the first thing that's broken (e.g. "codes expire after 10 minutes — re-run bind for
a fresh QR", or "the stored key can no longer decrypt your data — delete this server
in the iOS app and bind again"). Exit code 0 = all healthy, 1 = something needs the
hint above.

## MCP Tools (29)

`vaultbeat-apple-health serve` can start either a stdio MCP server or a streamable HTTP MCP
server. Every data tool accepts `owner` (user-ID prefix) to filter to one person and
`fresh` to bypass the local cache — omit `owner` and both partners' records mix into
one pool, so per-person analysis must always pass it. The tool names dropped the old
misleading `get_partner_*` prefix in the 16-tool release (2026-07-16): the tools
return whichever owners' envelopes this server holds, not specifically "the partner".

Binding / status:

- `vaultbeat_status` — local binding state (no keys/tokens in the result)
- `vaultbeat_start_binding` — generate a fresh QR binding payload
- `vaultbeat_poll_binding` — poll once for the iOS authorization
- `vaultbeat_doctor` — diagnose this install end to end, and report which data types
  are unavailable and why. Call it before telling a user their data is missing.

Health data:

- `vaultbeat_sync_sleep` — recent sleep records (incl. heart-rate samples) with per-day
  primary-session selection matching the iOS app
- `get_sleep_detail` — per-night HR+RR+stage timeline with stage intervals
- `get_water_intake` — recent daily intake + computed `average_daily_intake_liters`
- `get_weight_trend` — daily weights + latest/avg/min/max + OLS weekly rate
- `get_menstrual_cycle` — recent cycle samples + a next-period prediction (sensitive)
- `get_symptoms` — recent HealthKit symptom days grouped by data owner (sensitive)
- `get_notes` — free-text sleep/menstrual day annotations with their writer (sensitive)
- `get_strength_log` — strength-training sessions with exerc