feat: support custom bpm heart-rate range in create_run_workout (#224)

Named Garmin zones (Z1-Z5) don't always match a real training target -
e.g. a 136-148 bpm Zone 2 goal straddles Garmin's Z2 (118-137) and Z3
(138-157). Previously create_run_workout only accepted hr_zone, so the
watch would show "in range" for the whole zone (up to 157 bpm) even
when the actual target ceiling was lower, silently misleading the
in-workout HR feedback.

Add optional hr_min/hr_max params that build a custom bpm-range target
(targetValueOne/targetValueTwo) instead of a zoneNumber, matching a
range Garmin Connect already supports natively but this tool didn't
expose. hr_zone remains the default and is ignored when a range is
given. Verified against the live Garmin Connect API: the custom range
round-trips correctly with no zoneNumber set.

Co-authored-by: Michael McComiskey <michael.mccomiskey@wunderkind.co>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

Author: 3 people

src/garmin_mcp/workout_builders.py

@@ -45,22 +45,54 @@ def _zone_number(zone: str) -> int:
     raise ValueError(f"Invalid hr_zone '{zone}'. Use Z1-Z5 or 1-5.")
 
 
+def _hr_target(
+    hr_zone: str,
+    hr_min: Optional[int],
+    hr_max: Optional[int],
+) -> tuple:
+    """Resolve HR target fields and a short description suffix.
+
+    Returns (target_extra_fields, description_suffix). If hr_min/hr_max are
+    both given, builds a custom bpm-range target (targetValueOne/targetValueTwo)
+    instead of a named Garmin zone. A custom range and a named zone are mutually
+    exclusive -- if a range is given, hr_zone is ignored.
+    """
+    if hr_min is not None or hr_max is not None:
+        if hr_min is None or hr_max is None:
+            raise ValueError("hr_min and hr_max must both be provided together.")
+        if hr_min >= hr_max:
+            raise ValueError(f"hr_min ({hr_min}) must be less than hr_max ({hr_max}).")
+        return (
+            {"targetValueOne": float(hr_min), "targetValueTwo": float(hr_max)},
+            f"{hr_min}-{hr_max}bpm",
+        )
+    zone = _zone_number(hr_zone)
+    return ({"zoneNumber": zone}, f"Z{zone}")
+
+
 def build_run_json(
     name: str,
     run_seconds: int,
     warmup_min: int,
     cooldown_min: int,
     hr_zone: str = "Z3",
+    hr_min: Optional[int] = None,
+    hr_max: Optional[int] = None,
 ) -> dict:
-    """Build the Garmin Connect JSON for a continuous run workout."""
-    zone = _zone_number(hr_zone)
+    """Build the Garmin Connect JSON for a continuous run workout.
+
+    Targets a named heart-rate zone (hr_zone) by default. Pass hr_min and
+    hr_max together to target an exact custom bpm range instead (e.g. a
+    136-148 bpm range that doesn't line up with any single Garmin zone).
+    """
+    hr_target_fields, hr_desc = _hr_target(hr_zone, hr_min, hr_max)
     run_display = (
         f"{run_seconds // 60}m" if run_seconds % 60 == 0 else f"{run_seconds}s"
     )
     return {
         "workoutName": name,
         "description": (
-            f"{warmup_min}m warmup + {run_display} run Z{zone} + {cooldown_min}m cooldown"
+            f"{warmup_min}m warmup + {run_display} run {hr_desc} + {cooldown_min}m cooldown"
         ),
         "sportType": {"sportTypeId": 1, "sportTypeKey": "running"},
         "workoutSegments": [{
@@ -80,11 +112,11 @@ def build_run_json(
                     "type": "ExecutableStepDTO",
                     "stepOrder": 2,
                     "stepType": {"stepTypeId": 3, "stepTypeKey": "interval"},
-                    "description": f"Run {run_seconds}s Z{zone}",
+                    "description": f"Run {run_seconds}s {hr_desc}",
                     "endCondition": {"conditionTypeId": 2, "conditionTypeKey": "time"},
                     "endConditionValue": float(run_seconds),
                     "targetType": {"workoutTargetTypeId": 4, "workoutTargetTypeKey": "heart.rate.zone"},
-                    "zoneNumber": zone,
+                    **hr_target_fields,
                 },
                 {
                     "type": "ExecutableStepDTO",
@@ -363,17 +395,28 @@ async def create_run_workout(
         warmup_min: int,
         cooldown_min: int,
         hr_zone: str = "Z3",
+        hr_min: Optional[int] = None,
+        hr_max: Optional[int] = None,
     ) -> str:
         """Create a continuous run workout and upload it to Garmin Connect.
 
         Builds a single uninterrupted run interval with warmup and cooldown walks.
 
+        Targets a named Garmin heart-rate zone by default. Named zones (Z1-Z5)
+        don't line up with every real training target -- e.g. a 136-148 bpm
+        Zone 2 goal straddles Garmin's Z2 (118-137) and Z3 (138-157). Pass
+        hr_min and hr_max together to target that exact bpm range instead;
+        the watch will then show "in range" only for the range you actually
+        want, not a whole zone that over- or under-shoots it.
+
         Args:
             name: Workout name (e.g. "Step 8 - 30min continuous")
             run_seconds: Duration of the run in seconds
             warmup_min: Warmup walk duration in minutes
             cooldown_min: Cooldown walk duration in minutes
-            hr_zone: Target heart-rate zone (Z1-Z5, default Z3)
+            hr_zone: Target heart-rate zone (Z1-Z5, default Z3). Ignored if hr_min/hr_max are given.
+            hr_min: Optional custom target heart rate range, minimum bpm (must be given with hr_max)
+            hr_max: Optional custom target heart rate range, maximum bpm (must be given with hr_min)
         """
         try:
             workout_json = build_run_json(
@@ -382,6 +425,8 @@ async def create_run_workout(
                 warmup_min=warmup_min,
                 cooldown_min=cooldown_min,
                 hr_zone=hr_zone,
+                hr_min=hr_min,
+                hr_max=hr_max,
             )
             result = garmin_client.upload_workout(workout_json)
 

tests/integration/test_workout_builders_tools.py

@@ -166,6 +166,38 @@ async def test_create_run_workout_success(app_with_builders, mock_garmin_client)
     mock_garmin_client.upload_workout.assert_called_once()
 
 
+@pytest.mark.asyncio
+async def test_create_run_workout_custom_hr_range(app_with_builders, mock_garmin_client):
+    """hr_min/hr_max on the tool call produce a custom bpm-range target, not a zoneNumber."""
+    mock_garmin_client.upload_workout.return_value = {
+        "workoutId": 1111111111,
+        "workoutName": "Base run - 7/20",
+    }
+
+    result = await app_with_builders.call_tool(
+        "create_run_workout",
+        {
+            "name": "Base run - 7/20",
+            "run_seconds": 1440,
+            "warmup_min": 5,
+            "cooldown_min": 5,
+            "hr_min": 136,
+            "hr_max": 148,
+        },
+    )
+
+    assert result is not None
+    payload = json.loads(result[0][0].text)
+    assert payload["status"] == "success"
+
+    uploaded_json = mock_garmin_client.upload_workout.call_args[0][0]
+    interval_step = uploaded_json["workoutSegments"][0]["workoutSteps"][1]
+    assert interval_step["targetType"]["workoutTargetTypeKey"] == "heart.rate.zone"
+    assert interval_step["targetValueOne"] == 136.0
+    assert interval_step["targetValueTwo"] == 148.0
+    assert "zoneNumber" not in interval_step
+
+
 @pytest.mark.asyncio
 async def test_create_run_workout_exception(app_with_builders, mock_garmin_client):
     """create_run_workout returns an error string when the API raises an exception."""

tests/unit/test_workout_builders.py

@@ -71,6 +71,48 @@ def test_build_run_json_structure():
     assert steps[2]["endConditionValue"] == 300.0
 
 
+def test_build_run_json_custom_hr_range():
+    """hr_min/hr_max should produce a custom bpm-range target, not a zoneNumber."""
+    result = build_run_json(
+        name="Base run - custom range",
+        run_seconds=1440,
+        warmup_min=5,
+        cooldown_min=5,
+        hr_min=136,
+        hr_max=148,
+    )
+    steps = result["workoutSegments"][0]["workoutSteps"]
+    interval_step = steps[1]
+    assert interval_step["targetType"]["workoutTargetTypeKey"] == "heart.rate.zone"
+    assert interval_step["targetValueOne"] == 136.0
+    assert interval_step["targetValueTwo"] == 148.0
+    assert "zoneNumber" not in interval_step
+    assert "136-148bpm" in result["description"]
+
+
+def test_build_run_json_custom_hr_range_requires_both_bounds():
+    with pytest.raises(ValueError, match="hr_min and hr_max must both be provided together"):
+        build_run_json(
+            name="Bad range",
+            run_seconds=1440,
+            warmup_min=5,
+            cooldown_min=5,
+            hr_min=136,
+        )
+
+
+def test_build_run_json_custom_hr_range_rejects_inverted_bounds():
+    with pytest.raises(ValueError, match="must be less than"):
+        build_run_json(
+            name="Bad range",
+            run_seconds=1440,
+            warmup_min=5,
+            cooldown_min=5,
+            hr_min=148,
+            hr_max=136,
+        )
+
+
 def test_build_strength_json_structure():
     result = build_strength_json(
         name="Full Body A",