hevy-mcp 1.28.0 → 2.0.0

package/dist/{src-J8OsyJcw.mjs → src-c3mB-R0m.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.28.0" };
+		e.SENTRY_RELEASE = { id: "hevy-mcp@2.0.0" };
 		var n = new e.Error().stack;
-		n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "13440721-a791-4fcc-9147-27a915a2863d", e._sentryDebugIdIdentifier = "sentry-dbid-13440721-a791-4fcc-9147-27a915a2863d");
+		n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "17d5086b-9850-447d-9372-27bb2ce5dcc5", e._sentryDebugIdIdentifier = "sentry-dbid-17d5086b-9850-447d-9372-27bb2ce5dcc5");
 	} catch (e) {}
 })();
 import * as Sentry from "@sentry/node";
@@ -18,13 +18,17 @@ import { resourceFromAttributes } from "@opentelemetry/resources";
 import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
 import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
 import { MeterProvider, PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
-import { createHmac } from "node:crypto";
+import { createHmac, randomUUID } from "node:crypto";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import axios, { isAxiosError } from "axios";
 import { z as z$1 } from "zod/v4";
 import { deserializeMessage } from "@modelcontextprotocol/sdk/shared/stdio.js";
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import semver from "semver";
 //#region src/utils/telemetry.ts
 /**
 * Centralized telemetry initialization.
@@ -37,10 +41,10 @@ import { deserializeMessage } from "@modelcontextprotocol/sdk/shared/stdio.js";
 * OTel Collector → Honeycomb: performance traces, metrics
 */
 const name$1 = "hevy-mcp";
-const version$1 = "1.28.0";
+const version$1 = "2.0.0";
 const collectorToken = "NH9vOela-HYreQxAbJa68cjEmORoEKM57EvneUDVcOo";
 const COLLECTOR_ENDPOINT = "https://otel.chrisdoc.dev/v1";
-const sentryRelease = process.env.SENTRY_RELEASE ?? `hevy-mcp@1.28.0`;
+const sentryRelease = process.env.SENTRY_RELEASE ?? `hevy-mcp@2.0.0`;
 const resource = resourceFromAttributes({
 	"service.name": name$1,
 	"service.version": version$1
@@ -693,6 +697,93 @@ function withErrorHandling(fn, context) {
 	};
 }
 //#endregion
+//#region src/utils/debug.ts
+const DEBUG_PREFIX = "[hevy-mcp:debug] ";
+const MAX_DEBUG_RECORD_LENGTH = 8192;
+const MAX_REDACTION_DEPTH = 4;
+const MAX_OBJECT_KEYS = 20;
+function isDebugEnabled(env = process.env) {
+	return env.HEVY_MCP_DEBUG === "1";
+}
+function redactValue(value, depth, seen) {
+	if (value === null) return "[null]";
+	if (typeof value !== "object") return `[${typeof value}]`;
+	if (seen.has(value)) return "[circular]";
+	if (Array.isArray(value)) {
+		const lengthDescriptor = Object.getOwnPropertyDescriptor(value, "length");
+		const length = lengthDescriptor && "value" in lengthDescriptor && typeof lengthDescriptor.value === "number" ? lengthDescriptor.value : 0;
+		if (depth >= MAX_REDACTION_DEPTH) return {
+			type: "array",
+			length,
+			items: "[max-depth]"
+		};
+		seen.add(value);
+		try {
+			const itemCount = Math.min(length, MAX_OBJECT_KEYS);
+			const items = {};
+			for (let index = 0; index < itemCount; index += 1) {
+				const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+				items[`item-${index + 1}`] = descriptor && "value" in descriptor ? redactValue(descriptor.value, depth + 1, seen) : "[empty-or-accessor]";
+			}
+			return {
+				type: "array",
+				length,
+				items,
+				...length > MAX_OBJECT_KEYS ? { truncatedItems: length - MAX_OBJECT_KEYS } : {}
+			};
+		} finally {
+			seen.delete(value);
+		}
+	}
+	const keys = Object.keys(value);
+	if (depth >= MAX_REDACTION_DEPTH) return {
+		type: "object",
+		fieldCount: keys.length,
+		fields: "[max-depth]"
+	};
+	seen.add(value);
+	try {
+		const fields = {};
+		for (const [index, rawKey] of keys.slice(0, MAX_OBJECT_KEYS).entries()) {
+			const descriptor = Object.getOwnPropertyDescriptor(value, rawKey);
+			fields[`field-${index + 1}`] = descriptor && "value" in descriptor ? redactValue(descriptor.value, depth + 1, seen) : "[accessor]";
+		}
+		return {
+			type: "object",
+			fieldCount: keys.length,
+			fields,
+			...keys.length > MAX_OBJECT_KEYS ? { truncatedFields: keys.length - MAX_OBJECT_KEYS } : {}
+		};
+	} finally {
+		seen.delete(value);
+	}
+}
+/** Redact every input scalar while preserving bounded argument structure. */
+function redactToolArgs(args) {
+	try {
+		return redactValue(args, 0, /* @__PURE__ */ new WeakSet());
+	} catch {
+		return "[unavailable]";
+	}
+}
+/**
+* Write a single bounded structured debug record to stderr without throwing.
+*/
+function debugLog(event, data) {
+	if (!isDebugEnabled()) return;
+	try {
+		const record = JSON.stringify({
+			event,
+			...data
+		});
+		const output = record.length <= MAX_DEBUG_RECORD_LENGTH ? record : JSON.stringify({
+			event,
+			truncated: true
+		});
+		process.stderr.write(`${DEBUG_PREFIX}${output}\n`);
+	} catch {}
+}
+//#endregion
 //#region src/utils/telemetry-wrapper.ts
 /** Whitelist of safe argument keys that can be logged without exposing PII. */
 const ARGUMENT_WHITELIST = /* @__PURE__ */ new Set([
@@ -729,6 +820,10 @@ function extractSafeArgs(args) {
 function withTelemetry(fn, context) {
 	return async (rawArgs) => {
 		const args = rawArgs ?? {};
+		if (isDebugEnabled()) debugLog("tool_invocation", {
+			tool: context,
+			params: redactToolArgs(args)
+		});
 		const argumentKeyCount = Object.keys(args).length;
 		const startTime = Date.now();
 		let isError = false;
@@ -786,62 +881,6 @@ function withObservability(fn, context) {
 	return withErrorHandling(withTelemetry(fn, context), context);
 }
 //#endregion
-//#region src/generated/client/schemas/deletedWorkoutSchema.ts
-/**
-* Generated by Kubb (https://kubb.dev/).
-* Do not edit manually.
-*/
-const deletedWorkoutSchema = z$1.object({
-	type: z$1.string().describe("Indicates the type of the event (deleted)"),
-	id: z$1.string().describe("The unique identifier of the deleted workout"),
-	deleted_at: z$1.optional(z$1.string().describe("A date string indicating when the workout was deleted"))
-});
-//#endregion
-//#region src/generated/client/schemas/workoutSchema.ts
-/**
-* Generated by Kubb (https://kubb.dev/).
-* Do not edit manually.
-*/
-const workoutSchema = z$1.object({
-	id: z$1.optional(z$1.string().describe("The workout ID.")),
-	title: z$1.optional(z$1.string().describe("The workout title.")),
-	routine_id: z$1.optional(z$1.string().describe("The ID of the routine that this workout belongs to.")),
-	description: z$1.optional(z$1.string().describe("The workout description.")),
-	start_time: z$1.optional(z$1.string().describe("ISO 8601 timestamp of when the workout was recorded to have started.")),
-	end_time: z$1.optional(z$1.string().describe("ISO 8601 timestamp of when the workout was recorded to have ended.")),
-	updated_at: z$1.optional(z$1.string().describe("ISO 8601 timestamp of when the workout was last updated.")),
-	created_at: z$1.optional(z$1.string().describe("ISO 8601 timestamp of when the workout was created.")),
-	exercises: z$1.optional(z$1.array(z$1.object({
-		index: z$1.optional(z$1.number().describe("Index indicating the order of the exercise in the workout.")),
-		title: z$1.optional(z$1.string().describe("Title of the exercise")),
-		notes: z$1.optional(z$1.string().describe("Notes on the exercise")),
-		exercise_template_id: z$1.optional(z$1.string().describe("The id of the exercise template. This can be used to fetch the exercise template.")),
-		supersets_id: z$1.number().describe("The id of the superset that the exercise belongs to. A value of null indicates the exercise is not part of a superset.").nullish(),
-		sets: z$1.optional(z$1.array(z$1.object({
-			index: z$1.optional(z$1.number().describe("Index indicating the order of the set in the workout.")),
-			type: z$1.optional(z$1.string().describe("The type of set. This can be one of 'normal', 'warmup', 'dropset', 'failure'")),
-			weight_kg: z$1.number().describe("Weight lifted in kilograms.").nullish(),
-			reps: z$1.number().describe("Number of reps logged for the set").nullish(),
-			distance_meters: z$1.number().describe("Number of meters logged for the set").nullish(),
-			duration_seconds: z$1.number().describe("Number of seconds logged for the set").nullish(),
-			rpe: z$1.number().describe("RPE (Relative perceived exertion) value logged for the set").nullish(),
-			custom_metric: z$1.number().describe("Custom metric logged for the set (Currently only used to log floors or steps for stair machine exercises)").nullish()
-		})))
-	})))
-});
-//#endregion
-//#region src/generated/client/schemas/updatedWorkoutSchema.ts
-/**
-* Generated by Kubb (https://kubb.dev/).
-* Do not edit manually.
-*/
-const updatedWorkoutSchema = z$1.object({
-	type: z$1.string().describe("Indicates the type of the event (updated)"),
-	get workout() {
-		return workoutSchema;
-	}
-});
-//#endregion
 //#region src/generated/client/schemas/userInfoSchema.ts
 /**
 * Generated by Kubb (https://kubb.dev/).
@@ -966,7 +1005,16 @@ const formattedBodyMeasurementSchema = z.object({
 const workoutsOutputSchema = { workouts: z.array(formattedWorkoutSchema) };
 const workoutOutputSchema = { workout: formattedWorkoutSchema.nullable() };
 const workoutCountOutputSchema = { count: z.number().int() };
-const workoutEventsOutputSchema = { events: z.array(z.union([updatedWorkoutSchema, deletedWorkoutSchema])) };
+const formattedUpdatedWorkoutSchema = z.object({
+	type: z.literal("updated"),
+	workout: formattedWorkoutSchema
+});
+const formattedDeletedWorkoutSchema = z.object({
+	type: z.literal("deleted"),
+	id: z.string(),
+	deletedAt: z.string().optional()
+});
+const workoutEventsOutputSchema = { events: z.array(z.union([formattedUpdatedWorkoutSchema, formattedDeletedWorkoutSchema])) };
 const routinesOutputSchema = { routines: z.array(formattedRoutineSchema) };
 const routineOutputSchema = { routine: formattedRoutineSchema.nullable() };
 const exerciseTemplatesOutputSchema = { exerciseTemplates: z.array(formattedExerciseTemplateSchema) };
@@ -1074,6 +1122,16 @@ function updateAnnotations(title) {
 	};
 }
 //#endregion
+//#region src/utils/tool-descriptions.ts
+function describeTool({ summary, aliases, useCase, importantNotes }) {
+	return [
+		summary,
+		`Aliases: ${aliases.join(", ")}.`,
+		`<use_case>${useCase}</use_case>`,
+		`<important_notes>${importantNotes}</important_notes>`
+	].join(" ");
+}
+//#endregion
 //#region src/utils/schemas.ts
 function coerceNullishNumberInput(value) {
 	if (value === null || value === void 0) return value;
@@ -1196,7 +1254,16 @@ function registerBodyMeasurementTools(server, hevyClient) {
 		pageSize: z.coerce.number().int().gte(1).lte(10).default(10)
 	};
 	server.registerTool("get-body-measurements", {
-		description: "Get a paginated list of body measurements for the authenticated user. Returns measurements including weight, body fat, and various circumference measurements.",
+		description: describeTool({
+			summary: "Read-only. Lists dated body measurements for the account.",
+			aliases: [
+				"body stats history",
+				"list weigh-ins",
+				"measurement log"
+			],
+			useCase: "Use to browse measurement history; use get-body-measurement for one exact date.",
+			importantNotes: "Results are paginated; page starts at 1 and pageSize is limited to 10."
+		}),
 		inputSchema: getBodyMeasurementsSchema,
 		outputSchema: bodyMeasurementsOutputSchema,
 		annotations: readOnlyAnnotations("Get Body Measurements")
@@ -1212,7 +1279,16 @@ 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.registerTool("get-body-measurement", {
-		description: "Get a single body measurement by date. Returns all measurement fields for the specified date.",
+		description: describeTool({
+			summary: "Read-only. Retrieves the body measurement entry for one date.",
+			aliases: [
+				"get weigh-in",
+				"show body stats",
+				"measurement by date"
+			],
+			useCase: "Use when the exact measurement date is known; use get-body-measurements to browse dates.",
+			importantNotes: "date must use YYYY-MM-DD; at most one entry exists per date."
+		}),
 		inputSchema: getBodyMeasurementSchema,
 		outputSchema: bodyMeasurementOutputSchema,
 		annotations: readOnlyAnnotations("Get Body Measurement")
@@ -1228,7 +1304,16 @@ function registerBodyMeasurementTools(server, hevyClient) {
 		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). Must be unique — returns 409 if an entry already exists for this date."),
 		...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"), withObservability(async (args) => {
+	server.tool("create-body-measurement", describeTool({
+		summary: "Writes to the Hevy account by creating a dated body measurement.",
+		aliases: [
+			"log weigh-in",
+			"add body stats",
+			"record measurements"
+		],
+		useCase: "Use for a date without an entry; use update-body-measurement when that date already exists.",
+		importantNotes: "date must use YYYY-MM-DD and be unique. Null fields are omitted and cannot clear values; an existing date returns 409."
+	}), createBodyMeasurementSchema, createAnnotations("Create Body Measurement"), withObservability(async (args) => {
 		const client = requireClient(hevyClient);
 		const { date, ...fields } = args;
 		await client.createBodyMeasurement({
@@ -1241,7 +1326,16 @@ function registerBodyMeasurementTools(server, hevyClient) {
 		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 to update (YYYY-MM-DD). Must already exist — returns 404 otherwise."),
 		...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"), withObservability(async (args) => {
+	server.tool("update-body-measurement", describeTool({
+		summary: "Mutates the Hevy account by updating a body measurement for a date.",
+		aliases: [
+			"edit weigh-in",
+			"correct body stats",
+			"change measurements"
+		],
+		useCase: "Use to change fields on an existing date; use create-body-measurement for a new date.",
+		importantNotes: "date must use YYYY-MM-DD and already exist. Provide at least one numeric field; nulls are omitted and cannot clear stored values."
+	}), updateBodyMeasurementSchema, updateAnnotations("Update Body Measurement"), withObservability(async (args) => {
 		const client = requireClient(hevyClient);
 		const { date, ...fields } = args;
 		const payload = buildMeasurementPayload(fields);
@@ -1261,7 +1355,16 @@ function registerFolderTools(server, hevyClient) {
 		pageSize: z.coerce.number().int().gte(1).lte(10).default(5)
 	};
 	server.registerTool("get-routine-folders", {
-		description: "Get a paginated list of your routine folders, including both default and custom folders. Useful for organizing and browsing your workout routines.",
+		description: describeTool({
+			summary: "Read-only. Lists default and custom routine folders.",
+			aliases: [
+				"list folders",
+				"browse routine groups",
+				"show plan folders"
+			],
+			useCase: "Use to browse folder organization or discover folder IDs for routine creation.",
+			importantNotes: "Results are paginated; page starts at 1 and pageSize is limited to 10."
+		}),
 		inputSchema: getRoutineFoldersSchema,
 		outputSchema: routineFoldersOutputSchema,
 		annotations: readOnlyAnnotations("Get Routine Folders")
@@ -1277,7 +1380,16 @@ function registerFolderTools(server, hevyClient) {
 	}, "get-routine-folders"));
 	const getRoutineFolderSchema = { folderId: z.string().min(1) };
 	server.registerTool("get-routine-folder", {
-		description: "Get complete details of a specific routine folder by its ID, including name, creation date, and associated routines.",
+		description: describeTool({
+			summary: "Read-only. Retrieves one routine folder's metadata by ID.",
+			aliases: [
+				"show folder",
+				"folder details",
+				"routine folder metadata"
+			],
+			useCase: "Use for one known folder; use get-routine-folders to browse or discover folder IDs.",
+			importantNotes: "Requires a folderId from get-routine-folders or a prior create response."
+		}),
 		inputSchema: getRoutineFolderSchema,
 		outputSchema: routineFolderOutputSchema,
 		annotations: readOnlyAnnotations("Get Routine Folder")
@@ -1290,7 +1402,16 @@ function registerFolderTools(server, hevyClient) {
 		return createStructuredJsonResponse(folder, { routineFolder: folder });
 	}, "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"), withObservability(async (args) => {
+	server.tool("create-routine-folder", describeTool({
+		summary: "Writes to the Hevy account by creating a new routine folder.",
+		aliases: [
+			"add folder",
+			"organize routines",
+			"create plan group"
+		],
+		useCase: "Use to create an organizational destination before assigning new routines to a folderId.",
+		importantNotes: "Requires a non-empty name. Retrying or reusing a name can create duplicate folders."
+	}), createRoutineFolderSchema, createAnnotations("Create Routine Folder"), withObservability(async (args) => {
 		const client = requireClient(hevyClient);
 		const { name } = args;
 		const data = await client.createRoutineFolder({ routine_folder: { title: name } });
@@ -1355,7 +1476,16 @@ function registerRoutineTools(server, hevyClient) {
 		pageSize: z.coerce.number().int().gte(1).lte(10).default(5)
 	};
 	server.registerTool("get-routines", {
-		description: "Get a paginated list of your workout routines, including custom and default routines. Useful for browsing or searching your available routines.",
+		description: describeTool({
+			summary: "Read-only. Lists custom and default workout routines.",
+			aliases: [
+				"list routines",
+				"show workout plans",
+				"browse saved routines"
+			],
+			useCase: "Use to browse routines or discover a routine ID; use get-routine for one known routine.",
+			importantNotes: "Results are paginated; page starts at 1 and pageSize is limited to 10."
+		}),
 		inputSchema: getRoutinesSchema,
 		outputSchema: routinesOutputSchema,
 		annotations: readOnlyAnnotations("Get Routines")
@@ -1371,7 +1501,16 @@ function registerRoutineTools(server, hevyClient) {
 	}, "get-routines"));
 	const getRoutineSchema = { routineId: z.string().min(1) };
 	server.registerTool("get-routine", {
-		description: "Get a routine by its ID using the direct endpoint. Returns all details for the specified routine.",
+		description: describeTool({
+			summary: "Read-only. Retrieves one routine and its exercise configuration by ID.",
+			aliases: [
+				"show routine",
+				"fetch workout plan",
+				"routine details"
+			],
+			useCase: "Use when the routineId is known; use get-routines to browse or discover IDs.",
+			importantNotes: "Requires a routineId from get-routines or a prior create response."
+		}),
 		inputSchema: getRoutineSchema,
 		outputSchema: routineOutputSchema,
 		annotations: readOnlyAnnotations("Get Routine")
@@ -1406,7 +1545,16 @@ 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"), withObservability(async (args) => {
+	server.tool("create-routine", describeTool({
+		summary: "Writes to the Hevy account by creating a new workout routine.",
+		aliases: [
+			"add routine",
+			"build workout plan",
+			"save training template"
+		],
+		useCase: "Use to create a reusable plan; use create-workout to log a completed session.",
+		importantNotes: "Requires exercise template IDs; folderId is optional. Retrying can create duplicates, and non-fixed rep ranges may not display in Hevy apps."
+	}), createRoutineSchema, createAnnotations("Create Routine"), withObservability(async (args) => {
 		const client = requireClient(hevyClient);
 		const { title, folderId, notes, exercises } = args;
 		let usesRepRanges = false;
@@ -1473,7 +1621,16 @@ 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"), withObservability(async (args) => {
+	server.tool("update-routine", describeTool({
+		summary: "Mutates the Hevy account by replacing an existing routine's content.",
+		aliases: [
+			"edit routine",
+			"revise workout plan",
+			"replace routine exercises"
+		],
+		useCase: "Use to change a known routine; use create-routine for a separate new plan.",
+		importantNotes: "Requires routineId and the complete title and exercises payload; omitted exercises are removed. Non-fixed rep ranges may not display in Hevy apps."
+	}), updateRoutineSchema, updateAnnotations("Update Routine"), withObservability(async (args) => {
 		const client = requireClient(hevyClient);
 		const { routineId, title, notes, exercises } = args;
 		let usesRepRanges = false;
@@ -1529,7 +1686,16 @@ function registerTemplateTools(server, hevyClient, options = {}) {
 		pageSize: z.coerce.number().int().gte(1).lte(100).default(5)
 	};
 	server.registerTool("get-exercise-templates", {
-		description: "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.",
+		description: describeTool({
+			summary: "Read-only. Lists default and custom exercise templates with equipment and muscle metadata.",
+			aliases: [
+				"browse exercises",
+				"list exercise catalog",
+				"show movements"
+			],
+			useCase: "Use for page-by-page catalog browsing; use search-exercise-templates for a name lookup across the full catalog.",
+			importantNotes: "Results are paginated; page starts at 1 and pageSize is limited to 100."
+		}),
 		inputSchema: getExerciseTemplatesSchema,
 		outputSchema: exerciseTemplatesOutputSchema,
 		annotations: readOnlyAnnotations("Get Exercise Templates")
@@ -1545,7 +1711,16 @@ function registerTemplateTools(server, hevyClient, options = {}) {
 	}, "get-exercise-templates"));
 	const getExerciseTemplateSchema = { exerciseTemplateId: z.string().min(1) };
 	server.registerTool("get-exercise-template", {
-		description: "Get complete details of a specific exercise template by its ID, including name, category, equipment, muscle groups, and notes.",
+		description: describeTool({
+			summary: "Read-only. Retrieves complete metadata for one exercise template by ID.",
+			aliases: [
+				"show exercise details",
+				"fetch movement",
+				"exercise template info"
+			],
+			useCase: "Use after locating an exact template; use search-exercise-templates when only a name is known.",
+			importantNotes: "Requires an exerciseTemplateId from a template list, search, routine, or workout."
+		}),
 		inputSchema: getExerciseTemplateSchema,
 		outputSchema: exerciseTemplateOutputSchema,
 		annotations: readOnlyAnnotations("Get Exercise Template")
@@ -1563,7 +1738,16 @@ function registerTemplateTools(server, hevyClient, options = {}) {
 		endDate: z.string().datetime({ offset: true }).describe("ISO 8601 end date for filtering history").optional()
 	};
 	server.registerTool("get-exercise-history", {
-		description: "Get past sets for a specific exercise template, optionally filtered by start and end dates.",
+		description: describeTool({
+			summary: "Read-only. Retrieves past performed sets for one exercise template.",
+			aliases: [
+				"exercise progress",
+				"past sets",
+				"movement history"
+			],
+			useCase: "Use to analyze performance for one movement; use get-workouts for complete sessions.",
+			importantNotes: "Requires an exerciseTemplateId. Optional startDate and endDate must be ISO 8601 datetimes with an offset."
+		}),
 		inputSchema: getExerciseHistorySchema,
 		outputSchema: exerciseHistoryOutputSchema,
 		annotations: readOnlyAnnotations("Get Exercise History")
@@ -1584,7 +1768,16 @@ function registerTemplateTools(server, hevyClient, options = {}) {
 		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"), withObservability(async (args) => {
+	server.tool("create-exercise-template", describeTool({
+		summary: "Writes to the Hevy account by creating a custom exercise template.",
+		aliases: [
+			"add custom exercise",
+			"create movement",
+			"define exercise"
+		],
+		useCase: "Use only when the needed movement is absent; search-exercise-templates should check existing templates first.",
+		importantNotes: "Requires title, exercise type, equipment category, and primary muscle group. Retrying or reusing a title can create duplicates."
+	}), createExerciseTemplateSchema, createAnnotations("Create Exercise Template"), withObservability(async (args) => {
 		const client = requireClient(hevyClient);
 		const { title, exerciseType, equipmentCategory, muscleGroup, otherMuscles } = args;
 		return createJsonResponse({
@@ -1604,7 +1797,16 @@ function registerTemplateTools(server, hevyClient, options = {}) {
 		refresh: z.boolean().optional().default(false).describe("Set to true to invalidate the catalog cache and re-fetch all templates from the API")
 	};
 	server.registerTool("search-exercise-templates", {
-		description: "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.",
+		description: describeTool({
+			summary: "Read-only for the Hevy account. Searches the full exercise template catalog by title substring.",
+			aliases: [
+				"find exercise",
+				"look up movement",
+				"search exercise IDs"
+			],
+			useCase: "Use when a name or partial name is known, especially to discover IDs for workouts and routines; use get-exercise-templates for page browsing.",
+			importantNotes: "Matching is case-insensitive. The catalog is cached locally for 5 minutes; refresh:true re-fetches all pages and changes only local cache state."
+		}),
 		inputSchema: searchExerciseTemplatesSchema,
 		outputSchema: exerciseTemplatesOutputSchema,
 		annotations: readOnlyAnnotations("Search Exercise Templates")
@@ -1641,7 +1843,16 @@ function registerTemplateTools(server, hevyClient, options = {}) {
 //#region src/tools/user.ts
 function registerUserTools(server, hevyClient) {
 	server.registerTool("get-user-info", {
-		description: "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.",
+		description: describeTool({
+			summary: "Read-only. Returns the authenticated account's user ID, display name, and public profile URL.",
+			aliases: [
+				"who am I",
+				"account info",
+				"verify Hevy user"
+			],
+			useCase: "Use to confirm which Hevy account is connected before reading or writing account data.",
+			importantNotes: "Accepts no inputs and reports only the account associated with the configured credentials."
+		}),
 		inputSchema: {},
 		outputSchema: userOutputSchema,
 		annotations: readOnlyAnnotations("Get User Info")
@@ -1653,6 +1864,18 @@ function registerUserTools(server, hevyClient) {
 }
 //#endregion
 //#region src/tools/workouts.ts
+function formatWorkoutEvent(event) {
+	if (event.type === "updated" && "workout" in event) return {
+		type: "updated",
+		workout: formatWorkout(event.workout)
+	};
+	if (event.type === "deleted" && "id" in event) return {
+		type: "deleted",
+		id: event.id,
+		deletedAt: event.deleted_at
+	};
+	throw new Error(`Unsupported workout event type: ${event.type}`);
+}
 /**
 * Register all workout-related tools with the MCP server
 */
@@ -1662,7 +1885,16 @@ function registerWorkoutTools(server, hevyClient) {
 		pageSize: z.coerce.number().int().gte(1).lte(10).default(5)
 	};
 	server.registerTool("get-workouts", {
-		description: "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.",
+		description: describeTool({
+			summary: "Read-only. Lists workouts from newest to oldest with exercise and timing details.",
+			aliases: [
+				"list workout history",
+				"show recent workouts",
+				"browse logs"
+			],
+			useCase: "Use to browse or page through workout history; use get-workout when a workout ID is already known.",
+			importantNotes: "Results are paginated; page starts at 1 and pageSize is limited to 10."
+		}),
 		inputSchema: getWorkoutsSchema,
 		outputSchema: workoutsOutputSchema,
 		annotations: readOnlyAnnotations("Get Workouts")
@@ -1678,7 +1910,16 @@ function registerWorkoutTools(server, hevyClient) {
 	}, "get-workouts"));
 	const getWorkoutSchema = { workoutId: z.string().min(1) };
 	server.registerTool("get-workout", {
-		description: "Get complete details of a specific workout by ID. Returns all workout information including title, description, start/end times, and detailed exercise data.",
+		description: describeTool({
+			summary: "Read-only. Retrieves complete details for one workout by its ID.",
+			aliases: [
+				"show workout",
+				"fetch workout details",
+				"open workout log"
+			],
+			useCase: "Use after get-workouts identifies the exact workout; do not use for browsing multiple workouts.",
+			importantNotes: "Requires a workoutId discovered from a workout list, event, or prior create response."
+		}),
 		inputSchema: getWorkoutSchema,
 		outputSchema: workoutOutputSchema,
 		annotations: readOnlyAnnotations("Get Workout")
@@ -1691,7 +1932,16 @@ function registerWorkoutTools(server, hevyClient) {
 		return createStructuredJsonResponse(workout, { workout });
 	}, "get-workout"));
 	server.registerTool("get-workout-count", {
-		description: "Get the total number of workouts on the account. Useful for pagination or statistics.",
+		description: describeTool({
+			summary: "Read-only. Returns the total workout count for the account.",
+			aliases: [
+				"count workouts",
+				"how many workouts",
+				"workout total"
+			],
+			useCase: "Use for totals, statistics, or estimating pages; use get-workouts for actual workout records.",
+			importantNotes: "Returns only a count and accepts no paging or date filters."
+		}),
 		inputSchema: {},
 		outputSchema: workoutCountOutputSchema,
 		annotations: readOnlyAnnotations("Get Workout Count")
@@ -1705,7 +1955,16 @@ function registerWorkoutTools(server, hevyClient) {
 		since: z.string().default("1970-01-01T00:00:00Z")
 	};
 	server.registerTool("get-workout-events", {
-		description: "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.",
+		description: describeTool({
+			summary: "Read-only. Lists workout update and delete events since a timestamp, newest first.",
+			aliases: [
+				"sync workout changes",
+				"workout change feed",
+				"deleted workouts"
+			],
+			useCase: "Use to incrementally synchronize a local workout cache; use get-workouts for the current workout list.",
+			importantNotes: "since must be a timestamp string; events are paginated with pageSize at most 10, and the default since value reads from 1970."
+		}),
 		inputSchema: getWorkoutEventsSchema,
 		outputSchema: workoutEventsOutputSchema,
 		annotations: readOnlyAnnotations("Get Workout Events")
@@ -1716,7 +1975,7 @@ function registerWorkoutTools(server, hevyClient) {
 			page,
 			pageSize,
 			since
-		}))?.events || [];
+		}))?.events?.map(formatWorkoutEvent) || [];
 		if (events.length === 0) return createStructuredEmptyResponse(`No workout events found for the specified parameters since ${since}`, { events: [] });
 		return createStructuredJsonResponse(events, { events });
 	}, "get-workout-events"));
@@ -1744,7 +2003,16 @@ 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"), withObservability(async (args) => {
+	server.tool("create-workout", describeTool({
+		summary: "Writes to the Hevy account by creating a new workout.",
+		aliases: [
+			"log workout",
+			"add workout",
+			"record training session"
+		],
+		useCase: "Use to add a completed workout; use update-workout only when modifying an existing workout ID.",
+		importantNotes: "Requires UTC startTime/endTime in YYYY-MM-DDTHH:mm:ssZ form and exercise template IDs. Retrying can create duplicates."
+	}), createWorkoutSchema, createAnnotations("Create Workout"), withObservability(async (args) => {
 		const client = requireClient(hevyClient);
 		const { title, description, startTime, endTime, isPrivate, exercises } = args;
 		const requestBody = { workout: {
@@ -1800,7 +2068,16 @@ 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"), withObservability(async (args) => {
+	server.tool("update-workout", describeTool({
+		summary: "Mutates the Hevy account by replacing an existing workout.",
+		aliases: [
+			"edit workout",
+			"correct workout log",
+			"replace workout details"
+		],
+		useCase: "Use to revise a known workout; use create-workout for a new training session.",
+		importantNotes: "Requires workoutId plus the complete title, times, privacy, exercises, and sets payload; omitted optional values may be cleared or defaulted."
+	}), updateWorkoutSchema, updateAnnotations("Update Workout"), withObservability(async (args) => {
 		const client = requireClient(hevyClient);
 		const { workoutId, title, description, startTime, endTime, isPrivate, exercises } = args;
 		const requestBody = { workout: {
@@ -1878,6 +2155,81 @@ function assertApiKey(apiKey) {
 	}
 }
 //#endregion
+//#region src/utils/graceful-shutdown.ts
+const shutdownSignals = ["SIGINT", "SIGTERM"];
+const FORCED_EXIT_TIMEOUT_MS = 5e3;
+function flushStdout(stdout = process.stdout) {
+	return new Promise((resolve, reject) => {
+		try {
+			stdout.write("", (error) => {
+				if (error) {
+					reject(error);
+					return;
+				}
+				resolve();
+			});
+		} catch (error) {
+			reject(error);
+		}
+	});
+}
+function installGracefulShutdown({ target, process: processLike = process, logError = console.error, flush = flushStdout, forcedExitTimeoutMs = FORCED_EXIT_TIMEOUT_MS, scheduleForcedExit = setTimeout }) {
+	let listenersInstalled = true;
+	let shutdownSettled = false;
+	let shutdownPromise;
+	const cleanup = () => {
+		if (!listenersInstalled || shutdownPromise && !shutdownSettled) return;
+		listenersInstalled = false;
+		for (const signal of shutdownSignals) {
+			const listener = signalListeners.get(signal);
+			if (listener) processLike.removeListener(signal, listener);
+		}
+	};
+	const handleSignal = (signal) => {
+		if (shutdownPromise) return;
+		if (processLike.exitCode == null) processLike.exitCode = 0;
+		scheduleForcedExit(() => {
+			processLike.exit(processLike.exitCode ?? 0);
+		}, forcedExitTimeoutMs).unref();
+		shutdownPromise = (async () => {
+			logError(`Shutting down gracefully after ${signal}`);
+			let shutdownFailed = false;
+			let shutdownError;
+			try {
+				await target.close();
+			} catch (error) {
+				shutdownFailed = true;
+				shutdownError = error;
+			}
+			try {
+				await flush();
+			} catch (error) {
+				if (!shutdownFailed) shutdownError = error;
+				shutdownFailed = true;
+			}
+			try {
+				if (shutdownFailed) {
+					logError(`Graceful shutdown failed: ${shutdownError instanceof Error ? shutdownError.message : "Unknown shutdown error"}`);
+					processLike.exitCode = 1;
+					return;
+				}
+			} finally {
+				shutdownSettled = true;
+				cleanup();
+			}
+		})();
+	};
+	const signalListeners = new Map(shutdownSignals.map((signal) => [signal, () => handleSignal(signal)]));
+	for (const signal of shutdownSignals) {
+		const listener = signalListeners.get(signal);
+		if (listener) processLike.on(signal, listener);
+	}
+	return {
+		cleanup,
+		getShutdownPromise: () => shutdownPromise
+	};
+}
+//#endregion
 //#region src/generated/.kubb/fetch.ts
 let _config = {
 	baseURL: typeof AXIOS_BASE !== "undefined" ? AXIOS_BASE : void 0,
@@ -1901,13 +2253,13 @@ const mergeConfig = (...configs) => {
 	}, {});
 };
 const axiosInstance = axios.create(getConfig());
-const fetch = async (config) => {
+const fetch$1 = async (config) => {
 	return axiosInstance.request(mergeConfig(getConfig(), config)).catch((e) => {
 		throw e;
 	});
 };
-fetch.getConfig = getConfig;
-fetch.setConfig = setConfig;
+fetch$1.getConfig = getConfig;
+fetch$1.setConfig = setConfig;
 //#endregion
 //#region src/generated/client/api/getV1BodyMeasurements.ts
 function getGetV1BodyMeasurementsUrl() {
@@ -1921,7 +2273,7 @@ function getGetV1BodyMeasurementsUrl() {
 * {@link /v1/body_measurements}
 */
 async function getV1BodyMeasurements(headers, params, config = {}) {
-	const { client: request = fetch, ...requestConfig } = config;
+	const { client: request = fetch$1, ...requestConfig } = config;
 	return (await request({
 		method: "GET",
 		url: getGetV1BodyMeasurementsUrl().url.toString(),
@@ -1946,7 +2298,7 @@ function getGetV1BodyMeasurementsDateUrl(date) {
 * {@link /v1/body_measurements/:date}
 */
 async function getV1BodyMeasurementsDate(date, headers, config = {}) {
-	const { client: request = fetch, ...requestConfig } = config;
+	const { client: request = fetch$1, ...requestConfig } = config;
 	return (await request({
 		method: "GET",
 		url: getGetV1BodyMeasurementsDateUrl(date).url.toString(),
@@ -1970,7 +2322,7 @@ function getGetV1ExerciseHistoryExercisetemplateidUrl(exerciseTemplateId) {
 * {@link /v1/exercise_history/:exerciseTemplateId}
 */
 async function getV1ExerciseHistoryExercisetemplateid(exerciseTemplateId, headers, params, config = {}) {
-	const { client: request = fetch, ...requestConfig } = config;
+	const { client: request = fetch$1, ...requestConfig } = config;
 	return (await request({
 		method: "GET",
 		url: getGetV1ExerciseHistoryExercisetemplateidUrl(exerciseTemplateId).url.toString(),
@@ -1995,7 +2347,7 @@ function getGetV1ExerciseTemplatesUrl() {
 * {@link /v1/exercise_templates}
 */
 async function getV1ExerciseTemplates(headers, params, config = {}) {
-	const { client: request = fetch, ...requestConfig } = config;
+	const { client: request = fetch$1, ...requestConfig } = config;
 	return (await request({
 		method: "GET",
 		url: getGetV1ExerciseTemplatesUrl().url.toString(),
@@ -2020,7 +2372,7 @@ function getGetV1ExerciseTemplatesExercisetemplateidUrl(exerciseTemplateId) {
 * {@link /v1/exercise_templates/:exerciseTemplateId}
 */
 async function getV1ExerciseTemplatesExercisetemplateid(exerciseTemplateId, headers, config = {}) {
-	const { client: request = fetch, ...requestConfig } = config;
+	const { client: request = fetch$1, ...requestConfig } = config;
 	return (await request({
 		method: "GET",
 		url: getGetV1ExerciseTemplatesExercisetemplateidUrl(exerciseTemplateId).url.toString(),
@@ -2044,7 +2396,7 @@ function getGetV1RoutineFoldersUrl() {
 * {@link /v1/routine_folders}
 */
 async function getV1RoutineFolders(headers, params, config = {}) {
-	const { client: request = fetch, ...requestConfig } = config;
+	const { client: request = fetch$1, ...requestConfig } = config;
 	return (await request({
 		method: "GET",
 		url: getGetV1RoutineFoldersUrl().url.toString(),
@@ -2069,7 +2421,7 @@ function getGetV1RoutineFoldersFolderidUrl(folderId) {
 * {@link /v1/routine_folders/:folderId}
 */
 async function getV1RoutineFoldersFolderid(folderId, headers, config = {}) {
-	const { client: request = fetch, ...requestConfig } = config;
+	const { client: request = fetch$1, ...requestConfig } = config;
 	return (await request({
 		method: "GET",
 		url: getGetV1RoutineFoldersFolderidUrl(folderId).url.toString(),
@@ -2093,7 +2445,7 @@ function getGetV1RoutinesUrl() {
 * {@link /v1/routines}
 */
 async function getV1Routines(headers, params, config = {}) {
-	const { client: request = fetch, ...requestConfig } = config;
+	const { client: request = fetch$1, ...requestConfig } = config;
 	return (await request({
 		method: "GET",
 		url: getGetV1RoutinesUrl().url.toString(),
@@ -2118,7 +2470,7 @@ function getGetV1RoutinesRoutineidUrl(routineId) {
 * {@link /v1/routines/:routineId}
 */
 async function getV1RoutinesRoutineid(routineId, headers, config = {}) {
-	const { client: request = fetch, ...requestConfig } = config;
+	const { client: request = fetch$1, ...requestConfig } = config;
 	return (await request({
 		method: "GET",
 		url: getGetV1RoutinesRoutineidUrl(routineId).url.toString(),
@@ -2142,7 +2494,7 @@ function getGetV1UserInfoUrl() {
 * {@link /v1/user/info}
 */
 async function getV1UserInfo(headers, config = {}) {
-	const { client: request = fetch, ...requestConfig } = config;
+	const { client: request = fetch$1, ...requestConfig } = config;
 	return (await request({
 		method: "GET",
 		url: getGetV1UserInfoUrl().url.toString(),
@@ -2166,7 +2518,7 @@ function getGetV1WorkoutsUrl() {
 * {@link /v1/workouts}
 */
 async function getV1Workouts(headers, params, config = {}) {
-	const { client: request = fetch, ...requestConfig } = config;
+	const { client: request = fetch$1, ...requestConfig } = config;
 	return (await request({
 		method: "GET",
 		url: getGetV1WorkoutsUrl().url.toString(),
@@ -2191,7 +2543,7 @@ function getGetV1WorkoutsCountUrl() {
 * {@link /v1/workouts/count}
 */
 async function getV1WorkoutsCount(headers, config = {}) {
-	const { client: request = fetch, ...requestConfig } = config;
+	const { client: request = fetch$1, ...requestConfig } = config;
 	return (await request({
 		method: "GET",
 		url: getGetV1WorkoutsCountUrl().url.toString(),
@@ -2216,7 +2568,7 @@ function getGetV1WorkoutsEventsUrl() {
 * {@link /v1/workouts/events}
 */
 async function getV1WorkoutsEvents(headers, params, config = {}) {
-	const { client: request = fetch, ...requestConfig } = config;
+	const { client: request = fetch$1, ...requestConfig } = config;
 	return (await request({
 		method: "GET",
 		url: getGetV1WorkoutsEventsUrl().url.toString(),
@@ -2241,7 +2593,7 @@ function getGetV1WorkoutsWorkoutidUrl(workoutId) {
 * {@link /v1/workouts/:workoutId}
 */
 async function getV1WorkoutsWorkoutid(workoutId, headers, config = {}) {
-	const { client: request = fetch, ...requestConfig } = config;
+	const { client: request = fetch$1, ...requestConfig } = config;
 	return (await request({
 		method: "GET",
 		url: getGetV1WorkoutsWorkoutidUrl(workoutId).url.toString(),
@@ -2265,7 +2617,7 @@ function getPostV1BodyMeasurementsUrl() {
 * {@link /v1/body_measurements}
 */
 async function postV1BodyMeasurements(data, headers, config = {}) {
-	const { client: request = fetch, ...requestConfig } = config;
+	const { client: request = fetch$1, ...requestConfig } = config;
 	const requestData = data;
 	return (await request({
 		method: "POST",
@@ -2291,7 +2643,7 @@ function getPostV1ExerciseTemplatesUrl() {
 * {@link /v1/exercise_templates}
 */
 async function postV1ExerciseTemplates(data, headers, config = {}) {
-	const { client: request = fetch, ...requestConfig } = config;
+	const { client: request = fetch$1, ...requestConfig } = config;
 	const requestData = data;
 	return (await request({
 		method: "POST",
@@ -2317,7 +2669,7 @@ function getPostV1RoutineFoldersUrl() {
 * {@link /v1/routine_folders}
 */
 async function postV1RoutineFolders(data, headers, config = {}) {
-	const { client: request = fetch, ...requestConfig } = config;
+	const { client: request = fetch$1, ...requestConfig } = config;
 	const requestData = data;
 	return (await request({
 		method: "POST",
@@ -2343,7 +2695,7 @@ function getPostV1RoutinesUrl() {
 * {@link /v1/routines}
 */
 async function postV1Routines(data, headers, config = {}) {
-	const { client: request = fetch, ...requestConfig } = config;
+	const { client: request = fetch$1, ...requestConfig } = config;
 	const requestData = data;
 	return (await request({
 		method: "POST",
@@ -2369,7 +2721,7 @@ function getPostV1WorkoutsUrl() {
 * {@link /v1/workouts}
 */
 async function postV1Workouts(data, headers, config = {}) {
-	const { client: request = fetch, ...requestConfig } = config;
+	const { client: request = fetch$1, ...requestConfig } = config;
 	const requestData = data;
 	return (await request({
 		method: "POST",
@@ -2395,7 +2747,7 @@ function getPutV1BodyMeasurementsDateUrl(date) {
 * {@link /v1/body_measurements/:date}
 */
 async function putV1BodyMeasurementsDate(date, data, headers, config = {}) {
-	const { client: request = fetch, ...requestConfig } = config;
+	const { client: request = fetch$1, ...requestConfig } = config;
 	const requestData = data;
 	return (await request({
 		method: "PUT",
@@ -2421,7 +2773,7 @@ function getPutV1RoutinesRoutineidUrl(routineId) {
 * {@link /v1/routines/:routineId}
 */
 async function putV1RoutinesRoutineid(routineId, data, headers, config = {}) {
-	const { client: request = fetch, ...requestConfig } = config;
+	const { client: request = fetch$1, ...requestConfig } = config;
 	const requestData = data;
 	return (await request({
 		method: "PUT",
@@ -2447,7 +2799,7 @@ function getPutV1WorkoutsWorkoutidUrl(workoutId) {
 * {@link /v1/workouts/:workoutId}
 */
 async function putV1WorkoutsWorkoutid(workoutId, data, headers, config = {}) {
-	const { client: request = fetch, ...requestConfig } = config;
+	const { client: request = fetch$1, ...requestConfig } = config;
 	const requestData = data;
 	return (await request({
 		method: "PUT",
@@ -2519,6 +2871,15 @@ function getApiTimeoutMs() {
 	if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_API_TIMEOUT_MS;
 	return Math.trunc(parsed);
 }
+function normalizeMaxGetRetries(value) {
+	if (value === void 0 || !Number.isFinite(value) || value < 0) return 3;
+	return Math.floor(value);
+}
+function normalizeTimeoutMs(value) {
+	if (value === void 0 || !Number.isFinite(value) || value <= 0) return getApiTimeoutMs();
+	const normalizedValue = Math.floor(value);
+	return normalizedValue > 0 ? normalizedValue : getApiTimeoutMs();
+}
 function sleep(ms) {
 	return new Promise((resolve) => {
 		setTimeout(resolve, ms);
@@ -2606,7 +2967,7 @@ function markRetryExhausted(error, retryCount) {
 	if (retryError.code) retryError.hevyRetryOriginalCode = retryError.code;
 	retryError.code = HEVY_RETRY_EXHAUSTED_ERROR_CODE;
 }
-async function requestWithRetries(axiosInstance, config, logger) {
+async function requestWithRetries(axiosInstance, config, maxGetRetries, logger) {
 	let retryCount = 0;
 	while (true) try {
 		return await axiosInstance.request(config);
@@ -2628,7 +2989,7 @@ async function requestWithRetries(axiosInstance, config, logger) {
 			});
 			throw error;
 		}
-		if (retryCount >= 3) {
+		if (retryCount >= maxGetRetries) {
 			emitClientLog(logger, {
 				level: status === 429 ? "warning" : "error",
 				logger: "hevy-api",
@@ -2636,7 +2997,7 @@ async function requestWithRetries(axiosInstance, config, logger) {
 					message: "Hevy API request failed after retries",
 					status,
 					attempt: retryCount + 1,
-					maxAttempts: 4,
+					maxAttempts: maxGetRetries + 1,
 					method,
 					endpoint
 				}
@@ -2654,7 +3015,7 @@ async function requestWithRetries(axiosInstance, config, logger) {
 				message: status === 429 ? "Hevy API rate limit; retrying request" : "Retrying Hevy API request",
 				status,
 				attempt: retryCount + 1,
-				maxAttempts: 4,
+				maxAttempts: maxGetRetries + 1,
 				delayMs: retryDelayMs,
 				...status === 429 ? { retryAfterMs: retryAfterMs ?? null } : {},
 				method,
@@ -2664,10 +3025,10 @@ async function requestWithRetries(axiosInstance, config, logger) {
 		await sleep(retryDelayMs);
 	}
 }
-function createResilientClient(axiosInstance, logger) {
+function createResilientClient(axiosInstance, maxGetRetries, logger) {
 	let clientConfig = { baseURL: axiosInstance.defaults.baseURL };
 	const resilientClient = (async (config) => {
-		return requestWithRetries(axiosInstance, config, logger);
+		return requestWithRetries(axiosInstance, config, maxGetRetries, logger);
 	});
 	resilientClient.getConfig = () => ({ ...clientConfig });
 	resilientClient.setConfig = (config) => {
@@ -2723,9 +3084,11 @@ function finalizeRequestTrace(opts) {
 }
 function createClient$1(apiKey, baseUrl = "https://api.hevyapp.com", options = {}) {
 	const { logger } = options;
+	const maxGetRetries = normalizeMaxGetRetries(options.maxGetRetries);
+	const timeoutMs = normalizeTimeoutMs(options.timeoutMs);
 	const axiosInstance = axios.create({
 		baseURL: baseUrl,
-		timeout: getApiTimeoutMs(),
+		timeout: timeoutMs,
 		headers: { "api-key": apiKey }
 	});
 	axiosInstance.interceptors.request.use((config) => {
@@ -2733,11 +3096,13 @@ function createClient$1(apiKey, baseUrl = "https://api.hevyapp.com", options = {
 		const method = (config.method ?? "get").toUpperCase();
 		const url = config.url ?? "";
 		const endpoint = url.split("?")[0] ?? url;
+		const userId = getCurrentUserId();
 		tracedConfig._span = tracer.startSpan(`hevy.api.${method}`, { attributes: {
 			"http.method": method,
 			"http.url": url,
 			"http.base_url": config.baseURL ?? "",
-			"hevy.api.endpoint": endpoint
+			"hevy.api.endpoint": endpoint,
+			...userId ? { "user.id": userId } : {}
 		} });
 		tracedConfig._startTime = Date.now();
 		return config;
@@ -2749,6 +3114,13 @@ function createClient$1(apiKey, baseUrl = "https://api.hevyapp.com", options = {
 			url: response.config.url,
 			_startTime: tracedConfig._startTime
 		});
+		const requestContext = getRequestContext(response.config);
+		debugLog("api_response", {
+			method: requestContext.method,
+			endpoint: requestContext.endpoint,
+			durationMs,
+			status: response.status
+		});
 		finalizeRequestTrace({
 			span: tracedConfig._span,
 			statusCode: response.status,
@@ -2764,6 +3136,13 @@ function createClient$1(apiKey, baseUrl = "https://api.hevyapp.com", options = {
 			url: error.config?.url,
 			_startTime: tracedConfig._startTime
 		});
+		const requestContext = getRequestContext(error.config ?? {});
+		debugLog("api_response", {
+			method: requestContext.method,
+			endpoint: requestContext.endpoint,
+			durationMs,
+			status: error.response?.status ?? null
+		});
 		finalizeRequestTrace({
 			span: tracedConfig._span,
 			statusCode: error.response?.status ?? 0,
@@ -2775,7 +3154,7 @@ function createClient$1(apiKey, baseUrl = "https://api.hevyapp.com", options = {
 		throw error;
 	});
 	const headers = { "api-key": apiKey };
-	const client = createResilientClient(axiosInstance, logger);
+	const client = createResilientClient(axiosInstance, maxGetRetries, logger);
 	return {
 		getWorkouts: (params) => wrapApi(getV1Workouts)(headers, params, { client }),
 		getWorkout: (workoutId) => wrapApi(getV1WorkoutsWorkoutid)(workoutId, headers, { client }),
@@ -2832,6 +3211,9 @@ function createMcpClientLogger(server) {
 //#endregion
 //#region src/utils/stdio-observability.ts
 const UTF8_BOM = "";
+/** Maximum escaped characters included in a malformed stdin shape preview. */
+const STDIN_PARSE_SHAPE_PREVIEW_MAX_LENGTH = 200;
+const REDACTED_CONTENT_MARKER = "[REDACTED]";
 /**
 * Adapter boundary around MCP SDK stdio internals.
 *
@@ -2886,6 +3268,62 @@ function getFailureLocation(failurePosition, lineHadLeadingBom) {
 	if (failurePosition !== null) return "line_body";
 	return "unknown";
 }
+function createStructuralShapePreview(line) {
+	let shapePreview = "";
+	let inContentRun = false;
+	let inWhitespaceRun = false;
+	const append = (token) => {
+		if (shapePreview.length + token.length > STDIN_PARSE_SHAPE_PREVIEW_MAX_LENGTH) return false;
+		shapePreview += token;
+		return true;
+	};
+	for (const character of line) {
+		if ("{}[]:,\"".includes(character)) {
+			inContentRun = false;
+			inWhitespaceRun = false;
+			if (!append(character === "\"" ? "\\u0022" : character)) return {
+				shapePreview,
+				truncated: true
+			};
+			continue;
+		}
+		if (/\s/u.test(character)) {
+			inContentRun = false;
+			if (!inWhitespaceRun) {
+				if (!append("\\s")) return {
+					shapePreview,
+					truncated: true
+				};
+				inWhitespaceRun = true;
+			}
+			continue;
+		}
+		inWhitespaceRun = false;
+		if (!inContentRun) {
+			if (!append(REDACTED_CONTENT_MARKER)) return {
+				shapePreview,
+				truncated: true
+			};
+			inContentRun = true;
+		}
+	}
+	return {
+		shapePreview,
+		truncated: false
+	};
+}
+function getSafeErrorKind(error) {
+	if (error instanceof SyntaxError) return "SyntaxError";
+	if (error instanceof Error) return "Error";
+	return "UnknownError";
+}
+function reportStdinParseFailure(error, line, lineByteLength, failureLocation, failurePosition) {
+	try {
+		const errorKind = getSafeErrorKind(error);
+		const { shapePreview, truncated } = createStructuralShapePreview(line);
+		console.error(`Failed to parse MCP stdin message: error_kind=${errorKind} line_bytes=${lineByteLength} failure_location=${failureLocation} failure_position=${failurePosition === null ? "unknown" : failurePosition} shape_preview="${shapePreview}" shape_preview_redacted=true shape_preview_truncated=${truncated}`);
+	} catch {}
+}
 function deserializeMessageWithObservability(line, chunkSnapshot) {
 	const lineHadLeadingBom = line.startsWith(UTF8_BOM);
 	const normalizedLine = lineHadLeadingBom ? line.slice(1) : line;
@@ -2929,6 +3367,7 @@ function deserializeMessageWithObservability(line, chunkSnapshot) {
 				});
 				Sentry.captureException(error);
 			});
+			reportStdinParseFailure(error, line, lineByteLength, failureLocation, failurePosition);
 			throw error;
 		} finally {
 			span.end();
@@ -2951,9 +3390,164 @@ function createInstrumentedStdioTransport(transport) {
 	return transport;
 }
 //#endregion
+//#region src/utils/version-check.ts
+const CACHE_TTL_MS = 1440 * 60 * 1e3;
+const REQUEST_TIMEOUT_MS = 3e3;
+const REGISTRY_URL = "https://registry.npmjs.org";
+const defaultDependencies = {
+	fetch,
+	readFile,
+	mkdir,
+	writeFile,
+	rename,
+	unlink,
+	homedir,
+	randomUUID,
+	pid: process.pid,
+	now: Date.now,
+	env: process.env,
+	writeStderr: (message) => process.stderr.write(message)
+};
+const defaultSchedulerDependencies = {
+	setImmediate,
+	checkForUpdate
+};
+function getCachePath(dependencies) {
+	return join(dependencies.env.XDG_CACHE_HOME || join(dependencies.homedir(), ".cache"), "hevy-mcp", "update-check.json");
+}
+function parseCacheEntry(value, now) {
+	try {
+		const parsed = JSON.parse(value);
+		if (typeof parsed !== "object" || parsed === null || !("checkedAt" in parsed) || !("latestVersion" in parsed)) return;
+		const { checkedAt, latestVersion } = parsed;
+		if (typeof checkedAt !== "number" || !Number.isFinite(checkedAt) || typeof latestVersion !== "string" || !semver.valid(latestVersion)) return;
+		const age = now - checkedAt;
+		if (age < 0 || age >= CACHE_TTL_MS) return;
+		return {
+			checkedAt,
+			latestVersion
+		};
+	} catch {
+		return;
+	}
+}
+function parseLatestVersion(value) {
+	if (typeof value !== "object" || value === null || !("dist-tags" in value)) return;
+	const distTags = value["dist-tags"];
+	if (typeof distTags !== "object" || distTags === null || !("latest" in distTags) || typeof distTags.latest !== "string" || !semver.valid(distTags.latest)) return;
+	return distTags.latest;
+}
+function shouldNotifyAboutUpdate(currentVersion, latestVersion) {
+	const current = semver.parse(currentVersion);
+	const latest = semver.parse(latestVersion);
+	if (!current || !latest || latest.prerelease.length > 0 || !semver.gt(latest, current)) return false;
+	if (latest.major > current.major) return true;
+	return latest.major === current.major && latest.minor - current.minor > 2;
+}
+async function readFreshCachedVersion(cachePath, dependencies) {
+	try {
+		return parseCacheEntry(await dependencies.readFile(cachePath, "utf8"), dependencies.now())?.latestVersion;
+	} catch {
+		return;
+	}
+}
+async function fetchLatestVersion(packageName, dependencies) {
+	try {
+		const response = await dependencies.fetch(`${REGISTRY_URL}/${encodeURIComponent(packageName)}`, {
+			headers: { Accept: "application/vnd.npm.install-v1+json" },
+			signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+		});
+		if (!response.ok) return;
+		return parseLatestVersion(await response.json());
+	} catch {
+		return;
+	}
+}
+async function writeCache(cachePath, entry, dependencies) {
+	const temporaryPath = `${cachePath}.${dependencies.pid}.${dependencies.randomUUID()}.tmp`;
+	const payload = `${JSON.stringify(entry)}\n`;
+	try {
+		await dependencies.mkdir(dirname(cachePath), { recursive: true });
+		await dependencies.writeFile(temporaryPath, payload, "utf8");
+	} catch {
+		try {
+			await dependencies.unlink(temporaryPath);
+		} catch {}
+		return;
+	}
+	try {
+		await dependencies.rename(temporaryPath, cachePath);
+		return;
+	} catch {
+		try {
+			await dependencies.writeFile(cachePath, payload, "utf8");
+		} catch {}
+	}
+	try {
+		await dependencies.unlink(temporaryPath);
+	} catch {}
+}
+async function checkForUpdate(options, overrides = {}) {
+	try {
+		if (!semver.valid(options.currentVersion)) return;
+		const dependencies = {
+			...defaultDependencies,
+			...overrides
+		};
+		const cachePath = getCachePath(dependencies);
+		let latestVersion = await readFreshCachedVersion(cachePath, dependencies);
+		if (!latestVersion) {
+			latestVersion = await fetchLatestVersion(options.packageName, dependencies);
+			if (!latestVersion) return;
+			await writeCache(cachePath, {
+				checkedAt: dependencies.now(),
+				latestVersion
+			}, dependencies);
+		}
+		if (shouldNotifyAboutUpdate(options.currentVersion, latestVersion)) dependencies.writeStderr(`Update available for ${options.packageName}: current ${options.currentVersion}, latest ${latestVersion}. Notices are shown for newer major versions or when more than two minor versions behind. Update using your preferred installation method (for example, npm install -g ${options.packageName}@latest).\n`);
+	} catch {}
+}
+function scheduleUpdateCheck(options, overrides = {}) {
+	const dependencies = {
+		...defaultSchedulerDependencies,
+		...overrides
+	};
+	dependencies.setImmediate(() => {
+		dependencies.checkForUpdate(options).catch(() => void 0);
+	}).unref();
+}
+//#endregion
 //#region src/index.ts
 const name = name$1;
 const version = version$1;
+const SERVER_INSTRUCTIONS = [
+	[
+		"Hevy MCP connects clients to the authenticated user's Hevy",
+		"workout-tracking data, including workouts, routines, exercise templates,",
+		"routine folders, body measurements, and profile information.",
+		"HEVY_API_KEY must contain a valid Hevy API key."
+	].join(" "),
+	[
+		"Safety: all get-* and search-* tools are read-only. create-* and",
+		"update-* tools mutate Hevy data. Creates are additive and",
+		"non-idempotent, so repeating one can create duplicates. Updates can",
+		"overwrite existing data. Delete operations are not available."
+	].join(" "),
+	[
+		"Workflow: search exercise templates first, then use the returned",
+		"template IDs when creating workouts or routines. To create a completed",
+		"workout from a routine, fetch the routine as a plan, then obtain the",
+		"actual completed sets and end time from the user; never invent completion",
+		"data. Use the built-in workflow prompts when they match the task."
+	].join(" "),
+	["Pagination: start at page 1 and fetch only the pages needed. Most list", "tools allow pageSize up to 10; get-exercise-templates allows up to 100."].join(" "),
+	[
+		"Rate limits and retries: minimize repeated calls. If Hevy returns HTTP",
+		"429, follow its retry guidance. Transient read requests retry",
+		"automatically, but write requests do not; confirm uncertain write",
+		"outcomes before trying again."
+	].join(" ")
+].join("\n\n");
 const HELP_TEXT = [
 	"Usage:",
 	"  hevy-mcp [options]",
@@ -2965,6 +3559,7 @@ const HELP_TEXT = [
 	"",
 	"Environment:",
 	"  HEVY_API_KEY=<api-key>     Hevy API key from Hevy app settings",
+	"  HEVY_MCP_DEBUG=1           Enable verbose diagnostics on stderr",
 	"",
 	"Examples:",
 	"  HEVY_API_KEY=your-key npx hevy-mcp",
@@ -2979,6 +3574,21 @@ function getCliAction(args) {
 	return "start";
 }
 const HEVY_API_BASEURL = "https://api.hevyapp.com";
+const STARTUP_PROBE_TIMEOUT_MS = 5e3;
+const INVALID_API_KEY_MESSAGE = "HEVY_API_KEY is invalid or expired. Please check your API key in the Hevy app under Settings > API Key.";
+const API_KEY_VALIDATION_WARNING = "Warning: HEVY_API_KEY could not be validated during startup. Startup will continue; check your network connection and Hevy API availability.";
+const SAFE_NETWORK_ERROR_CODES = /* @__PURE__ */ new Set([
+	"EAI_AGAIN",
+	"ECONNABORTED",
+	"ECONNREFUSED",
+	"ECONNRESET",
+	"ENETUNREACH",
+	"ENOTFOUND",
+	"ERR_NETWORK",
+	"ERR_SOCKET_TIMEOUT",
+	"ETIMEDOUT",
+	"HEVY_RETRY_EXHAUSTED"
+]);
 const SENTRY_USER_ID_CONTEXT = "hevy-mcp:sentry-user-id:v1";
 function fingerprintApiKey(apiKey) {
 	return createHmac("sha256", apiKey).update(SENTRY_USER_ID_CONTEXT).digest("hex").slice(0, 10);
@@ -3007,6 +3617,33 @@ function createToolCountingServer(server) {
 		getCount: () => count
 	};
 }
+function getHttpStatus(error) {
+	if (!error || typeof error !== "object" || !("response" in error)) return;
+	const response = error.response;
+	if (!response || typeof response !== "object" || !("status" in response)) return;
+	return typeof response.status === "number" && Number.isInteger(response.status) && response.status >= 100 && response.status <= 599 ? response.status : void 0;
+}
+function getSafeValidationDiagnostic(error) {
+	const status = getHttpStatus(error);
+	if (status !== void 0) return `HTTP ${status}`;
+	if (!error || typeof error !== "object" || !("code" in error)) return;
+	const code = error.code;
+	return typeof code === "string" && SAFE_NETWORK_ERROR_CODES.has(code) ? code : void 0;
+}
+async function validateApiKey(apiKey) {
+	const startupProbeClient = createClient(apiKey, HEVY_API_BASEURL, {
+		maxGetRetries: 0,
+		timeoutMs: STARTUP_PROBE_TIMEOUT_MS
+	});
+	try {
+		await startupProbeClient.getUserInfo();
+	} catch (error) {
+		const status = getHttpStatus(error);
+		if (status === 401 || status === 403) throw new Error(INVALID_API_KEY_MESSAGE);
+		const diagnostic = getSafeValidationDiagnostic(error);
+		console.error(diagnostic ? `${API_KEY_VALIDATION_WARNING} Diagnostic: ${diagnostic}.` : API_KEY_VALIDATION_WARNING);
+	}
+}
 function buildServer(apiKey) {
 	const userId = fingerprintApiKey(apiKey);
 	return tracer.startActiveSpan("mcp.server.build", { attributes: {
@@ -3021,7 +3658,10 @@ function buildServer(apiKey) {
 			const baseServer = new McpServer({
 				name,
 				version
-			}, { capabilities: { logging: {} } });
+			}, {
+				capabilities: { logging: {} },
+				instructions: SERVER_INSTRUCTIONS
+			});
 			const server = Sentry.wrapMcpServerWithSentry(baseServer);
 			const clientLogger = createMcpClientLogger(server);
 			const hevyClient = tracer.startActiveSpan("mcp.hevy-client.initialize", (childSpan) => {
@@ -3064,15 +3704,16 @@ function buildServer(apiKey) {
 		}
 	});
 }
-function createServer({ config }) {
+async function createServer({ config }) {
 	const { apiKey } = serverConfigSchema.parse(config);
+	await validateApiKey(apiKey);
 	return buildServer(apiKey);
 }
 async function runServer() {
 	const args = process.argv.slice(2);
 	const cliAction = getCliAction(args);
 	if (cliAction === "version") {
-		console.log(version);
+		console.error(`${name} v${version}`);
 		return;
 	}
 	if (cliAction === "help") {
@@ -3084,7 +3725,7 @@ async function runServer() {
 		try {
 			const apiKey = parseConfig(args, process.env).apiKey;
 			assertApiKey(apiKey);
-			const server = buildServer(apiKey);
+			const server = await createServer({ config: { apiKey } });
 			console.error("Starting MCP server in stdio mode");
 			const transport = createInstrumentedStdioTransport(new StdioServerTransport());
 			await tracer.startActiveSpan("mcp.server.connect", { attributes: { "mcp.transport": "stdio" } }, async (connectSpan) => {
@@ -3098,6 +3739,11 @@ async function runServer() {
 					connectSpan.end();
 				}
 			});
+			scheduleUpdateCheck({
+				packageName: name$1,
+				currentVersion: version$1
+			});
+			installGracefulShutdown({ target: server });
 			span.setStatus({ code: SpanStatusCode.OK });
 		} catch (e) {
 			span.setStatus({ code: SpanStatusCode.ERROR });
@@ -3110,4 +3756,4 @@ async function runServer() {
 //#endregion
 export { createServer as n, runServer as r, configSchema as t };
 
-//# sourceMappingURL=src-J8OsyJcw.mjs.map
+//# sourceMappingURL=src-c3mB-R0m.mjs.map