hevy-mcp 1.26.0 → 1.26.1

package/README.md

@@ -38,10 +38,10 @@ A Model Context Protocol (MCP) server implementation that interfaces with the [H
 
 Pick the workflow that fits your setup:
 
-| Scenario              | Command                                     | Requirements               |
-| :-------------------- | :------------------------------------------ | :------------------------- |
-| **One-off stdio run** | `HEVY_API_KEY=sk_live... npx -y hevy-mcp`   | Node.js ≥ 26, Hevy API key |
-| **Local development** | `npm install && npm run build && npm start` | `.env` with `HEVY_API_KEY` |
+| Scenario              | Command                                                                                     | Requirements               |
+| :-------------------- | :------------------------------------------------------------------------------------------ | :------------------------- |
+| **One-off stdio run** | `HEVY_API_KEY=sk_live... npx -y hevy-mcp` or `HEVY_API_KEY=sk_live... bunx hevy-mcp@latest` | Node.js ≥ 26, Hevy API key |
+| **Local development** | `npm install && npm run build && npm start`                                                 | `.env` with `HEVY_API_KEY` |
 
 ---
 
@@ -49,18 +49,24 @@ Pick the workflow that fits your setup:
 
 - **Node.js**: v26 or higher (strongly recommended to use the exact version pinned in `.nvmrc`).
 - **npm**: v10 or higher.
+- **Bun** (optional): If you want to launch with `bunx`.
 - **Hevy API key**: Required for all operations (available with Hevy PRO).
 
 ---
 
 ## 📦 Installation
 
-### Run via npx (Recommended)
+### Run via npx or bunx
 
-You can launch the server directly without cloning:
+You can launch the server directly without cloning. Both launchers are covered
+by nightly smoke tests:
 
 ```bash
+# npm launcher
 HEVY_API_KEY=your_hevy_api_key_here npx -y hevy-mcp
+
+# bun launcher
+HEVY_API_KEY=your_hevy_api_key_here bunx hevy-mcp@latest
 ```
 
 ### Manual Installation
@@ -103,6 +109,15 @@ To use this server with Claude Desktop, add the following to your `claude_deskto
 }
 ```
 
+If you prefer Bun, swap the launcher fields:
+
+```json
+{
+	"command": "bunx",
+	"args": ["hevy-mcp@latest"]
+}
+```
+
 ### Cursor Configuration
 
 Add this server under `"mcpServers"` in `~/.cursor/mcp.json`:
@@ -121,6 +136,15 @@ Add this server under `"mcpServers"` in `~/.cursor/mcp.json`:
 }
 ```
 
+If you prefer Bun, swap the launcher fields:
+
+```json
+{
+	"command": "bunx",
+	"args": ["hevy-mcp@latest"]
+}
+```
+
 ### Other MCP Clients (via add-mcp)
 
 For a generic setup flow across MCP clients, use [`add-mcp`](https://github.com/neon-solutions/add-mcp):
@@ -144,16 +168,34 @@ This bootstraps the `hevy-mcp` entry in your client config without manual JSON e
 
 ## ⚙️ Configuration
 
-Supply your Hevy API key via:
+Supply your Hevy API key via the `HEVY_API_KEY` environment variable (in
+`.env` or system environment).
 
-1. **Environment Variable**: `HEVY_API_KEY` (in `.env` or system environment).
-2. **CLI Argument**: `--hevy-api-key=your_key` (after `--` in npm scripts).
+> ⚠️ CLI API key arguments (`--hevy-api-key=...`, `--hevyApiKey=...`,
+> `hevy-api-key=...`) are still accepted for backward compatibility, but are
+> deprecated and insecure. Use `HEVY_API_KEY` instead.
 
 ```env
 # Example .env
 HEVY_API_KEY=your_hevy_api_key_here
 ```
 
+### 🧠 Exercise Template Cache Behavior
+
+`search-exercise-templates` now uses a shared in-memory async cache for the
+full exercise template catalog:
+
+- **TTL**: 5 minutes per cached catalog entry.
+- **Memory bound**: max 1 catalog entry (LRU bounded cache).
+- **In-flight de-duplication**: concurrent requests share the same active
+  fetch when possible.
+- **Manual refresh**: set `refresh: true` in the tool input to invalidate the
+  cached catalog and force a re-fetch from the Hevy API.
+
+This cache currently applies to `search-exercise-templates` only. Paginated
+`get-exercise-templates` requests still call the API directly to keep paging
+behavior explicit and avoid cross-page invalidation complexity.
+
 ### 📡 Sentry Monitoring
 
 `hevy-mcp` includes Sentry monitoring to observe errors and usage in production. It initializes `@sentry/node` with tracing enabled and PII collection disabled by default. Recent observability changes also add:
@@ -166,15 +208,12 @@ HEVY_API_KEY=your_hevy_api_key_here
 ---
 
 <details>
-<summary><strong>⚠️ Deprecation Notices (HTTP/SSE & Docker)</strong></summary>
-
-### Stdio Only
+<summary><strong>⚠️ Migration Note (v1.18.0)</strong></summary>
 
-As of version **1.18.0**, `hevy-mcp` only supports **stdio** transport. HTTP/SSE transport has been completely removed to simplify the codebase and focus on the native MCP experience.
+As of **v1.18.0**, `hevy-mcp` removed both HTTP/SSE transport and Docker
+support.
 
-### Docker
-
-Docker-based workflows are retired. The provided `Dockerfile` now exits with a message pointing to the stdio-native experience. Legacy GHCR images are no longer updated.
+The supported path is stdio via `npx hevy-mcp`.
 
 </details>
 
@@ -191,6 +230,11 @@ Docker-based workflows are retired. The provided `Dockerfile` now exits with a m
 | **Body Measurements** | `get-body-measurements`, `get-body-measurement`, `create-body-measurement`, `update-body-measurement`                              |
 | **User**              | `get-user-info`                                                                                                                    |
 
+> **Delete operations are currently unsupported:** The upstream Hevy OpenAPI
+> spec does not expose `DELETE` endpoints for workouts, routines, routine
+> folders, exercise templates, or body measurements, so `hevy-mcp` does not
+> provide delete tools for these resources.
+
 ---
 
 ## 👨‍💻 Development & Contributing
@@ -199,6 +243,7 @@ Docker-based workflows are retired. The provided `Dockerfile` now exits with a m
 
 - **Build**: `npm run build`
 - **Lint/Format**: `npm run check` (uses oxlint/oxfmt)
+- **Type Check**: `npm run check:types`
 - **Unit Tests**: `npx vitest run --exclude tests/integration/**`
 - **Full Test Suite**: `npm test` (requires `HEVY_API_KEY`)
 - **Changeset Check**: `npm run check:changeset`
@@ -210,6 +255,8 @@ For a detailed senior engineer guide, please refer to [AGENTS.md](./AGENTS.md).
 - **Conventional Commits**: CI lints commit messages on pull requests, so use
   prefixes such as `feat:`, `fix:`, `docs:`, `ci:`, `chore:`, `refactor:`,
   `test:`, or `style:`.
+- **Type Checking**: CI runs `npm run check:types` on pull requests and pushes
+  to `main`; run this locally before opening a PR.
 - **Changesets**: Contributor pull requests targeting `main` must include a
   changeset. Dependabot PRs and automated `changeset-release/main` release PRs
   are handled by automation and skip this check.

package/dist/cli.mjs

@@ -4,12 +4,12 @@
 (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.1" };
 		var n = new e.Error().stack;
 		n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "03cf150f-6466-4ca3-9cf1-e423cc0e3cd2", e._sentryDebugIdIdentifier = "sentry-dbid-03cf150f-6466-4ca3-9cf1-e423cc0e3cd2");
 	} catch (e) {}
 })();
-import { r as runServer } from "./src-Di7keTQA.mjs";
+import { r as runServer } from "./src-_FHG1OUO.mjs";
 //#region src/cli.ts
 runServer().catch((error) => {
 	console.error("Fatal error in main():", error);

package/dist/index.mjs

@@ -4,10 +4,10 @@
 (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.1" };
 		var n = new e.Error().stack;
 		n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "5b077b94-9ef8-4f24-a0b0-8dcfbf491be1", e._sentryDebugIdIdentifier = "sentry-dbid-5b077b94-9ef8-4f24-a0b0-8dcfbf491be1");
 	} catch (e) {}
 })();
-import { n as createServer, r as runServer, t as configSchema } from "./src-Di7keTQA.mjs";
+import { n as createServer, r as runServer, t as configSchema } from "./src-_FHG1OUO.mjs";
 export { configSchema, createServer, createServer as default, runServer };

package/dist/{src-Di7keTQA.mjs → src-_FHG1OUO.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.1" };
 		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] = "d8a16a1c-7e19-4663-9699-a6c28dfa8b53", e._sentryDebugIdIdentifier = "sentry-dbid-d8a16a1c-7e19-4663-9699-a6c28dfa8b53");
 	} 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.1";
 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.1`;
 const resource = resourceFromAttributes({
 	"service.name": name$1,
 	"service.version": version$1
@@ -135,18 +135,21 @@ 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);
 	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,9 +158,49 @@ 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
 */
@@ -405,7 +448,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 +470,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
@@ -836,6 +876,92 @@ 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",
@@ -859,8 +985,27 @@ const MUSCLE_GROUPS = [
 	"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
 */
@@ -945,39 +1090,14 @@ function registerTemplateTools(server, hevyClient) {
 	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")
+		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) => {
+	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) => {
 		if (!hevyClient) throw new Error("API client not initialized. Please provide HEVY_API_KEY.");
 		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(hevyClient), { 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));
@@ -1165,16 +1285,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 +1312,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);
 	}
 }
@@ -1921,6 +2050,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 +2154,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 +2254,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 +2295,4 @@ async function runServer() {
 //#endregion
 export { createServer as n, runServer as r, configSchema as t };
 
-//# sourceMappingURL=src-Di7keTQA.mjs.map
+//# sourceMappingURL=src-_FHG1OUO.mjs.map