get_workout_count

Instructions

Implementation Reference

• src/hevy_mcp/tools/workouts.py:57-63 (handler)

  The actual handler function for the 'get_workout_count' tool. It calls the Hevy API at /workouts/count, extracts the workout_count, and returns a formatted response.

  @mcp.tool()
  @tool_guard
  async def get_workout_count() -> dict[str, Any]:
      """Total number of workouts the user has logged. Cheap; safe to call eagerly."""
      data = await client.get("/workouts/count")
      count = data.get("workout_count") if isinstance(data, dict) else data
      return {"text": f"{count} workouts", "data": data, "count": count}

• src/hevy_mcp/tools/workouts.py:20-63 (registration)

  The register() function that defines all workout tools (including get_workout_count) using the @mcp.tool() decorator. get_workout_count is registered at lines 57-63 within this function.

  def register(mcp, ctx) -> None:
      client = ctx.client
  
      @mcp.tool()
      @tool_guard
      async def list_workouts(
          page: int = Field(1, ge=1, description="1-indexed page number."),
          page_size: int = Field(10, ge=1, le=WORKOUT_PAGE_SIZE_MAX,
                                  description="Workouts per page. Hevy caps this at 10."),
      ) -> dict[str, Any]:
          """List the user's workouts in reverse-chronological order.
  
          Use this first when the user asks about "recent workouts", "last N sessions",
          "what did I train on Monday", etc. Each item is a *summary*; call
          `get_workout(workout_id)` for full set-by-set detail when the user asks
          about specific weights, RPE, or progression.
          """
          data = await client.get("/workouts", params={"page": page, "pageSize": page_size})
          items = _items(data)
          return {
              "text": "\n\n".join(format_workout(w) for w in items) or "(no workouts on this page)",
              "data": data,
              "page": page,
              "page_count": data.get("page_count") if isinstance(data, dict) else None,
          }
  
      @mcp.tool()
      @tool_guard
      async def get_workout(workout_id: str) -> dict[str, Any]:
          """Fetch a single workout with every set, rep, weight, RPE, and note.
  
          Use this when the user asks about a *specific* workout or wants to compare
          sets across sessions. Pair with `list_workouts` to discover the id first.
          """
          data = await client.get(f"/workouts/{workout_id}")
          return {"text": format_workout(_unwrap(data, "workout")), "data": data}
  
      @mcp.tool()
      @tool_guard
      async def get_workout_count() -> dict[str, Any]:
          """Total number of workouts the user has logged. Cheap; safe to call eagerly."""
          data = await client.get("/workouts/count")
          count = data.get("workout_count") if isinstance(data, dict) else data
          return {"text": f"{count} workouts", "data": data, "count": count}

• src/hevy_mcp/tools/__init__.py:1-12 (registration)

  The register_all() function that imports and calls workouts.register(), which ultimately registers get_workout_count.

  """Tool registration. Each module exposes `register(mcp, ctx)` to attach its tools."""
  
  from . import analytics, folders, routines, templates, webhooks, workouts
  
  
  def register_all(mcp, ctx) -> None:
      workouts.register(mcp, ctx)
      routines.register(mcp, ctx)
      folders.register(mcp, ctx)
      templates.register(mcp, ctx)
      webhooks.register(mcp, ctx)
      analytics.register(mcp, ctx)

• src/hevy_mcp/server.py:43-58 (registration)

  The server's build_server() function that calls register_all() to register all tools including get_workout_count on the FastMCP instance.

  def build_server() -> tuple[FastMCP, AppContext]:
      _configure_logging()
      client = HevyClient()
      ctx = AppContext(client=client, template_cache=TTLCache(ttl_seconds=24 * 60 * 60))
  
      mcp = FastMCP(
          name="hevy-mcp",
          instructions=(
              "Tools to read and write a user's data on Hevy (workout-tracking app). "
              "When the user asks to build or modify a routine from natural language, "
              "ALWAYS resolve exercise names to template ids via `search_exercise_templates` "
              "before calling `create_routine` or `update_routine`. Do not invent ids. "
              "Workout list pages are capped at 10 items by Hevy."
          ),
      )
      register_all(mcp, ctx)