feat: add proactive update checks (#562)

* feat: add proactive update checks

* fix: make update notices manager neutral

* fix: restore npm upgrade example

* fix: recover version cache rename failures

---------

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

Author: 3 people

.changeset/lovely-candles-smash.md

@@ -0,0 +1,6 @@
+---
+"hevy-mcp": patch
+---
+
+Notify users on stderr about newer major releases or when they are more than
+two minor versions behind, using package-manager-neutral guidance.

package-lock.json

@@ -70,6 +70,7 @@
 		"@sentry/node": "^10.58.0",
 		"@sentry/opentelemetry": "^10.58.0",
 		"axios": "^1.18.0",
+		"semver": "^7.8.5",
 		"zod": "^4.4.3"
 	},
 	"devDependencies": {
@@ -87,6 +88,7 @@
 		"@kubb/plugin-zod": "^4.38.0",
 		"@sentry/rollup-plugin": "^5.3.0",
 		"@types/node": "^26.0.0",
+		"@types/semver": "^7.7.1",
 		"@vitest/coverage-v8": "^4.1.9",
 		"abstract-syntax-tree": "^2.22.0",
 		"cross-env": "^10.1.0",

package.json

@@ -34,6 +34,7 @@ const testDoubles = vi.hoisted(() => ({
 		cleanup: vi.fn(),
 		getShutdownPromise: vi.fn(),
 	})),
+	scheduleUpdateCheck: vi.fn(),
 	sentry: {
 		init: vi.fn(() => ({})),
 		setUser: vi.fn(),
@@ -59,6 +60,10 @@ vi.mock("./utils/graceful-shutdown.js", () => ({
 	installGracefulShutdown: testDoubles.installGracefulShutdown,
 }));
 
+vi.mock("./utils/version-check.js", () => ({
+	scheduleUpdateCheck: testDoubles.scheduleUpdateCheck,
+}));
+
 vi.mock("./utils/telemetry.js", () => ({
 	Sentry: testDoubles.sentry,
 	tracer: {
@@ -303,6 +308,7 @@ describe("Server entry", () => {
 				expect(createClient).not.toHaveBeenCalled();
 				expect(testDoubles.startActiveSpan).not.toHaveBeenCalled();
 				expect(testDoubles.installGracefulShutdown).not.toHaveBeenCalled();
+				expect(testDoubles.scheduleUpdateCheck).not.toHaveBeenCalled();
 
 				const anyStdioModule = stdioModule as { __transports?: unknown[] };
 				expect(anyStdioModule.__transports).toHaveLength(0);
@@ -337,6 +343,7 @@ describe("Server entry", () => {
 				expect(createClient).not.toHaveBeenCalled();
 				expect(testDoubles.startActiveSpan).not.toHaveBeenCalled();
 				expect(testDoubles.installGracefulShutdown).not.toHaveBeenCalled();
+				expect(testDoubles.scheduleUpdateCheck).not.toHaveBeenCalled();
 
 				const anyStdioModule = stdioModule as { __transports?: unknown[] };
 				expect(anyStdioModule.__transports).toHaveLength(0);
@@ -377,6 +384,29 @@ describe("Server entry", () => {
 			expect(testDoubles.connect.mock.invocationCallOrder[0]).toBeLessThan(
 				testDoubles.installGracefulShutdown.mock.invocationCallOrder[0] ?? 0,
 			);
+			expect(testDoubles.scheduleUpdateCheck).toHaveBeenCalledWith({
+				packageName: "hevy-mcp",
+				currentVersion: "dev",
+			});
+		});
+
+		it("schedules the update check only after connection succeeds", async () => {
+			process.env = {
+				...originalEnv,
+				HEVY_API_KEY: "test-api-key",
+			};
+			process.argv = originalArgv.slice(0, 2);
+			const events: string[] = [];
+			testDoubles.connect.mockImplementationOnce(async () => {
+				events.push("connected");
+			});
+			testDoubles.scheduleUpdateCheck.mockImplementationOnce(() => {
+				events.push("scheduled");
+			});
+
+			await runServer();
+
+			expect(events).toEqual(["connected", "scheduled"]);
 		});
 
 		it("prefers CLI --hevy-api-key argument over environment variable", async () => {
@@ -414,6 +444,7 @@ describe("Server entry", () => {
 			await expect(runServer()).rejects.toThrow("connect failed");
 			expect(testDoubles.connect).toHaveBeenCalled();
 			expect(testDoubles.installGracefulShutdown).not.toHaveBeenCalled();
+			expect(testDoubles.scheduleUpdateCheck).not.toHaveBeenCalled();
 			expect(testDoubles.span.setStatus).toHaveBeenCalledWith({ code: 2 });
 		});
 

src/index.test.ts

@@ -27,6 +27,7 @@ import { installGracefulShutdown } from "./utils/graceful-shutdown.js";
 import { createClient } from "./utils/hevyClient.js";
 import { createMcpClientLogger } from "./utils/mcp-client-logger.js";
 import { createInstrumentedStdioTransport } from "./utils/stdio-observability.js";
+import { scheduleUpdateCheck } from "./utils/version-check.js";
 
 const name = serviceName;
 const version = serviceVersion;
@@ -308,6 +309,10 @@ export async function runServer() {
 						}
 					},
 				);
+				scheduleUpdateCheck({
+					packageName: serviceName,
+					currentVersion: serviceVersion,
+				});
 				installGracefulShutdown({ target: server });
 
 				span.setStatus({ code: SpanStatusCode.OK });