@trainheroic-unofficial/athlete-mcp 0.4.0 → 0.4.2

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";
 /**
@@ -848,6 +859,45 @@ async function logAthleteSet(client, args) {
 		exercisesLogged
 	};
 }
+/**
+* POST /v5/programWorkouts/personal — create a personal workout session for a given date.
+* Returns the key ids: workoutId (needed for addExercisesToWorkout), programWorkoutId,
+* savedWorkoutId, and groupId.
+*/
+async function createPersonalWorkout(client, date) {
+	const res = await client.request("POST", "/v5/programWorkouts/personal", { body: { date } });
+	if (!res.ok) throw new Error(`Create personal workout failed (HTTP ${res.status}).`);
+	if (!isRecord(res.data)) throw new Error("Unexpected response from /v5/programWorkouts/personal.");
+	const pw = isRecord(res.data.programWorkout) ? res.data.programWorkout : null;
+	const sw = isRecord(res.data.savedWorkout) ? res.data.savedWorkout : null;
+	if (!pw || !sw) throw new Error("Missing programWorkout or savedWorkout in response.");
+	const programWorkoutId = coerceInt(pw.id);
+	const workoutId = coerceInt(pw.workoutId);
+	const savedWorkoutId = coerceInt(sw.id);
+	const groupId = coerceInt(sw.group_id);
+	if (!programWorkoutId || !workoutId || !savedWorkoutId || !groupId) throw new Error("Could not parse required ids from personal workout response.");
+	return {
+		programWorkoutId,
+		workoutId,
+		savedWorkoutId,
+		groupId,
+		date: typeof pw.date === "string" ? pw.date : date
+	};
+}
+/**
+* PUT /v5/personalCalendar/workouts/{workoutId}/addExercises — add exercises to a personal
+* workout. Returns saved workout set objects: each top-level `id` is a savedWorkoutSetId
+* and `savedWorkoutSetExercises[].id` is a savedWorkoutSetExerciseId, both needed by
+* logAthleteSet.
+*/
+async function addExercisesToWorkout(client, workoutId, exercises) {
+	const res = await client.request("PUT", `/v5/personalCalendar/workouts/${workoutId}/addExercises`, { body: {
+		exercises,
+		circuits: []
+	} });
+	if (!res.ok) throw new Error(`Add exercises to workout failed (HTTP ${res.status}).`);
+	return res.data;
+}
 /** Flatten `/v5/exercises/{id}/history` into PRs + a session time-series. */
 function presentExerciseHistory(detail) {
 	return {
@@ -980,6 +1030,41 @@ function registerExerciseTools(server, ctx, userId) {
 		annotations: READ
 	}, ({ exerciseId, date }) => attempt(async () => jsonResult(await fetchExerciseStats(ctx.client, toId(exerciseId), await userId(), date))));
 }
+/** Create a personal workout session and add exercises to it. */
+function registerSessionTools(server, ctx) {
+	server.registerTool("athlete_session_create", {
+		title: "Create personal workout session",
+		description: "Create a new personal workout session for a given YYYY-MM-DD date on the athlete's personal calendar. Returns programWorkoutId, workoutId (pass to athlete_session_add_exercises), savedWorkoutId, groupId, and date.",
+		inputSchema: { date: dateString },
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			openWorldHint: true
+		}
+	}, ({ date }) => attempt(async () => jsonResult(await createPersonalWorkout(ctx.client, date))));
+	server.registerTool("athlete_session_add_exercises", {
+		title: "Add exercises to a personal workout session",
+		description: "Add one or more exercises to a personal workout session. Get workoutId from athlete_session_create. Each item needs an exerciseId (from athlete_exercises) and a 1-based order. Returns saved workout set objects: each top-level id is a savedWorkoutSetId and savedWorkoutSetExercises[].id is a savedWorkoutSetExerciseId — both needed for athlete_log_set.",
+		inputSchema: {
+			workoutId: idParam,
+			exercises: z.array(z.object({
+				exerciseId: idParam,
+				order: z.number().int().positive()
+			})).min(1)
+		},
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			openWorldHint: true
+		}
+	}, ({ workoutId, exercises }) => attempt(async () => {
+		const mapped = exercises.map((e) => ({
+			exerciseId: toId(e.exerciseId),
+			order: e.order
+		}));
+		return jsonResult(await addExercisesToWorkout(ctx.client, toId(workoutId), mapped), { hint: "Each top-level id is a savedWorkoutSetId; savedWorkoutSetExercises[].id is the savedWorkoutSetExerciseId for athlete_log_set." });
+	}));
+}
 /** The gated set-logging write. */
 function registerLogTool(server, ctx) {
 	server.registerTool("athlete_log_set", {
@@ -1030,9 +1115,13 @@ function registerAthleteTrainingTools(server, ctx) {
 	};
 	registerProfileTools(server, ctx, whoami, userId);
 	registerExerciseTools(server, ctx, userId);
+	registerSessionTools(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;
@@ -1044,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.0",
+  "version": "0.4.2",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -21,8 +21,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.4.3",
-    "@trainheroic-unofficial/core": "0.4.0",
-    "@trainheroic-unofficial/js": "0.4.0"
+    "@trainheroic-unofficial/core": "0.4.2",
+    "@trainheroic-unofficial/js": "0.4.2"
   },
   "devDependencies": {
     "@types/node": "^26.0.0",