hevy-coach 0.2.0 → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## 1.0.0 (unreleased)
+
+### Breaking
+
+- Node 22.18+ required.
+- `hevy-coach-http` requires `MCP_AUTH_TOKEN`, binds to `127.0.0.1` by default, and needs `MCP_ALLOWED_HOSTS` to bind elsewhere. CORS is off unless `MCP_ALLOWED_ORIGINS` lists browser origins.
+- `create-body-measurement` and `update-body-measurement` replaced by `log-body-measurement` (create or overwrite).
+- `create-routine` and `update-routine` take `folder_id` (snake_case). `update-routine` moves a routine when `folder_id` is given (null = "My Routines") and keeps the folder when it is omitted. `rpe` is no longer accepted on routine sets (Hevy rejects it).
+- Error results include Hevy's HTTP status, error code and message instead of a generic axios message.
+
+### Fixed
+
+- `get-exercise-progression` threw on live data: exercise history is flat (one row per set), not nested.
+- `get-workout` and `analyze-workout` returned "not found" for valid workouts because the response was assumed to be wrapped.
+- `batch-find-exercises` and `find-exercise` prefer an exact title match and rank partial matches by shortest title, so "Squat" no longer resolves to an arbitrary variant.
+- RPE inputs validated against Hevy's allowed values.
+- `get-exercise-progression` trends bodyweight exercises on max reps (was always "plateau") and reports a true all-time best; `progressionKg` is now `progression` with a `trendMetric` field.
+- `analyze-workout` judges "reps hit" on the weakest working set, not the mean; `get-training-summary` counts sessions per workout, not per exercise entry.
+- `find-exercise` matches muscle groups written with spaces ("upper back").
+- `create-exercise-template` invalidates the exercise cache so the new exercise is immediately findable.
+
+### Changed
+
+- Built on `@furkantanyol/hevy-client`; axios removed.
+- Coaching prompts moved to `prompts/` (`COACH.md`, `CHATGPT.md`, `GEMINI.md`).
+
+## 0.2.0 (2026-05-31)
+
+- Body measurement tools. Fixed exercise-history path, custom exercise body fields, routine folder handling.
+
+## 0.1.x
+
+- Initial MCP server with workout, routine, exercise and coaching tools.

package/README.md

@@ -1,30 +1,12 @@
-# HevyCoach
+# hevy-coach
 
