# Ultrahuman MCP

A compact, read-only Model Context Protocol server for Ultrahuman Partner API health data. It is designed to minimize provider calls and model-context usage while preserving the distinction between measured, derived, and unavailable values.

> Health data is sensitive. This project is not medical advice and is not affiliated with Ultrahuman.

## Features

- Compact daily, sleep, recovery, activity, CGM, and time-series tools
- Correct handling for the provider's capitalized `Sleep` metric
- Explicit `available` / `missing` status; absent data is never reported as zero
- Units, source fields, sample counts, and derived-value markers
- Per-date cache: 24 hours for completed days; 5 minutes for today
- Concurrent-request de-duplication
- Three-attempt transient-failure retry with backoff
- Trend range limit of 31 days and bounded concurrency of four requests
- Downsampled series by default; maximum 500 returned points
- Read-only: no profile writes, device changes, or credential MCP tools

## Partner API and authentication

Ultrahuman's documented Partner API uses OAuth 2.0 authorization-code and refresh-token flows, with `profile`, `ring_data`, and `cgm_data` scopes. A production deployment should use OAuth and store the client secret, access token, and rotated refresh token in a protected server-side secret store.

This server's default transport retains compatibility with an existing legacy Partner metrics deployment (`/api/v1/metrics` with a configured API key and email) because OAuth client credentials are not universally available. Set `ULTRAHUMAN_API_BASE_URL` when deploying a documented OAuth-compatible adapter. Do not assume legacy and OAuth endpoints have identical schemas.

## Credentials

Store credentials outside the repository, with directory mode `700` and file mode `600`:

```dotenv
ULTRAHUMAN_API_KEY=provider-issued-secret
ULTRAHUMAN_EMAIL=consented-user-email
```

Default file:

```text
~/.config/ultrahuman-mcp/credentials.env
```

Override via `ULTRAHUMAN_CREDENTIAL_FILE`. Never put credentials in source, MCP arguments, logs, or chat.

## Tools

| Tool | Output |
|---|---|
| `get_daily_summary` | compact daily overview |
| `get_sleep_details` | duration, stages, efficiency, SpO2, temperature deviation |
| `get_recovery_details` | recovery, HRV, resting HR, movement, VO₂ max |
| `get_activity_summary` | steps and activity metrics |
| `get_cgm_summary` | glucose series and metabolic metrics when consent/scope permits |
| `get_metric_data` | bounded/downsampled series for HR, HRV, temperature, steps, or glucose |
| `get_health_trends` | daily normalized summaries for up to 31 days |

All dates are `YYYY-MM-DD`. Time filters for series are UTC `HH:mm` until a provider user-time-zone field is available.

## Install and test

```bash
npm install
npm test
node src/main.js
```

## Data-quality rules

- A missing source field becomes `{ "value": null, "status": "missing" }`.
- Calculated values identify `derived: true` and include sample counts.
- A zero is emitted only when the provider actually supplies zero.
- Series responses include original and returned point counts plus a `downsampled` flag.
- Completed-day results can be cached; current-day data is intentionally short-lived.

## Current API coverage

The implementation supports metrics observed from the Partner metrics payload: sleep, HR, HRV, temperature, steps, resting HR, recovery, movement, active time, VO₂ max, glucose, average glucose, glucose variability, HbA1c, time-in-target, and metabolic score. Availability depends on the user's product, consent, and granted scopes.

## Security

Use least-privilege scopes. Keep health data out of logs. On OAuth migration, refresh on 401 once, trust the returned `expires_in`, atomically persist rotated refresh tokens, and revoke tokens when retiring an integration.

## License

MIT