feat: add server tool-selection instructions (#563)

Co-authored-by: CharlieHelps <charlie@charlielabs.ai>

Author: charliecreates[bot]

.changeset/bright-otters-guide.md

@@ -0,0 +1,6 @@
+---
+"hevy-mcp": patch
+---
+
+Provide MCP clients with concise server-level guidance for safe tool selection,
+recommended workout workflows, pagination, retries, and API-key setup.

src/index.test.ts

@@ -173,13 +173,47 @@ describe("Server entry", () => {
 		);
 	});
 
-	it("advertises logging capability and injects one client logger", () => {
+	it("advertises logging, rich instructions, and one client logger", () => {
 		createServer({ config: { apiKey: "test-key" } });
 
 		expect(testDoubles.mcpServerConstructor).toHaveBeenCalledWith(
 			{ name: "hevy-mcp", version: "dev" },
-			{ capabilities: { logging: {} } },
+			{
+				capabilities: { logging: {} },
+				instructions: expect.any(String),
+			},
 		);
+
+		const serverOptions = testDoubles.mcpServerConstructor.mock.calls[0]?.[1];
+		expect(serverOptions).toBeDefined();
+		if (
+			!serverOptions ||
+			typeof serverOptions !== "object" ||
+			!("instructions" in serverOptions) ||
+			typeof serverOptions.instructions !== "string"
+		) {
+			throw new Error("MCP server instructions were not provided");
+		}
+
+		const instructions = serverOptions.instructions;
+		expect(instructions.trim()).not.toBe("");
+		expect(instructions).toMatch(/Hevy[\s\S]*workout-tracking data/i);
+		expect(instructions).toMatch(/HEVY_API_KEY/);
+		expect(instructions).toMatch(/get-\*[\s\S]*search-\*[\s\S]*read-only/i);
+		expect(instructions).toMatch(/create-\*[\s\S]*update-\*[\s\S]*mutate/i);
+		expect(instructions).toMatch(/delete[\s\S]*not available/i);
+		expect(instructions).toMatch(/search[\s\S]*templates[\s\S]*template IDs/i);
+		expect(instructions).toMatch(/routine[\s\S]*actual completed sets/i);
+		expect(instructions).toMatch(/page 1/i);
+		expect(instructions).toMatch(/pageSize[\s\S]*10/i);
+		expect(instructions).toMatch(/get-exercise-templates[\s\S]*100/i);
+		expect(instructions).toMatch(/HTTP 429/i);
+		expect(instructions).toMatch(/read requests[\s\S]*retry automatically/i);
+		expect(instructions).toMatch(/write requests[\s\S]*do not/i);
+		// A 6,000-character cap is conservative for the sub-2,000-token goal;
+		// character count is intentionally not treated as an exact token count.
+		expect(instructions.length).toBeLessThan(6_000);
+
 		expect(createClient).toHaveBeenCalledWith(
 			"test-key",
 			"https://api.hevyapp.com",

src/index.ts

@@ -30,6 +30,38 @@ import { createInstrumentedStdioTransport } from "./utils/stdio-observability.js
 const name = serviceName;
 const version = serviceVersion;
 
+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]",
@@ -144,7 +176,10 @@ function buildServer(apiKey: string) {
 						name,
 						version,
 					},
-					{ capabilities: { logging: {} } },
+					{
+						capabilities: { logging: {} },
+						instructions: SERVER_INSTRUCTIONS,
+					},
 				);
 				const server = Sentry.wrapMcpServerWithSentry(baseServer);
 				const clientLogger = createMcpClientLogger(server);