# MissingMCP

*The MCP servers exist. Connecting them shouldn't be complicated.*

[![smithery badge](https://smithery.ai/badge/vaclav/garmin)](https://smithery.ai/servers/vaclav/garmin)

A multi-user, OAuth 2.1–protected gateway that hosts the connectors Claude is
missing, so a small trusted circle can connect their own accounts from any
Claude client (iOS, Android, Web, Desktop). The flagship connector is
[Garmin Connect](https://connect.garmin.com): the gateway wraps the
**unmodified** [`garmin_mcp`](https://github.com/Taxuspt/garmin_mcp) worker and
adds OAuth, per-user token isolation, and a reverse proxy. [WHOOP](https://www.whoop.com)
is served the same way but in-process, on WHOOP's own official OAuth v2 API.
The core is adapter-based and supports three forward strategies — **worker**
(garmin), **local** (whoop, in-process, no subprocess), and **remote** (MCP +
header injection, for services with a hosted MCP that lacks its own OAuth) —
see [Connectors](#connectors). The reference deployment runs at
[missingmcp.com](https://missingmcp.com).

```
Claude → POST /garmin/mcp (Bearer) → Gateway → 127.0.0.1:<port>/mcp (per-user garmin_mcp) → connect.garmin.com
```

## Why

`garmin_mcp` is a great MCP server, but it's single-user and stdio-only: each
person has to run it locally with their own Garmin tokens. This gateway makes it a
**remote MCP server** any Claude client can connect to over HTTP, with a proper
OAuth sign-in flow — so non-technical users just click "connect" and log in with
their Garmin credentials, and never touch a terminal or a token file.

## Features

- **OAuth 2.1** — Authorization Code + PKCE (S256) with Dynamic Client
  Registration. Connect from any Claude client; no manual token wrangling.
- **Garmin password is never stored** — used once to sign in (MFA supported);
  only the resulting session tokens are persisted.
- **Encrypted at rest** — tokens sealed with AES-256-GCM; the DB is useless without
  `GATEWAY_SECRET`. Bearer tokens are stored only as SHA-256 hashes.
- **Per-user isolation** — each account gets its own `garmin_mcp` worker bound to
  `127.0.0.1`, started on demand and reaped when idle.
- **Hardened** — one-time 10-min auth codes, CSRF on forms, per-IP/-token rate
  limits, the `garmin_mcp` worker pinned to a reviewed commit.
- **Off-box backups** — periodic encrypted SQLite snapshots to an S3-compatible
  bucket (see [Backups](#backups)).
- **Instructional landing page** served on `/` and as a friendly fallback for
  unknown paths.

## Deploy

**Railway (how missingmcp.com runs):** one service built from the `Dockerfile`,
a volume mounted at `/data`, a single replica (the gateway keeps process-local
state by design), and TLS terminated at the Railway edge. Set the env vars from
[Configuration](#configuration) on the service; pushes to `main` deploy
automatically once the service is connected to the GitHub repo. An optional
Railway bucket enables [Backups](#backups) (`railway bucket create backups`,
then wire its credentials as the `BACKUP_S3_*` variables).

**Self-hosted (plain Docker):**

```bash
cp .env.example .env          # set GATEWAY_SECRET, PUBLIC_URL, pin GARMIN_MCP_REF
docker build -t missingmcp .
docker run -d --name missingmcp --restart unless-stopped --env-file .env \
  -p 127.0.0.1:8080:8080 -v missingmcp-data:/data missingmcp
```

Put any TLS-terminating proxy in front (Caddy, nginx, Traefik). One non-obvious
requirement: `/​<adapter>/mcp` streams SSE, so disable response buffering and
raise the read timeout (nginx: `proxy_buffering off; proxy_read_timeout 3600s;`).
Then add `https://<your-domain>/garmin/mcp` as a remote MCP server in Claude.

## Local development

```bash
uv pip install -e ".[dev]"
uv run --extra dev pytest -q                 # run the test suite

# Run the gateway locally (no Garmin account needed to exercise the OAuth surface).
# garmin-mcp isn't on PATH locally, so point GARMIN_MCP_CMD at uvx.
GATEWAY_SECRET="$(openssl rand -base64 48)" \
PUBLIC_URL=http://localhost:8088 PORT=8088 DATA_DIR=./.localdata \
GARMIN_MCP_CMD="uvx --python 3.12 --from git+https://github.com/Taxuspt/garmin_mcp garmin-mcp" \
  uv run missingmcp
```

A `.env` file in the working directory is loaded automatically (real environment
variables take precedence), so you can drop the same values there instead.

## Connectors

Each connector is mounted under its own path prefix with its own OAuth flow and
its own Bearer tokens (there is no bare `/mcp`). The landing page on `/` lists
the available connectors.

### Garmin — `/garmin/mcp`

Sign in with your Garmin Connect email + password (MFA supported). The password
is used once for the Garmin login and discarded; only the resulting Garmin
session tokens are stored (AES-256-GCM encrypted). Each account gets its own
`garmin_mcp` worker process, bound to `127.0.0.1`, started on demand and reaped
when idle.

### WHOOP — `/whoop/mcp`

Sign in on WHOOP's own OAuth page — the gateway never sees your WHOOP password,
only the resulting (encrypted, read-only) tokens. Covers recovery, sleep,
strain & daily cycles, workouts, and body measurements. Served in-process on
WHOOP's official v2 API (no worker subprocess, no shared upstream). Requires
the operator to register a WHOOP developer app — see [WHOOP connector
setup](#whoop-connector-setup) in Configuration.

### Rohlík — no longer missing

The gateway briefly served a Rohlík connector (remote strategy: credential
headers injected into the hosted Rohlík MCP). It was retired in 2026-07 when
Rohlík shipped **its own OAuth-protected MCP** — add
`https://mcp.rohlik.cz/mcp` directly as a custom connector in Claude and sign
in in the browser ([Rohlík's guide](https://www.rohlik.cz/stranka/mcp-server)).
The remote-forward strategy remains a first-class, tested part of the core
(`tests/test_remote_forward.py`) for the next service that needs it.

## Connecting from Claude

1. In any Claude client: **Settings → Connectors → Add custom connector**, or in
   the CLI: `claude mcp add --transport http garmin https://<your-domain>/garmin/mcp`
   (whoop: `claude mcp add --transport http whoop https://<your-domain>/whoop/mcp`).
2. Claude opens the gateway's sign-in page — enter the service's email +
   password (Garmin also prompts for an MFA code when needed), or for WHOOP,
   sign in on WHOOP's own OAuth page.
3. Done — the service's tools are now available in Claude.

## Configuration

Set via environment (or `.env`). See [`.env.example`](.env.example).

| Variable | Required | Default | Description |
|---|---|---|---|
| `GATEWAY_SECRET` | **yes** | — | ≥32-char key for token encryption. Refuses to start with the placeholder. Generate with `openssl rand -base64 48`. |
| `PUBLIC_URL` | yes | `http://localhost:8080` | Public URL used in OAuth metadata + redirects. |
| `PORT` | no | `8080` | Listen port. |
| `DATA_DIR` | no | `/data` | Where the SQLite DB and per-user token dirs live. |
| `DB_PATH` | no | `$DATA_DIR/gateway.db` | Override the DB path. |
| `GARMIN_MCP_CMD` | no | `garmin-mcp` | Command to spawn the worker. Use a `uvx …` invocation when `garmin-mcp` isn't on PATH. |
| `GARMIN_MCP_REF` | no | pinned SHA in `Dockerfile` | Docker build arg: commit of `garmin_mcp` to install. Bumping it is a deliberate, reviewed action — afterwards run `python scripts/gen_garmin_tools.py` to refresh the tool listing on the `/garmin` page. |
| `WORKER_PORT_START` / `WORKER_PORT_END` | no | `9000` / `9099` | Port range for per-user workers. |
| `WORKER_IDLE_TTL` | no | `900` | Seconds before an idle worker is reaped. |
| `WORKER_STARTUP_TIMEOUT` | no | `20` | Seconds to wait for a worker to become healthy. |
| `MAX_WORKERS` | no | `10` | Max concurrent per-user workers. |
| `GARMIN_MCP_STATELESS_HTTP` | no | `true` | Run garmin workers' Streamable HTTP without MCP sessions (passed to every worker explicitly). A replaced worker (eviction, idle reap, crash, deploy) then still serves the client's old `Mcp-Session-Id` instead of answering 404 "Session not found"; the gateway answers GET/DELETE on `/garmin/mcp` with 405 itself. `false` is the rollback switch (session-ful workers, GET/DELETE forwarded). Accepts `true`/`false`, `1`/`0`, `yes`/`no`, `on`/`off` (case-insensitive; empty = default); any other value stops the gateway at startup. |
| `SSO_PROBE_INTERVAL` | no | `0` (off) | Seconds between browser-impersonated GET probes of Garmin's SSO embed widget, once per sign-in egress (event `sso-probe`, fields `via`, `egress_ip` — the egress's real outgoing IP via `cdn-cgi/trace`; plus `egress-health` per egress: real sign-in outcomes since the previous run, since the GET can't see a blocked credential POST; `egress-ip-changed` when an egress's IP changes, floor 60 s) — an attempt-independent block timeline for diagnosing egress-IP rate-limiting (reliability ticket 12). |
| `GARMIN_SSO_PROXY` | no | — (direct) | Comma-separated proxy URLs (`http://user:pass@host:port`) on dedicated IPs for the gateway's own Garmin traffic — sign-in, MFA, token verify — instead of the shared host egress that Garmin's SSO rate-limits (ticket 12). Each account sticks to one proxy (by account hash). Sign-in throttling (failing-logins map): one in-flight sign-in per login email (a concurrent one is turned away); a 2 min post-connect hold after a real connection; a "blocked" sign-in cools down only that account for 5 min, without an in-call retry; an egress's breaker trips once ≥2 distinct accounts are blocked on it with no sign-in getting through between, or on ≥10 blocks in an hour, resting it 30 min → 2 h → 6 h → 24 h on repeated trips (back to 30 min after a sign-in gets through). An egress tripped with no sign-in through since is *suspect*: one block on it trips the next step. A sign-in whose block trips its egress is retried once on the next route within the same call (if the first attempt took < 35 s); a block on that retry cools only the account. The rest level, rest end, egress IP and last ok/blocked times persist in the `egress_state` table, so deploys don't reset a burned IP; when the probe sees a route leave from a new IP, its state starts over (`sudo mmcp egress` shows it on hydra). A proxy that can't carry the request at all (port refused, CONNECT refused — curl's `CONNECT tunnel failed` / (5)/(7)/(97); Garmin never saw it) is outcome `egress`, not `blocked`: the account isn't cooled, the egress rests 5 min, and the same sign-in fails over to the next route within the call; only when every route is down does the user see an "unavailable on our side" message. The direct path stays as the last resort (reached only when every proxy is cooling down). Mobile SSO strategies are skipped on proxied sign-ins (they 429 from datacenter fingerprints even on a clean IP). Workers and all other traffic stay direct. Events: `garmin-login-attempt` (`account`, `egress`, `egress_ip`, `outcome`, `message`), `login-breaker-open` / `login-breaker-reject` (`scope`: `account`|`egress`|`egress_down`|`in_flight`|`post_success`, `egress`, `account`, `message`), `sso-probe` per egress (`via`, `message`), `egress-state-restored` at startup (`egress`, `egress_ip`, `rest_level`, `remaining_s`), `egress-state-save-failed` (`egress`, `error`). Logged as host:port only. |
| `ACCESS_TOKEN_TTL_DAYS` | no | `90` | Bearer token lifetime; user re-authenticates after it. `0` disables expiry. |
| `OPERATOR_NAME` / `OPERATOR_EMAIL` | no | — | Shown on the landing page. |
| `OPERATOR_URL` | no | — | Homepage the operator name links to (footer, trust notes). Unset → plain text. |
| `WHOOP_CLIENT_ID` / `WHOOP_CLIENT_SECRET` | no | — | Credentials of your WHOOP developer app (see WHOOP connector setup); both unset ⇒ the whoop connector is disabled. |
| `WHOOP_API_BASE` | no | `https://api.prod.whoop.com` | WHOOP API origin; override only for testing. |
| `BACKUP_S3_ENDPOINT` / `BACKUP_S3_BUCKET` / `BACKUP_S3_ACCESS_KEY` / `BACKUP_S3_SECRET_KEY` | no | — | S3-compatible bucket for off-box DB backups (see Backups). Backups are disabled unless all four are set. |
| `BACKUP_S3_REGION` | no | `auto` | SigV4 region of the bucket. |
| `BACKUP_S3_URL_STYLE` | no | `virtual-host` | `virtual-host` (Railway buckets) or `path`. |
| `BACKUP_INTERVAL_HOURS` | no | `6` | Hours between backup uploads. First backup runs right after startup. |
| `POSTHOG_API_KEY` | no | — | Public `phc_` project key. Unset ⇒ **all** PostHog telemetry (events, log tee, web analytics) is off. |
| `POSTHOG_LOGS` | no | `false` | `true` tees every structured stdout line to PostHog Logs over OTLP. Off by default since 2026-10-19: at 2,500 WAU that was 43M+ lines (~9 GB) a month on the PostHog bill, and Railway keeps the logs anyway. Strict `true`/`false`. |
| `POSTHOG_HOST` | no | `https://eu.i.posthog.com` | Server-side ingestion host (SDK events + OTLP log tee). |
| `POSTHOG_WEB_HOST` | no | `$POSTHOG_HOST` | posthog-js `api_host` — set it to the managed reverse proxy (e.g. `https://j.missingmcp.com`) for ad-blocker resilience. |
| `POSTHOG_UI_HOST` | no | `https://eu.posthog.com` | PostHog app host; posthog-js needs it when `POSTHOG_WEB_HOST` is a proxy. |
| `MAIL_API_TOKEN` | no | — | Cloudflare API token for mail campaigns — scope it to **Account → Email Sending → Edit** only. Campaigns are disabled unless this, `MAIL_ACCOUNT_ID` and `MAIL_FROM` are set. |
| `MAIL_ACCOUNT_ID` | no | — | Cloudflare account id the sending domain lives in. |
| `MAIL_FROM` | no | — | Sender address on an onboarded Cloudflare Email Sending (sub)domain, e.g. `you@news.example.com`. |
| `MAIL_FROM_NAME` | no | — | Sender display name. |
| `MAIL_REPLY_TO` | no | — | Where replies go; also the `mailto:` target of the `List-Unsubscribe` header. |
| `MAIL_DAILY_CAP` | no | `180` | Max campaign mails per rolling 24h (Cloudflare's quota window). Keep it under the Cloudflare account's daily quota (200 on a new account, shared by every sending domain). |
| `GATEWAY_LOG_FILE` | no | — | If set, tees structured + stdlib logs to this file. |
| `GATEWAY_LOG_LEVEL` | no | `info` | `debug`\|`info`\|`warning`\|`error`\|`critical`. `debug` is verbose (logs garminconnect/urllib3 internals) — avoid in production. |

### WHOOP connector setup

1. Create an app at <https://developer-dashboard.whoop.com> (instant self-service).
2. Redirect URI: `https://<your-domain>/whoop/oauth/callback` — exact match required.
3. Scopes: `read:recovery read:cycles read:workout read:sleep read:profile read:body_measurement offline`
   (`offline` is required — without it WHOOP issues no refresh token and sessions die after an hour).
4. Put the app's Client ID/Secret into `WHOOP_CLIENT_ID` / `WHOOP_CLIENT_SECRET`.

Note: an unapproved WHOOP app is limited to **10 WHOOP members**. To lift the
limit, submit the app for approval: <https://developer.whoop.com/docs/developing/app-approval/>
(requirements: [API Terms of Use](https://developer.whoop.com/api-terms-of-use/)
compliance, tested with ≥1 member, accurate app name / contact email / privacy-policy
URL in the dashboard, [brand-guidelines](https://developer.whoop.com/docs/developing/design-guidelines)
compliance, and their Typeform submission).

Operating obligations under the WHOOP API Terms of Use (the gateway's design
already covers the technical ones — no WHOOP data stored, encrypted tokens,
auto-purge of revoked accounts):

- Report any security incident involving WHOOP member data to
  <apisupport@whoop.com> without undue delay, and to affected users.
- No press release or public announcement that references WHOOP without
  WHOOP's prior written approval.
- Keep the app's Client ID/Secret out of the repo (env vars only) and never
  reuse them for another application.
- When a member revokes the app at WHOOP, the gateway detects it on the next
  refresh (`invalid_grant`), deletes the stored tokens, and revokes the
  member's gateway access tokens (log event `whoop-account-revoked`).

## Backups

When the `BACKUP_S3_*` variables are set, the gateway uploads a consistent
SQLite snapshot (via the SQLite backup API, WAL-safe) to the bucket right
after startup and then every `BACKUP_INTERVAL_HOURS`. Keys rotate by weekday
(`db/gateway-mon.db` … `db/gateway-sun.db`), giving seven days of retention
with no cleanup logic. Watch the `backup-ok` / `backup-failed` log events.

Only the DB is backed up — per-user token dirs under `DATA_DIR/users/` are
re-materialized from the DB on demand.

> **The backup is useless without `GATEWAY_SECRET`** (account blobs stay
> AES-256-GCM encrypted inside it) — and that is the point. Keep a copy of
> `GATEWAY_SECRET` somewhere that is *not* the bucket and *not* Railway
> (e.g. your password manager). Losing the secret = losing every account.

**Restore:** download the newest object, put it at `$DATA_DIR/gateway.db`
(delete any stale `gateway.db-wal`/`-shm` next to it), set the same
`GATEWAY_SECRET`, start the gateway. Bearer tokens and logins survive;
workers respawn lazily.

## Monitoring

Three helper scripts work directly on the gateway's DB (safe to run while the gateway is live):

```bash
python scripts/status.py          # summary counts only (safe to paste/share)
python scripts/status.py --detail # + per-account devices (token prefixes),
                                  #   usage summary, OAuth clients, running workers
python scripts/revoke.py --list                       # accounts + token counts
python scripts/revoke.py --account [<adapter>:]<key>  # kill-switch: revoke ALL the
                                                      #   account's tokens (bare key = garmin)
python scripts/revoke.py --account <key> --purge      # + delete stored account & usage
python scripts/revoke.py --device <hash-prefix>       # revoke ONE device (prefix from status.py)
python scripts/usage.py                               # per-account tool usage + leaderboard
python scripts/usage.py --account [<adapter>:]<key>   # one account's per-tool breakdown
python scripts/subscribers.py                         # newsletter signups + suggestions
python scripts/subscribers.py --emails                # subscriber emails, one per line
python scripts/daily_report.py                        # yesterday's new/active/total users (print)
python scripts/daily_report.py --post                 # + POST it to Slack ($SLACK_WEBHOOK_URL)
python scripts/add_beer.py --email <supporter>        # record a "buy me a beer" donation (1 beer, 5 EUR)
python scripts/add_beer.py --email <supporter> --beers 3 --at 2026-07-20  # 3 beers, backdated
```

`scripts/session_loss.py` works on Railway logs instead (`railway logs --json`
output, see its docstring): the share of garmin calls failing on a lost MCP
session (404), overall and within 5 s of a worker start — the before/after
measure for `GARMIN_MCP_STATELESS_HTTP`.

The gateway also posts this daily user-stats report to Slack on its own each
morning (`DAILY_REPORT_HOUR`, default 08:00 `DAILY_REPORT_TZ`) when
`SLACK_WEBHOOK_URL` is set; `scripts/daily_report.py` runs the same report on
demand for testing.

**Mail campaigns** — one-off announcements to users and newsletter
subscribers, sent through Cloudflare Email Sending (`MAIL_*` env above). The
operator creates and starts a campaign; the gateway drains it on its own, a
batch per minute, at most `MAIL_DAILY_CAP` a day, most active users first —
a large list simply spreads over several days.

```bash
# text lives in the repo: campaigns/<slug>.txt ("Subject: ..." line, blank line, body)
python scripts/campaign.py create <slug>                  # snapshot text + enqueue everyone not unsubscribed
python scripts/campaign.py create <slug> --audience users # or: subscribers
python scripts/campaign.py test <slug> --to <you>         # one real send, not recorded
python scripts/campaign.py start <slug>                   # the gateway starts sending
python scripts/campaign.py pause <slug>
python scripts/campaign.py status [<slug>]                # counts + sent in last 24h + ETA (no addresses)
python scripts/campaign.py status <slug> --unknown        # + addresses whose send is unknown
python scripts/campaign.py requeue-unknown <slug>         # decided to send those again
python scripts/campaign.py requeue-failed <slug>          # retry the failed ones (attempts reset)
python scripts/campaign.py unsubscribe <email>            # manual opt-out (e.g. from a reply)
```

Every recipient is a row in a send ledger, so nobody gets a campaign twice: a
send is recorded as `sending` *before* the API call, and a crash or an
ambiguous API failure (timeout, 5xx) parks it as `unknown` for the operator
instead of retrying blindly (and counts toward the daily cap). A rejection of
one address (400/422) retries that address up to 3 times without holding up
the rest; an account-wide error (bad token, quota, rate limit) charges nobody
and pauses the mailer for 15 min. An address that unsubscribed is dropped
right before every send, requeues included. Each mail carries an unsubscribe link plus RFC 8058 one-click
`List-Unsubscribe` headers (`/unsubscribe` — GET only confirms, POST
unsubscribes); an opt-out is global and drops the address from every campaign.
A campaign auto-pauses if hard bounces exceed 5% (judged after 50 sends).
Progress is reported **only** as log events — `campaign-batch`,
`campaign-daily-cap`, `campaign-auto-paused`, `campaign-done`,
`campaign-send-unknown`, `campaign-run-failed` — never by mail.

**Daily triage** — a GitHub Actions workflow
(`.github/workflows/daily-triage.yml`) runs `scripts/daily_triage.py` every
morning (~07:45 Prague): it pulls the last 24 h of error/warn rows from the
gateway's Railway logs, classifies the known error signatures
deterministically, and — only when something actionable remains — has Claude
write the operator's triage (what happened → what it means → proposed action,
per class) and posts it to Slack. Healthy days post a one-line "all quiet"
(the daily heartbeat); if the analysis fails, the deterministic aggregate
table posts instead — never silence. The analysis runs on the operator's
Claude subscription via headless Claude Code (repo secret
`CLAUDE_CODE_OAUTH_TOKEN`, minted with `claude setup-token`); an
`ANTHROPIC_API_KEY` secret works as the fallback backend. Also needs
`RAILWAY_API_TOKEN` + `SLACK_WEBHOOK_URL` (already present for the hourly
pager). Run by hand with `python scripts/daily_triage.py --dry-run` (needs the
`RAILWAY_*` env; the analysis step degrades gracefully without a token).

**Hourly hard-signal pager** — a GitHub Actions workflow
(`.github/workflows/hourly-digest.yml`) runs `scripts/hourly_digest.py` every
hour: it reads the last 60 min of the gateway's Railway logs via the Railway
API, does a liveness probe, and pages (`<!here>`) **only** on a hard signal —
a failed probe (site down), `worker-start-failed` across ≥2 distinct accounts
in the hour (the broken-image signature), any 5xx, any `critical`, or a
sign-in egress whose every `sso-probe` in the hour (≥2) failed to connect
(needs `SSO_PROBE_INTERVAL` ≤ 1800 s; fetched with its own log filter). It is
otherwise fully silent — plain error volume belongs to the daily triage.
Requires repo secrets `RAILWAY_API_TOKEN` + `SLACK_WEBHOOK_URL`
(service/environment ids are set as workflow env). `RAILWAY_API_TOKEN` may be a
Railway **project** token (narrowest scope — reaches only this project; sent via
the `Project-Access-Token` header) or an account/workspace token (sent as
`Authorization: Bearer`); the script tries both. Run it by hand with
`python scripts/hourly_digest.py --dry-run` (needs `RAILWAY_API_TOKEN`,
`RAILWAY_SERVICE_ID`, `RAILWAY_ENVIRONMENT_ID` in the environment).

**PostHog telemetry** — with `POSTHOG_API_KEY` set (see the env table), the
gateway also ships analytics to PostHog (EU cloud; design:
`docs/superpowers/specs/2026-07-20-posthog-telemetry-design.md`):
per-request `$mcp_*` events (PostHog's built-in MCP analytics), a lean
connect-funnel/conversion event set, an OTLP tee of the structured log stream
(PostHog Logs, only with `POSTHOG_LOGS=true` — Railway stays the durable archive), and posthog-js on the
site (UTM campaign attribution; autocapture disabled on OAuth pages). Egress
rule: identity + metadata only — never MCP bodies, credentials, or form
contents; the account email travels only as `distinct_id`. Everything is
fire-and-forget: a PostHog outage never blocks a request. The Slack reports
above keep running unchanged — PostHog complements them. When off-boarding a
user (`revoke.py --purge`), also delete the person in PostHog (People → delete)
to complete the GDPR path.

**Beer supporters** — `scripts/add_beer.py` records a "buy me a beer" donation
(`buymeacoffee.com/venik`) into a local `beers` audit table and emits a
`beer_purchased` PostHog event, best-effort attributed to the supporter's
gateway account (`matched` when the email is a known login). The event is meant to
feed the operator's connect→paying funnel and "beers this month" metric on the
Growth dashboard — those PostHog insights are **set up manually** and don't exist
until built. Ingestion is manual for now (BMC automation deferred; design:
`docs/superpowers/specs/2026-07-24-beer-supporters.md`). Same egress rule as
above — the email travels only as `distinct_id`, never the supporter name or
note.

**With Docker** the scripts are baked into the image at `/app/scripts`; run them
inside the container. `status.py` finds the DB under `/data` automatically:

```bash
docker exec missingmcp python /app/scripts/status.py
docker logs -f missingmcp                   # live structured-JSON events
```

**On Railway** run them over `railway ssh`; logs live in the Railway dashboard
(`railway logs --service gateway` for a live tail):

```bash
railway ssh --service gateway "python3 /app/scripts/status.py"
railway ssh --service gateway "python3 /app/scripts/revoke.py --account <email>"
```

All logging is structured JSON on stdout (one event per line) with a proper
`level` attribute — including uvicorn/stdlib records (event `stdlib-log`) and
each worker's own output (event `worker-log`, with an `account` attribute;
lines matching ERROR/Traceback are elevated to error severity). On Railway
that makes everything searchable in the log explorer — filter e.g.
`@event:worker-log @account:<email>` to trace one user's worker, or
`@level:error` for problems. Request latency is recorded per call in the
`mcp-response` event (`ttfb_ms`, `total_ms`, `bytes`, `tool`, `account`);
login/verify and worker-spawn events carry `ms` durations. The gateway also
logs a `stats` event (accounts / tokens / people-with-token / clients /
active-workers) on startup and whenever those counts change, and `status.py`
lists the running workers.

### Automatic data hygiene

The gateway keeps its own DB tidy — no manual grooming needed. Alongside expiring
old auth codes and access tokens, the background loop (roughly once a minute):

- **sweeps abandoned OAuth clients** — Claude registers a fresh client (DCR) on
  every connection attempt, and one that never completes the flow leaves a
  token-less client behind. Any client with **zero access tokens** older than one
  hour (comfortably above the 10-min code lifetime, so an in-progress sign-in is
  never touched) is removed. This is why `status.py`'s OAuth-client count tracks
  the number of connected devices rather than growing with every failed attempt.
  Revoking a device also leaves its client token-less, so it's swept the same way.
- **purges retired-adapter data** — if a connector is ever dropped, all its rows
  (accounts, tokens, clients, codes, usage) are deleted across the board. The
  retired set is an **explicit** list in the code, never inferred from
  configuration, so a missing env var can't accidentally wipe a live connector.

Both are logged only when they actually delete something — `cleanup-orphan-clients`
(`count`) and `cleanup-dead-adapter` (`adapter` + per-table counts) — so a quiet
log means there was nothing to clean. The one-hour threshold is a fixed constant,
not an env var, by design.

## How it works

1. Claude registers a client (DCR) and starts OAuth 2.1 (Authorization Code + PKCE).
2. On the authorize page the user signs in with Garmin (email + password, + MFA if
   prompted). The gateway logs in via `garminconnect`, stores **only the resulting
   tokens** (encrypted), and discards the password.
3. Claude exchanges the code for a Bearer token.
4. On each `/garmin/mcp` call the gateway ensures the user's `garmin_mcp` worker is running
   (its own tokens, bound to `127.0.0.1`) and reverse-proxies to it.

Adapters using the remote strategy replace steps 2 and 4 with a probe-verify
against the upstream MCP and a direct header-injected forward — no worker.

Adapters using an upstream-OAuth login (whoop) replace step 2 with a redirect
to the provider's own OAuth page; the provider calls back with tokens, which
the gateway verifies and persists the same way (verify-then-persist is
unchanged). Adapters using the local strategy (whoop) replace step 4: the
request is handled in-process — no worker, no shared upstream — and the
gateway refreshes the account's rotating WHOOP tokens itself as needed.

## Security

- Garmin password is never persisted; WHOOP passwords are never even seen
  (sign-in happens on WHOOP's own OAuth page, read-only scopes).
- Tokens encrypted at rest (AES-256-GCM); the DB is useless without `GATEWAY_SECRET`.
- A member revoking the app at WHOOP is detected on the next refresh and their
  stored tokens are purged automatically.
- Bearer tokens stored only as SHA-256 hashes.
- OAuth 2.1 PKCE (S256), one-time 10-min codes, CSRF on forms, per-IP/-token rate limits.
- Workers bind `127.0.0.1` only; `garmin_mcp` is pinned to a reviewed commit.

> Deploy only on infrastructure you control and trust. Back up `DATA_DIR`; keep
> `GATEWAY_SECRET` separately.

## Before you deploy

- **Set a real random `GATEWAY_SECRET`** (`openssl rand -base64 48`) — the app
  refuses to start with the placeholder from `.env.example`.
- **Pin `GARMIN_MCP_REF` to a reviewed commit SHA** — `main` is a floating ref that
  can change without notice (supply-chain).
- **Revoking access** — access tokens expire after `ACCESS_TOKEN_TTL_DAYS` (default
  90; the user just re-authenticates in Claude). To revoke sooner — a leaked token
  or a removed user — run `python scripts/revoke.py --account [<adapter>:]<email>` (kill-switch
  for all of that account's tokens). A single device can be revoked with `--device <hash-prefix>` (prefixes are shown by `status.py`).
- **Run a manual end-to-end smoke test** with a real Garmin account (including the
  MFA path) before connecting real users — the upstream is mocked in the
  automated tests.

## Support

If this gateway is useful to you, you can [buy me a beer 🍺](https://buymeacoffee.com/venik).

## License

[MIT](LICENSE) © 2026 Vaclav Slajs

## Acknowledgements

Wraps the excellent [`garmin_mcp`](https://github.com/Taxuspt/garmin_mcp) by Taxuspt,
unmodified. Garmin and Garmin Connect are trademarks of Garmin Ltd.; this project is
not affiliated with or endorsed by Garmin.