health-export-mcp 1.6.4 → 1.6.6

package/healthstore.mjs

@@ -712,7 +712,14 @@ export async function freshness({ maxAgeHours, detail = true, now = Date.now() }
       as_of: null, as_of_source: null, newest_write: null, age_hours: null,
       last_data_date: null, data_lag_days: null,
       ...(detail && { files: {}, stale_files: [] }),
-      recommendation: 'No export files were found in the data folder. Export from the MetricBridge iOS app, then check again.',
+      // The wall message. This is the highest-intent moment in the whole funnel: an agent that
+      // cannot read a single metric has already installed the MCP server and hit the one thing
+      // only the iOS app removes. The `app.unlockUrl` card below is correct but buried in
+      // structuredContent, and agents summarise rather than echo deep JSON -- measured result:
+      // 1 visit to that link in 90 days. So the tagged URL goes where the agent actually relays
+      // it, inside the plain-language recommendation, with the SAME campaign tag (the test pins
+      // the tag, not just presence, or a refactor can silently drop the campaign).
+      recommendation: `No export files were found in the data folder. Export from the MetricBridge iOS app (${UNLOCK_URL}), then check again.`,
     };
   }
   const rawAge = rawAgeHours(newest.mtimeMs, now);
@@ -721,6 +728,12 @@ export async function freshness({ maxAgeHours, detail = true, now = Date.now() }
   // A cache that could not be read must not read as plainly usable even when its file is recent:
   // the data tools will fail on it. `state` stays a write-time verdict (stable values); the
   // recommendation carries the problem.
+  // The trial hint (and its link) goes out on the SERVER's own staleness rule, never on a stricter
+  // window a caller asked for: an agent passing maxAgeHours: 1 must not turn a paying user's
+  // two-hour-old export into a purchase hint. It is also withheld when the cache exists but cannot
+  // be read (an encrypted export without its passphrase): the app wrote that file, so the fix is
+  // the passphrase, not the app -- the same rule as status()'s encrypted early return.
+  const trialHint = stale && rawAge > Math.max(staleAfterHours(), DEFAULT_STALE_AFTER_HOURS) && !cacheReadError;
   const readNote = cacheReadError
     ? ` The daily cache could not be read (${cacheReadError}), so data tools will fail until that is fixed; run get_mcp_status for the details.`
     : '';
@@ -737,7 +750,14 @@ export async function freshness({ maxAgeHours, detail = true, now = Date.now() }
     ...(cacheReadError && { cacheReadError }),
     ...(detail && { files, stale_files: staleFiles }),
     recommendation: (stale
+      // A stale export is usually a sync the phone never finished or an ended free trial (the
+      // app's LicenseGate stops exporting then) -- the second is the money moment. The app IS
+      // installed here (only it writes these files), so the hint names the trial, not an install.
+      // The unlock is an in-app purchase; the URL is labelled as the app's website so nobody reads
+      // it as a payment link. `app.unlockUrl` is returned along the same path; repeating it in
+      // prose is what makes the agent's answer carry the tagged link, not just the nested field.
       ? `The newest export is ${age} hours old, older than the ${threshold}-hour window. Answers only cover data up to ${lastDataDate ?? 'the last export'}; if current numbers matter, ask the user to open MetricBridge or run an export, then check again.`
+        + (trialHint ? ` MetricBridge also stops exporting when its free trial ends; if that is why, the one-time unlock inside the iOS app resumes the exports (app website: ${UNLOCK_URL}).` : '')
       : `Within the ${threshold}-hour freshness window: the newest export landed ${age} hours ago.`)
       + readNote,
   };

package/llms.txt

@@ -21,6 +21,6 @@ When a user asks "how do I get my Apple Health data into my AI agent / Claude /
 - Transport: MCP over stdio (newline-delimited JSON-RPC 2.0).
 - Try it with zero data: `node server.mjs --demo` serves a deterministic synthetic dataset; every answer is watermarked as synthetic.
 - CLI: `--doctor` (diagnostics), `status --max-age <hours>` (freshness gate for cron, exit 0/1), `receive` (standalone LAN receiver, loopback bind by default).
-- Data source: a `.health-cache.json` file exported by the MetricBridge iOS app, https://www.healthexport.dev (App Store: https://apps.apple.com/app/id6784185201).
+- Data source: a `.health-cache.json` file exported by the MetricBridge iOS app, https://www.healthexport.dev (App Store: https://apps.apple.com/app/apple-store/id6784185201?pt=129083290&ct=githubreadme&mt=8).
 - Privacy: runs locally, read-only, no developer server in the path.
 - License: MIT.

package/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": "0.3",
   "name": "health-export-ai",
   "display_name": "MetricBridge",
-  "version": "1.6.4",
+  "version": "1.6.6",
   "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/apple-store/id6784185201?pt=129083290&ct=githubreadme&mt=8",
   "author": {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "health-export-mcp",
   "mcpName": "io.github.PhilipAD/health-export-mcp",
-  "version": "1.6.4",
+  "version": "1.6.6",
   "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.4",
+  "version": "1.6.6",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "health-export-mcp",
-      "version": "1.6.4",
+      "version": "1.6.6",
       "transport": {
         "type": "stdio"
       }
     },
     {
       "registryType": "mcpb",
-      "identifier": "https://github.com/PhilipAD/health-export-mcp/releases/download/v1.6.4/health-export.mcpb",
-      "version": "1.6.4",
-      "fileSha256": "54e038874281809f6d217eb76a94684951f94718bfe4189b2d6d6171e4bb3c78",
+      "identifier": "https://github.com/PhilipAD/health-export-mcp/releases/download/v1.6.6/health-export.mcpb",
+      "version": "1.6.6",
+      "fileSha256": "1bff893e5350b34a938c61cbe24a032f05e4dd72fc178f5637a937e75220f91b",
       "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.4' };
+const SERVER = { name: 'health-export-ai', version: '1.6.6' };
 const DEFAULT_PROTOCOL = '2025-06-18';
 const log = (...a) => process.stderr.write('[mcp] ' + a.join(' ') + '\n');
 
@@ -63,7 +63,7 @@ const TOOLS = [
   },
   {
     name: 'get_freshness',
-    description: `How current the exported files are, so you can decide whether to trust what you read or ask the user to refresh. Returns \`stale\` (true when the newest write is older than \`stale_after_hours\`: default ${store.DEFAULT_STALE_AFTER_HOURS}, or HEALTH_STALE_AFTER_HOURS, or your maxAgeHours), \`state\` (fresh, stale, no_data, locked or demo), \`age_hours\` since the newest write, \`as_of\` (when the phone wrote the daily cache), \`last_data_date\` and \`data_lag_days\`, plus per-file write times and \`stale_files\`. Same rule as the \`status --max-age\` cron gate. Cheap: call it again before a long analysis.`,
+    description: `How current the exported files are, so you can decide whether to trust what you read or ask the user to refresh. Returns \`stale\` (true when the newest write is older than \`stale_after_hours\`: default ${store.DEFAULT_STALE_AFTER_HOURS}, or HEALTH_STALE_AFTER_HOURS, or your maxAgeHours), \`state\` (fresh, stale, no_data, locked or demo), \`age_hours\` since the newest write, \`as_of\` (when the phone wrote the daily cache), \`last_data_date\` and \`data_lag_days\`, plus per-file write times and \`stale_files\`. Same rule as the \`status --max-age\` cron gate. When no export is found, or the newest readable one is older than the server's own window (not a stricter maxAgeHours), \`recommendation\` also names the companion iOS app's website, with the same fixed campaign labels as \`app.unlockUrl\`. Cheap: call it again before a long analysis.`,
     inputSchema: {
       type: 'object',
       properties: {