hevy-mcp 1.26.0 → 1.26.2

package/dist/{src-Di7keTQA.mjs → src-CuOZcBEo.mjs}

@@ -4,9 +4,9 @@
 (function() {
 	try {
 		var e = "undefined" != typeof window ? window : "undefined" != typeof global ? global : "undefined" != typeof globalThis ? globalThis : "undefined" != typeof self ? self : {};
-		e.SENTRY_RELEASE = { id: "hevy-mcp@1.26.0" };
+		e.SENTRY_RELEASE = { id: "hevy-mcp@1.26.2" };
 		var n = new e.Error().stack;
-		n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "b6fef1cd-aaf1-497b-af9e-7d50fa405061", e._sentryDebugIdIdentifier = "sentry-dbid-b6fef1cd-aaf1-497b-af9e-7d50fa405061");
+		n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "425564da-031b-406e-b160-907df2faf2eb", e._sentryDebugIdIdentifier = "sentry-dbid-425564da-031b-406e-b160-907df2faf2eb");
 	} catch (e) {}
 })();
 import * as Sentry from "@sentry/node";
@@ -36,10 +36,10 @@ import { deserializeMessage } from "@modelcontextprotocol/sdk/shared/stdio.js";
 * OTel Collector → Honeycomb: performance traces, metrics
 */
 const name$1 = "hevy-mcp";
-const version$1 = "1.26.0";
+const version$1 = "1.26.2";
 const collectorToken = process.env.OTEL_COLLECTOR_TOKEN ?? "";
 const COLLECTOR_ENDPOINT = "https://otel.chrisdoc.dev/v1";
