health-export-mcp 1.6.2 → 1.6.4

package/AGENTS.md

@@ -3,7 +3,7 @@
 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 [MetricBridge](https://www.healthexport.dev) iOS app
-([App Store](https://apps.apple.com/app/id6784185201)) writes it to your iCloud Drive container:
+([App Store](https://apps.apple.com/app/apple-store/id6784185201?pt=129083290&ct=githubreadme&mt=8)) writes it to your iCloud Drive container:
 
 ```
 ~/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents

package/README.md

@@ -44,7 +44,7 @@ It's an MCP server that turns your Apple Health export into a tool your AI agent
 - **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.
-- **Where the data comes from:** the [MetricBridge](https://www.healthexport.dev) iOS app (formerly Health Export AI), [available on the App Store](https://apps.apple.com/app/id6784185201), writes the export this server reads. The server still reports itself as `health-export-ai` in `serverInfo`, and the npm package and repository names are unchanged.
+- **Where the data comes from:** the [MetricBridge](https://www.healthexport.dev) iOS app (formerly Health Export AI), [available on the App Store](https://apps.apple.com/app/apple-store/id6784185201?pt=129083290&ct=githubreadme&mt=8), writes the export this server reads. The server still reports itself as `health-export-ai` in `serverInfo`, and the npm package and repository names are unchanged.
 
 > **Just exported and the Mac has not seen it yet?** iCloud can take a few minutes to sync the
 > file across, so a check 60 seconds after tapping Run in the app can still show the old
@@ -61,7 +61,7 @@ It's an MCP server that turns your Apple Health export into a tool your AI agent
 
 The companion iOS app **[MetricBridge](https://www.healthexport.dev)** exports your Apple Health data, read-only, automatic, private. For this MCP server, export to a destination it can read:
 
-<p align="center"><a href="https://apps.apple.com/app/id6784185201"><img alt="Download MetricBridge 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://apps.apple.com/app/apple-store/id6784185201?pt=129083290&ct=githubreadme&mt=8"><img alt="Download MetricBridge 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>
 
 | Destination | Notes |
 |---|---|
@@ -221,7 +221,7 @@ node server.mjs --help
 
 <p align="center"><sub><a href="https://www.healthexport.dev">MetricBridge</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>
+<p align="center"><a href="https://apps.apple.com/app/apple-store/id6784185201?pt=129083290&ct=githubreadme&mt=8"><b>Download on the App Store →</b></a></p>
 
 ---
 
@@ -231,6 +231,7 @@ node server.mjs --help
 - **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).
+- **No telemetry.** The server makes no network requests. When it finds no usable export (none yet, a stale one, or `--demo`), `get_mcp_status` includes one static link to the companion app's website. That link carries fixed campaign labels (`utm_source=mcp`, `utm_medium=agent-tool`, `utm_campaign=mcp-unlock`) that are identical for every user and contain nothing about you or your data; they only count if you choose to open it.
 - **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).
 

package/healthstore.mjs

@@ -44,6 +44,32 @@ const DATA_DIR = (RAW_DIR === '~' || RAW_DIR.startsWith('~/'))
  *  elsewhere would silently diverge the moment tilde expansion or env handling changed here. */
 export const dataPath = (file) => path.join(DATA_DIR, file);
 
+// THE INSTALL-INTENT -> UNLOCK MIDDLE, MADE VISIBLE (2026-10-13).
+// The companion iOS app writes the export this server reads, and the funnel into it used to be
+// unmeasurable: install intent runs orders of magnitude above unlocks, and no tool answer carried
+// an attributable link to the app. This is that link. It is TEXT ONLY -- adding it changes no
+// network behaviour, so the server still makes zero runtime calls and the offline privacy promise
+// is untouched.
+//
+// `utm_campaign=mcp-unlock` names THIS surface, so a visit lands under one campaign in the site's
+// first-party analytics (Umami) instead of the undifferentiated direct bucket. site/app.js then
+// stamps the same value onto the App Store link's Apple campaign token (ct) on the way through, so
+// App Store Connect attributes the DOWNLOAD, not just the click on our site. `utm_source=mcp` and
+// `utm_medium=agent-tool` keep the surface separable from paid and organic traffic.
+export const UNLOCK_URL = 'https://www.healthexport.dev/?utm_source=mcp&utm_medium=agent-tool&utm_campaign=mcp-unlock';
+
+/** The user-facing app card. get_mcp_status (the tool agents call first) returns it ONLY when this
+ *  machine has no usable export: none at all, a stale one (a paused trial stops the writes), or the
+ *  synthetic demo dataset. A user with a working export already has the app, and a link on every
+ *  answer would be promotion rather than a description of what is missing, which is what MCP
+ *  directory review rules object to. Exported so the tests read the same string. */
+export const APP_INFO = {
+  name: 'MetricBridge',
+  unlockUrl: UNLOCK_URL,
+  note: 'The companion iOS app writes the export this server reads. unlockUrl is its website and carries fixed campaign labels (utm_source, utm_medium, utm_campaign) that are the same for every user. One-time unlock, no subscription.',
+};
+
+
 // Guard against reading something pathological, but sized for a real full-history cache.
 // Measured on this cache's exact shape (189 metrics x 3,653 days): 22.0 MB compact. The old
 // 64 MB ceiling was within reach of a long history once workouts were included -- and worse, the
@@ -459,6 +485,8 @@ export async function status() {
       // Write times are still readable when the contents are not.
       freshness: await freshness({ detail: false }),
       metrics: [],
+      // No `app` block here: an export that exists but cannot be decrypted was written by the app,
+      // so the fix is the passphrase in `note`, not a link to the app.
     };
   }
   const names = Object.keys(metrics);
@@ -467,9 +495,15 @@ export async function status() {
     const d = m?.daily?.[m.daily.length - 1]?.d;
     if (d && (!lastDate || d > lastDate)) lastDate = d;
   }
+  const fresh = await freshness({ detail: false });
+  // Locked is neither case: a pairing gate file exists only because the app wrote it.
+  const noUsableExport = DEMO || (p.ok && (names.length === 0 || fresh.stale === true));
   return {
     ok: names.length > 0 && p.ok,
     source: sourceLabel(),
+    // The campaign-tagged companion-app link, only when there is no usable export (see APP_INFO).
+    // Additive and text only: no runtime network call is made.
+    ...(noUsableExport && { app: APP_INFO }),
     // Demo mode is reported LOUDLY and first-class here, not only in the per-answer watermark:
     // get_mcp_status is the tool agents are told to call first, so this is where a human debugging
     // "why do my numbers look wrong" finds out they are not their numbers at all.
@@ -489,7 +523,7 @@ export async function status() {
     lastDataDate: lastDate,
     // Additive: the compact staleness signal (get_freshness has the per-file breakdown), so an
     // agent's first call already tells it whether to trust today's numbers.
-    freshness: await freshness({ detail: false }),
+    freshness: fresh,
     // Late-arrival recompute (cache schema minor 1). `supported: false` means the app that wrote
     // this cache predates it: past days are only as fresh as the run that last covered them.
     recompute: (() => {

package/manifest.json

@@ -2,9 +2,9 @@
   "manifest_version": "0.3",
   "name": "health-export-ai",
   "display_name": "MetricBridge",
-  "version": "1.6.2",
+  "version": "1.6.4",
   "description": "Query your Apple Health data, exported by the MetricBridge iOS app to iCloud Drive, from any MCP agent. Local-first, read-only, zero dependencies.",
-  "long_description": "A zero-dependency MCP server that exposes 190 Apple Health metrics (exported by the MetricBridge iOS app into an iCloud Drive folder) to any MCP-compatible agent: Claude Desktop, opencode, Cursor, OpenClaw, Hermes. No bridge, no Docker, no HTTP receiver: the server reads the synced cache file directly over stdio. 16 tools: get_mcp_status, get_freshness, list_metrics, get_health_metrics, get_trends, compare_periods, get_structured_export, get_intraday, query_health_data, list_events, get_profile, get_workouts, get_sleep_sessions, get_cycle_context, correlate_metrics, resolve_metric. Plus 22 MCP prompts and a --demo mode with a synthetic dataset. Get the companion iOS app on the App Store: https://apps.apple.com/app/id6784185201",
+  "long_description": "A zero-dependency MCP server that exposes 190 Apple Health metrics (exported by the MetricBridge iOS app into an iCloud Drive folder) to any MCP-compatible agent: Claude Desktop, opencode, Cursor, OpenClaw, Hermes. No bridge, no Docker, no HTTP receiver: the server reads the synced cache file directly over stdio. 16 tools: get_mcp_status, get_freshness, list_metrics, get_health_metrics, get_trends, compare_periods, get_structured_export, get_intraday, query_health_data, list_events, get_profile, get_workouts, get_sleep_sessions, get_cycle_context, correlate_metrics, resolve_metric. Plus 22 MCP prompts and a --demo mode with a synthetic dataset. Get the companion iOS app on the App Store: https://apps.apple.com/app/apple-store/id6784185201?pt=129083290&ct=githubreadme&mt=8",
   "author": {
     "name": "PhilipAD",
     "url": "https://github.com/PhilipAD"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "health-export-mcp",
   "mcpName": "io.github.PhilipAD/health-export-mcp",
-  "version": "1.6.2",
+  "version": "1.6.4",
   "type": "module",
   "description": "Open-source, zero-dependency Model Context Protocol (MCP) server to query Apple Health / HealthKit data (190 metrics) from Claude, ChatGPT, Cursor, OpenClaw, Hermes and any MCP agent.",
   "keywords": [

package/server.json

@@ -8,22 +8,22 @@
     "url": "https://github.com/PhilipAD/health-export-mcp",
     "source": "github"
   },
-  "version": "1.6.2",
+  "version": "1.6.4",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "health-export-mcp",
-      "version": "1.6.2",
+      "version": "1.6.4",
       "transport": {
         "type": "stdio"
       }
     },
     {
       "registryType": "mcpb",
-      "identifier": "https://github.com/PhilipAD/health-export-mcp/releases/download/v1.6.2/health-export.mcpb",
-      "version": "1.6.2",
-      "fileSha256": "e560da33c230c00b4a6a947c89ee274ff702f7356954b2b3b123ce5066ef4a8b",
+      "identifier": "https://github.com/PhilipAD/health-export-mcp/releases/download/v1.6.4/health-export.mcpb",
+      "version": "1.6.4",
+      "fileSha256": "54e038874281809f6d217eb76a94684951f94718bfe4189b2d6d6171e4bb3c78",
       "transport": {
         "type": "stdio"
       }

package/server.mjs

@@ -21,7 +21,7 @@ import * as ev from './events.mjs';
 import { PROMPTS } from './prompts.mjs';
 import { DEMO } from './demo.mjs';
 
-const SERVER = { name: 'health-export-ai', version: '1.6.2' };
+const SERVER = { name: 'health-export-ai', version: '1.6.4' };
 const DEFAULT_PROTOCOL = '2025-06-18';
 const log = (...a) => process.stderr.write('[mcp] ' + a.join(' ') + '\n');
 
@@ -57,7 +57,7 @@ const ANNOTATIONS = { readOnlyHint: true, idempotentHint: true, openWorldHint: f
 const TOOLS = [
   {
     name: 'get_mcp_status',
-    description: 'Health check: data source, how many metrics/workouts are available, which optional context files exist, the most recent data date, and a `recompute` summary of past days rebuilt after late-arriving samples (with any days too old to rebuild). Call this first to confirm the bridge is connected.',
+    description: 'Health check: data source, how many metrics/workouts are available, which optional context files exist, the most recent data date, and a `recompute` summary of past days rebuilt after late-arriving samples (with any days too old to rebuild). Call this first to confirm the bridge is connected. When there is no usable export (none found, a stale one, or demo data), the result also includes `app.unlockUrl`, the website of the companion iOS app that writes the export; the link carries fixed campaign attribution labels.',
     inputSchema: { type: 'object', properties: {} },
     handler: () => store.status(),
   },