hevy-mcp 1.28.1-beta.1 → 2.0.0

package/README.md

@@ -15,6 +15,7 @@ A Model Context Protocol (MCP) server implementation that interfaces with the [H
 - [Quick Start](#quick-start)
 - [Prerequisites](#prerequisites)
 - [Installation](#installation)
+  - [Run with Docker](#run-with-docker)
   - [Claude Desktop Configuration](#claude-desktop-configuration)
   - [Cursor Configuration](#cursor-configuration)
   - [Other MCP Clients (via add-mcp)](#other-mcp-clients-via-add-mcp)
@@ -39,10 +40,11 @@ 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` or `HEVY_API_KEY=sk_live... bunx hevy-mcp@latest` | Node.js ≥ 20, 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=your_key npx -y hevy-mcp` or `HEVY_API_KEY=your_key bunx hevy-mcp@latest` | Node.js ≥ 20, Hevy API key |
+| **Docker stdio run**  | `docker run -i --rm -e HEVY_API_KEY ghcr.io/chrisdoc/hevy-mcp:latest`                   | Docker, Hevy API key       |
+| **Local development** | `npm install && npm run build && npm start`                                             | `.env` with `HEVY_API_KEY` |
 
 ---
 
@@ -51,6 +53,7 @@ Pick the workflow that fits your setup:
 - **Node.js**: v20 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`.
+- **Docker** (optional): If you want an isolated container-based stdio setup.
 - **Hevy API key**: Required for all operations (available with Hevy PRO).
 
 ---
@@ -70,25 +73,6 @@ HEVY_API_KEY=your_hevy_api_key_here npx -y hevy-mcp
 HEVY_API_KEY=your_hevy_api_key_here bunx hevy-mcp@latest
 ```
 
-### Prerelease channel
-
-Install `hevy-mcp@beta` to opt into changes merged to `main` that have not yet
-reached a stable release:
-
-```bash
-npm install hevy-mcp@beta
-
-# npx launcher
-npx -y hevy-mcp@beta
-
-# bun launcher
-bunx hevy-mcp@beta
-```
-
-Beta builds may be less stable and can change before their stable release.
-`npm install hevy-mcp@latest` remains the stable channel. To switch back from
-beta, install `hevy-mcp@latest` again.
-
 ### Manual Installation
 
 ```bash
@@ -104,6 +88,26 @@ cp .env.sample .env
 # Edit .env and add your HEVY_API_KEY
 ```
 
+### Run with Docker
+
+Official multi-platform images are published to GitHub Container Registry for
+`linux/amd64` and `linux/arm64`:
+
+```bash
+export HEVY_API_KEY=your_hevy_api_key_here
+docker run -i --rm -e HEVY_API_KEY ghcr.io/chrisdoc/hevy-mcp:latest
+```
+
+The server uses stdio, so `-i` keeps standard input open for the MCP client.
+`--rm` removes the stopped container automatically. The `-e HEVY_API_KEY`
+form forwards the variable from the host environment without putting the key
+in the command arguments.
+
+Use `latest` to follow the newest stable release. For reproducible deployments,
+pin the exact version shown on the release, using a tag such as
+`ghcr.io/chrisdoc/hevy-mcp:X.Y.Z`. Major (`:X`) and major.minor (`:X.Y`) tags
+are also published for controlled automatic updates.
+
 ---
 
 ## 🔗 Integration
@@ -138,6 +142,41 @@ If you prefer Bun, swap the launcher fields:
 }
 ```
 
+To run Claude Desktop through Docker instead, first create an environment file
+outside the repository containing your real key:
+
+```dotenv
+HEVY_API_KEY=replace_with_your_real_key
+```
+
+Restrict access to that file where supported (for example,
+`chmod 600 /absolute/path/to/hevy-mcp.env`), then use its absolute path in the
+Claude Desktop configuration:
+
+```json
+{
+	"mcpServers": {
+		"hevy-mcp": {
+			"command": "docker",
+			"args": [
+				"run",
+				"-i",
+				"--rm",
+				"--env-file",
+				"/absolute/path/to/hevy-mcp.env",
+				"ghcr.io/chrisdoc/hevy-mcp:latest"
+			]
+		}
+	}
+}
+```
+
+This configuration runs the same stdio server inside the container; it does
+not expose an HTTP port or start a detached service. Docker reads the key from
+the environment file, so the Claude configuration does not replace an
+inherited key with a placeholder. Replace `latest` with an exact version tag if
+you want Claude Desktop to stay on a pinned release.
+
 ### Cursor Configuration
 
 Add this server under `"mcpServers"` in `~/.cursor/mcp.json`:
@@ -241,10 +280,11 @@ paging behavior explicit and avoid cross-page invalidation complexity.
 <details>
 <summary><strong>⚠️ Migration Note (v1.18.0)</strong></summary>
 
-As of **v1.18.0**, `hevy-mcp` removed both HTTP/SSE transport and Docker
-support.
+As of **v1.18.0**, `hevy-mcp` removed HTTP/SSE transport and its previous
+Docker packaging. Docker support is now available again for the stdio server.
 
-The supported path is stdio via `npx hevy-mcp`.
+Both `npx hevy-mcp` and the official container image use stdio; HTTP ports and
+detached-container deployment are not supported.
 
 </details>
 

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.28.1-beta.1" };
+		e.SENTRY_RELEASE = { id: "hevy-mcp@2.0.0" };
 		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-CHT_Meh8.mjs";
+import { r as runServer } from "./src-c3mB-R0m.mjs";
 //#region src/cli.ts
 runServer().catch((error) => {
 	console.error("Fatal error in main():", error);

package/dist/index.d.mts

@@ -14,7 +14,7 @@ declare function createServer({
   config
 }: {
   config: ServerConfig;
-}): McpServer;
+}): Promise<McpServer>;
 declare function runServer(): Promise<void>;
 //#endregion
 export { configSchema, createServer, createServer as default, runServer };

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.28.1-beta.1" };
+		e.SENTRY_RELEASE = { id: "hevy-mcp@2.0.0" };
 		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-CHT_Meh8.mjs";
+import { n as createServer, r as runServer, t as configSchema } from "./src-c3mB-R0m.mjs";
 export { configSchema, createServer, createServer as default, runServer };

package/dist/{src-CHT_Meh8.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.1-beta.1" };
+		e.SENTRY_RELEASE = { id: "hevy-mcp@2.0.0" };
 		var n = new e.Error().stack;
-		n && (e._sentryDebugIds = e._sentryDebugIds || {}, e._sentryDebugIds[n] = "aa9ed1a5-ba18-4930-8061-5891221f6944", e._sentryDebugIdIdentifier = "sentry-dbid-aa9ed1a5-ba18-4930-8061-5891221f6944");
+		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";
@@ -41,10 +41,10 @@ import semver from "semver";
 * OTel Collector → Honeycomb: performance traces, metrics
 */
 const name$1 = "hevy-mcp";
-const version$1 = "1.28.1-beta.1";
+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.1-beta.1`;
+const sentryRelease = process.env.SENTRY_RELEASE ?? `hevy-mcp@2.0.0`;
 const resource = resourceFromAttributes({
 	"service.name": name$1,
 	"service.version": version$1
@@ -2871,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);
@@ -2958,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);
@@ -2980,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",
@@ -2988,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
 				}
@@ -3006,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,
@@ -3016,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) => {
@@ -3075,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) => {
@@ -3085,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;
@@ -3141,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 }),
@@ -3561,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);
@@ -3589,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: {
@@ -3649,8 +3704,9 @@ function buildServer(apiKey) {
 		}
 	});
 }
-function createServer({ config }) {
+async function createServer({ config }) {
 	const { apiKey } = serverConfigSchema.parse(config);
+	await validateApiKey(apiKey);
 	return buildServer(apiKey);
 }
 async function runServer() {
@@ -3669,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) => {
@@ -3700,4 +3756,4 @@ async function runServer() {
 //#endregion
 export { createServer as n, runServer as r, configSchema as t };
 
-//# sourceMappingURL=src-CHT_Meh8.mjs.map
+//# sourceMappingURL=src-c3mB-R0m.mjs.map