MetricBridge Apple Health

Log a context event the user tells you about (a medication start, a habit change, a visit, a trip) so later analysis can segment around it. Writes ONLY health-events-agent.json in the export folder, never Apple Health and never a file the iOS app writes; the app shows these events read-only. Returns the stored event with its id (starting "agent-"). Idempotent: repeating a call with the same clientEventId (or, without one, the same date, type, title and endDate) returns the event already logged instead of adding a duplicate. Ask the user before logging anything they did not state. Refused in demo mode, when the folder is not writable, and on an encrypted export without HEALTH_EXPORT_PASSPHRASE (the file is sealed like the rest of the export when the passphrase is set).

Compare a metric between two arbitrary date periods (A vs B): each aggregate plus the change and percent change. Pass periodA/periodB explicitly, or pass anchor {eventId, days} to build both periods around a logged event (the before/after question, with the event day excluded from both sides).

Pearson correlation between two metrics' daily values: {metricA, metricB, lag (0 to 3, default 0), start, end}. lag pairs metricA on day d with metricB on day d+lag, so lag 1 compares against the FOLLOWING day. Returns alignedPairs, r (withheld below 10 aligned pairs), and both means. The answer always carries the association-not-causation caveat; treat every r as alignment in this file, not mechanism.

Morning check-ins the user chose to share (health-check-ins.json): per day a self-rated feeling (1 rough to 5 great), an optional note, an intention for the day and whether it happened (answered the next morning). Optional {start, end} filters. Returns the rows plus a summary (rated, averageFeeling, intentionsAnswered, intentionsMet). Opt-in in the iOS app and off by default, so available:false is the usual answer and means not shared, never "felt nothing". A self-rating is the person's own words, not a measurement.

Cycle context derived from user-logged period starts (health-cycles.json): day-in-cycle and a coarse phase label (follicular from day 1 to the observed midpoint of that cycle, luteal for the remainder). Derived from logged periods only, never predictive, and no ovulation estimate is made. Optional {date} for a single day; default returns per-day context for the last cycle.

How current the exported files are, so you can decide whether to trust what you read or ask the user to refresh. `stale` is judged on the core files (the daily cache and health-sessions.json), never on the hourly intraday file: true when their newest write is older than `stale_after_hours` (default 26, or HEALTH_STALE_AFTER_HOURS, or your maxAgeHours), or when this machine holds a stale copy. `state` is fresh, stale, stale_copy, no_data, locked or demo. stale_copy means the phone's manifest (.health-manifest.json) or iCloud says the phone wrote a newer version of a core file than the one on this machine (`stale_copy` lists each file with localWrittenAt, phoneWrittenAt and reason); relay the recommendation, which says how to make iCloud Drive download it. Also returns `age_hours`, `as_of` (when the phone wrote the daily cache), `last_data_date`, `data_lag_days`, per-file write times with each file's match against the manifest, `stale_files`, `manifest_behind` (the manifest lags the data, not stale), `sessions_last_night` (present or absent; without a manifest, advisory only, people skip nights) and, on a Mac, an advisory `icloud` status per core file. Same rule as the `status --max-age` cron gate. When no export is found, `recommendation` also names the companion iOS app's App Store page and website (the same links as `app.appStoreUrl` and `app.unlockUrl`); when the newest readable export is older than the server's own window (not a stricter maxAgeHours), it names the website. Both carry fixed campaign labels. Cheap: call it again before a long analysis.

Get values for a metric (or all metrics) over an optional date range, with an aggregate (avg/sum/min/max/latest). The core data-retrieval tool. Every result carries a `coverage` block giving the metric's real firstDate/lastDate/days: check it before trusting a long window, and note that `aggregate` is always computed over the full range even when `points` are rolled up. Single-metric answers also list any logged point events inside the window as segmentBoundaries. For blood_pressure_systolic or blood_pressure_diastolic at day granularity, the individual readings behind the daily mean are attached as `readings` [{t, systolic, diastolic, source, manual}] when the app exported them (health-readings.json), the most recent 150 in range, with `readingsOmitted` counting the rest. A day the app rebuilt after samples arrived late (or were deleted) carries `recomputed_at`, and a metric with rebuilt or possibly stale past days carries a `recompute` block (backfilled_days, recomputed_at, capped); untouched days carry neither.

