apple-health-export-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

A FastMCP (v3) stdio MCP server that answers questions about a user's exported Apple Health archive. Apple has no live API, so the flow is two-stage and snapshot-based:

export.zip ──(ingest CLI, one-time)──► SQLite (health.db) ──◄── MCP server tools query it

The design rationale lives in docs/adr.md (10 ADRs). Read it before changing how data is parsed, stored, or aggregated, and add an ADR entry for such changes — the reasoning there is load-bearing and not re-derivable from the diff.

Commands

uv sync                                   # set up the env
uv run pytest                             # all tests
uv run pytest tests/test_queries.py::test_sum_dedupes_parallel_sources_by_dominant_per_day  # single test
uv run ruff check                         # lint (CI gate)
uv run ruff format                        # format (CI checks --check)
uv run fastmcp inspect                    # list registered tools/prompts without a client
uv build                                  # sdist+wheel; uvx twine check dist/* before publishing

# Run the pieces directly:
apple-health-export-mcp-ingest <export.zip>   # build the DB (AH_DB_PATH or --db controls location)
apple-health-export-mcp                        # run the stdio server (reads the DB)

Architecture

Layering is deliberate — keep it:

• queries.py — pure SQL helpers + the typed result dataclasses (TypeInfo, QuantityPoint, SleepNight, …), no FastMCP import. All query logic and the unit tests live here so it stays testable without a server.
• tools.py — the MCP tool surface: thin wrappers over queries.py, the _store() context manager (DB open/close + ValueError/missing-DB → ToolError), and the reusable Annotated[..., Field(...)] argument types. Plain (un-decorated) functions exported via ALL.
• prompts.py — coaching prompt content as plain functions exported via ALL.
• server.py — wiring only: creates the mcp instance, registers tools.ALL (mcp.tool(annotations=READONLY)) and prompts.ALL (mcp.prompt), and holds main() + shutdown. tools.py/prompts.py stay decorator-free so they never import the mcp instance (no circular import); returning typed models lets FastMCP emit an output schema per tool.
• ingest.py — streaming iterparse of the export XML into SQLite; the one-time builder.
• db.py — schema + connect() + db_path() (env/XDG resolution).
• cli.py — the apple-health-export-mcp-ingest entry point.