Hevy MCP

Instructions

Implementation Reference

• src/tools/workouts.ts:55-77 (handler)

  Handler function for the 'get-workouts' tool. Fetches paginated workouts from the Hevy API using hevyClient, formats each workout using formatWorkout utility, and returns a JSON response with the list or an empty response if none found.

  withErrorHandling(async ({ page, pageSize }) => {
  	if (!hevyClient) {
  		throw new Error(
  			"API client not initialized. Please provide HEVY_API_KEY.",
  		);
  	}
  	const data = await hevyClient.getWorkouts({
  		page,
  		pageSize,
  	});
  
  	// Process workouts to extract relevant information
  	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:52-54 (schema)

  Zod schema defining input parameters for the 'get-workouts' tool: page (number >=1, default 1) and pageSize (int 1-10, default 5).

  	page: z.coerce.number().gte(1).default(1),
  	pageSize: z.coerce.number().int().gte(1).lte(10).default(5),
  },

• src/tools/workouts.ts:49-78 (registration)

  Registration of the 'get-workouts' tool on the MCP server within the registerWorkoutTools function, specifying name, description, input schema, and error-handling wrapped handler.

  	"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.",
  	{
  		page: z.coerce.number().gte(1).default(1),
  		pageSize: z.coerce.number().int().gte(1).lte(10).default(5),
  	},
  	withErrorHandling(async ({ page, pageSize }) => {
  		if (!hevyClient) {
  			throw new Error(
  				"API client not initialized. Please provide HEVY_API_KEY.",
  			);
  		}
  		const data = await hevyClient.getWorkouts({
  			page,
  			pageSize,
  		});
  
  		// Process workouts to extract relevant information
  		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"),
  );