Hevy MCP

Instructions

Implementation Reference

• src/tools/folders.ts:33-57 (handler)

  Handler function that fetches a paginated list of routine folders from the Hevy API client, formats each folder using formatRoutineFolder, handles empty results, and returns a JSON response or empty response.

  async ({ page, pageSize }: { page: number; pageSize: number }) => {
  	if (!hevyClient) {
  		throw new Error(
  			"API client not initialized. Please provide HEVY_API_KEY.",
  		);
  	}
  	const data = await hevyClient.getRoutineFolders({
  		page,
  		pageSize,
  	});
  
  	// Process routine folders to extract relevant information
  	const folders =
  		data?.routine_folders?.map((folder: RoutineFolder) =>
  			formatRoutineFolder(folder),
  		) || [];
  
  	if (folders.length === 0) {
  		return createEmptyResponse(
  			"No routine folders found for the specified parameters",
  		);
  	}
  
  	return createJsonResponse(folders);
  },

• src/tools/folders.ts:28-31 (schema)

  Input schema using Zod: page (coerced integer >=1, default 1), pageSize (coerced integer 1-10, default 5).

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

• src/tools/folders.ts:26-60 (registration)

  Registers the 'get-routine-folders' tool with the MCP server, providing tool name, description, input schema, and error-handling wrapped handler function.

  	"get-routine-folders",
  	"Get a paginated list of your routine folders, including both default and custom folders. Useful for organizing and browsing your workout routines.",
  	{
  		page: z.coerce.number().int().gte(1).default(1),
  		pageSize: z.coerce.number().int().gte(1).lte(10).default(5),
  	},
  	withErrorHandling(
  		async ({ page, pageSize }: { page: number; pageSize: number }) => {
  			if (!hevyClient) {
  				throw new Error(
  					"API client not initialized. Please provide HEVY_API_KEY.",
  				);
  			}
  			const data = await hevyClient.getRoutineFolders({
  				page,
  				pageSize,
  			});
  
  			// Process routine folders to extract relevant information
  			const folders =
  				data?.routine_folders?.map((folder: RoutineFolder) =>
  					formatRoutineFolder(folder),
  				) || [];
  
  			if (folders.length === 0) {
  				return createEmptyResponse(
  					"No routine folders found for the specified parameters",
  				);
  			}
  
  			return createJsonResponse(folders);
  		},
  		"get-routine-folders",
  	),
  );