Repository navigation
Releases
v0.8.1
Fixed
- CLI
--helpand--versionblocked instead of exiting — runningquantified-self-mcp --helpor--versionpreviously passed arguments straight into FastMCP's stdio transport, causing the process to block waiting on stdin. Added standard CLI argument parsing withargparseso help, version, and unknown flags exit immediately without launching the server or reading from stdin.
v0.8.0
What's Changed
Added
--demoCLI flag onquantified-self-init-db— seeds 60 days of realistic synthetic health data ending yesterday, allowing immediate local testing with MCP clients without requiring an external export. Bundlessample_data/in the distribution wheel.- Official MCP Registry integration — added validated
server.jsonschema metadata, ownership verification marker inREADME.md, and automated registry publishing via GitHub Actions in.github/workflows/publish.yml. - Documented Oura Ring API (v2) adapter — added Oura to
docs/importing.mdand CLI flags reference.
Fixed
get_data_statussaid CURRENT while a metric had stopped arriving — the status andlatest_datacame from the newest day of any metric, so steps logged daily kept the database CURRENT while HRV, sleep or any other metric had not been updated for weeks, and a client had nothing to tell it so. The result now carriesstale_metrics: each metric whose own latest day trails today by more than its threshold (stale_after_days, or 30 days for weight and workouts, as in the coverage matrix and the analytics' data health), most behind first.
Full Changelog: v0.7.0...v0.8.0
v0.7.0
What's Changed
Added
PROVENANCEevidence dimension evaluator — added a dedicated provenance dimension evaluator inqs_evidence/provenance.pythat assesses source consistency and detects unranked source conflicts or source switches across evaluation windows. Registered across all analyses inqs_evidence/registry.yamlwithon_not_assessed: cap.- MCP-boundary evidence regression test suite — added
tests/test_evidence_contract_mcp.pytesting evidence contract adherence, claim sound tiers, and provenance caveat enforcement across all public analytics tools.
Fixed
- Source provenance and unranked conflicts were not carried into
ClaimDecision— analytical tools (get_baseline,get_metric_trend,compare_metric_windows,detect_anomalies,find_metric_correlation,explain_metric_change, andget_recent_changes) previously surfaced source conflicts indata_healthbut did not thread them intoClaimDecision, allowing baseline and trend claims to returntier=supportedwith emptymust_stateeven when the underlying window had conflicting data sources. Provenance is now evaluated and threaded across all analytics tools; unranked source conflicts cap claim confidence and mandate caveats inmust_state.
Maintenance
- Update dependencies (
types-pyyaml,pytest-asyncio).
Full Changelog: v0.6.0...v0.7.0
v0.6.0
What's Changed
Added
- Oura Ring API (v2) import adapter (
--source oura): Parses Oura export and API JSON payloads into daily metrics and raw measurements stamped with provenance (source="Oura"). - FastMCP Pre-baked Prompts: Registered
weekly_health_reviewanddoctor_visit_prepfor structured, evidence-guarded LLM consultations. - Agent-eval negative routing test suite (
should_not_use): Added 20 negative routing scenarios across all registered tools ineval/agent/scenarios/negative_routing.yaml.
Fixed
- Sum metric conflict evaluation:
get_metric_provenancenow compares per-source day totals instead of day averages for sum metrics (steps, sleep, water, workouts), eliminating false conflicts (closes #60). - Unit mismatch validation:
log_measurementnow validates provided units against the metric's canonical unit, rejecting conflicting units withERR_INVALID_METRIC_VALUE(closes #58). - Apple Health sleep import ceiling:
adapt_apple_healthvalidates per-source sleep totals individually, preventing days from being dropped when cross-source sums exceed 24 hours (closes #61). - Health Connect timezone offsets: Places records on their local calendar day using zone offset fields rather than UTC.
- Privacy redactions for workouts: Applied
HEALTH_PRIVATE_FIELDSto duration and heart-rate fields in workout session tools (closes #57). - Health Connect multi-origin provenance: Records separate day totals per data origin instead of summing across apps (closes #59).
v0.5.0
Added
- WHOOP import (
--source whoop). Reads JSON saved from the WHOOP Developer API v2 (a JSON array of
records, or one{"records": [...]}response): sleep (sleep_hours, asleep time only), recovery
(resting_heart_rate,hrv_msas an RMSSD) and workouts (workout_minutes). Every value is kept as its
own observation with the sourceWHOOP, local days come from each record'stimezone_offset, repeated
records import once, and a bad record is skipped and reported without stopping the rest. Written against
WHOOP's documented v2 sample responses and tested on synthetic data only; the WHOOP app's CSV export is
not supported. Seedocs/importing.mdfor the exact rules and what is left out. - Consistent backups and safe restores (
quantified-self-backup). Copyinghealth.dbis not a backup:
the database runs in WAL mode, so with anything holding it open a copy of the file alone can be empty or
miss recent writes.quantified-self-backup create FILEuses SQLite's online-backup API for a consistent
single-file snapshot, integrity-checks it, owner-only permissions, and never overwrites an existing file.
quantified-self-backup restore FILEvalidates the backup first (integrity, health database, schema not
newer than this release), stages and re-checks a copy, refuses while another program has the database open,
and moves the current database aside as<name>.pre-restore-<time>instead of deleting it. It is a
command-line tool only, not an MCP tool. - Canonical ingestion contract (
ingest.py). The one shape every source adapter's observations
must take: metric, naive local timestamp, value, canonical unit, source, source record id, original
timezone and quality, with a strict validator that normalises known unit spellings (count/minto
bpm), rejects timestamps with a UTC offset, values outside the registry bounds, units that need a
conversion, and unknown fields, and drops repeated record ids. A bad record is rejected on its own
with a reason and the rest of a batch still loads. Nothing uses it yet: adapters are moved onto it in
following changes. - Source coverage matrix.
python -m source_coverage(or--json) measures what the database
actually holds, per importer, source and metric: first and latest day, days covered, gaps, freshness,
the status of the import that produced it, provenance (units, source types, measurement counts) and
how many days analytics resolved to each source. Each entry is classified green, yellow or red with
its reasons listed, and a per-domain view (sleep, HRV, heart rate, activity, body measurements,
workouts) states explicitly that readiness, training load and routes are not modelled. Metrics in
HEALTH_PRIVATE_FIELDSare left out. HRV recorded as SDNN (Apple Health) and as RMSSD (Health
Connect) under one metric is flagged asmixed_statistics. Read-only; no new MCP tool. - Incremental imports with an audit trail. Re-importing a source no longer deletes and rewrites
everything: each (metric, day) is compared with what the importer already stored, unchanged days are left
exactly as they were (ids andimported_atkeep recording when they were first imported), and only new
or changed days are written. Eachimportsrow now recordsrecords_seen,records_added,
records_updated,records_unchangedandrecords_removed(days dropped by--replace), plus the
dataset coverage before and after, andget_import_statusreturns them.quantified-self-init-dbprints
the same counts. Schema migration 9 adds the columns to databases that already have the table. - Import history and data freshness. Every
quantified-self-init-dbrun now
records animportsrow (importer, source file name and SHA-256, status
running/succeeded/failed, rows loaded and skipped, measurements
written, error). Two read-only MCP tools expose it:get_data_statusreports
whether the database isCURRENT,STALE,INCOMPLETE,NO_DATAor
IMPORT_FAILED(latest data date, coverage, gaps, last successful import,
suggested action), andget_import_statuslists recent import runs.
Metrics inHEALTH_PRIVATE_FIELDSare ignored when computing coverage. data_healthon every analytics tool. A single
data-quality state for the window behind the answer:VALID,
VALID_WITH_GAPS,INSUFFICIENT_DATA,STALEorIMPORT_INCOMPLETE, with
every applicable reason, the latest observation and its age, the covered
period, gaps, observation count and the last import. It combines the window's
existing evidence with the import history and dataset status, and is
separate fromclaim(which is unchanged). Results that rest on several
windows (period comparisons, correlations, recent changes, explanations)
report the weakest window and list every window's reasons.- Agent-loop eval (
eval/agent, Phase 1). A real model, the real MCP
server and real tool results in a multi-turn loop, scored per layer (routing,
arguments, execution) with replayable traces, deterministic fixtures defined
relative to today, and a tool coverage matrix built from the live tool list
(python -m eval.agent --coverage --strict). The harness itself is covered
by offline tests that need no API key. Interpretation and final-answer
scoring are not built yet and are reported as not scored.
Changed
- The evidence registry now describes what is actually evaluated —
trend,
window_comparison,correlationandanomalylist only the dimensions that
have evaluators (sample and temporal, plus missingness for the first three),
likebaseline. Previously they also listed robustness, practical,
provenance and measurement_validity, which no evaluator produced, so every
claim resolved those asnot_assessedand could never exceedsuggestive.
Nothing is tolerated to make that go away: those four analyses now carry an
explicitmax_tier: suggestiveceiling whose factor,practical_not_evaluated,
is added toclaim.decision.must_state(a statistically detectable but trivial
effect cannot be calledsupportedwhile practical significance is unchecked).
claim.profile.dimensionsfor those analyses no longer contains the
not_assessedrobustness/practical/provenance entries, and
robustness_not_assessed,practical_not_assessedand
provenance_not_assessedno longer appear inmust_state. A parity test now
fails if a registry dimension has no evaluator or an evaluator's output is not
in the registry.
Fixed
-
A mistyped or unsupported metric is no longer reported as "no data".
read_measurementsand
get_metric_provenanceanswered a name nothing is stored under (for examplesleepinstead of
sleep_hours) with a successful empty result, so a client would tell the user they had no such data.
They now return the same[invalid_metric]errorlog_measurementalready used, listing the supported
metrics and suggesting the closest one. A supported metric with no readings in the window still returns
an empty result, and a metric that has stored readings stays readable even if its aggregation rule was
removed. -
The HTTP transport no longer listens on every network interface. Setting
PORT(the cloud-deploy
mode) used to bind0.0.0.0with no authentication, so anyone who could reach the machine could call
every tool, including the ones that write, clear and export data. It now binds loopback (FastMCP's
default). A deployment that must be reached from outside, such as a container behind a platform
router, now has to opt in withFASTMCP_HOST=0.0.0.0; that is still allowed but logs a warning that
nothing authenticates callers. Stdio use (noPORT) is unchanged. -
read_measurementsandread_workout_sessionsvalidate their inputs. A start/end that was not a
realYYYY-MM-DDdate (last week,2026-3-5), a window ending before it starts, or alimit
outside 1-1000 used to return a successful empty list (or, forlimit=-1and an unparseable
end_date, an unbounded one), which reads as "no data". They now return the same structured
[invalid_range]error asread_health_data. ISO timestamps are still accepted as bounds by
read_measurements; empty strings still mean "not given". -
Re-importing changed days no longer scans the whole metric once per day. Replacing a changed
(metric, day) deleted the importer's old rows with a filter no index could serve, so each changed
day read every row of that metric. The delete now seeks the day through the existing
(metric, timestamp)index and keeps the original filter as an exact check, so the same rows are
deleted. On a 1M-row database with 5% of days changed, the re-import went from about 83s to
about 24s (measured with a throwaway benchmark, not part of the repo). -
A failed import is now visible to
get_data_statusandget_import_statuseven when it fails
while reading the file. Only failures after parsing were recorded inimports, so a truncated or
unreadable export left no trace and the status stayedCURRENT. A read failure is now recorded as a
failed run (statusIMPORT_FAILED, actionrerun_import). The recorded reason is the error class
plus its file position for XML/JSON/CSV/encoding errors and the OS reason for I/O errors; a file the
importer rejects with its own message (e.g. a CSV with no date column) is recorded as rejected, and any
other error by class name only, so a record value or the file's full path never reaches the
model. The importer still raises exactly as before. -
Analytics no longer present a source change as a health change.
daily_metricskeeps one source
per (metric, day), but a baseline, trend, anomaly scan, comparison or correlation read it as one
anonymous series, so a device switch inside a window, a different device in each compared window,
or two d...
v0.4.1
Changes
🧰 Maintenance
- build(deps-dev): update ruff requirement from <0.17,>=0.16.9 to >=0.16.10,<0.17 @dependabot[bot] (#48)
- build(deps-dev): update ruff requirement from <0.17,>=0.16.8 to >=0.16.9,<0.17 @dependabot[bot] (#47)
0.4.0
What's Changed
- docs: add tested client guides (Claude Desktop, LM Studio, Open WebUI) by @Thecimal in #41
- Delete node directory by @Thecimal in #42
- Update ruff requirement from <0.17,>=0.16.6 to >=0.16.7,<0.17 by @dependabot[bot] in #43
- P0 evidence profile by @Thecimal in #44
- build(deps-dev): update ruff requirement from <0.17,>=0.16.7 to >=0.16.8,<0.17 by @dependabot[bot] in #45
New Contributors
- @dependabot[bot] made their first contribution in #43
Full Changelog: v0.3.0...0.4.0