health-export-mcp 1.7.3 → 1.9.0

package/AGENTS.md

@@ -17,15 +17,19 @@ After configuring, restart the client and ask: **"Use health-export: what's my H
 
 ## Claude Code
 
-One command, no clone:
+One command, no clone, no environment variable on a Mac (1.7.3 finds the app's iCloud Drive folder itself):
 
 ```bash
-claude mcp add --transport stdio health-export \
-  --env "HEALTH_DATA_DIR=$HOME/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents" \
-  -- npx -y health-export-mcp
+claude mcp add health-export -- npx -y health-export-mcp
 ```
 
-Keep the double quotes (the folder name contains a space). Add `--scope user` to use it in every project. No export yet: `claude mcp add --transport stdio health-export-demo -- npx -y health-export-mcp --demo` serves synthetic data.
+Windows, Linux, or an export outside iCloud Drive:
+
+```bash
+claude mcp add health-export --env "HEALTH_DATA_DIR=/path/to/folder" -- npx -y health-export-mcp
+```
+
+Keep the double quotes if the path has a space. Add `--scope user` to use it in every project. No export yet: `claude mcp add health-export-demo -- npx -y health-export-mcp --demo` serves synthetic data. If Agent pairing is on, do not pass `PAIRING_SECRET` on the command line (shell history, `ps`); add it to the entry's `env` in the config file.
 
 ## Claude Desktop
 
@@ -56,7 +60,7 @@ Run `node gen-deeplinks.mjs` and open the generated VS Code link, or add the ser
 
 ## opencode
 
-`opencode.json` (project root) or `~/.config/opencode/opencode.json`:
+`opencode.json` (project root) or `~/.config/opencode/opencode.json`. Drop the `environment` line on a Mac using iCloud Drive; for a pinned checkout use `["node", "/ABSOLUTE/PATH/TO/server.mjs"]`:
 
 ```json
 {
@@ -64,9 +68,9 @@ Run `node gen-deeplinks.mjs` and open the generated VS Code link, or add the ser
   "mcp": {
     "health-export": {
       "type": "local",
-      "command": ["node", "/ABSOLUTE/PATH/TO/health-export-mcp/server.mjs"],
+      "command": ["npx", "-y", "health-export-mcp"],
       "enabled": true,
-      "environment": { "HEALTH_DATA_DIR": "~/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents" }
+      "environment": { "HEALTH_DATA_DIR": "/path/to/folder" }
     }
   }
 }
@@ -74,15 +78,15 @@ Run `node gen-deeplinks.mjs` and open the generated VS Code link, or add the ser
 
 ## OpenClaw
 
-Add the `health-export` block (same shape as Claude Desktop's `mcpServers` entry) to your OpenClaw MCP servers config, then reload.
+Add the `health-export` block (same shape as Claude Desktop's `mcpServers` entry: command `npx`, args `["-y", "health-export-mcp"]`, plus `HEALTH_DATA_DIR` off a Mac) to your OpenClaw MCP servers config, then reload.
 
 ## Hermes
 
-Add the `health-export` block to your Hermes agent's MCP servers config, then restart the daemon.
+Add the same `health-export` block to your Hermes agent's MCP servers config, then restart the daemon.
 
 ## Non-MCP clients, ChatGPT · Gemini · Grok · n8n · Home Assistant
 
-These don't speak MCP, so they don't use this server. Instead, the [MetricBridge](https://www.healthexport.dev) app **POSTs your data to a webhook** (or your own endpoint) and your automation/agent reads that JSON. Every delivery is token-authenticated.
+ChatGPT connects only to remote MCP servers (OpenAI's help centre: "Can I connect to a local MCP server? Not directly", checked 2026-10-27), and the others don't run local MCP servers either, so they don't use this one. Instead, the [MetricBridge](https://www.healthexport.dev) app **POSTs your data to a webhook** (or your own endpoint) and your automation/agent reads that JSON. Every delivery is token-authenticated.
 
 ---
 

package/README.md

@@ -1,6 +1,6 @@
 # health-export-mcp
 
-**An MCP server for your own Apple Health data.** 194 metrics, 16 read-only tools and 22 prompts over local stdio, with zero dependencies, no account and no server of ours in the path. Your agent gets JSON with units, date ranges and coverage, and answers from your numbers.
+**An MCP server for your own Apple Health data.** 194 metrics, 21 tools (19 read-only, plus two that log events to their own file) and 23 prompts over local stdio, with zero dependencies, no account and no server of ours in the path. Your agent gets JSON with units, date ranges and coverage, and answers from your numbers.
 
 <p align="center">
   <a href="https://www.npmjs.com/package/health-export-mcp"><img alt="npm" src="https://img.shields.io/npm/v/health-export-mcp?color=cb3837" /></a>
@@ -11,35 +11,34 @@
   <a href="https://glama.ai/mcp/servers/PhilipAD/health-export-mcp"><img alt="Glama score" src="https://glama.ai/mcp/servers/PhilipAD/health-export-mcp/badges/score.svg" /></a>
 </p>
 
-## Try it in 30 seconds (no iPhone, synthetic data)
+Docs and per-client config: **[healthexport.dev/mcp](https://www.healthexport.dev/mcp/)** · agents can run the setup from **[SKILL.md](https://www.healthexport.dev/SKILL.md)** · privacy: the server reads a local file and makes no network requests, so your health data never reaches us or a cloud AI through it.
+
+## Install: one command
 
 ```bash
-claude mcp add --transport stdio health-export-demo -- npx -y health-export-mcp --demo
+claude mcp add health-export -- npx -y health-export-mcp
 ```
 
-Ask *"Use health-export-demo: how did my HRV this week compare with last week?"* The tool call returns this (every demo answer is watermarked):
+On a Mac that is the whole install: since 1.7.3 the server finds the MetricBridge app's iCloud Drive folder by itself. On Windows or Linux, or for an export in another folder, add `--env "HEALTH_DATA_DIR=/path/to/folder"` before the `--`. Needs Node.js 18 or later. **Claude Desktop:** open [`health-export.mcpb`](https://github.com/PhilipAD/health-export-mcp/releases/latest/download/health-export.mcpb) instead (no JSON, no Node on your PATH). Cursor, VS Code, opencode, OpenClaw, Hermes: [AGENTS.md](AGENTS.md).
+
+Then ask *"Use health-export: how did my HRV this week compare with last week?"* The agent calls `get_trends` and gets numbers that carry their own provenance: unit, exact date ranges, whether each window was complete, and how much history the export holds. This is the real output on 1.7.3 (from the built-in `--demo` dataset, which is synthetic so it can be published; a real export answers with the same fields and without the watermark):
 
 ```json
 [SYNTHETIC DEMO DATA] {"metric":"heart_rate_variability","unit":"ms","window":7,"recent":50.859,"prior":51.306,
- "changePercent":-0.871,"direction":"flat","recentRange":{"from":"2026-08-12","to":"2026-08-18"},
- "windowSatisfied":true,"coverage":{"firstDate":"2025-07-15","lastDate":"2026-08-18","days":400}}
+ "change":-0.447,"changePercent":-0.871,"direction":"flat","recentRange":{"from":"2026-08-12","to":"2026-08-18"},
+ "recentDays":7,"priorDays":7,"windowSatisfied":true,"coverage":{"firstDate":"2025-07-15","lastDate":"2026-08-18","days":400}}
 ```
 
-## Use your real data (about 5 minutes, needs an iPhone)
+**No iPhone yet?** `claude mcp add health-export-demo -- npx -y health-export-mcp --demo` serves that watermarked synthetic dataset, so you can try every tool in 30 seconds before installing anything on a phone.
 
-1. **Export.** Install [MetricBridge](https://apps.apple.com/app/apple-store/id6784185201?pt=129083290&ct=githubreadme&mt=8&ppid=2c28f88a-d94f-48f9-8e6a-74a8d89ce66e) on the iPhone, allow Health read access and tap **Export now**. It writes `.health-cache.json` to iCloud Drive (or a folder, or your LAN). The app has a free trial, then one purchase, no subscription. This server is MIT and free.
-2. **Connect.** Claude Code:
-   ```bash
-   claude mcp add --transport stdio health-export -- npx -y health-export-mcp
-   ```
-   On a Mac the server finds the app's iCloud Drive folder by itself (since 1.7.3). Elsewhere, or for another folder, add `--env "HEALTH_DATA_DIR=/path/to/folder"`, with the quotes if the path has a space.
-   **Claude Desktop:** download [`health-export.mcpb`](https://github.com/PhilipAD/health-export-mcp/releases/latest/download/health-export.mcpb) and open it; no JSON and no Node on your PATH needed. Cursor, VS Code, opencode, OpenClaw and Hermes: see [AGENTS.md](AGENTS.md) and the [quickstart](#connect-apple-health-to-your-ai-agent-quickstart).
-3. **Check it arrived.** `npx -y health-export-mcp --doctor` prints the folder it chose and why, each file's age, and freshness. iCloud can take a few minutes to bring a new export to the Mac.
+## Use your real data (about 5 minutes the first time, needs an iPhone)
 
-Then ask *"Use health-export: compare my resting heart rate this month with last month."*
+1. **Export.** Install [MetricBridge](https://apps.apple.com/app/apple-store/id6784185201?pt=129083290&ct=githubreadme&mt=8&ppid=2c28f88a-d94f-48f9-8e6a-74a8d89ce66e) on the iPhone, allow Health read access and tap **Export now**. It writes `.health-cache.json` to iCloud Drive (or a folder, or your LAN). The app has a 7-day free trial, then one purchase ($24.99), no subscription. This server is MIT and free.
+2. **Connect.** The one command above (Claude Code), the `.mcpb` (Claude Desktop), or the block for your client in [AGENTS.md](AGENTS.md).
+3. **Check it arrived.** `npx -y health-export-mcp --doctor` prints the folder it chose and why, each file's age, and freshness. iCloud can take a few minutes to bring a new export to the Mac.
 
 <p align="center">
-  <img src="assets/architecture.svg" alt="Apple Health exports to iCloud, a folder, or your LAN; health-export-mcp reads it and serves 16 query tools to your AI agent" width="100%" />
+  <img src="assets/architecture.svg" alt="Apple Health exports to iCloud, a folder, or your LAN; health-export-mcp reads it and serves 21 tools to your AI agent" width="100%" />
 </p>
 
 ---
@@ -83,12 +82,12 @@ The companion iOS app **[MetricBridge](https://www.healthexport.dev)** exports y
 **Fastest, one command (Claude Code):**
 
 ```bash