The current hour-by-hour window from the iOS app's HOURLY automations (health-intraday.json, app 1.4+): each metric's hourly points (t, v = the hour's value) plus its latest value. The window covers a 48-hour span, yesterday 00:00 local to now, and the file is REPLACED on every run, so this is a live recent view, not history; use get_health_metrics for day-level questions. Discrete metrics (heart rate, SpO2, respiratory rate, HRV, resting heart rate) carry the hour's Min and Max beside v (the hour's mean) when the app version writes them; older exports cover today only and have no Min/Max. Returns available:false with setup guidance when no hourly automation has delivered yet.

The user's lab results from Apple Health Records (health-labs.json), exported only when they switched on Lab results > Include in exports in the MetricBridge iOS app, and only into a picked folder (never iCloud Drive). Off by default. Each test (LOINC code when the lab sent one, name, unit) lists its results oldest first, with the value, date, institution and the lab's own reference range, all exactly as reported. Nothing is flagged, graded or interpreted: do not call a result normal or abnormal, and never convert between units (a test in two units is listed once per unit, splitByUnit: true). Filters: {test (case-insensitive part of the name, e.g. ldl), loinc (exact code, e.g. 13457-7), start, end (local days, inclusive)}. Above 400 matching results the newest 400 are returned with `resultsOmitted`. No match returns count 0 with `knownTests`. When the file is missing the answer is available:false, which means the user has not exported lab results, not that they have none.

Health check: data source, how many metrics/workouts are available, which optional context files exist, the most recent data date, a compact `freshness` block (its `state` is stale_copy, with a `stale_copy` list, when this machine holds an older copy of the export than the phone last wrote), and a `recompute` summary of past days rebuilt after late-arriving samples (with any days too old to rebuild; `supported: null` when the cache cannot tell). Call this first to confirm the bridge is connected. The result also includes `app.unlockUrl` and `app.appStoreUrl`, the website and App Store page of the companion iOS app that writes the export; both links carry fixed campaign attribution labels.

The context fields the user explicitly opted in to sharing (health-profile.json): conditions, medications, goals, allergies, notes. Returns the fields plus a presentFields list. An absent field was withheld by the user or never enabled; absence must never be read as "none".

Clustered sleep sessions from health-sessions.json with {start, end, day} filters. Sessions are attributed to the WAKING day, matching the daily cache's sleep_analysis, so the two surfaces never disagree; a split night appears as separate sessions with the same day. Duplicate copies of one night left by older app versions (sharing an end time with, or lying inside, a longer session on the same day) are collapsed to the longer one and counted in `collapsedDuplicates`. A session with manualInBed:true was built from an In Bed entry typed into the Health app with no asleep sample. Timestamps carry the local UTC offset at the time of the sample.

The strength log the user keeps in the MetricBridge app (health-strength.json, opt-in, off by default): each session with its exercises and every set as entered (reps, kg, warmup or working, RPE), plus volumeKg, workingSets and an Epley bestEstimateKg per exercise, all-time records per exercise, and the routines the user saved (their own templates). Filters: {exercise (exact name, case-insensitive, e.g. "Back squat"), start, end (local days, inclusive)}. Sessions come oldest first; above 150 matches the most recent 150 are listed and `sessionsOmitted` counts the rest. An unknown exercise returns count 0 with `knownExercises`. Logged by hand, never read from Apple Health; when the file is missing the answer is available:false, which means the user has not switched the export on, not that they do not train.

Return clean structured JSON for the chosen metrics/date range. Paginated: the result carries `nextCursor` when more metrics remain; pass it back as `cursor` for the next page. Prefer naming the metrics you need and a date range; calling it bare over a full history is a lot of data.

Compare the most recent N-day window against the prior N days for a metric: change, percent change and direction (up/down/flat). Also returns `daysAvailable` and `windowSatisfied`: if windowSatisfied is false the file does not hold enough history for the window you asked for, and the comparison is over less data than requested. Logged point events inside the compared span are listed as segmentBoundaries.

Query the workouts cache with {activityType (a name like Running, or a raw HealthKit id like 37), start, end} filters and pagination ({limit} default 50 max 200, {cursor} from a previous nextCursor). Records are returned exactly as stored, including the newer optional keys (avgHeartRate, maxHeartRate, running dynamics, cycling power, intervals, hasRoute) when the app exported them; older caches simply lack those keys and nothing is fabricated. Also returns summary {count, byActivityType} over everything that matched.

Logged context events: medication starts, habit changes, doctor visits, life events, shift blocks, episodes, travel, and any type a newer app adds. Merges the app's health-events.json with health-events-agent.json (events logged with add_event); every event carries source "app" or "agent". Optional {type, tag, start, end} filters; a range event matches a window it overlaps. Sorted ascending by date. Returns available:false when neither file exists; absence means nothing was logged or exported, not that nothing happened.

List every available Apple Health metric with its unit, day count, and date range. Use this to discover metric names before querying.

Tags the user logged in the iOS app (health-tags.json): lifestyle tags such as Alcohol or Sauna, and supplements such as Creatine or Magnesium, by name only and never an amount. Optional {kind: all | supplement | lifestyle, start, end}. Returns one row per tag (kind, days logged, firstDay, lastDay, most logged first) and the tag names per day. Tag export is opt-in in the app and off by default, so available:false is the usual answer and means the file was not exported, not that nothing was tagged. Treat any difference after tagged days as an association in this person's own data, never as evidence that a supplement works.

Natural-language convenience: pass a question and get routed structured results. Prefer the specific tools above when you can, and call list_metrics first to see how much history exists, since this tool answers over whatever the file holds.

Remove an event that was logged with add_event (id starting "agent-", source "agent" in list_events) from health-events-agent.json. Events logged in the iOS app are refused: they are edited in the app. Removing an id that is already gone changes nothing and says so. Refused in demo mode and when the folder is not writable.

Look a metric name up in the canonical naming and unit table. Accepts the export's own name (step_count), a HealthKit identifier (StepCount, HKQuantityTypeIdentifierStepCount), a display title (Step Count) or a common alias (steps, hrv, spo2, weight) and returns the canonical metric, its unit (percentages are 0 to 1 fractions), the unit variants other apps use with the exact formula into the canonical unit, and whether this export holds it. Pass {value, unit} to convert one value, e.g. 180 lb to kg. A word naming several metrics (distance, calories) comes back ambiguous with candidates, and a different measure (RMSSD vs the SDNN that Apple Health stores) is refused with the reason: nothing is guessed. get_health_metrics, get_trends, compare_periods, get_structured_export and correlate_metrics accept the same aliases and report `resolvedFrom` when they used one; other tools take the export's own names. The export holds one value per metric per day, merged across sources by Apple Health, so this tool states honestly whether per-source disagreement can be seen in the file (exports that record per-source attribution carry `src`/`by` and a `sources` block; others report it as not available) rather than inventing it.