mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-08 20:42:43 +00:00
Marc-André Bombeck
1387cb56cc
Document the MCP server: an operator guide for enabling the off-by-default module and connecting Claude.ai / ChatGPT / Claude Desktop, a capabilities reference for the tool / resource / prompt catalogue and the grounding + write model, and a skill-author guide for building connectors against it. Link all three from the docs indexes.
87 lines
3.3 KiB
Markdown
87 lines
3.3 KiB
Markdown
# HealthLog API Spec
|
|
|
|
`openapi.yaml` is the canonical OpenAPI 3.1 description for the HealthLog
|
|
Next.js API. It is the source of truth for the native iOS client's
|
|
DTO codegen.
|
|
|
|
The MCP server is documented separately — it is a distinct contract over
|
|
JSON-RPC, not part of the REST OpenAPI spec:
|
|
|
|
- [`mcp-capabilities.md`](./mcp-capabilities.md) — the tool, resource, and
|
|
prompt catalogue, the grounding contract, and the write model.
|
|
- [`mcp-skills.md`](./mcp-skills.md) — building a connector or skill on
|
|
top of it.
|
|
- [`../self-hosting/mcp.md`](../self-hosting/mcp.md) — enabling and
|
|
connecting the surface (operator guide).
|
|
|
|
## Preview locally
|
|
|
|
Open an interactive Redoc preview in your browser:
|
|
|
|
```bash
|
|
npx @redocly/cli preview docs/api/openapi.yaml
|
|
```
|
|
|
|
Generate static HTML for sharing:
|
|
|
|
```bash
|
|
npx @redocly/cli build-docs docs/api/openapi.yaml --output docs/api/index.html
|
|
```
|
|
|
|
## Validate
|
|
|
|
```bash
|
|
npx @redocly/cli lint docs/api/openapi.yaml
|
|
```
|
|
|
|
The spec is expected to be lint-clean (errors = 0). Some warnings are
|
|
intentional:
|
|
|
|
- `no-server-example.com` — `http://localhost:3000` is the dev server.
|
|
- `operation-2xx-response` / `operation-4xx-response` — webhook + redirect
|
|
endpoints intentionally omit one or the other.
|
|
- `no-unused-components` — `ReminderPhase` is exposed for client codegen
|
|
even though no path response references it directly.
|
|
|
|
## Layout
|
|
|
|
- **`info`** — title, version (mirrored from `package.json`), description.
|
|
- **`servers`** — production `https://healthlog.bombeck.io` plus
|
|
`http://localhost:3000` for local development.
|
|
- **`tags`** — domain groupings (`Auth`, `Measurements`, `Medications`,
|
|
`Mood`, `Dashboard`, `Insights`, `Achievements`, `DoctorReport`,
|
|
`Integrations`, `User`, `Tokens`, `Notifications`, `Onboarding`,
|
|
`Health`, `Settings`, `Analytics`, `Export`, `AuditLog`,
|
|
`Monitoring`, `Webhooks`, `Ingest`, `Admin`).
|
|
- **`securitySchemes`**:
|
|
- `bearerAuth` — long-lived `hlk_*` API tokens issued via `POST /api/tokens`.
|
|
Required on `/api/ingest/medication`.
|
|
- `sessionCookie` — HttpOnly `healthlog_session` cookie set by the
|
|
password and passkey login flows. Used by the web app and any iOS
|
|
client running inside a web view.
|
|
- **`components.schemas`** — DTOs for all routes plus the underlying
|
|
Prisma models (e.g. `Measurement`, `Medication`, `MedicationIntakeEvent`,
|
|
`MoodEntry`, `User`, `DashboardLayout`, `ApiEnvelope`, `ApiError`).
|
|
- **`paths`** — all routes from `src/app/api/**/route.ts`, including
|
|
the `/api/admin/*` family which is tagged `Admin` and marked internal.
|
|
|
|
## Conventions
|
|
|
|
- Successful responses use the envelope `{ data, error: null }`.
|
|
- Error responses use the envelope `{ data: null, error: '<message>' }`.
|
|
- Pagination uses `limit` + `offset` query parameters and a
|
|
`meta: { total, limit, offset }` block on the response.
|
|
- All timestamps are ISO 8601 / RFC 3339 (`format: date-time`) in UTC.
|
|
- IDs are CUIDs (opaque strings).
|
|
|
|
## Updating the spec
|
|
|
|
When adding or changing routes:
|
|
|
|
1. Update the relevant route handler under `src/app/api/**/route.ts`.
|
|
2. Mirror the change in `openapi.yaml`. Keep `operationId` camelCase and
|
|
stable — the iOS codegen keys off it.
|
|
3. Run `npx @redocly/cli lint docs/api/openapi.yaml` and resolve all
|
|
errors. Warnings are tolerated when documented above.
|
|
4. Bump `info.version` if the change is breaking for clients.
|