feat(activities): add search + best-efforts + interval-stats tools

search_activities queries by name/keyword; get_activity_best_efforts returns
peak values over windows for a stream; get_activity_interval_stats computes
aggregate metrics for an arbitrary stream index range (distinct from the
per-interval get_activity_intervals). Spec-required params enforced (q, stream,
start/end index). Formatters added; tools registered in server.py and __init__.

Implements #3.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NGzHtDvJur9U7ysgRKRUTN

src/intervals_mcp_server/server.py

@@ -71,6 +71,9 @@ config = get_config()
 # Import tool modules to register them (tools register themselves via @mcp.tool() decorators)
 # Import tool functions for re-export
 from intervals_mcp_server.tools.activities import (  # pylint: disable=wrong-import-position  # noqa: E402
+    get_activity_best_efforts,
+    get_activity_interval_stats,
+    search_activities,
     add_activity_message,
     get_activities,
     get_activity_details,
@@ -116,6 +119,9 @@ __all__ = [
     "get_activity_intervals",
     "get_activity_messages",
     "get_activity_streams",
+    "search_activities",
+    "get_activity_best_efforts",
+    "get_activity_interval_stats",
     "get_events",
     "get_event_by_id",
     "delete_event",

src/intervals_mcp_server/tools/__init__.py

@@ -10,9 +10,12 @@ from mcp.server.fastmcp import FastMCP  # pylint: disable=import-error
 # Note: Tools register themselves via @mcp.tool() decorators when imported
 from intervals_mcp_server.tools.activities import (  # noqa: F401
     get_activities,
+    get_activity_best_efforts,
     get_activity_details,
+    get_activity_interval_stats,
     get_activity_intervals,
     get_activity_streams,
+    search_activities,
 )
 from intervals_mcp_server.tools.events import (  # noqa: F401
     add_or_update_event,
@@ -65,6 +68,9 @@ __all__ = [
     "get_activity_details",
     "get_activity_intervals",
     "get_activity_streams",
+    "search_activities",
+    "get_activity_best_efforts",
+    "get_activity_interval_stats",
     "get_events",
     "get_event_by_id",
     "delete_event",

src/intervals_mcp_server/tools/activities.py

@@ -14,7 +14,14 @@ from intervals_mcp_server.tools.gear import (
     resolve_gear_for_activity,
     resolve_gear_for_activities,
 )
-from intervals_mcp_server.utils.formatting import format_activity_message, format_activity_summary, format_intervals
+from intervals_mcp_server.utils.formatting import (
+    format_activity_message,
+    format_activity_search_results,
+    format_activity_summary,
+    format_best_efforts,
+    format_interval_stats,
+    format_intervals,
+)
 from intervals_mcp_server.utils.validation import resolve_date_params
 
 # Import mcp instance from shared module for tool registration
@@ -405,3 +412,110 @@ async def add_activity_message(
     if msg_id is not None:
         return f"Successfully added message (ID: {msg_id}) to activity {activity_id}."
     return f"Message appears to have been added to activity {activity_id}, but no ID was returned. Please verify manually."
+
+
+@mcp.tool()
+async def search_activities(query: str, limit: int = 20) -> str:
+    """Search the athlete's activities by name/keyword.
+
+    Args:
+        query: Search text matched against activity name/description (required).
+        limit: Maximum number of results to return (default 20).
+    """
+    try:
+        athlete_id_to_use, api_key = await credentials.resolve_caller_credentials()
+    except CredentialError as exc:
+        return str(exc)
+
+    if not query or not query.strip():
+        return "Error: a non-empty search query is required."
+
+    params: dict[str, Any] = {"q": query.strip(), "limit": limit}
+    result = await make_intervals_request(
+        url=f"/athlete/{athlete_id_to_use}/activities/search", api_key=api_key, params=params
+    )
+
+    if isinstance(result, dict) and "error" in result:
+        return f"Error searching activities: {result.get('message')}"
+
+    results = [r for r in result if isinstance(r, dict)] if isinstance(result, list) else []
+    if not results:
+        return f"No activities found matching '{query}'."
+    return format_activity_search_results(results)
+
+
+@mcp.tool()
+async def get_activity_best_efforts(
+    activity_id: str,
+    stream: str = "watts",
+    duration: int | None = None,
+    distance: float | None = None,
+    count: int | None = None,
+) -> str:
+    """Get the best efforts (peak values over windows) for an activity.
+
+    Args:
+        activity_id: The Intervals.icu activity ID.
+        stream: Data stream to analyze — e.g. "watts", "heartrate", "pace" (default "watts").
+        duration: Optional window duration in seconds to target.
+        distance: Optional window distance in meters to target.
+        count: Optional maximum number of efforts to return.
+    """
+    try:
+        _athlete_id, api_key = await credentials.resolve_caller_credentials()
+    except CredentialError as exc:
+        return str(exc)
+
+    params: dict[str, Any] = {"stream": stream}
+    if duration is not None:
+        params["duration"] = duration
+    if distance is not None:
+        params["distance"] = distance
+    if count is not None:
+        params["count"] = count
+
+    result = await make_intervals_request(
+        url=f"/activity/{activity_id}/best-efforts", api_key=api_key, params=params
+    )
+
+    if isinstance(result, dict) and "error" in result:
+        return f"Error fetching best efforts: {result.get('message')}"
+
+    efforts = result.get("efforts") if isinstance(result, dict) else None
+    if not efforts:
+        return f"No best-effort data found for activity {activity_id} (stream: {stream})."
+    return format_best_efforts([e for e in efforts if isinstance(e, dict)], stream)
+
+
+@mcp.tool()
+async def get_activity_interval_stats(activity_id: str, start_index: int, end_index: int) -> str:
+    """Compute aggregate stats for an index range of an activity's data streams.
+
+    start_index/end_index are positions in the activity's streams (as seen in the
+    streams or interval output). This computes metrics for that slice — it does NOT
+    list the activity's own intervals (use get_activity_intervals for that).
+
+    Args:
+        activity_id: The Intervals.icu activity ID.
+        start_index: Start position in the activity streams (required).
+        end_index: End position in the activity streams (required, > start_index).
+    """
+    try:
+        _athlete_id, api_key = await credentials.resolve_caller_credentials()
+    except CredentialError as exc:
+        return str(exc)
+
+    if start_index < 0 or end_index <= start_index:
+        return "Error: end_index must be greater than start_index and both non-negative."
+
+    params: dict[str, Any] = {"start_index": start_index, "end_index": end_index}
+    result = await make_intervals_request(
+        url=f"/activity/{activity_id}/interval-stats", api_key=api_key, params=params
+    )
+
+    if isinstance(result, dict) and "error" in result:
+        return f"Error fetching interval stats: {result.get('message')}"
+
+    if not isinstance(result, dict) or not result:
+        return f"No interval stats found for activity {activity_id} ({start_index}-{end_index})."
+    return format_interval_stats(result)

src/intervals_mcp_server/utils/formatting.py

@@ -816,3 +816,65 @@ def format_power_curves(
         lines.append("")
 
     return "\n".join(lines)
+
+
+def format_activity_search_results(results: list[dict[str, Any]]) -> str:
+    """Format activity search hits into a compact one-line-per-result list."""
+    lines = [f"Found {len(results)} activit{'y' if len(results) == 1 else 'ies'}:", ""]
+    for r in results:
+        date = r.get("start_date_local", "")
+        if isinstance(date, str) and len(date) > 10:
+            date = date[:10]
+        extra = []
+        if r.get("distance") is not None:
+            extra.append(f"{r['distance']}m")
+        if r.get("moving_time") is not None:
+            extra.append(f"{r['moving_time']}s")
+        if r.get("race"):
+            extra.append("RACE")
+        line = " | ".join([date or "?", str(r.get("type", "?")), str(r.get("name", "Unnamed"))])
+        if extra:
+            line += "  (" + ", ".join(extra) + ")"
+        line += f"  [id: {r.get('id', 'N/A')}]"
+        lines.append(line)
+    return "\n".join(lines)
+
+
+def format_best_efforts(efforts: list[dict[str, Any]], stream: str) -> str:
+    """Format best-effort windows for a stream (power/hr/pace) into text."""
+    lines = [f"Best Efforts ({stream}):", ""]
+    for e in efforts:
+        parts = []
+        if e.get("duration") is not None:
+            parts.append(_format_duration_label(int(e["duration"])))
+        if e.get("distance") is not None:
+            parts.append(f"{e['distance']}m")
+        label = " / ".join(parts) if parts else "effort"
+        idx = f"[idx {e.get('start_index', '?')}-{e.get('end_index', '?')}]"
+        lines.append(f"- {label}: avg {e.get('average', 'N/A')}  {idx}")
+    return "\n".join(lines)
+
+
+def format_interval_stats(interval: dict[str, Any]) -> str:
+    """Format a computed interval-stats block (a single Interval) into text."""
+    lines = ["Interval Stats:", ""]
+    for key, label, unit in [
+        ("moving_time", "Moving Time", "s"),
+        ("distance", "Distance", "m"),
+        ("average_watts", "Avg Power", "W"),
+        ("weighted_average_watts", "Weighted Avg Power", "W"),
+        ("max_watts", "Max Power", "W"),
+        ("average_watts_kg", "Avg Power", "W/kg"),
+        ("intensity", "Intensity", ""),
+        ("training_load", "Training Load", ""),
+        ("joules", "Work", "J"),
+        ("decoupling", "Decoupling", "%"),
+        ("average_heartrate", "Avg HR", "bpm"),
+        ("max_heartrate", "Max HR", "bpm"),
+        ("average_cadence", "Avg Cadence", "rpm"),
+        ("average_speed", "Avg Speed", "m/s"),
+        ("gap", "GAP", "m/s"),
+    ]:
+        if interval.get(key) is not None:
+            lines.append(f"- {label}: {interval[key]}{(' ' + unit) if unit else ''}")
+    return "\n".join(lines)