health-export-mcp 1.2.2

package/.dockerignore

@@ -0,0 +1,5 @@
+.git
+assets
+*.test.mjs
+.imgbotconfig
+.github

package/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "health-export": {
+      "command": "npx",
+      "args": ["-y", "health-export-mcp"],
+      "env": {
+        "HEALTH_DATA_DIR": "~/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents"
+      }
+    }
+  }
+}

package/AGENTS.md

@@ -0,0 +1,85 @@
+# Using health-export-mcp with your AI client
+
+Copy-paste setup for every supported agent. The server is a single Node script (`server.mjs`,
+zero dependencies). Point `HEALTH_DATA_DIR` at the folder that holds your exported
+`.health-cache.json` — by default the [Health Export AI](https://www.healthexport.dev) iOS app
+([App Store](https://apps.apple.com/app/id6784185201)) writes it to your iCloud Drive container:
+
+```
+~/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents
+```
+
+**Tip:** get the absolute path to `server.mjs` with `node -e "console.log(process.cwd()+'/server.mjs')"` (run inside the repo), or let `node apply-mcp-config.mjs` write the config for you.
+
+After configuring, restart the client and ask: **"Use health-export: what's my HRV trend this week?"**
+
+---
+
+## Claude Desktop
+
+`~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "health-export": {
+      "command": "node",
+      "args": ["/ABSOLUTE/PATH/TO/health-export-mcp/server.mjs"],
+      "env": { "HEALTH_DATA_DIR": "~/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents" }
+    }
+  }
+}
+```
+
+Or drag `health-export.mcpb` into **Claude Desktop → Settings → Extensions** (no JSON).
+
+## Cursor
+
+`~/.cursor/mcp.json` (same `mcpServers` shape as above), or run `node gen-deeplinks.mjs` for a one-click install link.
+
+## VS Code (Copilot / Continue)
+
+Run `node gen-deeplinks.mjs` and open the generated VS Code link, or add the server under your MCP settings.
+
+## opencode
+
+`opencode.json` (project root) or `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "health-export": {
+      "type": "local",
+      "command": ["node", "/ABSOLUTE/PATH/TO/health-export-mcp/server.mjs"],
+      "enabled": true,
+      "environment": { "HEALTH_DATA_DIR": "~/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents" }
+    }
+  }
+}
+```
+
+## OpenClaw
+
+Add the `health-export` block (same shape as Claude Desktop's `mcpServers` entry) 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.
+
+## Non-MCP clients — ChatGPT · Gemini · Grok · n8n · Home Assistant
+
+These don't speak MCP, so they don't use this server. Instead, the [Health Export AI](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.
+
+---
+
+## Auto-configure
+
+`node apply-mcp-config.mjs` detects installed clients and writes the config for you.
+
+## Example prompts
+
+- "What's my average resting heart rate over the last 7 days?"
+- "Compare my deep sleep this week vs last week."
+- "Is my VO₂ max trending up this quarter?"
+- "Export HRV, RHR and sleep as JSON for the last 14 days."

package/Dockerfile

@@ -0,0 +1,8 @@
+# health-export-mcp — zero-dependency MCP server (stdio JSON-RPC 2.0).
+# Used by directories (e.g. Glama) to build the server and run MCP introspection
+# (initialize + tools/list). No real Apple Health data is required for introspection.
+FROM node:20-alpine
+WORKDIR /app
+COPY . .
+# Zero dependencies — nothing to install.
+ENTRYPOINT ["node", "server.mjs"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Philip D'Souza
+
+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.

package/README.md

@@ -0,0 +1,270 @@
+# health-export-mcp — Apple Health MCP server for AI agents
+
+**Query your Apple Health data from Claude, ChatGPT, Cursor, OpenClaw, Hermes — and any other AI agent.**
+
+`health-export-mcp` is an open-source, **zero-dependency** [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that lets any MCP-compatible AI agent query your **Apple Health / HealthKit** data — **190 metrics** as clean JSON — in plain language. Local-first, read-only, no accounts, and no developer server in the path. It's the open-source server for the [Health Export AI](https://www.healthexport.dev) iOS app — **[available on the App Store](https://apps.apple.com/app/id6784185201)**.
+
+<p align="center"><a href="https://apps.apple.com/app/id6784185201"><img alt="Download Health Export AI on the App Store" src="https://img.shields.io/badge/Download_on_the-App_Store-0D96F6?style=for-the-badge&logo=apple&logoColor=white" height="38" /></a></p>
+
+<p align="center">
+  <a href="https://glama.ai/mcp/servers/PhilipAD/health-export-mcp"><img alt="Glama MCP Server" src="https://glama.ai/mcp/servers/PhilipAD/health-export-mcp/badges/score.svg" /></a>
+  <img alt="MCP" src="https://img.shields.io/badge/Model_Context_Protocol-server-6E56CF" />
+  <img alt="zero dependencies" src="https://img.shields.io/badge/dependencies-0-2ea44f" />
+  <img alt="Node ≥18" src="https://img.shields.io/badge/node-%E2%89%A518-339933?logo=node.js&logoColor=white" />
+  <img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue" />
+  <img alt="works with Claude, Cursor, ChatGPT, OpenClaw, Hermes" src="https://img.shields.io/badge/works_with-Claude_·_Cursor_·_ChatGPT_·_OpenClaw_·_Hermes-111" />
+</p>
+
+<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 7 query tools to your AI agent" width="100%" />
+</p>
+
+> Ask your agent: *"Compare my HRV this week vs last week and tell me if I'm recovering."* — it calls the tools and answers from your **actual numbers**.
+
+---
+
+## What is health-export-mcp?
+
+It's an MCP server that turns your Apple Health export into a tool your AI agent can query in natural language — HRV, sleep, resting heart rate, steps, workouts, VO₂ max, and 180+ more.
+
+- **Who it's for:** anyone who wants their AI to reason over their *real* health data instead of a stale CSV.
+- **What it isn't:** a cloud service. There's no developer server in the path — your data goes only where *you* point it.
+- **Setup:** point the server at your exported data and add it to your AI client.
+
+> **Try it with no iPhone needed:** `git clone https://github.com/PhilipAD/health-export-mcp.git && cd health-export-mcp && npm test` writes a 14-day sample cache and exercises every tool.
+
+---
+
+## Connect Apple Health to your AI agent — Quickstart
+
+### 1. Get your Apple Health data flowing
+
+The companion iOS app **[Health Export AI](https://www.healthexport.dev)** exports your Apple Health data — read-only, automatic, private. For this MCP server, export to a destination it can read:
+
+| Destination | Notes |
+|---|---|
+| **iCloud Drive** (default) | Your Mac reads the synced folder automatically |
+| **Local folder** | Any folder that syncs to your Mac (Dropbox, Google Drive, OneDrive, …) |
+| **LAN** (HTTP / WebSocket) | Direct push to the server — great over Tailscale |
+
+> Using a non-MCP tool (ChatGPT, n8n, Home Assistant)? The app can also POST to a **webhook** those tools read directly — see [Works with](#works-with-claude-cursor-chatgpt-openclaw-hermes).
+
+### 2. Add the server to your agent
+
+**Fastest — auto-configure:**
+
+```bash
+git clone https://github.com/PhilipAD/health-export-mcp.git
+cd health-export-mcp
+node apply-mcp-config.mjs     # detects installed clients and writes the config for you
+```
+
+**Manual — Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "health-export": {
+      "command": "npx",
+      "args": ["-y", "health-export-mcp"],
+      "env": { "HEALTH_DATA_DIR": "~/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents" }
+    }
+  }
+}
+```
+
+> `npx` fetches the published package at run time (npm verifies package integrity) — it runs anywhere, no clone or absolute path needed. 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**.
+
+**Cursor / VS Code:** `node gen-deeplinks.mjs` prints one-click install links.
+**opencode / OpenClaw / Hermes:** see **[AGENTS.md](AGENTS.md)** for the exact block — same shape, one per client.
+
+### 3. Ask your agent
+
+Restart the client and try:
+
+> *"Use health-export: what's my average HRV this week vs last week?"*
+
+---
+
+## Works with Claude, Cursor, ChatGPT, OpenClaw, Hermes
+
+| Client / Agent | Integration | How |
+|---|---|---|
+| **Claude Desktop** | Native MCP | `.mcpb` bundle, or `mcpServers` block |
+| **Cursor** | Native MCP | One-click deeplink, or `~/.cursor/mcp.json` |
+| **opencode** | Native MCP | `opencode.json` `mcp` block |
+| **OpenClaw** | Native MCP | Add the server block to your MCP config |
+| **Hermes** | Native MCP | Add the server block to your agent's MCP config |
+| **VS Code** (Copilot / Continue) | Native MCP | One-click deeplink |
+| **ChatGPT · Gemini · Grok** | Webhook* | Consume the app's webhook export |
+| **n8n · Home Assistant** | Webhook* | Trigger automations on the exported JSON |
+
+<sub>*MCP clients query this server directly over stdio. ChatGPT / Gemini / Grok / n8n / Home Assistant don't speak MCP — they consume the same Apple Health data via the iOS app's token-authenticated **webhook** export.</sub>
+
+---
+
+## The 7 MCP tools
+
+| Tool | What it does |
+|---|---|
+| `get_mcp_status` | Health check — source, metric/workout counts, latest data date. **Call first.** |
+| `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). |
+| `get_trends` | Recent N-day window vs the prior N days — change, % change, direction. |
+| `compare_periods` | A metric across two arbitrary date periods (A vs B). |
+| `get_structured_export` | Clean JSON for chosen metrics/range — drop straight into context. |
+| `query_health_data` | Natural-language convenience: *"average HRV last month"* → routed structured results. |
+
+**Coverage:** 190 Apple Health metrics across activity, heart, HRV, mobility, respiratory, body, sleep, hearing, and nutrition — plus workouts.
+
+---
+
+## Example AI queries
+
+```text
+"What has my resting heart rate done over the last 30 days?"
+"Compare my deep sleep this week vs last week."
+"Is my VO₂ max trending up or down this quarter?"
+"Give me a clean JSON export of HRV, RHR and sleep for the last 14 days."
+"Correlate my step count with my sleep duration this month."
+```
+
+---
+
+## Use cases
+
+- **AI health coach** — let an agent reason over your real HRV, resting heart rate, and sleep to suggest when to push and when to recover, grounded in your actual numbers instead of generic advice.
+- **Training-load analysis** — pull workouts, VO₂ max, and heart-rate trends so your agent can flag overreaching, plot fitness progression, and pace a training block.
+- **Sleep correlations** — have your agent correlate deep-sleep duration against steps, caffeine, late workouts, or screen time to find what actually moves your sleep quality.
+- **Quantified-self dashboards** — feed clean JSON for any metric set and date range straight into a notebook, spreadsheet, or LLM-built dashboard for your own self-tracking.
+- **Personal research & experiments** — run n-of-1 experiments (supplement, routine, or protocol changes) and let an agent compare before/after periods across 190 metrics to see what changed.
+
+---
+
+## The app that feeds it
+
+<p align="center">
+  <img src="assets/screenshot-dashboard.png" alt="Health Export AI dashboard" width="240" />
+  &nbsp;&nbsp;
+  <img src="assets/screenshot-metrics.png" alt="190 Apple Health metrics" width="240" />
+  &nbsp;&nbsp;
+  <img src="assets/screenshot-destinations.png" alt="Export to iCloud, folder, LAN, or webhook" width="240" />
+</p>
+
+<p align="center"><sub><a href="https://www.healthexport.dev">Health Export AI</a> — exports your Apple Health to your agent, automatically.</sub></p>
+
+<p align="center"><a href="https://apps.apple.com/app/id6784185201"><b>Download on the App Store →</b></a></p>
+
+---
+
+## Privacy & security
+
+- **Read-only.** The server only reads your exported data — it never touches HealthKit and never writes back.
+- **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.
+- **Auditable.** Zero dependencies and a few hundred lines of readable JavaScript — read every line.
+- **Signed releases.** Hosted artifacts are minisign-signed and checksummed — see [Verifying releases](#verifying-releases).
+
+---
+
+## Verifying releases
+
+The server artifacts hosted at `healthexport.dev/mcp/` (used by the [setup skill](https://healthexport.dev/SKILL.md)) are **minisign-signed**, and every download is **SHA-256 checksummed**. The signing public key is published **in this repo** (`minisign.pub`) and in `SKILL.md` — **pin it from here, not only from the website**, so a compromise of the website alone cannot swap both an artifact and its key.
+
+```bash
+PUBKEY='RWS6TxVWSKUblYkx7Db6ZpmvHALwHpznZpjaED/FlZj+PpxSlel0MxHZ'   # = minisign.pub in this repo
+curl -fsSL https://healthexport.dev/mcp/SHA256SUMS         -o SHA256SUMS
+curl -fsSL https://healthexport.dev/mcp/SHA256SUMS.minisig -o SHA256SUMS.minisig
+minisign -Vm SHA256SUMS -P "$PUBKEY" || { echo "signature INVALID — do not run"; exit 1; }   # fail closed
+curl -fsSL https://healthexport.dev/mcp/server.mjs -o server.mjs
+shasum -a 256 --ignore-missing -c SHA256SUMS || { echo "checksum mismatch — do not run"; exit 1; }
+```
+
+The pinned, checksum-verified download above is the locked-down path. `npx health-export-mcp` instead resolves the latest version published to npm at run time (npm provides its own package integrity). Full security overview: <https://healthexport.dev/security>. Report vulnerabilities to **security@healthexport.dev**.
+
+---
+
+## Requirements
+
+- **Node.js ≥ 18** (`node -v`).
+- A folder containing a `.health-cache.json` exported by [Health Export AI](https://www.healthexport.dev) — or run `npm test` to generate a sample one.
+- An MCP-compatible client (Claude Desktop, Cursor, opencode, OpenClaw, Hermes, VS Code) — or any tool that can read the webhook export.
+
+---
+
+## FAQ
+
+**How do I get my Apple Health data into Claude / ChatGPT / my AI agent?**
+Install `health-export-mcp`, export your Apple Health data with the [Health Export AI](https://www.healthexport.dev) iOS app (to iCloud, a folder, or your LAN), then add the MCP server to your AI client. Your agent can then query your Apple Health metrics in natural language. (Non-MCP tools like ChatGPT read the app's webhook export instead.)
+
+**Is my health data sent to a server?**
+Not to us. The MCP server runs locally and reads only the export files or endpoints you configure — there's no developer server in the path. Where your iOS export is delivered (iCloud, your LAN, a webhook) is entirely your choice.
+
+**Which agents are supported?**
+Any MCP client — Claude Desktop, Cursor, opencode, OpenClaw, Hermes, VS Code — natively. ChatGPT, Gemini, Grok, n8n, and Home Assistant consume the same data via webhook.
+
+**Do I need the iOS app?**
+The app is the easiest way to get Apple Health data off your iPhone in the format this server reads. You can also point `HEALTH_DATA_DIR` at any folder containing a compatible `.health-cache.json`.
+
+---
+
+## Troubleshooting
+
+- **"No metrics found"** — confirm `HEALTH_DATA_DIR` points at the folder containing `.health-cache.json`, and that the app has exported at least once. Run `get_mcp_status` to see the resolved source and latest date.
+- **Server not visible in the client** — use an **absolute** path to `server.mjs`, ensure Node ≥18, and fully restart the client.
+- **Locked data error** — the export file is protected until first unlock after reboot; unlock your device once.
+
+---
+
+## Run it locally
+
+```bash
+# Node ≥18, no install needed
+HEALTH_DATA_DIR=~/Library/Mobile\ Documents/iCloud~ai~healthexport~app/Documents node server.mjs
+
+# integration test — writes a 14-day sample cache and exercises every tool
+npm test
+```
+
+stdio transport (newline-delimited JSON-RPC 2.0) — the universal MCP transport. Optionally set `HEALTH_LISTEN=1` to also accept LAN pushes from the iOS app in the same process (see [`receiver.mjs`](receiver.mjs)).
+
+---
+
+## How it works
+
+The iOS app reads Apple Health (read-only) and writes a compact `.health-cache.json` to the destination you choose. This server reads that file and exposes the 7 tools above over MCP. No bridge, no Docker, no database — just a file and stdio.
+
+```
+Apple Health → Health Export AI (iOS) → .health-cache.json → health-export-mcp → MCP client → you
+```
+
+---
+
+## Related projects
+
+Other Apple Health MCP servers in the ecosystem — worth a look depending on your setup:
+
+- **[neiltron/apple-health-mcp](https://github.com/neiltron/apple-health-mcp)** — an MCP server that runs SQL-style queries over an Apple Health export.
+- **[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:** zero dependencies, clean structured JSON, 190 Apple Health metrics, and the widest agent support (Claude, Cursor, opencode, OpenClaw, Hermes, VS Code natively — plus ChatGPT/Gemini/Grok/n8n/Home Assistant via webhook).
+
+---
+
+## Related
+
+- **Companion iOS app:** [Health Export AI](https://www.healthexport.dev) — exports 190 Apple Health metrics to your agent, automatically.
+- **Model Context Protocol:** [modelcontextprotocol.io](https://modelcontextprotocol.io)
+- **Per-agent setup:** [AGENTS.md](AGENTS.md)
+
+If this helps your setup, a ⭐ makes it easier for others to find.
+
+## License
+
+MIT — see [LICENSE](LICENSE). Contributions welcome.
+
+---
+
+<sub>Apple Health MCP server · export Apple Health to AI · HealthKit MCP server · query Apple Health with Claude / ChatGPT / Cursor · Model Context Protocol health server · Apple Health to LLM · HRV, sleep & heart rate for AI agents.</sub>

package/apply-mcp-config.mjs

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+// Health Export AI — safe, idempotent MCP config writer.
+//
+// Adds (or updates) ONE "health-export" server entry in the config file of a
+// given MCP client, preserving everything else. Backs up the file first, writes
+// atomically, and NEVER prints the pairing secret.
+//
+//   node apply-mcp-config.mjs --client <id> --server-path <abs> --data-dir <abs> [opts]
+//
+//   --client   claude-desktop | claude-code | cursor | vscode | opencode   (required)
+//   --server-path  absolute path to server.mjs                              (required)
+//   --data-dir     absolute path to the folder holding .health-cache.json   (required)
+//   --pairing-secret-env   read the secret from $HEALTH_EXPORT_PAIRING_SECRET
+//   --clear-pairing-secret remove any existing pairing secret from the entry
+//   --env KEY=VALUE        extra env var for the entry (repeatable). For the LAN
+//                          listen path: --env HEALTH_LISTEN=1 --env HEALTH_LISTEN_HOST=0.0.0.0
+//   --listen-token-env     set HEALTH_LISTEN_TOKEN from $HEALTH_EXPORT_LISTEN_TOKEN
+//                          (the iOS pairing code) — keeps it off argv, like the secret.
+//   --name <id>            server entry name (default: health-export)
+//   --config-path <path>   override the client's default config file
+//   --dry-run             show what would change; write nothing
+//
+// Idempotent re-runs: if you don't pass --pairing-secret-env, an existing secret
+// (or VS Code ${input:…} reference) is PRESERVED, not dropped. Use
+// --clear-pairing-secret to remove it on purpose.
+//
+// Secrets: pass the pairing code via the env var, never on argv (argv is visible
+// to other processes). For VS Code the secret is NEVER written to disk — the
+// config references ${input:...} so VS Code prompts for it.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+// ---- args ----------------------------------------------------------------
+const argv = process.argv.slice(2);
+const opt = (k) => { const i = argv.indexOf(k); return i >= 0 ? argv[i + 1] : undefined; };
+const flag = (k) => argv.includes(k);
+
+const client = opt('--client');
+const name = opt('--name') || 'health-export';
+const dryRun = flag('--dry-run');
+const useSecretEnv = flag('--pairing-secret-env');
+const clearSecret = flag('--clear-pairing-secret');
+
+const expand = (p) => (p && p.startsWith('~')) ? path.join(os.homedir(), p.slice(1)) : p;
+const serverPath = expand(opt('--server-path'));
+const dataDir = expand(opt('--data-dir'));
+const secret = useSecretEnv ? (process.env.HEALTH_EXPORT_PAIRING_SECRET || '') : '';
+const VSCODE_INPUT = '${input:health_pairing_secret}';
+
+// repeatable --env KEY=VALUE (e.g. the LAN listen keys)
+const extraEnv = {};
+for (let i = 0; i < argv.length; i++) {
+  if (argv[i] === '--env' && argv[i + 1]) {
+    const kv = argv[i + 1]; const eq = kv.indexOf('=');
+    if (eq > 0) extraEnv[kv.slice(0, eq)] = kv.slice(eq + 1);
+  }
+}
+// LAN token via env (keeps it off argv, like the pairing secret). The listen token
+// and the pairing secret are the same iOS code, so fall back to the secret's env var —
+// one `read -rs HEALTH_EXPORT_PAIRING_SECRET` capture then covers both roles.
+const useListenTokenEnv = flag('--listen-token-env');
+const listenToken = useListenTokenEnv
+  ? (process.env.HEALTH_EXPORT_LISTEN_TOKEN || process.env.HEALTH_EXPORT_PAIRING_SECRET || '')
+  : '';
+
+const die = (msg) => { console.error('error: ' + msg); process.exit(1); };
+
+const CLIENTS = {
+  'claude-desktop': { topKey: 'mcpServers', shape: 'standard', def: claudeDesktopPath },
+  'claude-code':    { topKey: 'mcpServers', shape: 'standard', def: () => path.join(process.cwd(), '.mcp.json') },
+  'cursor':         { topKey: 'mcpServers', shape: 'standard', def: () => path.join(os.homedir(), '.cursor', 'mcp.json') },
+  'vscode':         { topKey: 'servers',    shape: 'vscode',   def: () => path.join(process.cwd(), '.vscode', 'mcp.json') },
+  'opencode':       { topKey: 'mcp',        shape: 'opencode', def: opencodePath },
+};
+
+if (!client || !CLIENTS[client]) die(`--client must be one of: ${Object.keys(CLIENTS).join(', ')}`);
+if (!serverPath) die('--server-path is required (absolute path to server.mjs)');
+if (!dataDir) die('--data-dir is required (absolute path to the export folder)');
+if (!path.isAbsolute(serverPath)) die('--server-path must be absolute: ' + serverPath);
+if (!path.isAbsolute(dataDir)) die('--data-dir must be absolute: ' + dataDir);
+
+function claudeDesktopPath() {
+  if (process.platform === 'darwin') return path.join(os.homedir(), 'Library/Application Support/Claude/claude_desktop_config.json');
+  if (process.platform === 'win32') return path.join(process.env.APPDATA || path.join(os.homedir(), 'AppData/Roaming'), 'Claude', 'claude_desktop_config.json');
+  return path.join(os.homedir(), '.config/Claude/claude_desktop_config.json');
+}
+function opencodePath() {
+  const local = path.join(process.cwd(), 'opencode.json');
+  if (fs.existsSync(local)) return local;
+  return path.join(os.homedir(), '.config/opencode/opencode.json');
+}
+
+const spec = CLIENTS[client];
+const file = expand(opt('--config-path')) || spec.def();
+
+// ---- read existing config first (so we can preserve secrets + other keys) -
+let root = {};
+let existed = false;
+if (fs.existsSync(file)) {
+  existed = true;
+  const raw = fs.readFileSync(file, 'utf8').trim();
+  if (raw) {
+    try { root = JSON.parse(raw); }
+    catch { die(`${file} is not plain JSON (it may use comments). Edit it by hand using the recipe in SKILL.md.`); }
+  }
+  if (typeof root !== 'object' || Array.isArray(root)) die(`${file} is not a JSON object.`);
+}
+const prev = (root[spec.topKey] && root[spec.topKey][name]) || null;
+const prevEnv = prev ? (prev.env || prev.environment) : null;
+const prevSecret = prevEnv ? prevEnv.PAIRING_SECRET : undefined;
+
+// ---- decide what the secret should be after this run ----------------------
+// kinds: {kind:'value',value} write a literal · {kind:'input'} VS Code ref · {kind:'none'}
+function resolveSecret() {
+  if (clearSecret) return { kind: 'none', why: 'cleared' };
+  if (spec.shape === 'vscode') {
+    if (useSecretEnv) return { kind: 'input', why: 'prompted by VS Code (${input:…}), not stored' };
+    if (prevSecret === VSCODE_INPUT) return { kind: 'input', why: 'preserved existing input ref' };
+    return { kind: 'none', why: 'none' };
+  }
+  if (useSecretEnv && secret) return { kind: 'value', value: secret, why: 'set from $HEALTH_EXPORT_PAIRING_SECRET' };
+  // --pairing-secret-env but the env var is empty: don't wipe an existing secret.
+  if (useSecretEnv && !secret) {
+    if (prevSecret !== undefined && prevSecret !== '') return { kind: 'value', value: prevSecret, why: '$HEALTH_EXPORT_PAIRING_SECRET empty — preserved existing' };
+    return { kind: 'none', why: '$HEALTH_EXPORT_PAIRING_SECRET empty — left unset' };
+  }
+  if (prevSecret !== undefined && prevSecret !== '') return { kind: 'value', value: prevSecret, why: 'preserved existing' };
+  return { kind: 'none', why: 'none' };
+}
+const sec = resolveSecret();
+
+// ---- build the server entry for this client's shape ----------------------
+// Preserve any prior env keys (e.g. HEALTH_LISTEN*), update HEALTH_DATA_DIR, merge
+// --env passthrough, then resolve the secret.
+function mergedEnv() {
+  const env = { ...(prevEnv || {}) };
+  env.HEALTH_DATA_DIR = dataDir;
+  Object.assign(env, extraEnv);
+  if (listenToken) env.HEALTH_LISTEN_TOKEN = listenToken; // empty → prior value preserved
+  delete env.PAIRING_SECRET;
+  if (sec.kind === 'value') env.PAIRING_SECRET = sec.value;
+  else if (sec.kind === 'input') env.PAIRING_SECRET = VSCODE_INPUT;
+  // VS Code: never persist a secret/token literal — route it through a prompted ${input:…}.
+  // (.vscode/mcp.json is often committed; literals would leak the pairing code at rest.)
+  if (spec.shape === 'vscode') {
+    for (const k of Object.keys(env)) {
+      if (/secret|token/i.test(k) && typeof env[k] === 'string' && env[k] && !env[k].startsWith('${')) {
+        env[k] = '${input:' + k.toLowerCase() + '}';
+      }
+    }
+  }
+  return env;
+}
+function buildEntry() {
+  if (spec.shape === 'opencode') return { type: 'local', command: ['node', serverPath], enabled: true, environment: mergedEnv() };
+  if (spec.shape === 'vscode') return { type: 'stdio', command: 'node', args: [serverPath], env: mergedEnv() };
+  // standard (Claude Desktop / Claude Code / Cursor)
+  return { command: 'node', args: [serverPath], env: mergedEnv() };
+}
+
+const wasPresent = !!prev;
+root[spec.topKey] = root[spec.topKey] || {};
+root[spec.topKey][name] = buildEntry();
+
+// VS Code: declare a password promptString for every ${input:id} the entry references,
+// and drop our managed inputs no longer referenced. Secrets stay off disk.
+if (spec.shape === 'vscode') {
+  const entryEnv = root[spec.topKey][name].env || {};
+  const used = new Set();
+  for (const v of Object.values(entryEnv)) {
+    const m = typeof v === 'string' && v.match(/^\$\{input:([A-Za-z0-9_]+)\}$/);
+    if (m) used.add(m[1]);
+  }
+  const DESC = { health_pairing_secret: 'Health Export pairing code', health_listen_token: 'Health Export LAN token (iOS pairing code)' };
+  root.inputs = Array.isArray(root.inputs) ? root.inputs : [];
+  for (const id of used) {
+    if (!root.inputs.some((i) => i && i.id === id)) {
+      root.inputs.push({ type: 'promptString', id, description: DESC[id] || 'Health Export secret', password: true });
+    }
+  }
+  root.inputs = root.inputs.filter((i) => !(i && /^health_(pairing_secret|listen_token)$/.test(i.id) && !used.has(i.id)));
+  if (root.inputs.length === 0) delete root.inputs;
+}
+if (spec.shape === 'opencode' && !root.$schema) root.$schema = 'https://opencode.ai/config.json';
+
+// ---- redacted summary (never print the secret) ---------------------------
+const redacted = JSON.parse(JSON.stringify(root[spec.topKey][name]));
+const scrub = (o) => { for (const k of Object.keys(o || {})) { if (/secret|token/i.test(k) && o[k] && !String(o[k]).startsWith('${')) o[k] = '********'; } };
+scrub(redacted.env); scrub(redacted.environment);
+
+console.log(`client:      ${client}`);
+console.log(`config file: ${file}${existed ? '' : '  (will be created)'}`);
+console.log(`action:      ${wasPresent ? 'UPDATE existing' : 'ADD'} "${name}" under "${spec.topKey}"`);
+console.log(`secret:      ${sec.why}`);
+console.log(`entry:       ${JSON.stringify(redacted)}`);
+
+if (dryRun) { console.log('\ndry run — nothing written.'); process.exit(0); }
+
+// ---- back up + atomic write ----------------------------------------------
+// If a literal secret is being written (non-VS-Code clients), lock files to owner-only 0600.
+const hasLiteralSecret = sec.kind === 'value';
+const mode = hasLiteralSecret ? 0o600 : 0o644;
+fs.mkdirSync(path.dirname(file), { recursive: true });
+if (existed && !fs.existsSync(file + '.bak')) {            // don't clobber an existing backup
+  fs.copyFileSync(file, file + '.bak');
+  if (hasLiteralSecret) { try { fs.chmodSync(file + '.bak', 0o600); } catch {} }
+  console.log(`backup:      ${file}.bak`);
+}
+const tmp = file + '.tmp-' + process.pid;
+fs.writeFileSync(tmp, JSON.stringify(root, null, 2) + '\n', { mode });
+fs.renameSync(tmp, file);
+try { fs.chmodSync(file, mode); } catch {}
+console.log('\nwritten. Restart/reload the client, then call get_mcp_status to verify.');

package/gen-deeplinks.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+// Generate one-click MCP install deeplinks for Cursor and VS Code that point at
+// the local Health Export stdio server. No bridge, no Docker — just node + stdio.
+//
+//   node gen-deeplinks.mjs [serverPath] [healthDataDir]
+//
+// Defaults assume the installed bundle layout + the iCloud Drive export folder.
+//
+// NOTE the two clients use DIFFERENT config encodings (verified 2026):
+//   • Cursor  — config = base64(JSON of the inner server object)
+//   • VS Code — the whole server JSON is URL-encoded (NOT base64), and it
+//     includes "name" + "type" inline.
+import path from 'node:path';
+import os from 'node:os';
+
+const serverPath = process.argv[2] || path.join(process.cwd(), 'server.mjs');
+const dataDir = process.argv[3] ||
+  path.join(os.homedir(), 'Library/Mobile Documents/iCloud~ai~healthexport~app/Documents');
+
+const name = 'health-export';
+const env = { HEALTH_DATA_DIR: dataDir };
+
+// Cursor: inner server object, base64-encoded, passed as ?config=
+const cursorCfg = { command: 'node', args: [serverPath], env };
+const cursorB64 = encodeURIComponent(Buffer.from(JSON.stringify(cursorCfg)).toString('base64'));
+
+// VS Code: full server object (with name + type), URL-encoded JSON — no base64.
+const vscodeCfg = { name, type: 'stdio', command: 'node', args: [serverPath], env };
+const vscodeEnc = encodeURIComponent(JSON.stringify(vscodeCfg));
+// Web redirect form takes name + config separately (config = URL-encoded JSON of the inner object).
+const vscodeWebCfg = encodeURIComponent(JSON.stringify({ type: 'stdio', command: 'node', args: [serverPath], env }));
+
+console.log('Cursor config:', JSON.stringify(cursorCfg));
+console.log('VS Code config:', JSON.stringify(vscodeCfg));
+console.log('\nCursor:      cursor://anysphere.cursor-deeplink/mcp/install?name=' + name + '&config=' + cursorB64);
+console.log('VS Code:     vscode:mcp/install?' + vscodeEnc);
+console.log('VS Code web: https://insiders.vscode.dev/redirect/mcp/install?name=' + name + '&config=' + vscodeWebCfg);