get-workouts

Instructions

Implementation Reference

• src/tools/workouts.ts:39-66 (handler)

  Registration and handler of the 'get-workouts' tool with the MCP server, including schema definition, error handling wrapper, and handler logic that calls hevyClient.getWorkouts() and formats results.

  server.tool(
  	"get-workouts",
  	"Get a paginated list of workouts. Returns workout details including title, description, start/end times, and exercises performed. Results are ordered from newest to oldest.",
  	getWorkoutsSchema,
  	withErrorHandling(async (args: GetWorkoutsParams) => {
  		if (!hevyClient) {
  			throw new Error(
  				"API client not initialized. Please provide HEVY_API_KEY.",
  			);
  		}
  		const { page, pageSize } = args;
  		const data: GetV1Workouts200 = await hevyClient.getWorkouts({
  			page,
  			pageSize,
  		});
  
  		const workouts =
  			data?.workouts?.map((workout) => formatWorkout(workout)) || [];
  
  		if (workouts.length === 0) {
  			return createEmptyResponse(
  				"No workouts found for the specified parameters",
  			);
  		}
  
  		return createJsonResponse(workouts);
  	}, "get-workouts"),
  );

• src/tools/workouts.ts:33-36 (schema)

  Zod schema for get-workouts params: page (number >=1, default 1) and pageSize (integer 1-10, default 5).

  const getWorkoutsSchema = {
  	page: z.coerce.number().gte(1).default(1),
  	pageSize: z.coerce.number().int().gte(1).lte(10).default(5),
  } as const;

• src/utils/formatters.ts:134-164 (helper)

  Helper function that transforms raw Hevy API workout data into a formatted structure with camelCase keys, computed duration, and nested exercise/set formatting.

  export function formatWorkout(workout: Workout): FormattedWorkout {
  	return {
  		id: workout.id,
  		title: workout.title,
  		description: workout.description,
  		startTime: workout.start_time,
  		endTime: workout.end_time,
  		createdAt: workout.created_at,
  		updatedAt: workout.updated_at,
  		duration: calculateDuration(workout.start_time, workout.end_time),
  		exercises: workout.exercises?.map((exercise) => {
  			return {
  				index: exercise.index,
  				name: exercise.title,
  				exerciseTemplateId: exercise.exercise_template_id,
  				notes: exercise.notes,
  				supersetsId: exercise.supersets_id,
  				sets: exercise.sets?.map((set) => ({
  					index: set.index,
  					type: set.type,
  					weight: set.weight_kg,
  					reps: set.reps,
  					distance: set.distance_meters,
  					duration: set.duration_seconds,
  					rpe: set.rpe,
  					customMetric: set.custom_metric,
  				})),
  			};
  		}),
  	};
  }

• src/utils/response-formatter.ts:29-45 (helper)

  Helper function that creates a standardized MCP response with JSON content, used to format the workouts result.

  export function createJsonResponse(
  	data: unknown,
  	options: JsonFormatOptions = { pretty: true, indent: 2 },
  ): McpToolResponse {
  	const jsonString = options.pretty
  		? JSON.stringify(data, null, options.indent)
  		: JSON.stringify(data);
  
  	return {
  		content: [
  			{
  				type: "text" as const,
  				text: jsonString,
  			},
  		],
  	};
  }