-claude mcp add --transport stdio health-export \
-  --env "HEALTH_DATA_DIR=$HOME/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents" \
-  -- npx -y health-export-mcp
+claude mcp add health-export -- npx -y health-export-mcp
+# Windows, Linux, or an export outside iCloud Drive:
+claude mcp add health-export --env "HEALTH_DATA_DIR=/path/to/folder" -- npx -y health-export-mcp
 ```
 
-Everything before `--` is an option for `claude mcp add`, everything after it is the command that starts the server. The path is double-quoted because the iCloud folder name contains a space, and `$HOME` is used because a quoted `~` is not expanded by the shell. Exporting somewhere else? Replace the path with your own folder. Add `--scope user` to make the server available in every project (the default scope is the current project only). Check it with `claude mcp list`.
+Everything before `--` is an option for `claude mcp add`, everything after it is the command that starts the server. On a Mac the server reads the app's iCloud Drive folder when `HEALTH_DATA_DIR` is unset (1.7.3+); if you set it to that folder by hand, double-quote it (the folder name contains a space) and use `$HOME`, because a quoted `~` is not expanded by the shell. Add `--scope user` to make the server available in every project (the default scope is the current project only). Check it with `claude mcp list`.
 
 **Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`), and any client that takes an `mcpServers` block:
 