-const sentryRelease = process.env.SENTRY_RELEASE ?? `hevy-mcp@1.26.0`;
+const sentryRelease = process.env.SENTRY_RELEASE ?? `hevy-mcp@1.26.2`;
 const resource = resourceFromAttributes({
 	"service.name": name$1,
 	"service.version": version$1
@@ -127,6 +127,48 @@ const serverStartups = meter.createCounter("mcp.server.startups", { description:
 /**
 * Centralized error handling utility for MCP tools
 */
+function normalizeHeaderValue$1(value) {
+	if (typeof value === "string") {
+		const trimmed = value.trim();
+		return trimmed.length > 0 ? trimmed : void 0;
+	}
+	if (typeof value === "number" && Number.isFinite(value)) return String(value);
+	if (Array.isArray(value) && value.length > 0) return normalizeHeaderValue$1(value[0]);
+}
+function getHeaderValue$1(headers, key) {
+	if (!headers || typeof headers !== "object") return;
+	if ("get" in headers && typeof headers.get === "function") return normalizeHeaderValue$1(headers.get(key));
+	const headerRecord = headers;
+	return normalizeHeaderValue$1(headerRecord[key] ?? headerRecord[key.toLowerCase()] ?? headerRecord[key.toUpperCase()]);
+}
+function formatSecondsLabel(seconds) {
+	const roundedSeconds = Math.max(0, Math.round(seconds));
+	return `${roundedSeconds} second${roundedSeconds === 1 ? "" : "s"}`;
+}
+function getRateLimitMessage(error) {
+	if (!isAxiosError(error)) return "Rate limited by Hevy. Please wait and retry.";
+	const retryAfterHeader = getHeaderValue$1(error.response?.headers, "retry-after");
+	if (!retryAfterHeader) return "Rate limited by Hevy (HTTP 429). Please wait and retry your request.";
+	const seconds = Number(retryAfterHeader);
+	if (Number.isFinite(seconds) && seconds >= 0) return `Rate limited by Hevy (HTTP 429). Please wait about ${formatSecondsLabel(seconds)} before retrying.`;
+	const retryAtMillis = Date.parse(retryAfterHeader);
+	if (!Number.isNaN(retryAtMillis)) return `Rate limited by Hevy (HTTP 429). Please wait about ${formatSecondsLabel(Math.ceil(Math.max(0, retryAtMillis - Date.now()) / 1e3))} before retrying.`;
+	return "Rate limited by Hevy (HTTP 429). Please wait and retry your request.";
+}
+function isRetryExhaustedError(error) {
+	return !!error && typeof error === "object" && error.hevyRetryExhausted === true;
+}
+function getRetryExhaustedMessage(error) {
+	const retryCount = typeof error === "object" && error !== null ? error.hevyRetryCount : void 0;
+	const attemptCount = typeof retryCount === "number" && Number.isFinite(retryCount) ? retryCount + 1 : void 0;
+	if (attemptCount) return `Unable to complete the request after ${attemptCount} attempts to the Hevy API due to transient failures. Please try again shortly.`;
+	return "Unable to complete the request after multiple attempts to the Hevy API due to transient failures. Please try again shortly.";
+}
+function getUserFacingMessage(error, defaultMessage) {
+	if (isRetryExhaustedError(error)) return getRetryExhaustedMessage(error);
+	if (isAxiosError(error) && error.response?.status === 429) return getRateLimitMessage(error);
+	return defaultMessage;
+}
 /**
 * Create a standardized error response for MCP tools
 *
@@ -135,18 +177,22 @@ const serverStartups = meter.createCounter("mcp.server.startups", { description:
 * @returns A formatted MCP tool response with error information
 */
 function createErrorResponse(error, context) {
-	let errorMessage = error instanceof Error ? error.message : String(error);
-	if (isAxiosError(error) && error.response?.data) {
-		const { data } = error.response;
-		if (typeof data === "string") errorMessage = data;
-		else if (data && typeof data === "object") try {
-			errorMessage = JSON.stringify(data);
-		} catch (_e) {
-			errorMessage = String(data);
-		}
-	}
+	const originalErrorMessage = extractErrorMessage(error);
+	let errorMessage = originalErrorMessage;
+	const axiosErrorContext = extractAxiosErrorContext(error);
+	const mappedHevyErrorMessage = mapHevyErrorMessageByStatus(axiosErrorContext?.status);
+	if (mappedHevyErrorMessage) errorMessage = mappedHevyErrorMessage;
+	if (!mappedHevyErrorMessage && axiosErrorContext?.data) errorMessage = stringifyErrorData(axiosErrorContext.data);
+	errorMessage = getUserFacingMessage(error, errorMessage);
 	const errorCode = error instanceof Error && "code" in error ? error.code : void 0;
 	const errorType = determineErrorType(error, errorMessage);
+	const errorContext = {
+		sourceContext: context,
+		originalErrorMessage,
+		errorCode,
+		errorType,
+		axios: axiosErrorContext ?? void 0
+	};
 	const formattedMessage = `${context ? `[${context}] ` : ""}Error: ${errorMessage}`;
 	const errorCodeSuffix = errorCode ? `, Code: ${errorCode}` : "";
 	console.error(`${formattedMessage} (Type: ${errorType}${errorCodeSuffix})`, error);
@@ -155,13 +201,55 @@ function createErrorResponse(error, context) {
 			type: "text",
 			text: formattedMessage
 		}],
-		isError: true
+		isError: true,
+		errorContext
 	};
 }
+function extractErrorMessage(error) {
+	if (error instanceof Error) return error.message;
+	if (typeof error === "string") return error;
+	if (error && typeof error === "object" && "message" in error && typeof error.message === "string") return error.message;
+	if (error && typeof error === "object") try {
+		return JSON.stringify(error);
+	} catch (_e) {
+		return "Unknown error object";
+	}
+	return String(error);
+}
+function extractAxiosErrorContext(error) {
+	if (!isAxiosError(error)) return null;
+	return {
+		status: error.response?.status,
+		statusText: error.response?.statusText,
+		data: error.response?.data,
+		method: error.config?.method,
+		url: error.config?.url
+	};
+}
+function mapHevyErrorMessageByStatus(status) {
+	if (status === 401 || status === 403) return "The Hevy API key is invalid or has expired. Check HEVY_API_KEY.";
+	if (status === 404) return "The requested resource was not found in Hevy.";
+	if (status === 409) return "A conflict occurred (e.g., a body measurement already exists for this date). Use the update tool instead.";
+	if (status === 422) return "The request failed Hevy validation. Check the field values and try again.";
+	if (status === 429) return "Rate limited by Hevy. Please wait and retry.";
+	if (status && status >= 500 && status <= 599) return "Hevy API experienced an error. Please retry later.";
+	return null;
+}
+function stringifyErrorData(data) {
+	if (typeof data === "string") return data;
+	if (data && typeof data === "object") try {
+		return JSON.stringify(data);
+	} catch (_e) {
+		return "Unable to serialize error response data";
+	}
+	return String(data);
+}
 /**
 * Determine the type of error based on error characteristics
 */
 function determineErrorType(error, message) {
+	if (isRetryExhaustedError(error)) return "NETWORK_ERROR";
+	if (isAxiosError(error) && error.response?.status === 429) return "RATE_LIMIT";
 	const messageLower = message.toLowerCase();
 	const nameLower = error instanceof Error ? error.name.toLowerCase() : "";
 	if (nameLower.includes("network") || messageLower.includes("network") || nameLower.includes("fetch") || messageLower.includes("fetch") || nameLower.includes("timeout") || messageLower.includes("timeout")) return "NETWORK_ERROR";
@@ -405,7 +493,7 @@ function createJsonResponse(data, options = {
 }) {
 	return { content: [{
 		type: "text",
-		text: options.pretty ? JSON.stringify(data, null, options.indent) : JSON.stringify(data)
+		text: (options.pretty ? JSON.stringify(data, null, options.indent) : JSON.stringify(data)) ?? "null"
 	}] };
 }
 /**
@@ -427,10 +515,7 @@ function createTextResponse(message) {
 * @returns A formatted MCP tool response for empty results
 */
 function createEmptyResponse(message = "No data found") {
-	return { content: [{
-		type: "text",
-		text: message
-	}] };
+	return createTextResponse(message);
 }
 //#endregion
 //#region src/utils/tool-annotations.ts
@@ -466,8 +551,86 @@ function updateAnnotations(title) {
 	};
 }
 //#endregion
-//#region src/tools/body-measurements.ts
+//#region src/utils/tool-helpers.ts
+const HEVY_CLIENT_NOT_INITIALIZED_ERROR = "API client not initialized. Please provide HEVY_API_KEY.";
+/**
+* Assert that the Hevy API client is initialized before running a tool.
+*/
+function requireClient(client) {
+	if (!client) throw new Error(HEVY_CLIENT_NOT_INITIALIZED_ERROR);
+	return client;
+}
+//#endregion
+//#region src/utils/schemas.ts
+function coerceNullishNumberInput(value) {
+	if (value === null || value === void 0) return value;
+	if (typeof value !== "string") return value;
+	const trimmed = value.trim();
+	if (trimmed === "") return;
+	const lowered = trimmed.toLowerCase();
+	if (lowered === "null") return null;
+	if (lowered === "undefined") return;
+	const asNumber = Number(trimmed);
+	if (Number.isNaN(asNumber)) return value;
+	return asNumber;
+}
+const zNullableInt = z.preprocess(coerceNullishNumberInput, z.number().int().nullable().optional());
 const zNullableNumber = z.preprocess((value) => value === "" ? void 0 : value, z.coerce.number().nullable().optional());
+const zOptionalRepRange = z.preprocess((value) => value === null ? void 0 : value, z.object({
+	start: zNullableInt,
+	end: zNullableInt
+}).optional());
+const setTypeEnum = z.enum([
+	"warmup",
+	"normal",
+	"failure",
+	"dropset"
+]).default("normal");
+const muscleGroupEnum = z.enum([
+	"abdominals",
+	"shoulders",
+	"biceps",
+	"triceps",
+	"forearms",
+	"quadriceps",
+	"hamstrings",
+	"calves",
+	"glutes",
+	"abductors",
+	"adductors",
+	"lats",
+	"upper_back",
+	"traps",
+	"lower_back",
+	"chest",
+	"cardio",
+	"neck",
+	"full_body",
+	"other"
+]);
+const exerciseTypeEnum = z.enum([
+	"weight_reps",
+	"reps_only",
+	"bodyweight_reps",
+	"bodyweight_assisted_reps",
+	"duration",
+	"weight_duration",
+	"distance_duration",
+	"short_distance_weight"
+]);
+const equipmentCategoryEnum = z.enum([
+	"none",
+	"barbell",
+	"dumbbell",
+	"kettlebell",
+	"machine",
+	"plate",
+	"resistance_band",
+	"suspension",
+	"other"
+]);
+//#endregion
+//#region src/tools/body-measurements.ts
 const bodyMeasurementFieldsSchema = {
 	weightKg: zNullableNumber.describe("Body weight in kilograms"),
 	leanMassKg: zNullableNumber.describe("Lean body mass in kilograms"),
@@ -520,9 +683,9 @@ function registerBodyMeasurementTools(server, hevyClient) {
 		pageSize: z.coerce.number().int().gte(1).lte(10).default(10)
 	};
 	server.tool("get-body-measurements", "Get a paginated list of body measurements for the authenticated user. Returns measurements including weight, body fat, and various circumference measurements.", getBodyMeasurementsSchema, readOnlyAnnotations("Get Body Measurements"), withErrorHandling(async (args) => {
-		if (!hevyClient) throw new Error("API client not initialized. Please provide HEVY_API_KEY.");
+		const client = requireClient(hevyClient);
 		const { page, pageSize } = args;
-		const measurements = (await hevyClient.getBodyMeasurements({
+		const measurements = (await client.getBodyMeasurements({
 			page,
 			pageSize
 		}))?.body_measurements?.map((measurement) => formatBodyMeasurement(measurement)) || [];
@@ -531,9 +694,9 @@ function registerBodyMeasurementTools(server, hevyClient) {
 	}, "get-body-measurements"));
 	const getBodyMeasurementSchema = { date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be in YYYY-MM-DD format").describe("The date of the body measurement (YYYY-MM-DD)") };
 	server.tool("get-body-measurement", "Get a single body measurement by date. Returns all measurement fields for the specified date.", getBodyMeasurementSchema, readOnlyAnnotations("Get Body Measurement"), withErrorHandling(async (args) => {
-		if (!hevyClient) throw new Error("API client not initialized. Please provide HEVY_API_KEY.");
+		const client = requireClient(hevyClient);
 		const { date } = args;
-		const data = await hevyClient.getBodyMeasurement(date);
+		const data = await client.getBodyMeasurement(date);
 		if (!data) return createEmptyResponse(`No body measurement found for date ${date}`);
 		return createJsonResponse(formatBodyMeasurement(data));
 	}, "get-body-measurement"));
@@ -542,9 +705,9 @@ function registerBodyMeasurementTools(server, hevyClient) {
 		...bodyMeasurementFieldsSchema
 	};
 	server.tool("create-body-measurement", "Create a body measurement entry for a given date. All measurement fields are optional; null values are treated as omitted, since the Hevy API does not support clearing individual fields. Returns 409 if an entry already exists for that date — use update-body-measurement instead.", createBodyMeasurementSchema, createAnnotations("Create Body Measurement"), withErrorHandling(async (args) => {
-		if (!hevyClient) throw new Error("API client not initialized. Please provide HEVY_API_KEY.");
+		const client = requireClient(hevyClient);
 		const { date, ...fields } = args;
-		await hevyClient.createBodyMeasurement({
+		await client.createBodyMeasurement({
 			date,
 			...buildMeasurementPayload(fields)
 		});
@@ -555,11 +718,11 @@ function registerBodyMeasurementTools(server, hevyClient) {
 		...bodyMeasurementFieldsSchema
 	};
 	server.tool("update-body-measurement", "Update an existing body measurement entry for a given date. Only the fields you provide are sent and updated; null values are treated as omitted, since the Hevy API does not support clearing individual fields. Requires at least one measurement field. Returns 404 if no entry exists for the date.", updateBodyMeasurementSchema, updateAnnotations("Update Body Measurement"), withErrorHandling(async (args) => {
-		if (!hevyClient) throw new Error("API client not initialized. Please provide HEVY_API_KEY.");
+		const client = requireClient(hevyClient);
 		const { date, ...fields } = args;
 		const payload = buildMeasurementPayload(fields);
 		if (Object.keys(payload).length === 0) throw new Error("No measurement fields provided. Include at least one numeric measurement field (e.g. weightKg) to update.");
-		await hevyClient.updateBodyMeasurement(date, payload);
+		await client.updateBodyMeasurement(date, payload);
 		return createTextResponse(`Body measurement for ${date} updated successfully.`);
 	}, "update-body-measurement"));
 }
@@ -574,9 +737,9 @@ function registerFolderTools(server, hevyClient) {
 		pageSize: z.coerce.number().int().gte(1).lte(10).default(5)
 	};
 	server.tool("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.", getRoutineFoldersSchema, readOnlyAnnotations("Get Routine Folders"), withErrorHandling(async (args) => {
-		if (!hevyClient) throw new Error("API client not initialized. Please provide HEVY_API_KEY.");
+		const client = requireClient(hevyClient);
 		const { page, pageSize } = args;
-		const folders = (await hevyClient.getRoutineFolders({
+		const folders = (await client.getRoutineFolders({
 			page,
 			pageSize
 		}))?.routine_folders?.map((folder) => formatRoutineFolder(folder)) || [];
@@ -585,17 +748,17 @@ function registerFolderTools(server, hevyClient) {
 	}, "get-routine-folders"));
 	const getRoutineFolderSchema = { folderId: z.string().min(1) };
 	server.tool("get-routine-folder", "Get complete details of a specific routine folder by its ID, including name, creation date, and associated routines.", getRoutineFolderSchema, readOnlyAnnotations("Get Routine Folder"), withErrorHandling(async (args) => {
-		if (!hevyClient) throw new Error("API client not initialized. Please provide HEVY_API_KEY.");
+		const client = requireClient(hevyClient);
 		const { folderId } = args;
-		const data = await hevyClient.getRoutineFolder(folderId);
+		const data = await client.getRoutineFolder(folderId);
 		if (!data) return createEmptyResponse(`Routine folder with ID ${folderId} not found`);
 		return createJsonResponse(formatRoutineFolder(data));
 	}, "get-routine-folder"));
 	const createRoutineFolderSchema = { name: z.string().min(1) };
 	server.tool("create-routine-folder", "Create a new routine folder in your Hevy account. Requires a name for the folder. Returns the full folder details including the new folder ID.", createRoutineFolderSchema, createAnnotations("Create Routine Folder"), withErrorHandling(async (args) => {
-		if (!hevyClient) throw new Error("API client not initialized. Please provide HEVY_API_KEY.");
+		const client = requireClient(hevyClient);
 		const { name } = args;
-		const data = await hevyClient.createRoutineFolder({ routine_folder: { title: name } });
+		const data = await client.createRoutineFolder({ routine_folder: { title: name } });
 		if (!data) return createEmptyResponse("Failed to create routine folder: Server returned no data");
 		return createJsonResponse(formatRoutineFolder(data), {
 			pretty: true,
@@ -625,23 +788,6 @@ function parseJsonArray(val) {
 }
 //#endregion
 //#region src/tools/routines.ts
-function coerceNullishNumberInput(value) {
-	if (value === null || value === void 0) return value;
-	if (typeof value !== "string") return value;
-	const trimmed = value.trim();
-	if (trimmed === "") return;
-	const lowered = trimmed.toLowerCase();
-	if (lowered === "null") return null;
-	if (lowered === "undefined") return;
-	const asNumber = Number(trimmed);
-	if (Number.isNaN(asNumber)) return value;
-	return asNumber;
-}
-const zNullableInt = z.preprocess(coerceNullishNumberInput, z.number().int().nullable().optional());
-const zOptionalRepRange = z.preprocess((value) => value === null ? void 0 : value, z.object({
-	start: zNullableInt,
-	end: zNullableInt
-}).optional());
 function buildRepRange(repRange) {
 	if (!repRange) return null;
 	const start = repRange.start ?? void 0;
@@ -674,9 +820,9 @@ function registerRoutineTools(server, hevyClient) {
 		pageSize: z.coerce.number().int().gte(1).lte(10).default(5)
 	};
 	server.tool("get-routines", "Get a paginated list of your workout routines, including custom and default routines. Useful for browsing or searching your available routines.", getRoutinesSchema, readOnlyAnnotations("Get Routines"), withErrorHandling(async (args) => {
-		if (!hevyClient) throw new Error("API client not initialized. Please provide HEVY_API_KEY.");
+		const client = requireClient(hevyClient);
 		const { page, pageSize } = args;
-		const routines = (await hevyClient.getRoutines({
+		const routines = (await client.getRoutines({
 			page,
 			pageSize
 		}))?.routines?.map((routine) => formatRoutine(routine)) || [];
@@ -685,9 +831,9 @@ function registerRoutineTools(server, hevyClient) {
 	}, "get-routines"));
 	const getRoutineSchema = { routineId: z.string().min(1) };
 	server.tool("get-routine", "Get a routine by its ID using the direct endpoint. Returns all details for the specified routine.", getRoutineSchema, readOnlyAnnotations("Get Routine"), withErrorHandling(async (args) => {
-		if (!hevyClient) throw new Error("API client not initialized. Please provide HEVY_API_KEY.");
+		const client = requireClient(hevyClient);
 		const { routineId } = args;
-		const data = await hevyClient.getRoutineById(String(routineId));
+		const data = await client.getRoutineById(String(routineId));
 		if (!data || !data.routine) return createEmptyResponse(`Routine with ID ${routineId} not found`);
 		return createJsonResponse(formatRoutine(data.routine));
 	}, "get-routine"));
@@ -701,12 +847,7 @@ function registerRoutineTools(server, hevyClient) {
 			restSeconds: z.coerce.number().int().min(0).optional(),
 			notes: z.string().optional(),
 			sets: z.array(z.object({
-				type: z.enum([
-					"warmup",
-					"normal",
-					"failure",
-					"dropset"
-				]).default("normal"),
+				type: setTypeEnum,
 				weight: z.coerce.number().optional(),
 				weightKg: z.coerce.number().optional(),
 				reps: zNullableInt,
@@ -720,10 +861,10 @@ function registerRoutineTools(server, hevyClient) {
 		})))
 	};
 	server.tool("create-routine", "Create a new workout routine in your Hevy account. Requires a title and at least one exercise with sets. Optionally assign to a folder. Returns the full routine details including the new routine ID.", createRoutineSchema, createAnnotations("Create Routine"), withErrorHandling(async (args) => {
-		if (!hevyClient) throw new Error("API client not initialized. Please provide HEVY_API_KEY.");
+		const client = requireClient(hevyClient);
 		const { title, folderId, notes, exercises } = args;
 		let usesRepRanges = false;
-		const data = await hevyClient.createRoutine({ routine: {
+		const data = await client.createRoutine({ routine: {
 			title,
 			folder_id: folderId ?? null,
 			notes: notes ?? "",
@@ -773,12 +914,7 @@ function registerRoutineTools(server, hevyClient) {
 			restSeconds: z.coerce.number().int().min(0).optional(),
 			notes: z.string().optional(),
 			sets: z.array(z.object({
-				type: z.enum([
-					"warmup",
-					"normal",
-					"failure",
-					"dropset"
-				]).default("normal"),
+				type: setTypeEnum,
 				weight: z.coerce.number().optional(),
 				weightKg: z.coerce.number().optional(),
 				reps: zNullableInt,
@@ -792,10 +928,10 @@ function registerRoutineTools(server, hevyClient) {
 		})))
 	};
 	server.tool("update-routine", "Update an existing routine by ID. You can modify the title, notes, and exercise configurations. Returns the updated routine with all changes applied.", updateRoutineSchema, updateAnnotations("Update Routine"), withErrorHandling(async (args) => {
-		if (!hevyClient) throw new Error("API client not initialized. Please provide HEVY_API_KEY.");
+		const client = requireClient(hevyClient);
 		const { routineId, title, notes, exercises } = args;
 		let usesRepRanges = false;
-		const data = await hevyClient.updateRoutine(routineId, { routine: {
+		const data = await client.updateRoutine(routineId, { routine: {
 			title,
 			notes: notes ?? null,
 			exercises: exercises.map((exercise) => {
@@ -836,31 +972,114 @@ function registerRoutineTools(server, hevyClient) {
 	}, "update-routine"));
 }
 //#endregion
+//#region src/utils/cache.ts
+/**
+* Shared in-memory cache for async fetches with TTL, LRU eviction,
+* in-flight de-duplication, and explicit refresh/invalidation support.
+*/
+var AsyncTtlCache = class {
+	ttlMs;
+	maxSize;
+	now;
+	entries = /* @__PURE__ */ new Map();
+	inFlight = /* @__PURE__ */ new Map();
+	requestCounter = 0;
+	constructor(options, now = Date.now) {
+		const { ttlMs, maxSize } = options;
+		if (ttlMs <= 0) throw new Error("Cache ttlMs must be greater than 0.");
+		if (maxSize <= 0) throw new Error("Cache maxSize must be greater than 0.");
+		this.ttlMs = ttlMs;
+		this.maxSize = maxSize;
+		this.now = now;
+	}
+	async getOrFetch(key, fetcher, options = {}) {
+		const { refresh = false } = options;
+		if (refresh) this.invalidate(key);
+		else {
+			const cachedEntry = this.entries.get(key);
+			if (cachedEntry !== void 0) {
+				if (cachedEntry.expiresAt > this.now()) {
+					this.markAsRecentlyUsed(key, cachedEntry);
+					return cachedEntry.value;
+				}
+				this.entries.delete(key);
+			}
+			const inFlightEntry = this.inFlight.get(key);
+			if (inFlightEntry !== void 0) return inFlightEntry.promise;
+		}
+		const requestId = ++this.requestCounter;
+		const request = (async () => {
+			try {
+				const value = await fetcher();
+				if (this.isCurrentRequest(key, requestId)) this.setValue(key, value);
+				return value;
+			} finally {
+				if (this.inFlight.get(key)?.requestId === requestId) this.inFlight.delete(key);
+			}
+		})();
+		this.inFlight.set(key, {
+			promise: request,
+			requestId
+		});
+		return request;
+	}
+	invalidate(key) {
+		this.entries.delete(key);
+		this.inFlight.delete(key);
+	}
+	clear() {
+		this.entries.clear();
+		this.inFlight.clear();
+	}
+	get size() {
+		return this.entries.size;
+	}
+	isCurrentRequest(key, requestId) {
+		return this.inFlight.get(key)?.requestId === requestId;
+	}
+	markAsRecentlyUsed(key, entry) {
+		this.entries.delete(key);
+		this.entries.set(key, entry);
+	}
+	setValue(key, value) {
+		this.entries.delete(key);
+		this.entries.set(key, {
+			value,
+			expiresAt: this.now() + this.ttlMs
+		});
+		this.evictLeastRecentlyUsed();
+	}
+	evictLeastRecentlyUsed() {
+		while (this.entries.size > this.maxSize) {
+			const oldestKey = this.entries.keys().next().value;
+			if (oldestKey === void 0) return;
+			this.entries.delete(oldestKey);
+		}
+	}
+};
+//#endregion
 //#region src/tools/templates.ts
-const MUSCLE_GROUPS = [
-	"abdominals",
-	"shoulders",
-	"biceps",
-	"triceps",
-	"forearms",
-	"quadriceps",
-	"hamstrings",
-	"calves",
-	"glutes",
-	"abductors",
-	"adductors",
-	"lats",
-	"upper_back",
-	"traps",
-	"lower_back",
-	"chest",
-	"cardio",
-	"neck",
-	"full_body",
-	"other"
-];
-let exerciseTemplateCache = null;
-let exerciseTemplateFetch = null;
+const EXERCISE_TEMPLATE_CATALOG_CACHE_KEY = "exercise-template-catalog";
+const exerciseTemplateCatalogCache = new AsyncTtlCache({
+	ttlMs: 300 * 1e3,
+	maxSize: 1
+});
+async function fetchExerciseTemplateCatalog(hevyClient) {
+	const allTemplates = [];
+	let page = 1;
+	let pageCount = 1;
+	do {
+		const data = await hevyClient.getExerciseTemplates({
+			page,
+			pageSize: 100
+		});
+		const templates = data?.exercise_templates ?? [];
+		allTemplates.push(...templates);
+		pageCount = data?.page_count ?? 1;
+		page++;
+	} while (page <= pageCount);
+	return allTemplates;
+}
 /**
 * Register all exercise template-related tools with the MCP server
 */
@@ -870,9 +1089,9 @@ function registerTemplateTools(server, hevyClient) {
 		pageSize: z.coerce.number().int().gte(1).lte(100).default(5)
 	};
 	server.tool("get-exercise-templates", "Get a paginated list of exercise templates (default and custom) with details like name, category, equipment, and muscle groups. Useful for browsing or searching available exercises.", getExerciseTemplatesSchema, readOnlyAnnotations("Get Exercise Templates"), withErrorHandling(async (args) => {
-		if (!hevyClient) throw new Error("API client not initialized. Please provide HEVY_API_KEY.");
+		const client = requireClient(hevyClient);
 		const { page, pageSize } = args;
-		const templates = (await hevyClient.getExerciseTemplates({
+		const templates = (await client.getExerciseTemplates({
 			page,
 			pageSize
 		}))?.exercise_templates?.map((template) => formatExerciseTemplate(template)) || [];
@@ -881,9 +1100,9 @@ function registerTemplateTools(server, hevyClient) {
 	}, "get-exercise-templates"));
 	const getExerciseTemplateSchema = { exerciseTemplateId: z.string().min(1) };
 	server.tool("get-exercise-template", "Get complete details of a specific exercise template by its ID, including name, category, equipment, muscle groups, and notes.", getExerciseTemplateSchema, readOnlyAnnotations("Get Exercise Template"), withErrorHandling(async (args) => {
-		if (!hevyClient) throw new Error("API client not initialized. Please provide HEVY_API_KEY.");
+		const client = requireClient(hevyClient);
 		const { exerciseTemplateId } = args;
-		const data = await hevyClient.getExerciseTemplate(exerciseTemplateId);
+		const data = await client.getExerciseTemplate(exerciseTemplateId);
 		if (!data) return createEmptyResponse(`Exercise template with ID ${exerciseTemplateId} not found`);
 		return createJsonResponse(formatExerciseTemplate(data));
 	}, "get-exercise-template"));
@@ -893,9 +1112,9 @@ function registerTemplateTools(server, hevyClient) {
 		endDate: z.string().datetime({ offset: true }).describe("ISO 8601 end date for filtering history").optional()
 	};
 	server.tool("get-exercise-history", "Get past sets for a specific exercise template, optionally filtered by start and end dates.", getExerciseHistorySchema, readOnlyAnnotations("Get Exercise History"), withErrorHandling(async (args) => {
-		if (!hevyClient) throw new Error("API client not initialized. Please provide HEVY_API_KEY.");
+		const client = requireClient(hevyClient);
 		const { exerciseTemplateId, startDate, endDate } = args;
-		const history = (await hevyClient.getExerciseHistory(exerciseTemplateId, {
+		const history = (await client.getExerciseHistory(exerciseTemplateId, {
 			...startDate ? { start_date: startDate } : {},
 			...endDate ? { end_date: endDate } : {}
 		}))?.exercise_history?.map((entry) => formatExerciseHistoryEntry(entry)) || [];
@@ -904,35 +1123,16 @@ function registerTemplateTools(server, hevyClient) {
 	}, "get-exercise-history"));
 	const createExerciseTemplateSchema = {
 		title: z.string().min(1),
-		exerciseType: z.enum([
-			"weight_reps",
-			"reps_only",
-			"bodyweight_reps",
-			"bodyweight_assisted_reps",
-			"duration",
-			"weight_duration",
-			"distance_duration",
-			"short_distance_weight"
-		]),
-		equipmentCategory: z.enum([
-			"none",
-			"barbell",
-			"dumbbell",
-			"kettlebell",
-			"machine",
-			"plate",
-			"resistance_band",
-			"suspension",
-			"other"
-		]),
-		muscleGroup: z.enum(MUSCLE_GROUPS),
-		otherMuscles: z.array(z.enum(MUSCLE_GROUPS)).default([])
+		exerciseType: exerciseTypeEnum,
+		equipmentCategory: equipmentCategoryEnum,
+		muscleGroup: muscleGroupEnum,
+		otherMuscles: z.array(muscleGroupEnum).default([])
 	};
 	server.tool("create-exercise-template", "Create a custom exercise template with title, type, equipment, and muscle groups.", createExerciseTemplateSchema, createAnnotations("Create Exercise Template"), withErrorHandling(async (args) => {
-		if (!hevyClient) throw new Error("API client not initialized. Please provide HEVY_API_KEY.");
+		const client = requireClient(hevyClient);
 		const { title, exerciseType, equipmentCategory, muscleGroup, otherMuscles } = args;
 		return createJsonResponse({
-			id: (await hevyClient.createExerciseTemplate({ exercise: {
+			id: (await client.createExerciseTemplate({ exercise: {
 				title,
 				exercise_type: exerciseType,
 				equipment_category: equipmentCategory,
@@ -944,40 +1144,15 @@ function registerTemplateTools(server, hevyClient) {
 	}, "create-exercise-template"));
 	const searchExerciseTemplatesSchema = {
 		query: z.string().min(1).describe("Case-insensitive substring to match against exercise template titles"),
-		primaryMuscleGroup: z.enum(MUSCLE_GROUPS).optional().describe("Optional filter to restrict results to a specific primary muscle group"),
-		refresh: z.boolean().optional().default(false).describe("Set to true to bust the in-memory cache and re-fetch all templates from the API")
+		primaryMuscleGroup: muscleGroupEnum.optional().describe("Optional filter to restrict results to a specific primary muscle group"),
+		refresh: z.boolean().optional().default(false).describe("Set to true to invalidate the catalog cache and re-fetch all templates from the API")
 	};
-	server.tool("search-exercise-templates", "Search exercise templates by name with optional muscle group filter. Fetches all templates from the Hevy API on first call and caches them in memory for subsequent searches. Use refresh:true to force a re-fetch.", searchExerciseTemplatesSchema, readOnlyAnnotations("Search Exercise Templates"), withErrorHandling(async (args) => {
-		if (!hevyClient) throw new Error("API client not initialized. Please provide HEVY_API_KEY.");
+	server.tool("search-exercise-templates", "Search exercise templates by name with optional muscle group filter. Fetches all templates from the Hevy API on first call, caches the catalog in memory with a bounded TTL cache, and reuses it for subsequent searches. Use refresh:true to force a re-fetch.", searchExerciseTemplatesSchema, readOnlyAnnotations("Search Exercise Templates"), withErrorHandling(async (args) => {
+		const client = requireClient(hevyClient);
 		const { query, primaryMuscleGroup, refresh } = args;
-		if (exerciseTemplateCache === null || refresh) {
-			if (refresh) exerciseTemplateFetch = null;
-			if (exerciseTemplateFetch === null) exerciseTemplateFetch = (async () => {
-				try {
-					const allTemplates = [];
-					let page = 1;
-					let pageCount = 1;
-					do {
-						const data = await hevyClient.getExerciseTemplates({
-							page,
-							pageSize: 100
-						});
-						const templates = data?.exercise_templates ?? [];
-						allTemplates.push(...templates);
-						pageCount = data?.page_count ?? 1;
-						page++;
-					} while (page <= pageCount);
-					exerciseTemplateCache = allTemplates;
-					return allTemplates;
-				} finally {
-					exerciseTemplateFetch = null;
-				}
-			})();
-			await exerciseTemplateFetch;
-		}
+		const catalog = await exerciseTemplateCatalogCache.getOrFetch(EXERCISE_TEMPLATE_CATALOG_CACHE_KEY, () => fetchExerciseTemplateCatalog(client), { refresh });
 		const queryLower = query.toLowerCase();
-		if (exerciseTemplateCache === null) throw new Error("Failed to populate exercise template cache.");
-		let results = exerciseTemplateCache.filter((t) => (t.title ?? "").toLowerCase().includes(queryLower));
+		let results = catalog.filter((t) => (t.title ?? "").toLowerCase().includes(queryLower));
 		if (primaryMuscleGroup !== void 0) results = results.filter((t) => t.primary_muscle_group === primaryMuscleGroup);
 		if (results.length === 0) return createEmptyResponse(`No exercise templates found matching "${query}"${primaryMuscleGroup ? ` with primary muscle group "${primaryMuscleGroup}"` : ""}`);
 		return createJsonResponse(results.map(formatExerciseTemplate));
@@ -987,8 +1162,7 @@ function registerTemplateTools(server, hevyClient) {
 //#region src/tools/user.ts
 function registerUserTools(server, hevyClient) {
 	server.tool("get-user-info", "Get the authenticated user's account info, including user ID, display name, and public profile URL. Useful for verifying which account the API key belongs to.", {}, readOnlyAnnotations("Get User Info"), withErrorHandling(async (_args) => {
-		if (!hevyClient) throw new Error("API client not initialized. Please provide HEVY_API_KEY.");
-		const data = await hevyClient.getUserInfo();
+		const data = await requireClient(hevyClient).getUserInfo();
 		if (!data?.data) return createEmptyResponse("No user info found for the authenticated user");
 		return createJsonResponse(data.data);
 	}, "get-user-info"));
@@ -1004,9 +1178,9 @@ function registerWorkoutTools(server, hevyClient) {
 		pageSize: z.coerce.number().int().gte(1).lte(10).default(5)
 	};
 	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, readOnlyAnnotations("Get Workouts"), withErrorHandling(async (args) => {
-		if (!hevyClient) throw new Error("API client not initialized. Please provide HEVY_API_KEY.");
+		const client = requireClient(hevyClient);
 		const { page, pageSize } = args;
-		const workouts = (await hevyClient.getWorkouts({
+		const workouts = (await client.getWorkouts({
 			page,
 			pageSize
 		}))?.workouts?.map((workout) => formatWorkout(workout)) || [];
@@ -1015,15 +1189,14 @@ function registerWorkoutTools(server, hevyClient) {
 	}, "get-workouts"));
 	const getWorkoutSchema = { workoutId: z.string().min(1) };
 	server.tool("get-workout", "Get complete details of a specific workout by ID. Returns all workout information including title, description, start/end times, and detailed exercise data.", getWorkoutSchema, readOnlyAnnotations("Get Workout"), withErrorHandling(async (args) => {
-		if (!hevyClient) throw new Error("API client not initialized. Please provide HEVY_API_KEY.");
+		const client = requireClient(hevyClient);
 		const { workoutId } = args;
-		const data = await hevyClient.getWorkout(workoutId);
+		const data = await client.getWorkout(workoutId);
 		if (!data) return createEmptyResponse(`Workout with ID ${workoutId} not found`);
 		return createJsonResponse(formatWorkout(data));
 	}, "get-workout"));
 	server.tool("get-workout-count", "Get the total number of workouts on the account. Useful for pagination or statistics.", {}, readOnlyAnnotations("Get Workout Count"), withErrorHandling(async () => {
-		if (!hevyClient) throw new Error("API client not initialized. Please provide HEVY_API_KEY.");
-		return createJsonResponse({ count: (await hevyClient.getWorkoutCount())?.workout_count ?? 0 });
+		return createJsonResponse({ count: (await requireClient(hevyClient).getWorkoutCount())?.workout_count ?? 0 });
 	}, "get-workout-count"));
 	const getWorkoutEventsSchema = {
 		page: z.coerce.number().int().gte(1).default(1),
@@ -1031,9 +1204,9 @@ function registerWorkoutTools(server, hevyClient) {
 		since: z.string().default("1970-01-01T00:00:00Z")
 	};
 	server.tool("get-workout-events", "Retrieve a paged list of workout events (updates or deletes) since a given date. Events are ordered from newest to oldest. The intention is to allow clients to keep their local cache of workouts up to date without having to fetch the entire list of workouts.", getWorkoutEventsSchema, readOnlyAnnotations("Get Workout Events"), withErrorHandling(async (args) => {
-		if (!hevyClient) throw new Error("API client not initialized. Please provide HEVY_API_KEY.");
+		const client = requireClient(hevyClient);
 		const { page, pageSize, since } = args;
-		const events = (await hevyClient.getWorkoutEvents({
+		const events = (await client.getWorkoutEvents({
 			page,
 			pageSize,
 			since
@@ -1052,12 +1225,7 @@ function registerWorkoutTools(server, hevyClient) {
 			supersetId: z.coerce.number().nullable().optional(),
 			notes: z.string().optional().nullable(),
 			sets: z.array(z.object({
-				type: z.enum([
-					"warmup",
-					"normal",
-					"failure",
-					"dropset"
-				]).default("normal"),
+				type: setTypeEnum,
 				weight: z.coerce.number().optional().nullable(),
 				weightKg: z.coerce.number().optional().nullable(),
 				reps: z.coerce.number().int().optional().nullable(),
@@ -1071,7 +1239,7 @@ function registerWorkoutTools(server, hevyClient) {
 		})))
 	};
 	server.tool("create-workout", "Create a new workout in your Hevy account. Requires title, start/end times, and at least one exercise with sets. Returns the complete workout details upon successful creation including the newly assigned workout ID.", createWorkoutSchema, createAnnotations("Create Workout"), withErrorHandling(async (args) => {
-		if (!hevyClient) throw new Error("API client not initialized. Please provide HEVY_API_KEY.");
+		const client = requireClient(hevyClient);
 		const { title, description, startTime, endTime, isPrivate, exercises } = args;
 		const requestBody = { workout: {
 			title,
@@ -1094,7 +1262,7 @@ function registerWorkoutTools(server, hevyClient) {
 				}))
 			}))
 		} };
-		const data = await hevyClient.createWorkout(requestBody);
+		const data = await client.createWorkout(requestBody);
 		if (!data) return createEmptyResponse("Failed to create workout: Server returned no data");
 		return createJsonResponse(formatWorkout(data), {
 			pretty: true,
@@ -1113,12 +1281,7 @@ function registerWorkoutTools(server, hevyClient) {
 			supersetId: z.coerce.number().nullable().optional(),
 			notes: z.string().optional().nullable(),
 			sets: z.array(z.object({
-				type: z.enum([
-					"warmup",
-					"normal",
-					"failure",
-					"dropset"
-				]).default("normal"),
+				type: setTypeEnum,
 				weight: z.coerce.number().optional().nullable(),
 				weightKg: z.coerce.number().optional().nullable(),
 				reps: z.coerce.number().int().optional().nullable(),
@@ -1132,7 +1295,7 @@ function registerWorkoutTools(server, hevyClient) {
 		})))
 	};
 	server.tool("update-workout", "Update an existing workout by ID. You can modify the title, description, start/end times, privacy setting, and exercise data. Returns the updated workout with all changes applied.", updateWorkoutSchema, updateAnnotations("Update Workout"), withErrorHandling(async (args) => {
-		if (!hevyClient) throw new Error("API client not initialized. Please provide HEVY_API_KEY.");
+		const client = requireClient(hevyClient);
 		const { workoutId, title, description, startTime, endTime, isPrivate, exercises } = args;
 		const requestBody = { workout: {
 			title,
@@ -1155,7 +1318,7 @@ function registerWorkoutTools(server, hevyClient) {
 				}))
 			}))
 		} };
-		const data = await hevyClient.updateWorkout(workoutId, requestBody);
+		const data = await client.updateWorkout(workoutId, requestBody);
 		if (!data) return createEmptyResponse(`Failed to update workout with ID ${workoutId}`);
 		return createJsonResponse(formatWorkout(data), {
 			pretty: true,
@@ -1165,16 +1328,23 @@ function registerWorkoutTools(server, hevyClient) {
 }
 //#endregion
 //#region src/utils/config.ts
+const DEPRECATED_CLI_ARGUMENT_WARNING = [
+	"DEPRECATION WARNING: Passing the Hevy API key via CLI arguments",
+	"(--hevy-api-key=..., --hevyApiKey=..., hevy-api-key=...) is",
+	"deprecated and insecure. Use the HEVY_API_KEY environment",
+	"variable instead."
+].join(" ");
 /**
 * Parse CLI arguments and environment to derive configuration.
-* Priority order for API key: CLI flag forms > environment variable.
-* Supported CLI arg forms:
+* Priority order for API key: deprecated CLI flag forms > environment variable.
+* Supported deprecated CLI arg forms:
 *   --hevy-api-key=KEY
 *   --hevyApiKey=KEY
 *   hevy-api-key=KEY (bare, e.g. when passed after npm start -- )
 */
 function parseConfig(argv, env) {
 	let apiKey = "";
+	let usedDeprecatedApiKeyArg = false;
 	const apiKeyArgPatterns = [
 		/^--hevy-api-key=(.+)$/i,
 		/^--hevyApiKey=(.+)$/i,
@@ -1185,17 +1355,19 @@ function parseConfig(argv, env) {
 			const m = raw.match(pattern);
 			if (m) {
 				apiKey = m[1];
+				usedDeprecatedApiKeyArg = true;
 				break;
 			}
 		}
 		if (apiKey) break;
 	}
+	if (usedDeprecatedApiKeyArg) console.error(DEPRECATED_CLI_ARGUMENT_WARNING);
 	if (!apiKey) apiKey = env.HEVY_API_KEY || "";
 	return { apiKey };
 }
 function assertApiKey(apiKey) {
 	if (!apiKey) {
-		console.error("Hevy API key is required. Provide it via the HEVY_API_KEY environment variable or the --hevy-api-key=YOUR_KEY command argument.");
+		console.error("Hevy API key is required. Provide it via the HEVY_API_KEY environment variable.");
 		process.exit(1);
 	}
 }
@@ -1794,6 +1966,134 @@ async function putV1WorkoutsWorkoutid(workoutId, data, headers, config = {}) {
 function wrapApi(fn) {
 	return fn;
 }
+const DEFAULT_API_TIMEOUT_MS = 3e4;
+const RETRY_BACKOFF_MAX_MS = 5e3;
+const HEVY_RETRY_EXHAUSTED_ERROR_CODE = "HEVY_RETRY_EXHAUSTED";
+const RETRYABLE_STATUS_CODES = /* @__PURE__ */ new Set([
+	408,
+	429,
+	500,
+	502,
+	503,
+	504
+]);
+const RETRYABLE_NETWORK_ERROR_CODES = /* @__PURE__ */ new Set([
+	"ECONNABORTED",
+	"ECONNREFUSED",
+	"ECONNRESET",
+	"EAI_AGAIN",
+	"ENETUNREACH",
+	"ENOTFOUND",
+	"ERR_NETWORK",
+	"ERR_SOCKET_TIMEOUT",
+	"ETIMEDOUT"
+]);
+function getApiTimeoutMs() {
+	const rawValue = process.env.HEVY_MCP_API_TIMEOUT;
+	if (!rawValue) return DEFAULT_API_TIMEOUT_MS;
+	const parsed = Number(rawValue);
+	if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_API_TIMEOUT_MS;
+	return Math.trunc(parsed);
+}
+function sleep(ms) {
+	return new Promise((resolve) => {
+		setTimeout(resolve, ms);
+	});
+}
+function isGetRequest(config) {
+	return config.method?.toUpperCase() === "GET";
+}
+function isRetryableStatus(status) {
+	if (status === void 0) return false;
+	return RETRYABLE_STATUS_CODES.has(status);
+}
+function isTransientNetworkError(error) {
+	if (error.code === "ERR_CANCELED") return false;
+	if (error.code && RETRYABLE_NETWORK_ERROR_CODES.has(error.code)) return true;
+	if (error.response) return false;
+	const message = error.message.toLowerCase();
+	return message.includes("network") || message.includes("socket hang up") || message.includes("timeout");
+}
+function normalizeHeaderValue(value) {
+	if (typeof value === "string") {
+		const trimmed = value.trim();
+		return trimmed.length > 0 ? trimmed : void 0;
+	}
+	if (typeof value === "number" && Number.isFinite(value)) return String(value);
+	if (Array.isArray(value) && value.length > 0) return normalizeHeaderValue(value[0]);
+}
+function getHeaderValue(headers, key) {
+	if (!headers || typeof headers !== "object") return;
+	if ("get" in headers && typeof headers.get === "function") return normalizeHeaderValue(headers.get(key));
+	const headerRecord = headers;
+	return normalizeHeaderValue(headerRecord[key] ?? headerRecord[key.toLowerCase()] ?? headerRecord[key.toUpperCase()]);
+}
+function parseRetryAfterMs(value) {
+	const numericSeconds = Number(value);
+	if (Number.isFinite(numericSeconds) && numericSeconds >= 0) return Math.min(RETRY_BACKOFF_MAX_MS, Math.round(numericSeconds * 1e3));
+	const dateMillis = Date.parse(value);
+	if (Number.isNaN(dateMillis)) return;
+	return Math.min(RETRY_BACKOFF_MAX_MS, Math.max(0, dateMillis - Date.now()));
+}
+function getRetryAfterDelayMs(error) {
+	if (error.response?.status !== 429) return;
+	const retryAfterHeader = getHeaderValue(error.response.headers, "retry-after");
+	if (!retryAfterHeader) return;
+	return parseRetryAfterMs(retryAfterHeader);
+}
+function getExponentialBackoffMs(retryAttempt) {
+	const delay = 300 * 2 ** Math.max(0, retryAttempt - 1);
+	return Math.min(RETRY_BACKOFF_MAX_MS, delay);
+}
+function getRetryDelayMs(error, retryAttempt) {
+	const exponentialDelay = getExponentialBackoffMs(retryAttempt);
+	const retryAfterDelay = getRetryAfterDelayMs(error);
+	if (retryAfterDelay === void 0) return exponentialDelay;
+	return Math.min(RETRY_BACKOFF_MAX_MS, Math.max(exponentialDelay, retryAfterDelay));
+}
+function shouldRetryRequest(config, error) {
+	if (!isGetRequest(config)) return false;
+	return isRetryableStatus(error.response?.status) || isTransientNetworkError(error);
+}
+function markRetryExhausted(error, retryCount) {
+	const retryError = error;
+	retryError.hevyRetryExhausted = true;
+	retryError.hevyRetryCount = retryCount;
+	retryError.hevyRetryStatus = error.response?.status;
+	if (retryError.code) retryError.hevyRetryOriginalCode = retryError.code;
+	retryError.code = HEVY_RETRY_EXHAUSTED_ERROR_CODE;
+}
+async function requestWithRetries(axiosInstance, config) {
+	let retryCount = 0;
+	while (true) try {
+		return await axiosInstance.request(config);
+	} catch (error) {
+		if (!isAxiosError(error)) throw error;
+		if (!shouldRetryRequest(config, error)) throw error;
+		if (retryCount >= 3) {
+			markRetryExhausted(error, retryCount);
+			throw error;
+		}
+		retryCount += 1;
+		await sleep(getRetryDelayMs(error, retryCount));
+	}
+}
+function createResilientClient(axiosInstance) {
+	let clientConfig = { baseURL: axiosInstance.defaults.baseURL };
+	const resilientClient = (async (config) => {
+		return requestWithRetries(axiosInstance, config);
+	});
+	resilientClient.getConfig = () => ({ ...clientConfig });
+	resilientClient.setConfig = (config) => {
+		clientConfig = {
+			...clientConfig,
+			...config
+		};
+		if (config.baseURL !== void 0) axiosInstance.defaults.baseURL = config.baseURL;
+		return resilientClient.getConfig();
+	};
+	return resilientClient;
+}
 /**
 * Extract common request metadata from an Axios config.
 * Shared between the success and error response interceptors to avoid
@@ -1838,6 +2138,7 @@ function finalizeRequestTrace(opts) {
 function createClient$1(apiKey, baseUrl = "https://api.hevyapp.com") {
 	const axiosInstance = axios.create({
 		baseURL: baseUrl,
+		timeout: getApiTimeoutMs(),
 		headers: { "api-key": apiKey }
 	});
 	axiosInstance.interceptors.request.use((config) => {
@@ -1887,7 +2188,7 @@ function createClient$1(apiKey, baseUrl = "https://api.hevyapp.com") {
 		throw error;
 	});
 	const headers = { "api-key": apiKey };
-	const client = axiosInstance;
+	const client = createResilientClient(axiosInstance);
 	return {
 		getWorkouts: (params) => wrapApi(getV1Workouts)(headers, params, { client }),
 		getWorkout: (workoutId) => wrapApi(getV1WorkoutsWorkoutid)(workoutId, headers, { client }),
@@ -1921,6 +2222,44 @@ function createClient(apiKey, baseUrl) {
 //#endregion
 //#region src/utils/stdio-observability.ts
 const UTF8_BOM = "";
+/**
+* Adapter boundary around MCP SDK stdio internals.
+*
+* MCP SDK v1.29.0 exposes public message-level hooks but does not expose a
+* public raw-chunk hook on `StdioServerTransport`. To capture chunk metadata,
+* we currently rely on private internals (`_ondata`, `_readBuffer`, `_buffer`)
+* in this one place.
+*
+* If those internals change in a future SDK release, this adapter should fail
+* closed and preserve default transport behavior (no instrumentation patching).
+*/
+function createSdkPrivateStdioAdapter(transport) {
+	const mutableTransport = transport;
+	return {
+		wrapOnData(onChunk) {
+			const originalOnData = mutableTransport._ondata;
+			if (typeof originalOnData !== "function") return;
+			mutableTransport._ondata = (chunk) => {
+				onChunk(chunk);
+				originalOnData(chunk);
+			};
+		},
+		installReadMessageHook(onReadLine) {
+			const readBuffer = mutableTransport._readBuffer;
+			if (!readBuffer || typeof readBuffer.readMessage !== "function") return false;
+			readBuffer.readMessage = () => {
+				const buffer = readBuffer._buffer;
+				if (!buffer) return null;
+				const index = buffer.indexOf("\n");
+				if (index === -1) return null;
+				const lineBuffer = buffer.subarray(0, index);
+				readBuffer._buffer = buffer.subarray(index + 1);
+				return onReadLine(lineBuffer.toString("utf8").replace(/\r$/, ""));
+			};
+			return true;
+		}
+	};
+}
 function hasUtf8BomPrefix(chunk) {
 	return chunk.length >= 3 && chunk[0] === 239 && chunk[1] === 187 && chunk[2] === 191;
 }
@@ -1987,36 +2326,48 @@ function deserializeMessageWithObservability(line, chunkSnapshot) {
 	});
 }
 function createInstrumentedStdioTransport(transport) {
-	const mutableTransport = transport;
+	const privateAdapter = createSdkPrivateStdioAdapter(transport);
 	let lastChunkSnapshot = {
 		lastChunkByteLength: 0,
 		lastChunkStartsWithUtf8Bom: false
 	};
-	const originalOnData = mutableTransport._ondata;
-	if (typeof originalOnData === "function") mutableTransport._ondata = (chunk) => {
+	privateAdapter.wrapOnData((chunk) => {
 		lastChunkSnapshot = {
 			lastChunkByteLength: chunk.byteLength,
 			lastChunkStartsWithUtf8Bom: hasUtf8BomPrefix(chunk)
 		};
-		originalOnData(chunk);
-	};
-	const readBuffer = mutableTransport._readBuffer;
-	if (!readBuffer || typeof readBuffer.readMessage !== "function") return transport;
-	readBuffer.readMessage = () => {
-		const buffer = readBuffer._buffer;
-		if (!buffer) return null;
-		const index = buffer.indexOf("\n");
-		if (index === -1) return null;
-		const lineBuffer = buffer.subarray(0, index);
-		readBuffer._buffer = buffer.subarray(index + 1);
-		return deserializeMessageWithObservability(lineBuffer.toString("utf8").replace(/\r$/, ""), lastChunkSnapshot);
-	};
+	});
+	if (!privateAdapter.installReadMessageHook((line) => deserializeMessageWithObservability(line, lastChunkSnapshot))) return transport;
 	return transport;
 }
 //#endregion
 //#region src/index.ts
 const name = name$1;
 const version = version$1;
+const HELP_TEXT = [
+	"Usage:",
+	"  hevy-mcp [options]",
+	"",
+	"Options:",
+	"  -h, --help                 Show this help message and exit",
+	"  -v, --version              Show version and exit",
+	"  --hevy-api-key=<api-key>   (deprecated, use HEVY_API_KEY env var)",
+	"",
+	"Environment:",
+	"  HEVY_API_KEY=<api-key>     Hevy API key from Hevy app settings",
+	"",
+	"Examples:",
+	"  HEVY_API_KEY=your-key npx hevy-mcp",
+	"  npx hevy-mcp --hevy-api-key=your-key",
+	"  npm start -- --hevy-api-key=your-key"
+].join("\n");
+function getCliAction(args) {
+	for (const arg of args) {
+		if (arg === "--version" || arg === "-v") return "version";
+		if (arg === "--help" || arg === "-h") return "help";
+	}
+	return "start";
+}
 const HEVY_API_BASEURL = "https://api.hevyapp.com";
 const SENTRY_USER_ID_CONTEXT = "hevy-mcp:sentry-user-id:v1";
 function fingerprintApiKey(apiKey) {
@@ -2075,10 +2426,20 @@ function createServer({ config }) {
 	return buildServer(apiKey);
 }
 async function runServer() {
+	const args = process.argv.slice(2);
+	const cliAction = getCliAction(args);
+	if (cliAction === "version") {
+		console.log(version);
+		return;
+	}
+	if (cliAction === "help") {
+		console.log(HELP_TEXT);
+		return;
+	}
 	serverStartups.add(1, { version });
 	await tracer.startActiveSpan("mcp.server.run", { attributes: { "mcp.transport": "stdio" } }, async (span) => {
 		try {
-			const apiKey = parseConfig(process.argv.slice(2), process.env).apiKey;
+			const apiKey = parseConfig(args, process.env).apiKey;
 			assertApiKey(apiKey);
 			const server = buildServer(apiKey);
 			console.error("Starting MCP server in stdio mode");
@@ -2106,4 +2467,4 @@ async function runServer() {
 //#endregion
 export { createServer as n, runServer as r, configSchema as t };
 
-//# sourceMappingURL=src-Di7keTQA.mjs.map
+//# sourceMappingURL=src-CuOZcBEo.mjs.map