python demo/run_example.py

============================================================
1. calculate_daily_needs — establish calorie/macro targets
============================================================
{
  "bmr": 1422,
  "tdee": 2204,
  "target_calories": 1704,
  "macro_split": {
    "protein_g": 122,
    "carbs_g": 189,
    "fat_g": 51
  },
  "goal": "lose",
  "goal_label": "Fat loss (~0.5 kg/week deficit)",
  "activity_level": "moderate",
  "note": "~500 kcal/day deficit; expect ~0.5 kg loss per week",
  "coaching_context": "For a 32-year-old female at 68 kg / 170 cm with moderate activity, targeting lose. Daily target: 1704 kcal (122g protein / 189g carbs / 51g fat)."
}

============================================================
2. calculate_bmi — quick screening metric
============================================================
{
  "bmi": 23.5,
  "category": "Normal weight",
  "healthy_weight_range_kg": { "min": 53.5, "max": 72.0 },
  "weight_kg": 68,
  "height_cm": 170,
  "note": "BMI is a population-level screening tool. It does not account for muscle mass, bone density, age, or fat distribution. Body fat percentage and waist circumference provide a fuller picture."
}

============================================================
3. calculate_water_intake — daily hydration target
============================================================
{
  "daily_water_target_ml": 2780,
  "range_ml": { "min": 2502, "max": 3058 },
  "in_liters": 2.78,
  "in_cups_8oz": 12,
  "activity_level": "moderate",
  "climate": "temperate",
  "note": "This is an estimate for total fluid intake (water, beverages, food moisture). Pure water needs are roughly 70-80% of this figure. Urine color is the simplest real-time hydration check: pale yellow = well hydrated."
}

============================================================
4. calculate_calories_burned — factor in a planned workout
============================================================
{
  "activity": "running (5mph / 12 min/mile)",
  "duration_minutes": 30,
  "weight_kg": 68,
  "met_value": 8.3,
  "intensity": "vigorous",
  "calories_burned": 282,
  "calories_per_minute": 9.4,
  "source": "2011 Compendium of Physical Activities (Ainsworth et al.)",
  "note": "MET-based estimates assume average metabolic efficiency. Individual variation (fitness level, terrain, pace consistency) typically puts real burn within ±15% of this estimate."
}

1. calculate_daily_needs   → establishes calorie/macro targets
2. get_food_nutrition      → checks specific foods against those targets
3. suggest_recipe          → finds meals that fit the daily plan
4. build_workout_plan      → creates a training program for the goal
5. get_health_topic_summary → answers background health questions with citations
6. check_supplement_interaction → safety-checks supplements being considered
7. get_preventive_care_recommendations → surfaces relevant screenings

cd mcp-health-coach
pip install -r requirements.txt

cp .env.example .env
# Edit .env with your keys

pytest tests/ -v

{
  "mcpServers": {
    "health-coach": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-health-coach/server.py"],
      "env": {
        "EDAMAM_APP_ID": "your-id",
        "EDAMAM_APP_KEY": "your-key"
      }
    }
  }
}

mcp-health-coach/
├── server.py                      # MCP entrypoint, tool registration (31 tools)
├── tools/
│   ├── nutrition.py               # get_food_nutrition (USDA + OFF)
│   ├── recipes.py                 # suggest_recipe (Edamam)
│   ├── exercise.py                # get_exercise (Wger + ExerciseDB)
│   ├── workout_plan.py            # build_workout_plan (composition)
│   ├── daily_needs.py             # calculate_daily_needs (pure logic)
│   ├── health_topics.py           # get_health_topic_summary (MedlinePlus)
│   ├── supplement_interactions.py # check_supplement_interaction (openFDA)
│   ├── preventive_care.py         # get_preventive_care_recommendations (ODPHP)
│   ├── body_metrics.py            # BMI, body fat, water intake, weight range
│   ├── calorie_burn.py            # calculate_calories_burned, list_activities
│   ├── meal_totals.py             # get_meal_totals, compare_foods
│   ├── nutrient_search.py         # find_foods_high_in_nutrient
│   ├── vitamin_info.py            # get_vitamin_mineral_info
│   ├── research.py                # search_nutrition_research (PubMed)
│   └── biometrics.py              # wearable aggregation, recovery/strain/HRV, behavior journal
├── integrations/
│   ├── oura.py                    # Oura Ring API v2
│   ├── polar.py                   # Polar Accesslink API v3
│   ├── withings.py                # Withings Health API
│   ├── fitbit.py                  # Fitbit Web API
│   ├── garmin.py                  # Garmin Connect (via garminconnect lib)
│   └── ble_gatt.py                # Direct BLE Heart Rate Service (via bleak)
├── lib/
│   ├── cache.py                   # Shared TTL cache (1hr, 512 entries)
│   ├── http_client.py             # Retry/timeout HTTP client
│   ├── normalization.py           # Unified NutritionFact schema
│   ├── disclaimers.py             # Structural disclaimer wrapper
│   └── safety_filters.py         # Hardcoded emergency redirect
├── tests/
│   ├── test_daily_needs.py        # BMR/TDEE formula correctness
│   ├── test_normalization.py      # Cross-source schema consistency
│   ├── test_disclaimer_wrapper.py # Disclaimer always present
│   ├── test_safety_filters.py    # Emergency patterns 100% blocked
│   ├── test_biometrics.py         # Wearable aggregation, recovery/strain/HRV, journal
│   └── test_integrations.py      # Per-device auth/parsing + degradation paths
├── config/
│   └── claude_desktop_config.example.json
├── demo/
│   └── run_example.py             # Key-free walkthrough of the local-logic tool chain
├── .env.example
└── requirements.txt