ironcompass-usage

IronCompass Usage Guide

IronCompass is a personal health tracking platform. You log data via MCP tools and the user views it on a web dashboard.

Core Pattern: Query Before Log

Always call ironcompass_query_today before prompting the user to log data. This shows what's already recorded so you can focus on what's missing and avoid duplicate inserts. When logging past days, pass the target date — e.g., ironcompass_query_today with date: "2026-03-07" — not today's date.

Data Dependencies

Most tables have a foreign key to daily_entries. The log tools handle this automatically — you do not need to call ironcompass_log_daily first. The first log call for any date auto-creates a minimal daily entry.

Upsert vs Insert Tools

Calling the wrong tool twice has different consequences:

Upsert tools (safe to re-call, updates existing row):

• ironcompass_log_daily, ironcompass_log_sleep, ironcompass_log_fasting, ironcompass_log_pullups, ironcompass_log_bodycomp — all keyed on date

Insert tools (creates a new row every call — will duplicate if called twice):

• ironcompass_log_bp, ironcompass_log_workout, ironcompass_log_meal, ironcompass_log_metric

For insert tools, always check ironcompass_query_today first to avoid duplicating existing records.

Merge tool:

• ironcompass_log_supplements — merges new supplements with the existing list for that date, does not overwrite

Tool Parameters

All log tools accept an optional date (YYYY-MM-DD). If omitted, defaults to today. Always use explicit dates when logging past days.

Supplements

Pass as an array of lowercase, hyphenated strings: ["vitamin-d", "omega-3", "creatine"].

Custom Metrics

The name is automatically lowercased. Multiple entries per day per metric are summed in the dashboard. Include unit on at least the first entry (e.g., "cups", "ml").

Workout Details

The details field is a JSON object with type-specific structure:

• Strength: {"exercises": [{"name": "Bench Press", "sets": [{"reps": 8, "weight": 135}]}]}
• Hike/Run: {"trail": "Mission Peak", "out_and_back": true}
• Golf: {"course": "Pebble Beach", "score": 92, "holes": 18}

Use ironcompass_list_workout_types to get valid type names. The source field defaults to "manual" — set to "apple_health", "hevy", "strava", etc. for integration data.

start_time and end_time accept HH:MM (auto-adds local timezone offset) or full ISO 8601 datetime strings. Always include a timezone offset in ISO strings (e.g., 2026-03-10T07:59:00-07:00). Strings without offset are treated as local time, but prefer HH:MM when only local time is known.

Query Tools

ironcompass_query_today — All data for a single date. Accepts optional date param.

ironcompass_query_week — Last 7 days with aggregates (weight delta, avg sleep, workout count, protein/calories, fasting compliance, alcohol, pullups, custom metrics). Does not include streaks — call ironcompass_query_streak separately. Always returns last 7 days from today — does not accept a date parameter.

ironcompass_query_trend — Time-series points and summary stats over N days. Built-in metrics: weight, energy, sleep, hrv, hr-sleep, readiness, bp, pullups, calories, protein, body-fat. Also accepts any custom metric name (aggregated as daily sums).

ironcompass_query_streak — Current streak count and start date. Valid: alcohol-free, fasting, workout, logging. Streaks skip today if not yet logged (so a streak doesn't break just because it's morning).

Delete Tools

Require a UUID from a prior query result. Always confirm with the user before deleting.

• ironcompass_delete_workout, ironcompass_delete_meal, ironcompass_delete_metric

Dashboard URLs

Every response includes a dashboard_url. URL patterns for deep linking:

• /?view=daily&date=YYYY-MM-DD — day view
• /?view=weekly&date=YYYY-MM-DD — weekly view (date = Monday)
• /?view=metrics — trends and streaks
• /?month=YYYY-MM-DD — calendar month