@trainheroic-unofficial/athlete-mcp 0.4.1 → 0.5.0

package/README.md

@@ -1,13 +1,17 @@
 # @trainheroic-unofficial/athlete-mcp
 
-Local single-user MCP server for a TrainHeroic **athlete**. Runs on your machine over stdio; credentials come from the environment.
+Local single-user [MCP](https://modelcontextprotocol.io) server for a TrainHeroic **athlete** — it exposes one [TrainHeroic](https://www.trainheroic.com) athlete's own training to an AI assistant (Claude Code, Claude Desktop, or any MCP client) as callable tools. It runs on your machine and speaks the MCP stdio transport, so the assistant launches it as a subprocess.
 
-It exposes the logged-in athlete's own training — scheduled and completed workouts, per-exercise history, PRs, working maxes, and lifetime totals — plus a confirmation-gated workout-logging write. For coaching (rosters, teams, programs, messaging), use [`@trainheroic-unofficial/coach-mcp`](../coach-mcp). For the hosted version (no install, OAuth login, both surfaces), see the [root README](../../README.md).
+It reads two required environment variables, `TRAINHEROIC_EMAIL` and `TRAINHEROIC_PASSWORD` — your existing TrainHeroic login. These are your real credentials in plaintext; the config below puts them in a file or shell history, so treat them as secrets.
+
+It exposes the logged-in athlete's own training — scheduled and completed workouts, per-exercise history, PRs (personal records), working maxes, and lifetime totals — plus one confirmation-gated write that logs a completed set. For coaching (rosters, teams, programs, messaging), use [`@trainheroic-unofficial/coach-mcp`](../coach-mcp). For a hosted version that holds credentials server-side behind OAuth and gives a coach login both the athlete and coaching tools, see the [root README](../../README.md).
 
 ---
 
 ## Install
 
+Needs Node (>= 18); the commands below fetch the package with `npx` on first run.
+
 ### Claude Code
 
 ```bash
@@ -19,7 +23,11 @@ claude mcp add trainheroic-athlete \
 
 ### Claude Desktop / `.mcp.json` / other stdio clients
 
-```jsonc
+Put this in your client's MCP config — for Claude Desktop that's `claude_desktop_config.json`
+(macOS: `~/Library/Application Support/Claude/`; Windows: `%APPDATA%\Claude\`); for a
+project-scoped Claude Code setup it's `.mcp.json` at the repo root.
+
+```json
 {
   "mcpServers": {
     "trainheroic-athlete": {
@@ -27,37 +35,49 @@ claude mcp add trainheroic-athlete \
       "args": ["-y", "@trainheroic-unofficial/athlete-mcp"],
       "env": {
         "TRAINHEROIC_EMAIL": "athlete@example.com",
-        "TRAINHEROIC_PASSWORD": "yourpassword",
-      },
-    },
-  },
+        "TRAINHEROIC_PASSWORD": "yourpassword"
+      }
+    }
+  }
 }
 ```
 
-A coach account works here too: a coach login also carries athlete scope, so it can read its own training through these tools.
+A coach account works here too: a TrainHeroic coach account also has its own athlete-side data, so it can read its own training through these tools. After it connects, ask the assistant something like "show my recent workouts" to confirm the tools are available.
 
 ---
 
 ## Tools
 
+All read-only except `athlete_log_set`. The assistant fills in each tool's parameters (dates
+are `YYYY-MM-DD`); your MCP client shows the full schema for each.
+
 - `athlete_whoami` — identity (id, name, roles)
 - `athlete_profile` — lifetime totals + profile
 - `athlete_prefs` — notification/display preferences
-- `athlete_workouts` — scheduled + completed workouts in a date range (flattened)
+- `athlete_workouts` — scheduled + completed workouts in a date range, flattened into one list
 - `athlete_exercises` — search the exercises you've logged
 - `athlete_exercise_history` — per-exercise PRs + dated session history
 - `athlete_personal_records` — exercise personal records
 - `athlete_exercise_stats` — last performance + PR as of a date
 - `athlete_working_maxes` — working max per exercise
 - `athlete_leaderboard` — benchmark/test workout leaderboard
-- `athlete_log_set` — gated: log completed set results to your (coach-visible) training log
+
+**Write (confirmation-gated):**
+
+- `athlete_log_set` — logs completed set results to your training log. This is a real write
+  that your coach can see. It confirms before running: the server asks the client to confirm,
+  falling back to an explicit `confirm: true` argument when the client can't prompt.
 
 ---
 
 ## Develop
 
+Run `pnpm install` once at the repo root (Node >= 22, pnpm 10), then from this package. The
+`pnpm start`/`pnpm inspect` commands need `TRAINHEROIC_EMAIL` and `TRAINHEROIC_PASSWORD`
+exported in your shell. "MCP Inspector" is the [official MCP debugging UI](https://github.com/modelcontextprotocol/inspector).
+
 ```bash
-pnpm start       # run from source (needs TRAINHEROIC_EMAIL and TRAINHEROIC_PASSWORD)
+pnpm start       # run from source
 pnpm inspect     # MCP Inspector UI against the source server
 pnpm build       # tsdown → dist/server.mjs
 pnpm typecheck

package/dist/server.mjs

@@ -415,6 +415,17 @@ async function confirmGate(server, requestId, message, confirmArg) {
 	}
 }
 //#endregion
+//#region ../core/src/instructions.ts
+/**
+* Server-level guidance passed as the MCP `instructions` string. The host model receives it
+* in the initialize result and treats it like a system hint. Its job is to stop tool-layer
+* implementation details from leaking into user-facing replies: by default a model narrates
+* capability using the raw snake_case tool name (e.g. `athlete_session_create`), and the tool
+* descriptions here reference each other by name to drive correct chaining, which primes that
+* leak further. This tells the host to keep that wiring internal and speak in app terms.
+*/
+const SERVER_INSTRUCTIONS = "Speak to the user in plain, everyday language about their training. Describe what you are doing in the TrainHeroic app's own terms (for example, say you are creating a workout rather than naming a tool). Do not surface internal tool names (the snake_case identifiers such as athlete_session_create), raw parameter names, or numeric ids in your replies unless the user explicitly asks for them; they are implementation details. The tool descriptions cross-reference each other by name only so you can chain them correctly. Keep that wiring to yourself.";
+//#endregion
 //#region ../js/src/auth.ts
 const AUTH_URL = "https://apis.trainheroic.com/auth";
 /**
@@ -1108,6 +1119,9 @@ function registerAthleteTrainingTools(server, ctx) {
 	registerLogTool(server, ctx);
 }
 //#endregion
+//#region package.json
+var version = "0.4.1";
+//#endregion
 //#region src/server.ts
 async function main() {
 	const email = process.env.TRAINHEROIC_EMAIL;
@@ -1119,8 +1133,8 @@ async function main() {
 	const client = new TrainHeroicClient(email, password);
 	const server = new McpServer({
 		name: "trainheroic-athlete",
-		version: "0.1.0"
-	});
+		version
+	}, { instructions: SERVER_INSTRUCTIONS });
 	registerAthleteTrainingTools(server, { client });
 	await server.connect(new StdioServerTransport());
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trainheroic-unofficial/athlete-mcp",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -21,8 +21,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.4.3",
-    "@trainheroic-unofficial/js": "0.4.1",
-    "@trainheroic-unofficial/core": "0.4.1"
+    "@trainheroic-unofficial/core": "0.5.0",
+    "@trainheroic-unofficial/js": "0.5.0"
   },
   "devDependencies": {
     "@types/node": "^26.0.0",