AGENTS.md · neiltron/apple-health-mcp

Sections

1. Project
2. Validate changes
3. Code map
4. Invariants
5. Local planning

First lines (shown under the repo's MIT license)

# Repository guidance

## Project

This package is a local `stdio` MCP server that queries Simple Health Export
CSV files through an in-memory DuckDB database. The public npm package and MCP
Registry entry are both named in `package.json` and `server.json`.

## Validate changes

Run all four checks before handing off code changes:

```bash
npm run lint
npm test
npm run typecheck
npm run build
```

Tests use Bun. The published runtime requires Node.js 22 or newer.

## Code map

- `src/server.ts`: configuration, MCP tool schemas, dispatch, and stdio startup
- `src/importers/`: per-format ingestion (detection and loading) behind the
  `FormatImporter` interface, plus the single-format registry
- `src/db/`: format-agnostic catalog, lazy table loader, and DuckDB wrapper
- `src/tools/`: implementations of `health_schema`, `health_query`, and
  `health_report`
- `src/core/`: query caching, lazy-load coordination, and memory management
- `server.json`: MCP Registry metadata
- `docs/solutions/`: documented solutions and decisions from past work (bugs,
  tooling choices, patterns), organized by category with YAML frontmatter
  (`module`, `tags`, `problem_type`) — relevant when working in documented areas
- `CONCEPTS.md`: shared domain vocabulary (entities, named processes, status
  concepts) — relevant when orienting to the codebase or discussing domain terms

See `docs/architecture.md` for the runtime flow and `docs/querying.md` for the
normalized data model.

## Invariants

- Never write logs or diagnostics to stdout while the MCP transport is active;
  stdout is reserved for protocol messages.
- Preserve the `health_query` query checks. The supported statements and
  restricted functions are listed in `docs/architecture.md` under "Query
  safeguards". Check queries before loading, cache lookup, or execution.
  Keep supported statements and rejected operations covered by tests.
- Do not call the query checks a security boundary or an OS sandbox. Untrusted
  SQL requires process or OS isolation.
- Keep DuckDB file, external-access, configuration-lock, memory, and no-spill
  settings enabled. `allowed_directories` permits reads and writes inside
  `HEALTH_DATA_DIR`.
- Preserve lazy loading unless a deliberate architecture change replaces it.
- Category labels such as sleep stages live in `valueText`; their numeric
  `value` is `NULL`.
- Derive sleep and workout duration from `startDate` and `endDate`; exported
  duration fields are not consistent across formats.
- Workout exports may be one combined file or separate files per activity.
- Never commit personal health exports, databases, logs, or local paths.
- Keep versions synchronized across `package.json`, `server.json` (server and
  package versions), and the MCP implementation version in `src/server.ts`.

## Local planning

`ROADMAP.md` is a local, intentionally uncommitted working plan excluded through
`.git/info/exclude`. Do not add it to commits unless the maintainer explicitly
changes that policy.