@@ -97,14 +96,13 @@ Everything before `--` is an option for `claude mcp add`, everything after it is
   "mcpServers": {
     "health-export": {
       "command": "npx",
-      "args": ["-y", "health-export-mcp"],
-      "env": { "HEALTH_DATA_DIR": "~/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents" }
+      "args": ["-y", "health-export-mcp"]
     }
   }
 }
 ```
 
-> `npx -y` fetches the published package at run time without an install prompt (npm verifies package integrity), so it runs anywhere with no clone or absolute path. The server expands a leading `~` in `HEALTH_DATA_DIR` itself, so the JSON form can keep it. Prefer to pin a vetted local checkout instead? Use `"command": "node", "args": ["REPLACE_WITH_ABSOLUTE_PATH/server.mjs"]`, get the path with `node -e "console.log(process.cwd()+'/server.mjs')"` inside the repo.
+> Off a Mac, or for another folder, add `"env": { "HEALTH_DATA_DIR": "/path/to/folder" }` to the entry (a leading `~` is expanded by the server). `npx -y` fetches the published package at run time without an install prompt (npm verifies package integrity), so it runs anywhere with no clone or absolute path. The server expands a leading `~` in `HEALTH_DATA_DIR` itself, so the JSON form can keep it. Prefer to pin a vetted local checkout instead? Use `"command": "node", "args": ["REPLACE_WITH_ABSOLUTE_PATH/server.mjs"]`, get the path with `node -e "console.log(process.cwd()+'/server.mjs')"` inside the repo.
 > Or skip JSON entirely, drag **`health-export.mcpb`** into **Claude Desktop → Settings → Extensions**.
 
 **Auto-configure from a clone:**
@@ -144,26 +142,31 @@ Restart the client and try:
 
 ---
 
-## The 16 MCP tools
+## The 21 MCP tools
 
 Full reference with request/response examples: **[healthexport.dev/mcp](https://www.healthexport.dev/mcp/#tools)**.
 
 | Tool | What it does |
 |---|---|
 | `get_mcp_status` | Health check: source, metric/workout counts, which context files exist, latest data date, and a `freshness` summary. **Call first.** |
-| `get_freshness` | How current the export is: `stale` against a stated threshold (26 h by default, `HEALTH_STALE_AFTER_HOURS`, or `maxAgeHours`), `age_hours`, `as_of`, `last_data_date`, per-file write times. Same rule as the `status --max-age` cron gate. |
+| `get_freshness` | How current the export is: `stale` judged on the core files (daily cache, sleep sessions) against a stated threshold (26 h by default, `HEALTH_STALE_AFTER_HOURS`, or `maxAgeHours`), `age_hours`, `as_of`, `last_data_date`, per-file write times. `state: "stale_copy"` (with a `stale_copy` list) when the phone's `.health-manifest.json` or iCloud says this Mac holds an older copy of a core file than the phone wrote. Same rule as the `status --max-age` cron gate. |
 | `list_metrics` | Every available metric with unit, day count, and date range. |
-| `get_health_metrics` | Daily values for a metric (or all) over a date range + an aggregate (avg/sum/min/max/latest). Supports `filterDays` (restrict to days covered by logged events, with `negate`). |
+| `get_health_metrics` | Daily values for a metric (or all) over a date range + an aggregate (avg/sum/min/max/latest). Supports `filterDays` (restrict to days covered by logged events, with `negate`). Blood pressure at day granularity also lists the individual `readings` (`health-readings.json`). |
 | `get_trends` | Recent N-day window vs the prior N days: change, % change, direction. Supports `excludeTravelDays`. |
 | `compare_periods` | A metric across two arbitrary date periods (A vs B), or around a logged event via `anchor: {eventId, days}` (the event day excluded from both sides). |
 | `get_structured_export` | Clean JSON for chosen metrics/range, paginated with a cursor. |
-| `get_intraday` | Today's hour-by-hour window from the app's hourly automations (`health-intraday.json`, app 1.4+), replaced each run. |
+| `get_intraday` | The hour-by-hour window from the app's hourly automations (`health-intraday.json`, app 1.4+): yesterday and today, replaced each run, with each hour's `Min`/`Max` for discrete metrics when the app writes them. |
 | `query_health_data` | Natural-language convenience: *"average HRV last month"* routed to structured results. |
-| `list_events` | Logged context events (medication, habit, visit, life, shift, episode, travel) with type/tag/date filters. |
+| `list_events` | Logged context events (medication, habit, visit, life, shift, episode, travel) with type/tag/date filters, from the app and from `add_event`, each labelled `source: "app"` or `"agent"`. |
+| `add_event` | Log an event the user states (a medication start, a trip) into `health-events-agent.json`, the one file this server writes. Idempotent by `clientEventId`. |
+| `remove_event` | Remove an event logged with `add_event`. Events logged in the iOS app are edited there. |
 | `get_profile` | Opted-in context fields (conditions, medications, goals, allergies, notes) plus `presentFields`. Absent fields were withheld, never "none". |
 | `get_workouts` | Workouts by activity/date with pagination; includes heart rate, running dynamics, cycling power, intervals and `hasRoute` when exported. |
-| `get_sleep_sessions` | Clustered sleep sessions attributed to the waking day; split nights returned as-is. |
+| `get_sleep_sessions` | Clustered sleep sessions attributed to the waking day; split nights returned as separate sessions, duplicate copies of one night collapsed (`collapsedDuplicates`). |
+| `get_strength_log` | The strength log typed into the iOS app (`health-strength.json`, opt-in, off by default): each session with every set as entered, `volumeKg`, `workingSets`, an Epley `bestEstimateKg` per exercise, all-time records, and the user's saved routines. Filter by `exercise`, `start`, `end`. Missing file → `available:false`. |
+| `get_check_ins` | Morning check-ins the user chose to share (`health-check-ins.json`, off by default in the app): self-rated feeling 1 to 5, note, intention and whether it happened, plus a summary. A self-rating, not a measurement. |
 | `get_cycle_context` | Day-in-cycle and coarse phase derived from logged period starts. Never predictive. |
+| `list_tags` | Tags logged in the app (`health-tags.json`, opt-in there and off by default): lifestyle tags and supplements by name, never an amount. `{kind: all, supplement or lifestyle, start, end}`; one row per tag plus the names per day. |
 | `correlate_metrics` | Pearson correlation between two metrics with a 0..3 day lag. Association, not causation, always stated. |
 | `resolve_metric` | Canonical name and unit for any spelling (`steps`, `StepCount`, `Body Weight`, `hrv`), unit variants with exact formulas, an optional `{value, unit}` conversion, and whether the export holds it. Ambiguous words come back with candidates, never guessed. The data tools accept the same aliases and report `resolvedFrom`. When the export carries per-source attribution (app builds that write `src`/`by` on daily points and a `health-sources.json`, cache schema minor 2), the answer adds a `sources` block naming the devices that fed the export, which one won each metric and the priority rules, and `sourceMerge` reports disagreement as visible; older exports report it as not available. |
 
@@ -171,23 +174,23 @@ Full reference with request/response examples: **[healthexport.dev/mcp](https://
 
 ### Data files
 
-The daily cache (`.health-cache.json`) and workouts cache are joined by optional context files, all read-only and all optional: `health-events.json` (the logging surface), `health-profile.json` (opt-in context), `health-sessions.json` (sleep sessions), `health-cycles.json` (observed cycle starts), `health-days.json` (timezone change log). An absent file is reported as `available:false` with a note, never as "no data". Formats: [docs/SCHEMA-CONTRACTS.md](docs/SCHEMA-CONTRACTS.md).
+The daily cache (`.health-cache.json`) and workouts cache are joined by optional context files, all optional: `health-events.json` (the logging surface), `health-profile.json` (opt-in context), `health-sessions.json` (sleep sessions), `health-cycles.json` (observed cycle starts), `health-days.json` (timezone change log), `health-readings.json` (individual blood pressure readings), `health-check-ins.json` (morning check-ins, opt-in), `health-strength.json` (the strength log, when its export is switched on), `health-tags.json` (logged tags with supplements marked, opt-in in the app) and `.health-manifest.json` (what the phone last wrote, for the stale-copy check). The server reads all of them and writes only `health-events-agent.json` (events logged with `add_event`). An absent file is reported as `available:false` with a note, never as "no data". Formats: [docs/SCHEMA-CONTRACTS.md](docs/SCHEMA-CONTRACTS.md).
 
-Two patterns worth knowing: [query a parent's Apple Health from your own AI](docs/caregiver-setup.md) (consent-first, the parent's phone is the authority) and [logging data into Apple Health via Shortcuts](docs/shortcuts-write-bridge.md) (the server and app stay strictly read-only).
+Two patterns worth knowing: [query a parent's Apple Health from your own AI](docs/caregiver-setup.md) (consent-first, the parent's phone is the authority) and [logging data into Apple Health via Shortcuts](docs/shortcuts-write-bridge.md) (the server never writes to Apple Health).
 
 ### MCP prompts
 
-The server ships 22 prompts over `prompts/list` / `prompts/get`: daily brief, weekly review, doctor visit prep, what changed since my last visit, sleep quality and regularity, HRV trend, training and race week reviews, zone minutes, n-of-1 experiment, medication before/after, GLP-1 dose-step compare, sobriety milestone, shift block compare, travel-honest monthly review, cycle-aware trend read, caregiver check-in, glucose day summary, long-term activity narrative, data coverage audit, and a profile-aware context bootstrap. Every prompt leads with coverage honesty and never turns data into diagnosis.
+The server ships 23 prompts over `prompts/list` / `prompts/get`: daily brief, weekly review, doctor visit prep, what changed since my last visit, sleep quality and regularity, HRV trend, training and race week reviews, zone minutes, n-of-1 experiment, medication before/after, GLP-1 dose-step compare, sobriety milestone, shift block compare, travel-honest monthly review, cycle-aware trend read, caregiver check-in, glucose day summary, long-term activity narrative, data coverage audit, a nutrition week summary, and a profile-aware context bootstrap. Every prompt leads with coverage honesty and never turns data into diagnosis.
 
 ### Demo mode
 
-`node server.mjs --demo` (or `HEALTH_DEMO=1`) serves a deterministic synthetic dataset: ~15 metrics over 400 days, 30 workouts with intervals, 8 events, a profile, 60 sleep sessions, cycle starts and a timezone change, anchored to a fixed date with a seeded PRNG. Every answer carries `demo: true` and a `[SYNTHETIC DEMO DATA]` text prefix, so demo output can never pass for a real export.
+`node server.mjs --demo` (or `HEALTH_DEMO=1`) serves a deterministic synthetic dataset: ~15 metrics over 400 days, 30 workouts with intervals, 8 events, a profile, 60 sleep sessions, cycle starts, a timezone change and 30 days of tags, anchored to a fixed date with a seeded PRNG. Every answer carries `demo: true` and a `[SYNTHETIC DEMO DATA]` text prefix, so demo output can never pass for a real export.
 
 ### CLI
 
 ```bash
 node server.mjs --doctor            # diagnostics: files, sizes, schema, freshness, pairing