-AI personal training system that connects to [Hevy](https://hevyapp.com) via MCP (Model Context Protocol). Not just another API wrapper — HevyCoach adds coaching intelligence on top of workout data.
+MCP server that turns an AI assistant into a strength coach with access to your [Hevy](https://hevyapp.com) account. Every read endpoint, routine and workout writes, and coaching tools built on top: workout-vs-plan analysis, exercise progression with estimated 1RM, training summaries, exercise name resolution.
 
-**What makes this different from existing Hevy MCP servers:** Other servers give you CRUD operations. HevyCoach adds the brain — workout analysis, progression tracking with Epley 1RM estimation, training summaries, and exercise search. Combined with the CLAUDE.md coaching prompt, it turns Claude into a full athletic coach covering strength, hypertrophy, VO2max, mobility, flexibility, and longevity.
+Requires Node 22.18+ and a Hevy API key (Hevy Settings → API).
 
-## What You Get
+## Install
 
-- **Complete athletic programming** — strength, hypertrophy, VO2max, mobility, flexibility, stamina, longevity
-- **Coaching intelligence** — workout analysis, progression tracking, automatic adaptation recommendations
-- **Auto-pushed to Hevy** — routines appear in your app, ready to log
-- **Daily briefings** — morning message with today's workout + conditioning + mobility
-- **Adaptive coaching** — reads your completed workouts and adjusts programming
-- **Weekly reviews** — volume tracking, PR highlights, conditioning adherence, program adjustments
-
-## Setup
-
-### Prerequisites
-
-- [Hevy Pro](https://hevyapp.com) subscription (required for API access)
-- API key from Hevy Settings → API
-- Node.js 18+
-- [Claude Desktop](https://claude.ai/download) (or any MCP-compatible client)
-
-### Quick Start (npx)
-
-Add to your Claude Desktop MCP config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
 
 ```json
 {
@@ -32,145 +14,59 @@ Add to your Claude Desktop MCP config (`~/Library/Application Support/Claude/cla
     "hevy-coach": {
       "command": "npx",
       "args": ["-y", "hevy-coach"],
-      "env": {
-        "HEVY_API_KEY": "your-hevy-api-key"
-      }
+      "env": { "HEVY_API_KEY": "your-hevy-api-key" }
     }
   }
 }
 ```
 
-Restart Claude Desktop. The tools appear in the MCP tools list.
-
-### Install from Source
+**Claude Code:**
 
 ```bash
-git clone https://github.com/furkantanyol/hevy-coach.git
-cd hevy-coach
-npm install
-npm run build
-```
-
-Then use the local path in your MCP config:
-
-```json
-{
-  "mcpServers": {
-    "hevy-coach": {
-      "command": "node",
-      "args": ["/absolute/path/to/hevy-coach/dist/cli.js"],
-      "env": {
-        "HEVY_API_KEY": "your-hevy-api-key"
-      }
-    }
-  }
-}
+claude mcp add hevy-coach -e HEVY_API_KEY=your-hevy-api-key -- npx -y hevy-coach
 ```
 
-### Add the Coaching Brain
-
-Create a Claude Project called **"HevyCoach"**:
-
-1. Open Claude Desktop → Projects → New Project
-2. Name it "HevyCoach"
-3. In Project Instructions, paste the contents of `CLAUDE.md`
-4. Add `training-history.md` as a project file
-
-### Start Training
-
-Open the HevyCoach project and say:
-
-> "I want to start training with you. Let's do the onboarding."
-
-Claude will ask about your body, training history, goals, and preferences. Then it generates your full program (strength + conditioning + mobility) and pushes routines to Hevy.
-
-### Daily Automation (Optional)
-
-Create two Claude Desktop scheduled tasks:
-
-**Morning briefing (7 AM):**
-> Read my HevyCoach program. Tell me today's workout with warmup, exercises, sets/reps/weights, conditioning if scheduled, and daily mobility drills.
-
-**Evening sync (11:59 PM):**
-> Fetch my latest Hevy workout. Analyze it against today's plan. Summarize performance, note progressions or missed targets, and adjust upcoming sessions if needed.
+Then add the coaching persona from the repository's `prompts/COACH.md` to your project instructions and say "let's do the onboarding".
 
 ## Tools
 
-### User Tools
-| Tool | Description |
-|------|-------------|
-| `get-user-info` | Get authenticated user's profile (ID, name, Hevy URL) |
-
-### Workout Tools
-| Tool | Description |
-|------|-------------|
-| `get-workouts` | List recent workouts (paginated) |
-| `get-workout` | Get specific workout by ID |
-| `create-workout` | Create a new workout with exercises and sets |
-| `update-workout` | Update an existing workout by ID |
-| `get-workout-count` | Total logged workouts |
-| `get-workout-events` | Track changes since a date |
-
-### Routine Tools
-| Tool | Description |
-|------|-------------|
-| `get-routines` | List saved routines |
-| `get-routine` | Get routine details |
-| `create-routine` | Push routine to Hevy |
-| `update-routine` | Modify existing routine |
-| `get-routine-folder` | Get a single routine folder by ID |
-| `get-routine-folders` | List routine folders |
-| `create-routine-folder` | Create folder |
-
-### Exercise Tools
-| Tool | Description |
-|------|-------------|
-| `get-exercise-templates` | Browse exercise library |
-| `get-exercise-template` | Get exercise details |
-| `get-exercise-history` | Past performance data |
-| `create-exercise-template` | Create custom exercise |
-
-### Coaching Tools
-| Tool | Description |
-|------|-------------|
-| `analyze-workout` | Compare completed vs planned workout. Returns per-exercise analysis with progression recommendations. |
-| `get-training-summary` | Aggregate last N workouts: volume, frequency, consistency, duration trends. |
-| `get-exercise-progression` | Track exercise over time: weight/rep trends, estimated 1RM (Epley), plateau detection. |
-| `find-exercise` | Search exercises by name or muscle group. Returns compact id + title pairs. |
-| `batch-find-exercises` | Look up multiple exercises at once. Loads library once, returns map of query → match. Use this when creating routines. |
-
-## Architecture
-
-```
-hevy-coach/
-├── src/
-│   ├── index.ts           # Server factory
-│   ├── cli.ts             # CLI entry point (stdio transport)
-│   ├── tools/
-│   │   ├── users.ts       # User profile
-│   │   ├── workouts.ts    # Workout CRUD
-│   │   ├── routines.ts    # Routine CRUD
-│   │   ├── exercises.ts   # Exercise templates
-│   │   └── coaching.ts    # Coaching intelligence (the differentiator)
-│   └── utils/
-│       ├── hevy-client.ts # Hevy API client
-│       └── response.ts    # MCP response helpers
-├── CLAUDE.md              # Coaching brain + user profile + program
-├── training-history.md    # Long-term tracking template
-└── package.json
-```
-
-## Development
+| Tool | Purpose |
+|---|---|
+| `get-user-info` | Profile |
+| `get-workouts`, `get-workout`, `get-workout-count`, `get-workout-events` | Logged workouts and change feed |
+| `create-workout`, `update-workout` | Log or replace a workout |
+| `get-routines`, `get-routine`, `create-routine`, `update-routine` | Routines (templates) |
+| `get-routine-folders`, `get-routine-folder`, `create-routine-folder` | Folders |
+| `get-exercise-templates`, `get-exercise-template`, `create-exercise-template` | Exercise library |
+| `get-exercise-history` | Every set of one exercise |
+| `get-body-measurements`, `get-body-measurement`, `log-body-measurement` | Body measurements |
+| `analyze-workout` | Completed workout vs plan → per-exercise recommendation |
+| `get-training-summary` | Volume, frequency, duration over the last N workouts |
+| `get-exercise-progression` | Session-by-session weight, reps, Epley 1RM, trend |
+| `find-exercise`, `batch-find-exercises` | Resolve names to template ids |
+
+Errors come back with Hevy's HTTP status, error code and message so the assistant can react (e.g. `routine-limit-exceeded` on free accounts).
+
+## HTTP transport
+
+For assistants that connect over HTTP (ChatGPT, Gemini), run `hevy-coach-http`. It proxies your Hevy account, so it is locked down by default:
+
+| Variable | Required | Meaning |
+|---|---|---|
+| `HEVY_API_KEY` | yes | Hevy API key |
+| `MCP_AUTH_TOKEN` | yes | Bearer token clients must send. Use a long random secret. |
+| `PORT` | no | Default 3000 |
+| `HOST` | no | Default `127.0.0.1`. Anything else requires `MCP_ALLOWED_HOSTS`. |
+| `MCP_ALLOWED_HOSTS` | when exposed | Comma-separated hostnames accepted in `Host` (DNS-rebinding protection) |
+| `MCP_ALLOWED_ORIGINS` | no | Comma-separated browser origins allowed by CORS. Off otherwise. |
 
 ```bash
-npm run build    # Compile TypeScript
-npm run dev      # Watch mode
+HEVY_API_KEY=... MCP_AUTH_TOKEN=$(openssl rand -hex 32) npx -p hevy-coach hevy-coach-http
+# MCP endpoint: http://127.0.0.1:3000/mcp   Health: /health
 ```
 
-## Credits
-
-Inspired by [chrisdoc/hevy-mcp](https://github.com/chrisdoc/hevy-mcp) and [tomtorggler/hevy-mcp-server](https://github.com/tomtorggler/hevy-mcp-server). Built from scratch with coaching intelligence as the core focus.
+Put it behind HTTPS (a tunnel or reverse proxy) before pointing a hosted assistant at it.
 
 ## License
 
-MIT — Furkan Tanyol
+MIT

package/dist/cli.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { n as createServer } from "./src-BxQx3e_u.mjs";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+//#region src/cli.ts
+const apiKey = process.env.HEVY_API_KEY;
+if (!apiKey) {
+	console.error("HEVY_API_KEY environment variable is required.");
+	console.error("Get your API key from Hevy Settings → API.");
+	process.exit(1);
+}
+createServer({ apiKey }).connect(new StdioServerTransport()).catch((error) => {
+	console.error("Failed to start hevy-coach:", error);
+	process.exit(1);
+});
+//#endregion
+export {};

package/dist/http.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+import { n as createServer } from "./src-BxQx3e_u.mjs";
+import { randomUUID, timingSafeEqual } from "node:crypto";
+import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+//#region src/utils/auth.ts
+/** Constant-time bearer check. An empty or missing header never matches. */
+function isAuthorized(authorizationHeader, token) {
+	const presented = Buffer.from((authorizationHeader ?? "").replace(/^Bearer\s+/i, ""));
+	const expected = Buffer.from(token);
+	if (presented.length === 0 || presented.length !== expected.length) return false;
+	return timingSafeEqual(presented, expected);
+}
+//#endregion
+//#region src/http.ts
+const log = (message) => console.error(`[hevy-coach] ${message}`);
+const fail = (message) => {
+	log(message);
+	process.exit(1);
+};
+const DEFAULT_PORT = 3e3;
+const LOCALHOST = "127.0.0.1";
+const LOCALHOST_ALIASES = /* @__PURE__ */ new Set([
+	LOCALHOST,
+	"localhost",
+	"::1"
+]);
+const csv = (value) => (value ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+const apiKey = process.env.HEVY_API_KEY || fail("HEVY_API_KEY environment variable is required.");
+const authToken = process.env.MCP_AUTH_TOKEN || fail("MCP_AUTH_TOKEN is required: this server proxies your Hevy account. Generate a long random secret.");
+if (authToken.length < 32) fail(`MCP_AUTH_TOKEN must be at least 32 characters, e.g. openssl rand -hex 32.`);
+const port = Number(process.env.PORT ?? DEFAULT_PORT);
+if (!Number.isInteger(port) || port <= 0) fail(`PORT must be a positive integer, got "${process.env.PORT}".`);
+const host = process.env.HOST ?? LOCALHOST;
+const allowedHosts = csv(process.env.MCP_ALLOWED_HOSTS);
+const allowedOrigins = csv(process.env.MCP_ALLOWED_ORIGINS);
+const isLocal = LOCALHOST_ALIASES.has(host);
+if (!isLocal && allowedHosts.length === 0) fail(`HOST=${host} exposes the server beyond localhost; set MCP_ALLOWED_HOSTS to your public hostname(s).`);
+const app = createMcpExpressApp(isLocal ? { host } : {
+	host,
+	allowedHosts
+});
+app.use((req, res, next) => {
+	const origin = req.headers.origin;
+	if (origin && allowedOrigins.includes(origin)) {
+		res.setHeader("Access-Control-Allow-Origin", origin);
+		res.setHeader("Vary", "Origin");
+		res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization, mcp-session-id");
+		res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
+		res.setHeader("Access-Control-Expose-Headers", "mcp-session-id");
+	}
+	if (req.method === "OPTIONS") {
+		res.sendStatus(204);
+		return;
+	}
+	next();
+});
+function bearerAuth(req, res, next) {
+	if (isAuthorized(req.headers.authorization, authToken)) {
+		next();
+		return;
+	}
+	res.status(401).json({ error: "Unauthorized" });
+}
+const transports = /* @__PURE__ */ new Map();
+const jsonRpcError = (res, status, message) => res.status(status).json({
+	jsonrpc: "2.0",
+	error: {
+		code: -32e3,
+		message
+	},
+	id: null
+});
+function existingTransport(req, res) {
+	const sessionId = req.headers["mcp-session-id"];
+	const transport = typeof sessionId === "string" ? transports.get(sessionId) : void 0;
+	if (!transport) jsonRpcError(res, 400, "Missing or unknown mcp-session-id");
+	return transport;
+}
+async function startSession(req, res) {
+	const transport = new StreamableHTTPServerTransport({
+		sessionIdGenerator: () => randomUUID(),
+		onsessioninitialized: (sid) => {
+			transports.set(sid, transport);
+			log(`session started ${sid}`);
+		}
+	});
+	transport.onclose = () => {
+		if (transport.sessionId) {
+			transports.delete(transport.sessionId);
+			log(`session closed ${transport.sessionId}`);
+		}
+	};
+	await createServer({ apiKey }).connect(transport);
+	await transport.handleRequest(req, res, req.body);
+}
+app.get("/health", (_req, res) => {
+	res.json({
+		status: "ok",
+		server: "hevy-coach"
+	});
+});
+app.post("/mcp", bearerAuth, async (req, res) => {
+	try {
+		if (req.headers["mcp-session-id"]) await existingTransport(req, res)?.handleRequest(req, res, req.body);
+		else if (isInitializeRequest(req.body)) await startSession(req, res);
+		else jsonRpcError(res, 400, "Bad Request: missing session ID or not an initialize request");
+	} catch (error) {
+		log(`POST /mcp failed: ${String(error)}`);
+		if (!res.headersSent) jsonRpcError(res, 500, "Internal server error");
+	}
+});
+for (const method of ["get", "delete"]) app[method]("/mcp", bearerAuth, async (req, res) => {
+	const transport = existingTransport(req, res);
+	if (!transport) return;
+	try {
+		await transport.handleRequest(req, res);
+	} catch (error) {
+		log(`${method.toUpperCase()} /mcp failed: ${String(error)}`);
+		if (!res.headersSent) res.status(500).send("Internal server error");
+	}
+});
+app.listen(port, host, () => {
+	log(`listening on http://${host}:${port}/mcp (bearer auth on)`);
+}).on("error", (error) => fail(`could not listen on ${host}:${port}: ${error.message}`));
+for (const signal of ["SIGINT", "SIGTERM"]) process.on(signal, async () => {
+	log("shutting down");
+	await Promise.all([...transports.values()].map((t) => t.close().catch(() => void 0)));
+	process.exit(0);
+});
+//#endregion
+export {};

package/dist/index.d.mts

@@ -0,0 +1,6 @@
+import { HevyClientOptions } from "@furkantanyol/hevy-client";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+//#region src/index.d.ts
+export declare const SERVER_VERSION = "1.0.0";
+export declare function createServer(options: HevyClientOptions): McpServer;
+//#endregion

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { n as createServer, t as SERVER_VERSION } from "./src-BxQx3e_u.mjs";
+export { SERVER_VERSION, createServer };