# ResMed-Data-MCP

Archives raw data from a ResMed AirSense CPAP's SD card — read over Wi-Fi via
a Toshiba FlashAir card — into a local SQLite database on a Mac Mini, and
serves it read-only to any MCP client (Claude, Codex, Grok, etc.) over the
LAN via Streamable HTTP.

This is a personal quantified-self data plane, not a clinical tool: it
archives every field the device reports (AHI, leak rate, pressure, usage
hours, and everything else in the nightly summary, plus raw signal detail as
it becomes available) without computing or interpreting anything. Synthesis
— trends, "how did I sleep", correlations — is left to whatever AI client
queries it.

## How it works

The AirSense writes to its SD card in the [EDF](https://www.edfplus.info/)
format: `STR.edf` is a rolling ~365-day nightly summary (one data record per
night, one signal per column — AHI, leak, pressure, usage minutes, etc.),
and `DATALOG/<YYYYMMDD>/` holds per-night detail files at higher resolution
once the device has flushed them. A generic EDF/EDF+ parser
([`src/edf/parse.ts`](src/edf/parse.ts)) reads both without any ResMed-specific
field list — it just reads whatever signals the header declares, so it also
works on future firmware and other ResMed models without changes.

## Architecture

| Process | Role |
| --- | --- |
| **Indexer** (`resmed-data-mcp indexer`) | Always-on host. Polls the FlashAir on an interval (default 5m), downloads STR.edf and any new/changed DATALOG files, parses them, and writes to SQLite. |
| **MCP server** (`resmed-data-mcp serve`, default) | Always-on read-only MCP server over Streamable HTTP. Opens the same SQLite file read-only (WAL mode lets it read while the indexer writes). |

Both run as separate LaunchAgents (see `examples/`) so a slow FlashAir sync
never blocks queries and a client bug never touches the data. The MCP server
listens on `0.0.0.0:8420` by default, so it's reachable identically whether
a client is on the same Mac or elsewhere on the LAN — every client just
points at `http://<host>:8420/mcp`.

## Data model

- **`nightly_summary`** — one row per calendar night, one column per signal
  STR.edf reports (columns are discovered from the device automatically, not
  hardcoded — so `AHI`, `Leak_95`, `Duration`, `S_C_Press`, etc. all show up
  as real, queryable REAL columns). This is the ergonomic table for "how did
  I sleep" questions.
- **`edf_signals` / `edf_signal_records`** — the fully generic archive:
  every signal, from every file ever seen (STR.edf and every DATALOG detail
  file), with raw digital samples preserved as-is plus enough calibration
  metadata to decode them. This is what "as much raw data as possible" means
  in practice — `nightly_summary` is a convenience view over a subset of it.
- **`source_files`, `sync_runs`, `devices`** — provenance and operational
  history: what file came from where, when, and whether syncing is healthy.

Event files are decoded into `session_events`. Each apnea or hypopnea row includes the pressure and leak at that minute and whether pressure rose over the next two minutes. `minute_stats` is one row per minute of pressure, leak, flow limitation, tidal volume, respiratory rate, snore, oxygen, and event counts. `night_therapy` rolls those minutes up against the night's minimum and maximum pressure.

No vector database: this data is fully structured and numeric (nightly
metrics, calibrated signal samples), which SQL aggregation handles better
than similarity search. If a future signal turns out to carry free text
worth searching semantically, that's a reason to reconsider, not a default.

## MCP tools

| Tool | Purpose |
| --- | --- |
| `list_nights` | Nightly summary rows in a date range, newest first. |
| `get_night` | Full summary row for one date. |
| `get_trend` | Time series + min/max/avg for one `nightly_summary` column. |
| `get_therapy_nights` | One row per night: settings, AHI, leak, minutes spent at the pressure floor and ceiling, and obstructive events in those minutes. |
| `get_night_minutes` | Minute-by-minute pressure, leak, flow limitation, breathing, snore, oxygen, and event counts for one night. |
| `get_night_detail` | Sessions for one night, plus each event with pressure, leak, and whether pressure rose afterward. |
| `list_signals` | Discover every raw signal label across all ingested files. |
| `get_signal_samples` | Raw samples for one signal in one file. Not the therapy view. |
| `query_raw` | Arbitrary read-only SELECT against the full schema. |
| `sync_status` | Last sync run, device info, row counts — how fresh is this. |

The connection backing the MCP server is opened SQLite-read-only, so
`query_raw` can't write regardless of what SQL text it's given — that's
enforced by the database, not just by string validation.

## Install

```bash
npm install -g resmed-data-mcp
```

Requires **Node.js 22.5+** (uses the built-in `node:sqlite` module — no
native dependencies, no `npm rebuild` across machines/architectures).

### Develop from source

```bash
git clone https://github.com/sfls1397/ResMed-Data-MCP.git
cd ResMed-Data-MCP
npm install   # runs `tsc` via the prepare script
```

### Configure

Copy `examples/config.json.example` to `~/.resmed-data-mcp/config.json` and
set `flashAirBaseUrl` to your FlashAir's address (find it with your router's
DHCP client list, or the FlashAir's own config page). Everything else has a
sane default. Configure the address once; later package upgrades reuse the existing local file:

| Key | Default | Notes |
| --- | --- | --- |
| `flashAirBaseUrl` | `http://flashair.local` | Generic placeholder; configure your actual card address locally |
| `pollInterval` | `5m` | Clamped to 30s–1h |
| `serverHost` | `0.0.0.0` | Bind address for the MCP server |
| `serverPort` | `8420` | |

Env vars override the file: `RESMED_DATA_FLASHAIR_URL`,
`RESMED_DATA_POLL_INTERVAL`, `RESMED_DATA_SERVER_HOST`,
`RESMED_DATA_SERVER_PORT`, `RESMED_DATA_DB_PATH`. `RESMED_DATA_HOME`
relocates the whole `~/.resmed-data-mcp/` directory (test/dev only).

### Backfill once, then install the LaunchAgents

```bash
resmed-data-mcp backfill     # one-shot: pulls everything currently on the card
```

Copy `examples/com.resmed-data-mcp.indexer.plist` and
`examples/com.resmed-data-mcp.server.plist` into `~/Library/LaunchAgents/`,
replacing `REPLACE_ME_WITH_NPM_BIN_DIR` and
`REPLACE_ME` (your username) with real values, then:

```bash
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.resmed-data-mcp.indexer.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.resmed-data-mcp.server.plist
```

### Point clients at it

See `examples/mcp-client.json`. Any MCP client that supports an HTTP server
entry (Claude, Codex, Grok Bot, ...) connects the same way whether it runs on
the Mac Mini itself or another machine on the same LAN:

```json
{ "mcpServers": { "resmed-data": { "url": "http://<host>:8420/mcp" } } }
```

## Paths

All under `~/.resmed-data-mcp/` (config cannot override this directory):

| Path | Purpose |
| --- | --- |
| `~/.resmed-data-mcp/config.json` | Settings (see above) |
| `~/.resmed-data-mcp/data.sqlite` | The database (WAL mode) |
| `~/.resmed-data-mcp/indexer.lock` | Sync-cycle lock, so an overlapping poll never runs concurrently with itself |

## Security

No authentication — this is meant for a trusted home LAN only. Don't expose
port 8420 to the internet (no port forwarding, no tunnel). The MCP server's
database connection is read-only at the SQLite level, so even a buggy or
malicious client can't write through it.

## Known limitations

- **EDF+ annotation signals** (the "EDF Annotations" channel, used for event
  timestamps in some DATALOG detail files) are archived as raw bytes but not
  decoded into structured events yet — there was no real annotation-bearing
  file available to validate a decoder against when this was built. Decoding
  can be added once DATALOG detail files with real annotations exist on a
  card.
## License

MIT


## Privacy gates and synthetic fixtures

EDF test buffers are constructed in code with generic patient headers and
fixed samples. SQL fixtures use in-memory databases and synthetic therapy
values; no patient export, card image, or local SQLite database is tracked.
Keep actual device addresses and patient data in local settings and storage.

Install Gitleaks 8.30.1 and enable the staged gate once per clone:

```bash
git config core.hooksPath .githooks
gitleaks git --log-opts=--all --config .gitleaks.toml --redact=100 --no-banner .
npm run build && npm run scan:package
```

Push and pull-request CI scans full fetched history and package contents.
The prepublishOnly lifecycle rebuilds and scans the exact npm file list.
After a history rewrite, discard old clones and re-clone; merging old history
can restore removed data. Releases use GitHub Release → npm OIDC.