-node server.mjs status --max-age 24 # exit 0 if data is fresh, 1 if stale (cron gate)
+node server.mjs status --max-age 24 # exit 0 if data is fresh, 1 if stale or a stale iCloud copy (cron gate)
 node server.mjs receive             # standalone LAN receiver (binds 127.0.0.1 by default)
 node server.mjs --help
 ```
@@ -251,7 +254,7 @@ with exactly two shapes: `{"state": "trial", "daysRemaining": N}` or `{"state":
 export from a trial adds one sentence to `get_freshness` naming when the trial ends; an unlocked export
 adds nothing. No network call is involved and nothing is sent anywhere.
 
-- **Read-only.** The server only reads your exported data, it never touches HealthKit and never writes back.
+- **Reads your export, never Apple Health.** The server never touches HealthKit. Its only write is `health-events-agent.json`, the events an agent logs with `add_event` / `remove_event`; it never modifies a file the app writes. Both tools are refused in demo mode and on a read-only folder, and the file is sealed like the rest of an encrypted export.
 - **Local-first.** It runs on your machine over stdio. There is **no developer server** in the path.
 - **Optional pairing.** Set `PAIRING_SECRET` to the code the iOS app shows (Settings → Agent pairing) to gate access.
 - **Encrypted exports (optional).** If you switch on Export encryption in the iOS app, set `HEALTH_EXPORT_PASSPHRASE` (or `HEALTH_EXPORT_PASSPHRASE_FILE`) to the same passphrase and the server decrypts on your machine. See [Encrypted exports](#encrypted-exports).
@@ -352,6 +355,7 @@ For your own data, yes: the server reads the file the MetricBridge app writes an
 - **"No metrics found":** run `npx -y health-export-mcp --doctor`. It prints the folder the server chose and why (`HEALTH_DATA_DIR`, the iCloud default on a Mac, or the current directory) and whether `.health-cache.json` is there. Confirm the app has exported at least once; `get_mcp_status` shows the same source and the latest date.
 - **Server not visible in the client:** run `npx -y health-export-mcp --doctor` in a terminal. If it works there, the client can't find `npx` (common for Claude Desktop with Node from nvm or Homebrew): use the `.mcpb`, or set `"command"` to the full path from `which npx`. Then fully quit and reopen the client.
 - **Exports stopped after a week:** the app's free trial ended. `get_freshness` reports the export as stale and links the unlock page; once the app is unlocked, exports resume with no change on this side.
+- **Answers miss last night, or `state: "stale_copy"`:** this Mac's iCloud Drive has an older copy of the export than the phone wrote. Wait a few minutes, or open the MetricBridge folder in iCloud Drive in Finder and choose Download Now on the file (Remove Download drops only this Mac's local copy, and it downloads again). `--doctor` lists each stale copy.
 - **Locked data error:** the export file is protected until first unlock after reboot; unlock your device once.
 
 ---
@@ -372,7 +376,7 @@ stdio transport (newline-delimited JSON-RPC 2.0), the universal MCP transport. O
 
 ## How it works
 
-The iOS app reads Apple Health (read-only) and writes a compact `.health-cache.json` (plus optional context files) to the destination you choose. This server reads those files and exposes the 16 tools above over MCP. No bridge, no Docker, no database: just files and stdio.
+The iOS app reads Apple Health (read-only) and writes a compact `.health-cache.json` (plus optional context files) to the destination you choose. This server reads those files and exposes the 21 tools above over MCP. No bridge, no Docker, no database: just files and stdio.
 
 ```
 Apple Health → MetricBridge (iOS) → .health-cache.json → health-export-mcp → MCP client → you
@@ -388,7 +392,7 @@ Other Apple Health MCP servers in the ecosystem, worth a look depending on your
 - **[the-momentum/apple-health-mcp-server](https://github.com/the-momentum/apple-health-mcp-server):** an MCP server for analyzing Apple Health data exported from the Health app.
 - **[HealthyApps/health-auto-export-mcp-server](https://github.com/HealthyApps/health-auto-export-mcp-server):** an MCP server for the Health Auto Export app's data.
 
-**How `health-export-mcp` differs:** the iPhone app keeps the export current in the background, so there's no manual `export.xml` and no re-import; the server has zero dependencies and needs no Docker, database or Mac app; every answer carries its units, date range and coverage; and it's read-only end to end.
+**How `health-export-mcp` differs:** the iPhone app keeps the export current in the background, so there's no manual `export.xml` and no re-import; the server has zero dependencies and needs no Docker, database or Mac app; every answer carries its units, date range and coverage; and it never writes to Apple Health: its only write is the events file your agent logs to.
 
 ---
 

package/demo.mjs

@@ -211,10 +211,68 @@ function buildSessions(rng) {
   return { schema: 1, writtenAt: WRITTEN_AT, sessions };
 }
 
+// Three weeks of a simple squat, bench and row programme, three sessions a week, adding 2.5 kg
+// each week (the same shape as the app's screenshot seed). Built from fixed numbers, no PRNG, so
+// the derived volume and Epley estimates are easy to check by hand.
+function buildStrength() {
+  const epley = (kg, reps) => (reps === 1 ? kg : Math.round(kg * (1 + reps / 30) * 10) / 10);
+  const backs = [20, 18, 16, 13, 11, 9, 6, 4, 2];
+  const sessions = backs.map((back, i) => {
+    const add = Math.floor(i / 3) * 2.5;
+    const lift = (name, reps, kg, rpe, warmup) => ({
+      name,
+      volumeKg: Math.round(3 * reps * kg * 10) / 10,
+      sets: [...(warmup ? [{ reps: 8, kg: warmup, kind: 'warmup' }] : []),
+             ...[0, 1, 2].map(() => ({ reps, kg, kind: 'working', rpe }))],
+      bestEstimateKg: epley(kg, reps),
+    });
+    const exercises = [
+      lift('Back squat', 5, 80 + add, 8, 40),
+      lift('Bench press', 6, 60 + add, 8.5),
+      lift('Barbell row', 8, 50 + add, 7.5),
+    ];
+    return {
+      id: `demo-str-${i + 1}`,
+      start: `${day(back)}T18:00:00+01:00`,
+      day: day(back),
+      volumeKg: Math.round(exercises.reduce((t, e) => t + e.volumeKg, 0) * 10) / 10,
+      workingSets: 9,
+      exercises,
+      minutes: 55,
+      effort: 7,
+    };
+  });
+  const last = sessions[sessions.length - 1];
+  const records = last.exercises.map((e) => ({
+    exercise: e.name,
+    sessions: sessions.length,
+    lastDay: last.day,
+    bestEstimateKg: e.bestEstimateKg,
+    bestEstimateDay: sessions.find((s) => s.exercises.some((x) => x.name === e.name && x.bestEstimateKg === e.bestEstimateKg)).day,
+    heaviestKg: e.sets[e.sets.length - 1].kg,
+  }));
+  return { schema: 1, app: '1.21', writtenAt: WRITTEN_AT, unit: 'kg', formula: 'strength-v1', sessions, records };
+}
+
 function buildCycles() {
   return { schema: 1, writtenAt: WRITTEN_AT, cycleStarts: [day(77), day(49), day(20)] };
 }
 
+// The tag log as the app exports it with "Include tags in exports" on: creatine daily for the last
+// 30 days, magnesium on alternate days, sauna every fifth day, and a few evenings of alcohol.
+function buildTags() {
+  const days = {};
+  const add = (back, name) => { (days[day(back)] ??= []).push(name); };
+  for (let i = 0; i < 30; i++) {
+    add(i, 'Creatine');
+    if (i % 2 === 0) add(i, 'Magnesium');
+  }
+  for (let i = 0; i < 90; i += 5) add(i, 'Sauna');
+  for (const i of [3, 10, 17, 24, 31, 45]) add(i, 'Alcohol');
+  for (const d of Object.keys(days)) days[d].sort();
+  return { schema: 1, writtenAt: WRITTEN_AT, days, supplements: ['Creatine', 'Magnesium'] };
+}
+
 function buildDaysFile() {
   return {
     schema: 1,
@@ -254,6 +312,8 @@ export function demoData() {
     sessions: buildSessions(rng),
     cycles: buildCycles(),
     days: buildDaysFile(),
+    strength: buildStrength(),
+    tags: buildTags(),
   };
   return _demo;
 }