feat: add --help and --version CLI flags (#431)

* feat: add help and version CLI flags

* fix: deprecate --hevy-api-key help text

---------

Co-authored-by: CharlieHelps <charlie@charlielabs.ai>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

Author: 3 people

.changeset/slimy-coins-smash.md

@@ -0,0 +1,7 @@
+---
+"hevy-mcp": patch
+---
+
+Add CLI `--help`/`-h` and `--version`/`-v` flags that print output and
+exit before server startup, with unit test coverage for flag and default
+startup behavior.

src/index.test.ts

@@ -170,6 +170,62 @@ describe("Server entry", () => {
 	});
 
 	describe("runServer", () => {
+		it.each(["--version", "-v"])(
+			"prints version for %s and exits before server startup",
+			async (flag) => {
+				process.env = {
+					...originalEnv,
+					HEVY_API_KEY: "test-api-key",
+				};
+				process.argv = [...originalArgv.slice(0, 2), flag];
+
+				const logSpy = vi
+					.spyOn(console, "log")
+					.mockImplementation(() => undefined);
+
+				await runServer();
+
+				expect(logSpy).toHaveBeenCalledWith("dev");
+				expect(createClient).not.toHaveBeenCalled();
+				expect(testDoubles.startActiveSpan).not.toHaveBeenCalled();
+
+				const anyStdioModule = stdioModule as { __transports?: unknown[] };
+				expect(anyStdioModule.__transports).toHaveLength(0);
+
+				logSpy.mockRestore();
+			},
+		);
+
+		it.each(["--help", "-h"])(
+			"prints help for %s and exits before server startup",
+			async (flag) => {
+				process.env = {
+					...originalEnv,
+					HEVY_API_KEY: "test-api-key",
+				};
+				process.argv = [...originalArgv.slice(0, 2), flag];
+
+				const logSpy = vi
+					.spyOn(console, "log")
+					.mockImplementation(() => undefined);
+
+				await runServer();
+
+				expect(logSpy).toHaveBeenCalledTimes(1);
+				const [helpText] = logSpy.mock.calls[0] ?? [];
+				expect(helpText).toContain("Usage:");
+				expect(helpText).toContain("HEVY_API_KEY");
+				expect(helpText).toContain("Examples:");
+				expect(createClient).not.toHaveBeenCalled();
+				expect(testDoubles.startActiveSpan).not.toHaveBeenCalled();
+
+				const anyStdioModule = stdioModule as { __transports?: unknown[] };
+				expect(anyStdioModule.__transports).toHaveLength(0);
+
+				logSpy.mockRestore();
+			},
+		);
+
 		it("uses HEVY_API_KEY from the environment and connects stdio transport", async () => {
 			process.env = {
 				...originalEnv,

src/index.ts

@@ -27,6 +27,38 @@ import { createInstrumentedStdioTransport } from "./utils/stdio-observability.js
 const name = serviceName;
 const version = serviceVersion;
 
+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: string[]): "start" | "version" | "help" {
+	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";
@@ -127,6 +159,19 @@ export function createServer({ config }: { config: ServerConfig }) {
 export default createServer;
 
 export 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(
@@ -138,7 +183,6 @@ export async function runServer() {
 		},
 		async (span) => {
 			try {
-				const args = process.argv.slice(2);
 				const cfg = parseConfig(args, process.env);
 				const apiKey = cfg.apiKey;
 				assertApiKey(apiKey);