fh-usage

name	fh-usage
description	Reference guide for Function Health MCP data model, auth flow, and tool patterns
user-invocable	false

Function Health MCP — Usage Reference

Background context for working with Function Health lab data. This skill is loaded automatically to help you use the FH tools effectively.

Data Model: Test Rounds

Function Health runs comprehensive lab panels requiring 1-3 lab visits over several weeks. All visits within one test round share the same requisitionId.

• Results are grouped by round, not individual visit dates
• Each round directory is keyed by the earliest visit date (e.g., 2026-01-20/)
• round-meta.json in each directory contains: requisitionId, visitDates, resultCount
• A complete round typically has 100+ biomarkers across multiple categories

Offline-First Architecture

Query tools read from ~/.function-health/exports/ — they never hit the API:

• fh_results, fh_biomarker, fh_summary, fh_categories, fh_changes, fh_recommendations, fh_report

Only two tools make API calls:

• fh_sync — full data pull, writes to local store
• fh_check — lightweight requisition count check

Authentication Flow

Login is CLI-only (password requires hidden terminal input):

npx -y -p function-health-mcp function-health login

The fh_login MCP tool only checks auth status and directs users to the CLI command. Never attempt to collect credentials through the MCP tool.

Credentials are stored at ~/.function-health/credentials.json (0o600 permissions). Tokens auto-refresh via Firebase JWT. If the refresh token is revoked, the server falls back to re-login using FH_EMAIL and FH_PASSWORD (from environment variables or ~/lifeos/.env / ~/.env files). Check authHint in fh_status output for guidance when auth fails.

Tool Parameter Patterns

• Fuzzy biomarker matching: Names are matched case-insensitively with substring matching. "vitamin d" matches "Vitamin D, 25-Hydroxy".
• Filter options: fh_results accepts status ("in_range" | "out_of_range"), category, biomarker, and visit filters.
• Optional date params: fh_changes accepts from and to date strings; defaults to comparing the two most recent rounds.
• Force sync: fh_sync has a 1-hour cooldown. Pass force: true to override.

Change Notifications

When fh_sync detects changes between rounds, it writes notification files to ~/.function-health/changes/:

• Files are JSON with timestamps, accumulate until acknowledged
• fh_notifications reads pending notifications (call without acknowledge)
• fh_notifications with acknowledge: true clears them
• Notifications persist across conversations — missed days don't lose data
• Capped at 100 files (oldest pruned automatically)

Common Patterns

1. Always start with fh_status — confirms auth, data availability, and last sync time
2. Sync before querying if no data — fh_status shows hasData: false when exports are empty
3. Results come from /results-report — the biomarkerResultsRecord field, NOT the /results endpoint (which returns PDFs)
4. Compare complete rounds — fh_changes compares all markers across entire rounds, not individual visits
5. Daily briefing pattern — check fh_notifications first, present changes, then acknowledge