health-export-mcp 1.3.0 → 1.4.0

package/README.md

@@ -16,7 +16,7 @@
 </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 8 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 14 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**.
@@ -31,7 +31,7 @@ It's an MCP server that turns your Apple Health export into a tool your AI agent
 - **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.
+> **Try it with no iPhone needed:** `node server.mjs --demo` serves a deterministic synthetic dataset (400 days, workouts, events, sleep sessions) with every answer watermarked as synthetic. Or run `npm test` to write a sample cache and exercise every tool.
 
 ---
 
@@ -104,20 +104,51 @@ Restart the client and try:
 
 ---
 
-## The 8 MCP tools
+## The 14 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, latest data date. **Call first.** |
+| `get_mcp_status` | Health check: source, metric/workout counts, which context files exist, 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. |
-| `get_intraday` | Today's hour-by-hour window from the app's hourly automations (`health-intraday.json`, app 1.4+) — replaced each run, latest value per metric. |
-| `query_health_data` | Natural-language convenience: *"average HRV last month"* → routed structured results. |
+| `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_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. |
+| `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. |
+| `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_cycle_context` | Day-in-cycle and coarse phase derived from logged period starts. Never predictive. |
+| `correlate_metrics` | Pearson correlation between two metrics with a 0..3 day lag. Association, not causation, always stated. |
+
+**Coverage:** 190 Apple Health metrics across activity, heart, HRV, mobility, respiratory, body, sleep, hearing, and nutrition, plus workouts. Data answers carry honest `coverage` blocks, and single-metric answers list logged events inside the window as `segmentBoundaries` so an average across a medication start or life change cannot masquerade as one regime.
+
+### 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).
+
+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).
+
+### MCP prompts
 
-**Coverage:** 190 Apple Health metrics across activity, heart, HRV, mobility, respiratory, body, sleep, hearing, and nutrition — plus workouts.
+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.
+
+### 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.
+
+### 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 receive             # standalone LAN receiver (binds 127.0.0.1 by default)
+node server.mjs --help
+```
 
 ---
 
@@ -234,7 +265,7 @@ stdio transport (newline-delimited JSON-RPC 2.0) — the universal MCP transport
 
 ## 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 8 tools above over MCP. No bridge, no Docker, no database — just a file 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 14 tools above over MCP. No bridge, no Docker, no database: just files and stdio.
 
 ```
 Apple Health → Health Export AI (iOS) → .health-cache.json → health-export-mcp → MCP client → you

package/demo.mjs

@@ -0,0 +1,259 @@
+// demo.mjs, the deterministic synthetic dataset behind --demo / HEALTH_DEMO=1.
+//
+// Purpose: let anyone exercise every tool with zero real data and zero iPhone. The dataset is
+// SYNTHETIC and every answer the server gives in demo mode is watermarked (demo: true plus a
+// [SYNTHETIC DEMO DATA] text prefix in server.mjs), so a screenshot or a pasted answer can never
+// pass for a real export.
+//
+// Determinism rules, both load-bearing:
+//   1. A seeded PRNG (mulberry32, fixed seed). Math.random would make every run a different
+//      "person", so a bug reproduced in demo mode could vanish on the next spawn.
+//   2. NO Date.now anywhere in generation. The date range is anchored to a FIXED end day
+//      (2026-08-18), so demo answers are byte-identical across runs and across machines, which is
+//      what makes them assertable in tests and comparable in bug reports.
+
+export const DEMO = process.argv.includes('--demo') || process.env.HEALTH_DEMO === '1';
+
+// Fixed anchor: the newest synthetic day. Never derived from the clock (see rule 2 above).
+export const DEMO_END = '2026-08-18';
+const DEMO_END_UTC = Date.UTC(2026, 7, 18);
+const DAYS = 400;
+const WRITTEN_AT = '2026-08-18T21:00:00Z';
+const SEED = 0x5EED1E;
+
+// mulberry32: tiny, fast, good-enough 32-bit PRNG. Cryptographic quality is irrelevant here;
+// reproducibility is the whole point.
+function mulberry32(seed) {
+  let t = seed >>> 0;
+  return function () {
+    t += 0x6D2B79F5;
+    let x = t;
+    x = Math.imul(x ^ (x >>> 15), x | 1);
+    x ^= x + Math.imul(x ^ (x >>> 7), x | 61);
+    return ((x ^ (x >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+// back = how many days before DEMO_END. back 0 is the anchor day itself.
+function day(back) {
+  return new Date(DEMO_END_UTC - back * 86400000).toISOString().slice(0, 10);
+}
+const r2 = (n) => Math.round(n * 100) / 100;
+const r3 = (n) => Math.round(n * 1000) / 1000;
+
+// The synthetic person has a few deliberate storylines so the segment/anchor/correlate tools have
+// something honest to find: a medication start that lowers resting HR, a night-shift block and a
+// migraine episode that dent HRV, and a trip that shortens sleep. Everything else is base + weekly
+// rhythm + noise.
+const MED_START_BACK = 200;      // medication event lands on day(back=200)
+const SHIFT_BACK = [90, 84];     // night shift block, inclusive day range
+const EPISODE_BACK = [60, 58];   // migraine episode
+const TRAVEL_BACK = [39, 32];    // trip; the tz change entry lands on the RETURN day (back=32)
+
+const inBack = (back, [hi, lo]) => back <= hi && back >= lo;
+
+function buildMetrics(rng) {
+  const m = {};
+  const put = (name, unit, cumulative, fn) => {
+    const daily = [];
+    for (let back = DAYS - 1; back >= 0; back--) {
+      const v = fn(back);
+      if (v == null) continue;                    // sparse metrics skip days, like real ones do
+      daily.push({ d: day(back), v });
+    }
+    m[name] = { unit, cumulative: !!cumulative, daily };
+  };
+  const week = (back) => Math.sin(((DAYS - back) % 7) / 7 * 2 * Math.PI);
+
+  put('step_count', 'count', true, (b) => Math.round(8500 + week(b) * 2200 + (rng() - 0.5) * 3000));
+  put('heart_rate', 'count/min', false, (b) => r2(68 + week(b) * 3 + (rng() - 0.5) * 6));
+  put('resting_heart_rate', 'count/min', false, (b) =>
+    r2((b <= MED_START_BACK ? 54 : 58) + (rng() - 0.5) * 3));
+  put('heart_rate_variability', 'ms', false, (b) => {
+    let base = 52 + week(b) * 4;
+    if (inBack(b, SHIFT_BACK) || inBack(b, EPISODE_BACK)) base -= 9;
+    return r2(base + (rng() - 0.5) * 10);
+  });
+  put('sleep_analysis', 'hr', false, (b) => {
+    let base = 7.4 + week(b) * 0.4;
+    if (inBack(b, TRAVEL_BACK)) base -= 1.1;
+    return r2(base + (rng() - 0.5) * 1.0);
+  });
+  put('weight_body_mass', 'kg', false, (b) => r2(81.5 - (DAYS - b) * 0.008 + (rng() - 0.5) * 0.6));
+  put('blood_oxygen_saturation', '%', false, () => r3(0.955 + rng() * 0.035));
+  put('active_energy', 'kcal', true, (b) => Math.round(520 + week(b) * 140 + (rng() - 0.5) * 200));
+  put('vo2_max', 'ml/kg*min', false, (b) => (b % 7 === 0 ? r2(44 + (DAYS - b) * 0.004 + (rng() - 0.5) * 0.8) : null));
+  put('respiratory_rate', 'count/min', false, () => r2(14 + (rng() - 0.5) * 1.6));
+
+  // Glucose plus the contract-7 derived metrics, present only on the "CGM period" (last 150 days),
+  // because a real cache only carries them on days with at least 24 readings.
+  const CGM_DAYS = 150;
+  const glucoseMean = new Map();
+  put('blood_glucose', 'mg/dL', false, (b) => {
+    if (b >= CGM_DAYS) return null;
+    const v = r2(112 + week(b) * 6 + (rng() - 0.5) * 14);
+    glucoseMean.set(b, v);
+    return v;
+  });
+  const gm = (b) => glucoseMean.get(b);
+  put('glucose_time_in_range_pct', '%', false, (b) => (b >= CGM_DAYS ? null : r3(0.86 - Math.max(0, gm(b) - 100) * 0.004 - rng() * 0.04)));
+  put('glucose_time_below_range_pct', '%', false, (b) => (b >= CGM_DAYS ? null : r3(rng() * 0.03)));
+  put('glucose_time_above_range_pct', '%', false, (b) => {
+    if (b >= CGM_DAYS) return null;
+    const tir = m.glucose_time_in_range_pct.daily.find((p) => p.d === day(b))?.v ?? 0.8;
+    const below = m.glucose_time_below_range_pct.daily.find((p) => p.d === day(b))?.v ?? 0.01;
+    return r3(Math.max(0, 1 - tir - below));
+  });
+  put('glucose_cv_pct', '%', false, (b) => (b >= CGM_DAYS ? null : r3(0.24 + rng() * 0.08)));
+  // GMI per Bergenstal 2018: 3.31 + 0.02392 x mean mg/dL, stored /100 like every % metric.
+  put('glucose_gmi_pct', '%', false, (b) => (b >= CGM_DAYS ? null : r3((3.31 + 0.02392 * gm(b)) / 100)));
+
+  put('exercise_time', 'min', true, (b) => Math.round(Math.max(0, 32 + week(b) * 18 + (rng() - 0.5) * 24)));
+  put('walking_running_distance', 'km', true, (b) => r2(6.2 + week(b) * 2 + (rng() - 0.5) * 2.4));
+  return m;
+}
+
+function buildWorkouts(rng) {
+  const workouts = [];
+  for (let n = 0; n < 30; n++) {
+    const back = 393 - n * 13;                              // oldest first, newest ~1 week ago
+    const d = day(back);
+    const kinds = [
+      { name: 'Running', activityType: 37 },
+      { name: 'Cycling', activityType: 13 },
+      { name: 'Walking', activityType: 52 },
+    ];
+    const k = kinds[n % 3];
+    const durationMin = Math.round(40 + rng() * 35);
+    const start = `${d}T07:30:00+01:00`;
+    const endMs = Date.parse(start) + durationMin * 60000;
+    // Render the end instant on the same +01:00 wall clock as the start: shift by the offset, then
+    // relabel the Z. Rendering the raw instant with a +01:00 suffix would silently shift end times
+    // an hour early.
+    const end = new Date(endMs + 3600000).toISOString().replace(/\.\d{3}Z$/, '+01:00');
+    const w = {
+      id: `demo-w-${String(n + 1).padStart(2, '0')}`,
+      name: k.name,
+      activityType: k.activityType,
+      start,
+      end,
+      duration: durationMin * 60,
+      activeEnergyBurned: Math.round(durationMin * (5 + rng() * 6)),
+      distanceMeters: Math.round(durationMin * (k.name === 'Cycling' ? 420 : 160) * (0.9 + rng() * 0.2)),
+      distanceSource: 'watch',
+      avgHeartRate: Math.round(128 + rng() * 22),
+      maxHeartRate: Math.round(160 + rng() * 20),
+      elevationAscendedMeters: Math.round(rng() * 220),
+    };
+    if (k.name === 'Running') {
+      w.runningPowerAvgWatts = Math.round(255 + rng() * 40);
+      w.strideLengthAvgMeters = r2(1.02 + rng() * 0.18);
+      w.verticalOscillationAvgCm = r2(7.6 + rng() * 1.8);
+      w.groundContactTimeAvgMs = Math.round(240 + rng() * 40);
+      w.hasRoute = true;
+      const lap = Math.floor((durationMin * 60) / 3);
+      w.intervals = [0, 1, 2].map((i) => ({
+        start: new Date(Date.parse(start) + i * lap * 1000).toISOString(),
+        end: new Date(Date.parse(start) + (i + 1) * lap * 1000).toISOString(),
+        duration: lap,
+        kind: 'lap',
+      }));
+    }
+    if (k.name === 'Cycling') {
+      w.cyclingPowerAvgWatts = Math.round(180 + rng() * 60);
+      w.cadenceAvg = Math.round(82 + rng() * 12);
+      w.hasRoute = true;
+    }
+    workouts.push(w);
+  }
+  return workouts;
+}
+
+function buildEvents() {
+  const events = [
+    { id: 'demo-evt-med-1', date: day(MED_START_BACK), type: 'medication', title: 'Started propranolol 40mg', tags: ['propranolol'] },
+    { id: 'demo-evt-visit-1', date: day(180), type: 'visit', title: 'GP review', tags: ['gp'] },
+    { id: 'demo-evt-habit-1', date: day(150), type: 'habit', title: 'Stopped caffeine after midday', tags: ['caffeine'] },
+    { id: 'demo-evt-life-1', date: day(120), type: 'life', title: 'Moved house' },
+    { id: 'demo-evt-shift-1', date: day(SHIFT_BACK[0]), endDate: day(SHIFT_BACK[1]), type: 'shift', title: 'Night shift block', tags: ['nights'] },
+    { id: 'demo-evt-episode-1', date: day(EPISODE_BACK[0]), endDate: day(EPISODE_BACK[1]), type: 'episode', title: 'Migraine episode', tags: ['migraine'] },
+    { id: 'demo-evt-travel-1', date: day(TRAVEL_BACK[0]), endDate: day(TRAVEL_BACK[1]), type: 'travel', title: 'Trip to New York', tags: ['travel'] },
+    { id: 'demo-evt-visit-2', date: day(40), type: 'visit', title: 'GP follow up', tags: ['gp'] },
+  ].sort((a, b) => a.date.localeCompare(b.date));
+  return { schema: 1, app: '1.5', writtenAt: WRITTEN_AT, events };
+}
+
+function buildSessions(rng) {
+  const sessions = [];
+  for (let back = 58; back >= 0; back--) {
+    const hours = r2(inBack(back, TRAVEL_BACK) ? 5.4 + rng() * 0.8 : 6.9 + rng() * 1.4);
+    const startH = 22 + Math.floor(rng() * 2);
+    const startMin = Math.floor(rng() * 60);
+    const endH = Math.floor((startH + hours) % 24);
+    sessions.push({
+      start: `${day(back + 1)}T${String(startH).padStart(2, '0')}:${String(startMin).padStart(2, '0')}:00+01:00`,
+      end: `${day(back)}T${String(endH).padStart(2, '0')}:${String(startMin).padStart(2, '0')}:00+01:00`,
+      day: day(back),
+      hours,
+      stages: { core: r2(hours * 0.55), deep: r2(hours * 0.16), rem: r2(hours * 0.24), awake: r2(hours * 0.05) },
+    });
+  }
+  // One split night: the same waking day carries a second, short session (a 90 minute early wake
+  // and a return to bed). Split nights are the exact case get_sleep_sessions must return as-is.
+  sessions.push({
+    start: `${day(3)}T05:40:00+01:00`,
+    end: `${day(3)}T07:10:00+01:00`,
+    day: day(3),
+    hours: 1.5,
+    stages: { core: 1.1, deep: 0.1, rem: 0.25, awake: 0.05 },
+  });
+  sessions.sort((a, b) => a.start.localeCompare(b.start));
+  return { schema: 1, writtenAt: WRITTEN_AT, sessions };
+}
+
+function buildCycles() {
+  return { schema: 1, writtenAt: WRITTEN_AT, cycleStarts: [day(77), day(49), day(20)] };
+}
+
+function buildDaysFile() {
+  return {
+    schema: 1,
+    writtenAt: WRITTEN_AT,
+    currentTz: 'Europe/London',
+    // One change entry: the return from the synthetic New York trip. The day a change lands on is
+    // by definition not 24 hours long, which is what excludeTravelDays keys off.
+    changes: [{ from: day(TRAVEL_BACK[1]), tz: 'Europe/London', utcOffsetMin: 60 }],
+    note: 'Timezone history is recorded from 2026-07-17 onward. Days before the first change entry were bucketed in the timezone current at export time.',
+  };
+}
+
+function buildProfile() {
+  return {
+    schema: 1,
+    writtenAt: WRITTEN_AT,
+    fields: {
+      conditions: ['migraine'],
+      medications: ['propranolol 40mg'],
+      goals: ['average 7.5 hours of sleep', '10k steps most days'],
+      notes: 'Training for an autumn half marathon.',
+    },
+  };
+}
+
+// Built once and cached: generation is cheap but the memoized loaders upstream key on object
+// identity, so handing out a fresh object per call would defeat their caching.
+let _demo = null;
+export function demoData() {
+  if (_demo) return _demo;
+  const rng = mulberry32(SEED);
+  _demo = {
+    metrics: buildMetrics(rng),
+    workouts: buildWorkouts(rng),
+    events: buildEvents(),
+    profile: buildProfile(),
+    sessions: buildSessions(rng),
+    cycles: buildCycles(),
+    days: buildDaysFile(),
+  };
+  return _demo;
+}

package/events.mjs

@@ -0,0 +1,288 @@
+// events.mjs, readers for the context files added by the 2026-08 feature wave
+// (docs/SCHEMA-CONTRACTS.md is the authoritative contract):
+//
+//   health-events.json    the one logging surface (medication, habit, visit, life, shift, episode, travel, other)
+//   health-profile.json   per-field opt-in context the user chose to share
+//   health-sessions.json  clustered sleep sessions, attributed to the WAKING day
+//   health-cycles.json    user-logged menstrual cycle starts (observed only, never predictive)
+//   health-days.json      the timezone change log (the travel-day source)
+//
+// Every file is OPTIONAL. An absent file answers {available:false, note}, never "no data": a
+// consumer must never read a missing file as "nothing happened". All reads share healthstore's
+// (mtime, size) memo and sit behind the same pairing gate as the cache, because these files carry
+// exactly the kind of context (medication, cycles) that the pairing gate exists to protect.
+//
+// This module and healthstore.mjs import each other. The cycle is deliberate and safe: both sides
+// reference the other's bindings only INSIDE functions, never during module evaluation, so ESM's
+// in-progress module record is fully initialized by the first call. Moving the shared low-level
+// helpers out would mean relocating DATA_DIR resolution, which healthstore.test.mjs pins by
+// setting HEALTH_DATA_DIR before import.
+
+import { readJSONCached, assertUnlocked, assertDay, dataPath } from './healthstore.mjs';
+import { DEMO, demoData } from './demo.mjs';
+
+export const KNOWN_EVENT_TYPES = ['medication', 'habit', 'visit', 'life', 'shift', 'episode', 'travel', 'other'];
+// Range events describe a STATE that covers days (a shift block, a trip, an episode). They are not
+// segment boundaries: an average across a state is an average of that state, not a before/after mix.
+const RANGE_TYPES = new Set(['shift', 'travel', 'episode']);
+
+const EVENTS_FILE = 'health-events.json';
+const PROFILE_FILE = 'health-profile.json';
+const SESSIONS_FILE = 'health-sessions.json';
+const CYCLES_FILE = 'health-cycles.json';
+const DAYS_FILE = 'health-days.json';
+
+// YYYY-MM-DD day arithmetic without timezones: date-only strings parse as UTC midnight, so adding
+// whole days can never cross a DST boundary.
+export function addDays(d, n) {
+  return new Date(Date.parse(d) + n * 86400000).toISOString().slice(0, 10);
+}
+
+function absent(file, what) {
+  return {
+    available: false,
+    note: `No ${file} found. ${what} Absence of the file means it was never exported (or the app predates it), not that nothing happened.`,
+  };
+}
+
+// ---- raw loaders (memoized via healthstore's readJSONCached) ---------------
+
+/** The parsed events file, or null when absent/corrupt. Callers treat null as "unavailable". */
+export function loadEventsFile() {
+  if (DEMO) return demoData().events;
+  const raw = readJSONCached(dataPath(EVENTS_FILE), null);
+  return raw && Array.isArray(raw.events) ? raw : null;
+}
+
+export function loadDaysFile() {
+  if (DEMO) return demoData().days;
+  const raw = readJSONCached(dataPath(DAYS_FILE), null);
+  return raw && Array.isArray(raw.changes) ? raw : null;
+}
+
+function loadProfileFile() {
+  if (DEMO) return demoData().profile;
+  const raw = readJSONCached(dataPath(PROFILE_FILE), null);
+  return raw && raw.fields && typeof raw.fields === 'object' ? raw : null;
+}
+
+function loadSessionsFile() {
+  if (DEMO) return demoData().sessions;
+  const raw = readJSONCached(dataPath(SESSIONS_FILE), null);
+  return raw && Array.isArray(raw.sessions) ? raw : null;
+}
+
+function loadCyclesFile() {
+  if (DEMO) return demoData().cycles;
+  const raw = readJSONCached(dataPath(CYCLES_FILE), null);
+  return raw && Array.isArray(raw.cycleStarts) ? raw : null;
+}
+
+// ---- derived helpers shared with healthstore's segment honesty -------------
+
+/** Every local day an event covers: endDate ranges inclusive, point events their single day. */
+export function eventDays(e) {
+  if (!e?.date) return [];
+  if (!e.endDate || e.endDate < e.date) return [e.date];
+  const days = [];
+  for (let d = e.date; d <= e.endDate; d = addDays(d, 1)) {
+    days.push(d);
+    if (days.length > 3700) break;   // a corrupt endDate must not spin a ten-year loop
+  }
+  return days;
+}
+
+/** The set of days covered by events matching {eventType, eventTag}. Null when the file is absent,
+ *  which callers must surface honestly rather than treating as an empty match. */
+export function matchingEventDaySet({ eventType, eventTag } = {}) {
+  const file = loadEventsFile();
+  if (!file) return null;
+  const days = new Set();
+  for (const e of file.events) {
+    if (eventType && e.type !== eventType) continue;
+    if (eventTag && !(Array.isArray(e.tags) && e.tags.includes(eventTag))) continue;
+    for (const d of eventDays(e)) days.add(d);
+  }
+  return days;
+}
+
+/** Days on which a timezone change landed (day length was not 24h). Null when no log exists. */
+export function travelDaySet() {
+  const file = loadDaysFile();
+  if (!file) return null;
+  const days = new Set();
+  for (const c of file.changes) {
+    if (typeof c?.from === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(c.from)) days.add(c.from);
+  }
+  return days;
+}
+
+/** Segment boundaries inside [start, end]: POINT events (no endDate) of the boundary types.
+ *  Range events (shift, travel, episode) are states, not boundaries, and are excluded; so are
+ *  visits, which observe rather than change anything. Point events of a type this server does not
+ *  know are INCLUDED: an unknown type written by a newer app is more likely an intervention we
+ *  cannot classify than noise, and silently ignoring it would hide a real segment. */
+export function boundariesIn(start, end) {
+  const file = loadEventsFile();
+  if (!file) return null;
+  const boundaryType = (t) => t === 'medication' || t === 'habit' || t === 'life' || t === 'other'
+    || !KNOWN_EVENT_TYPES.includes(t);
+  return file.events
+    .filter((e) => e?.date && !e.endDate && boundaryType(e.type)
+      && (!start || e.date >= start) && (!end || e.date <= end))
+    .map((e) => ({ date: e.date, type: e.type, title: e.title ?? null }))
+    .sort((a, b) => a.date.localeCompare(b.date));
+}
+
+export const SEGMENT_NOTE = (n) =>
+  `The window spans ${n} logged event(s). An average across a boundary can be a number that was true on no actual day; consider compare_periods anchored at the event date.`;
+
+/** Find one event by id. Returns {available:false} | {available:true, event|null}. */
+export function findEvent(id) {
+  const file = loadEventsFile();
+  if (!file) return { available: false, event: null };
+  return { available: true, event: file.events.find((e) => e?.id === id) ?? null };
+}
+
+// ---- tool-level answers ----------------------------------------------------
+
+export async function listEvents({ type, tag, start, end } = {}) {
+  assertUnlocked();
+  start = assertDay(start, 'start');
+  end = assertDay(end, 'end');
+  if (start && end && start > end) throw new Error(`start (${start}) is after end (${end})`);
+  const file = loadEventsFile();
+  if (!file) {
+    return absent(EVENTS_FILE, 'Events appear when the iOS app (1.5 or later) logs one (medication start, habit change, visit, shift block, trip) and exports.');
+  }
+  // Unknown types pass through unharmed: no allowlist here. A type filter matches the stored
+  // string exactly, so a newer app's types remain reachable by name.
+  let events = file.events.filter((e) => e && typeof e.date === 'string');
+  if (type) events = events.filter((e) => e.type === type);
+  if (tag) events = events.filter((e) => Array.isArray(e.tags) && e.tags.includes(tag));
+  // A range event is "in" the window when it OVERLAPS it, matching how its days are counted.
+  if (start || end) {
+    events = events.filter((e) => {
+      const last = e.endDate && e.endDate >= e.date ? e.endDate : e.date;
+      return (!start || last >= start) && (!end || e.date <= end);
+    });
+  }
+  events = [...events].sort((a, b) => a.date.localeCompare(b.date) || String(a.id).localeCompare(String(b.id)));
+  return {
+    available: true,
+    count: events.length,
+    knownTypes: KNOWN_EVENT_TYPES,
+    events,
+    ...(events.length === 0 && {
+      note: 'No events matched. The file is present; nothing matching this filter has been logged.',
+    }),
+  };
+}
+
+export async function getProfile() {
+  assertUnlocked();
+  const file = loadProfileFile();
+  const withheldNote =
+    'Fields are per-field opt-in. An absent field was withheld by the user or never enabled; absence must not be read as "none". Age, sex, height and weight are HealthKit metrics in the daily cache, not profile fields.';
+  if (!file) {
+    return absent(PROFILE_FILE, 'The profile appears when the user opts in to sharing context fields in the iOS app (1.5 or later) and exports. ' + withheldNote);
+  }
+  const presentFields = Object.keys(file.fields);
+  return {
+    available: true,
+    presentFields,
+    fields: file.fields,
+    writtenAt: file.writtenAt ?? null,
+    note: withheldNote,
+  };
+}
+
+export async function getSleepSessions({ start, end, day } = {}) {
+  assertUnlocked();
+  start = assertDay(start, 'start');
+  end = assertDay(end, 'end');
+  day = assertDay(day, 'day');
+  if (start && end && start > end) throw new Error(`start (${start}) is after end (${end})`);
+  const file = loadSessionsFile();
+  if (!file) {
+    return absent(SESSIONS_FILE, 'Sleep sessions appear when the iOS app (1.5 or later) exports its clustered sessions.');
+  }
+  let sessions = file.sessions.filter((s) => s && typeof s.day === 'string');
+  if (day) sessions = sessions.filter((s) => s.day === day);
+  if (start) sessions = sessions.filter((s) => s.day >= start);
+  if (end) sessions = sessions.filter((s) => s.day <= end);
+  sessions = [...sessions].sort((a, b) => String(a.start).localeCompare(String(b.start)));
+  return {
+    available: true,
+    count: sessions.length,
+    sessions,
+    note: 'Sessions are attributed to the WAKING day: a night from 23:00 on the 18th to 06:50 on the 19th belongs to day 2026-08-19, matching the daily cache\'s sleep_analysis attribution. Multiple sessions on one day are a split night, returned as-is; union the hours, never sum overlapping sessions.',
+  };
+}
+
+// ---- cycle context ---------------------------------------------------------
+
+const CYCLE_BASIS = 'Derived from logged periods, not predictive. Phase labels are coarse: follicular from day 1 to the observed midpoint of that cycle (day 14 for the ongoing cycle, whose length is not yet observed), luteal for the remainder. No ovulation estimate is made.';
+
+function cycleDayContext(date, starts) {
+  // starts is ascending. Find the last start <= date.
+  let idx = -1;
+  for (let i = 0; i < starts.length; i++) if (starts[i] <= date) idx = i;
+  if (idx < 0) return null;
+  const start = starts[idx];
+  const next = starts[idx + 1];   // undefined for the ongoing cycle
+  const dayInCycle = Math.round((Date.parse(date) - Date.parse(start)) / 86400000) + 1;
+  const observedLength = next ? Math.round((Date.parse(next) - Date.parse(start)) / 86400000) : null;
+  const midpoint = observedLength ? Math.floor(observedLength / 2) : 14;
+  return {
+    date,
+    cycleStart: start,
+    dayInCycle,
+    phase: dayInCycle <= midpoint ? 'follicular' : 'luteal',
+    observedCycleLengthDays: observedLength,
+    ongoing: !next,
+  };
+}
+
+export async function getCycleContext({ date } = {}) {
+  assertUnlocked();
+  date = assertDay(date, 'date');
+  const file = loadCyclesFile();
+  // The derived-not-predictive basis rides on EVERY answer, the unavailable one included: an
+  // agent that only ever sees the absent branch must still learn what this surface is and is not.
+  const starts = file ? [...file.cycleStarts].filter((d) => typeof d === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(d)).sort() : [];
+  if (!starts.length) {
+    return {
+      ...absent(CYCLES_FILE, 'Cycle context appears when menstrual flow is logged in Apple Health and the iOS app (1.5 or later) exports the observed cycle starts.'),
+      basis: CYCLE_BASIS,
+    };
+  }
+  if (date) {
+    const ctx = cycleDayContext(date, starts);
+    if (!ctx) {
+      return {
+        available: true,
+        date,
+        context: null,
+        cycleStarts: starts,
+        note: `${date} is before the first logged cycle start (${starts[0]}), so no day-in-cycle can be derived for it. ` + CYCLE_BASIS,
+      };
+    }
+    return { available: true, date, context: ctx, cycleStarts: starts, basis: CYCLE_BASIS };
+  }
+  // Default: per-day context for the last cycle, from its start through the current day (in demo
+  // mode the fixed synthetic anchor, so demo answers stay deterministic).
+  const lastStart = starts[starts.length - 1];
+  const today = DEMO ? '2026-08-18' : new Date().toISOString().slice(0, 10);
+  const until = today >= lastStart ? today : lastStart;
+  const days = [];
+  for (let d = lastStart; d <= until && days.length < 120; d = addDays(d, 1)) {
+    days.push(cycleDayContext(d, starts));
+  }
+  return {
+    available: true,
+    cycleStarts: starts,
+    lastCycle: { start: lastStart, days },
+    basis: CYCLE_BASIS,
+  };
+}

package/glama.json

@@ -5,7 +5,7 @@
   ],
   "name": "health-export-mcp",
   "description": "Query 190 Apple Health/HealthKit metrics from any MCP AI agent — zero-dependency, local-first, read-only. The open-source server for the Health Export AI app.",
-  "longDescription": "An open-source, zero-dependency MCP server that turns your Apple Health export into 8 query tools any AI agent can call in natural language. Tracks HRV, sleep, resting heart rate, steps, workouts, VO₂ max, and 180+ more metrics — all local-first with no developer server in the path.",
+  "longDescription": "An open-source, zero-dependency MCP server that turns your Apple Health export into 14 query tools any AI agent can call in natural language. Tracks HRV, sleep, resting heart rate, steps, workouts, VO₂ max, and 180+ more metrics — all local-first with no developer server in the path.",
   "categories": [
     "healthcare",
     "lifestyle",