@trainheroic-unofficial/athlete-mcp 0.6.0 → 0.6.2

package/README.md

@@ -72,7 +72,7 @@ are `YYYY-MM-DD`); your MCP client shows the full schema for each.
 
 ## Develop
 
-Run `pnpm install` once at the repo root (Node >= 22, pnpm 10), then from this package. The
+Run `pnpm install` once at the repo root (Node >= 24, pnpm 11), 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).
 

package/dist/server.mjs

@@ -684,35 +684,134 @@ function prescribedSets(ex) {
 	}
 	return out;
 }
-function presentExercise(ex) {
+/**
+* The per-set values the athlete actually logged, read from a saved-copy exercise. A set
+* counts as performed only when its `param_{i}_made` flag is 1: the saved copy pre-fills the
+* `param_N_data` slots with the prescription, so the presence of data alone does not mean a
+* set was done. `param_{i}_made` is the same per-set flag the logging write sets, and is the
+* only reliable signal (the `completed` flags are often left at 0 on a logged session).
+*/
+function performedSets(ex) {
+	const out = [];
+	for (let i = 1; i <= SLOTS; i += 1) {
+		if (coerceInt(ex[`param_${i}_made`]) !== 1) continue;
+		const p1 = ex[`param_1_data_${i}`];
+		const p2 = ex[`param_2_data_${i}`];
+		const has1 = nonEmpty(p1);
+		const has2 = nonEmpty(p2);
+		if (has1 && has2) out.push(`${p1} @ ${p2}`);
+		else if (has1) out.push(String(p1));
+		else if (has2) out.push(`@ ${p2}`);
+	}
+	return out;
+}
+function presentExercise(ex, performedById) {
 	const instruction = typeof ex.instruction === "string" && ex.instruction !== "" ? ex.instruction : null;
+	const id = coerceInt(ex.id);
 	return {
 		exerciseId: coerceInt(ex.exercise_id),
 		title: typeof ex.title === "string" ? ex.title : "",
 		instruction,
 		units: exerciseUnits(ex.param_1_type, ex.param_2_type),
-		prescribed: prescribedSets(ex)
+		prescribed: prescribedSets(ex),
+		performed: (id !== null ? performedById.get(id) : void 0) ?? []
 	};
 }
-function presentBlock(set) {
+function presentBlock(set, performedById) {
 	const exercises = Array.isArray(set.workoutSetExercises) ? set.workoutSetExercises : [];
 	return {
 		order: coerceInt(set.order) ?? 0,
 		title: typeof set.title === "string" && set.title !== "" ? set.title : null,
 		instruction: typeof set.instruction === "string" && set.instruction !== "" ? set.instruction : null,
 		isTest: coerceInt(set.is_test) === 1,
-		exercises: exercises.filter(isRecord).map(presentExercise)
+		exercises: exercises.filter(isRecord).map((ex) => presentExercise(ex, performedById))
 	};
 }
 function str(v) {
 	return typeof v === "string" && v !== "" ? v : null;
 }
-/** Flatten one `/3.0/athlete/programworkout/range` item into a readable workout. */
+/** Every logged set (programmed + athlete-added) in the saved copy, paired with its exercises. */
+function savedSets(saved) {
+	const out = [];
+	for (const key of ["workoutSets", "addedWorkoutSets"]) {
+		const sets = Array.isArray(saved[key]) ? saved[key] : [];
+		for (const set of sets) {
+			if (!isRecord(set)) continue;
+			const exercises = (Array.isArray(set.workoutSetExercises) ? set.workoutSetExercises : []).filter(isRecord);
+			out.push({
+				set,
+				exercises
+			});
+		}
+	}
+	return out;
+}
+/**
+* Map each prescription exercise id to the per-set values the athlete logged. In the saved
+* copy, `workout_set_exercise_id` points back at the prescription exercise's `id`, and the
+* entered values live in the same `param_N_data` slots as a prescription — so the
+* prescription reader works on them unchanged.
+*/
+function performedByExerciseId(sets) {
+	const map = /* @__PURE__ */ new Map();
+	for (const { exercises } of sets) for (const ex of exercises) {
+		const id = coerceInt(ex.workout_set_exercise_id);
+		if (id === null) continue;
+		const values = performedSets(ex);
+		if (values.length > 0) map.set(id, values);
+	}
+	return map;
+}
+/** Present a logged set straight from the saved copy (athlete-added or personal work). */
+function presentSavedBlock(set, exercises) {
+	return {
+		order: coerceInt(set.order) ?? 0,
+		title: typeof set.title === "string" && set.title !== "" ? set.title : null,
+		instruction: typeof set.instruction === "string" && set.instruction !== "" ? set.instruction : null,
+		isTest: coerceInt(set.is_test) === 1,
+		exercises: exercises.map((ex) => ({
+			exerciseId: coerceInt(ex.exercise_id),
+			title: typeof ex.exercise_title === "string" ? ex.exercise_title : "",
+			instruction: typeof ex.instruction === "string" && ex.instruction !== "" ? ex.instruction : null,
+			units: exerciseUnits(ex.param_1_type, ex.param_2_type),
+			prescribed: [],
+			performed: performedSets(ex)
+		}))
+	};
+}
+/**
+* Flatten one `/3.0/athlete/programworkout/range` item into a readable workout, merging the
+* prescription (`summarizedSavedWorkout.workout`) with what the athlete logged
+* (`summarizedSavedWorkout.saved_workout`). Each exercise carries both its `prescribed` and
+* `performed` sets; athlete-added/personal work that has no prescription is appended as its
+* own blocks. No `raw` is needed to see logged results.
+*/
 function presentAthleteWorkout(raw) {
 	const rec = raw;
 	const ssw = isRecord(rec.summarizedSavedWorkout) ? rec.summarizedSavedWorkout : {};
 	const workout = isRecord(ssw.workout) ? ssw.workout : {};
-	const sets = Array.isArray(workout.workoutSets) ? workout.workoutSets : [];
+	const saved = isRecord(ssw.saved_workout) ? ssw.saved_workout : {};
+	const prescriptionSets = (Array.isArray(workout.workoutSets) ? workout.workoutSets : []).filter(isRecord);
+	const logged = savedSets(saved);
+	const performedById = performedByExerciseId(logged);
+	const blocks = prescriptionSets.map((s) => presentBlock(s, performedById)).sort((a, b) => a.order - b.order);
+	const prescribedIds = /* @__PURE__ */ new Set();
+	for (const s of prescriptionSets) {
+		const exs = Array.isArray(s.workoutSetExercises) ? s.workoutSetExercises : [];
+		for (const ex of exs) {
+			if (!isRecord(ex)) continue;
+			const id = coerceInt(ex.id);
+			if (id !== null) prescribedIds.add(id);
+		}
+	}
+	for (const { set, exercises } of logged) {
+		const extra = exercises.filter((ex) => {
+			if (performedSets(ex).length === 0) return false;
+			const id = coerceInt(ex.workout_set_exercise_id);
+			return id === null || !prescribedIds.has(id);
+		});
+		if (extra.length > 0) blocks.push(presentSavedBlock(set, extra));
+	}
 	return {
 		id: coerceInt(rec.id),
 		date: str(rec.date) ?? "",
@@ -720,12 +819,24 @@ function presentAthleteWorkout(raw) {
 		program: str(rec.program_title),
 		team: str(rec.team_title),
 		instruction: str(workout.instruction),
-		blocks: sets.filter(isRecord).map(presentBlock).sort((a, b) => a.order - b.order)
+		logged: blocks.some((b) => b.exercises.some((e) => e.performed.length > 0)),
+		blocks
 	};
 }
 function presentAthleteWorkouts(list) {
 	return list.map(presentAthleteWorkout);
 }
+/**
+* Narrow a presented workout list for the common "what did I actually do" reads. `loggedOnly`
+* keeps only workouts the athlete logged a set on (the reliable signal, not the API's
+* completion flag). `limit` keeps the most recent N by date (newest first). Both are pure
+* post-filters over the presented view; the raw API path is left untouched.
+*/
+function selectWorkouts(list, opts = {}) {
+	let out = opts.loggedOnly === true ? list.filter((w) => w.logged) : [...list];
+	if (opts.limit !== void 0) out = [...out].sort((a, b) => a.date < b.date ? 1 : a.date > b.date ? -1 : 0).slice(0, opts.limit);
+	return out;
+}
 const MAX_PARAM_SLOTS = 10;
 /**
 * Build the body for `PUT /1.0/athlete/savedworkoutsetexercise/{id}`. The body uses
@@ -919,6 +1030,27 @@ function presentExerciseHistory(detail) {
 	};
 }
 //#endregion
+//#region ../core/src/history.ts
+/**
+* Trim a presented exercise history's session time-series to an inclusive YYYY-MM-DD window.
+* The `liftPRs` board stays all-time (PRs are not a windowed concept). Dates compare as their
+* first 10 chars so both "YYYY-MM-DD" and "YYYY-MM-DDThh:mm" values filter correctly. Shared by
+* the athlete's own history tool and the coach's per-roster-athlete history tool.
+*/
+function historyInRange(presented, since, until) {
+	if (since === void 0 && until === void 0) return presented;
+	const sessions = presented.sessions.filter((s) => {
+		const d = (s.date ?? "").slice(0, 10);
+		if (since !== void 0 && d < since) return false;
+		if (until !== void 0 && d > until) return false;
+		return true;
+	});
+	return {
+		...presented,
+		sessions
+	};
+}
+//#endregion
 //#region ../core/src/tools/athlete-training.ts
 /** Identity, profile, prefs, working maxes, leaderboard. */
 function registerProfileTools(server, ctx, whoami, userId) {
@@ -930,7 +1062,7 @@ function registerProfileTools(server, ctx, whoami, userId) {
 	}, () => attempt(async () => jsonResult(await whoami())));
 	server.registerTool("athlete_profile", {
 		title: "Athlete profile + lifetime totals",
-		description: "Lifetime training totals (reps, volume, sessions, first/last logged) plus the profile (name, units, dob). Set useMetric for kg/metric totals.",
+		description: "Lifetime training totals in one call — all-time session count (summary.sessions_count), total reps and volume, first/last logged date — plus the profile (name, units, dob). Use this for any 'how many sessions all-time / total volume ever' question rather than summing athlete_workouts windows. Set useMetric for kg/metric totals.",
 		inputSchema: { useMetric: z.boolean().optional() },
 		annotations: READ
 	}, ({ useMetric }) => attempt(async () => {
@@ -949,7 +1081,7 @@ function registerProfileTools(server, ctx, whoami, userId) {
 	}, () => attempt(async () => jsonResult(await fetchAthletePrefs(ctx.client))));
 	server.registerTool("athlete_working_maxes", {
 		title: "Working maxes",
-		description: "The athlete's working max per exercise (drives % prescriptions).",
+		description: "The athlete's working max per exercise (drives % prescriptions). An entry can carry a null value: the exercise has a working-max slot but no number has been set yet, which means there is effectively no working max for it.",
 		inputSchema: {},
 		annotations: READ
 	}, () => attempt(async () => jsonResult(await fetchWorkingMaxes(ctx.client))));
@@ -971,58 +1103,71 @@ function registerProfileTools(server, ctx, whoami, userId) {
 		return jsonResult(await fetchLeaderboard(ctx.client, toId(workoutId), opts));
 	}));
 }
+const ATHLETE_WORKOUTS_DESC = "Workouts in an inclusive YYYY-MM-DD window, flattened to blocks/exercises. Each exercise carries both its `prescribed` sets (what the program called for) and `performed` sets (what the athlete actually logged); each workout has a top-level `logged` flag. Use `performed`/`logged` to tell what was recorded or done. That is the reliable signal: a session can hold logged sets while the API's own completion flags stay 0, and an empty `performed` means nothing was logged for that exercise. For 'did I record anything / what did I do', set loggedOnly:true to return only sessions with logged sets (it keeps whole sessions that have any logged set, so individual exercises inside can still show empty `performed`; it also shrinks a large result); limit returns the most recent N workouts (newest first). For 'what's my next workout', query a forward window from today; if it comes back empty, the most recent session is likely yesterday's still-unlogged one, so widen the window backward a day or two. Both filters apply to the presented view, not raw. raw:true returns the untouched API objects. This is a date-windowed fetch, NOT an aggregate: for lifetime totals (all-time session count, total volume, first/last logged date) call athlete_profile instead of summing windows — a multi-year range here can time out. Narrow the window if the result is truncated.";
+const ATHLETE_EXERCISE_HISTORY_DESC = "Per-exercise PRs and the dated session time-series (sets performed, estimated 1RM). The returned `sessions` run all-time, newest first; pass since/until (YYYY-MM-DD, inclusive) to keep only sessions in that window — use it for 'last 3 months' / 'this year' questions so the result stays small. `liftPRs` are always all-time and ignore since/until. Set raw:true for the untouched API object. Get the exercise id from athlete_exercises.";
+const ATHLETE_EXERCISES_DESC = "The exercises the athlete has logged (id + title + positional units). Pass q to free-text search by name; use the returned id with athlete_exercise_history, athlete_personal_records, or athlete_exercise_stats (all of which require an exercise id).";
 /** Workouts, exercise catalog, per-exercise history/PRs/stats. */
 function registerExerciseTools(server, ctx, userId) {
 	server.registerTool("athlete_workouts", {
 		title: "Workouts in a date range",
-		description: "Scheduled + completed workouts in an inclusive YYYY-MM-DD window, flattened to blocks/exercises with per-set prescriptions and positional units. Set raw:true for the untouched API objects. Narrow the window if the result is truncated.",
+		description: ATHLETE_WORKOUTS_DESC,
 		inputSchema: {
 			startDate: dateString,
 			endDate: dateString,
-			raw: z.boolean().optional()
+			raw: z.boolean().optional(),
+			loggedOnly: z.boolean().optional(),
+			limit: z.number().int().positive().max(200).optional()
 		},
 		annotations: READ
-	}, ({ startDate, endDate, raw }) => attempt(async () => {
+	}, ({ startDate, endDate, raw, loggedOnly, limit }) => attempt(async () => {
 		const workouts = await fetchAthleteWorkouts(ctx.client, startDate, endDate);
-		return jsonResult(raw === true ? workouts : presentAthleteWorkouts(workouts), { hint: "Narrow startDate/endDate to shrink this result." });
+		if (raw === true) return jsonResult(workouts, { hint: "Narrow startDate/endDate to shrink this result." });
+		const opts = {};
+		if (loggedOnly !== void 0) opts.loggedOnly = loggedOnly;
+		if (limit !== void 0) opts.limit = limit;
+		return jsonResult(selectWorkouts(presentAthleteWorkouts(workouts), opts), { hint: "Large? Set loggedOnly:true, pass limit, or narrow startDate/endDate." });
 	}));
 	server.registerTool("athlete_exercises", {
 		title: "Search logged exercises",
-		description: "The exercises the athlete has logged (id + title + positional units). Pass q to free-text search by name; use the returned id with athlete_exercise_history / _stats.",
+		description: ATHLETE_EXERCISES_DESC,
 		inputSchema: {
 			q: z.string().optional(),
 			limit: z.number().int().positive().max(200).optional()
 		},
 		annotations: READ
 	}, ({ q, limit }) => attempt(async () => {
-		return jsonResult((q !== void 0 && q.trim() !== "" ? await searchExerciseHistory(ctx.client, q, limit ?? 20) : await fetchExerciseHistoryList(ctx.client)).map((r) => ({
+		const items = (q !== void 0 && q.trim() !== "" ? await searchExerciseHistory(ctx.client, q, limit ?? 20) : await fetchExerciseHistoryList(ctx.client)).map((r) => ({
 			id: r.id,
 			title: r.title,
 			isCircuit: r.isCircuit ?? false,
 			units: exerciseUnits(r.param1Type, r.param2Type)
-		})), { hint: "Pass q to search by name, or limit to cap the list." });
+		}));
+		return jsonResult(limit !== void 0 ? items.slice(0, limit) : items, { hint: "Pass q to search by name, or limit to cap the list." });
 	}));
 	server.registerTool("athlete_exercise_history", {
 		title: "Exercise history + PRs",
-		description: "Per-exercise PRs and the dated session time-series (sets performed, estimated 1RM). Set raw:true for the untouched API object. Get the exercise id from athlete_exercises.",
+		description: ATHLETE_EXERCISE_HISTORY_DESC,
 		inputSchema: {
 			exerciseId: idParam,
-			raw: z.boolean().optional()
+			raw: z.boolean().optional(),
+			since: dateString.optional(),
+			until: dateString.optional()
 		},
 		annotations: READ
-	}, ({ exerciseId, raw }) => attempt(async () => {
+	}, ({ exerciseId, raw, since, until }) => attempt(async () => {
 		const detail = await fetchExerciseHistoryDetail(ctx.client, toId(exerciseId), await userId());
-		return jsonResult(raw === true ? detail : presentExerciseHistory(detail));
+		if (raw === true) return jsonResult(detail);
+		return jsonResult(historyInRange(presentExerciseHistory(detail), since, until));
 	}));
 	server.registerTool("athlete_personal_records", {
 		title: "Exercise personal records",
-		description: "Personal records for an exercise (reps/weight, strength-standard filters).",
+		description: "The all-time PR board for an exercise (reps/weight per rep-max, strength-standard filters). Get the exercise id from athlete_exercises. For a point-in-time snapshot use athlete_exercise_stats; for the dated session trend use athlete_exercise_history.",
 		inputSchema: { exerciseId: idParam },
 		annotations: READ
 	}, ({ exerciseId }) => attempt(async () => jsonResult(await fetchPersonalRecords(ctx.client, toId(exerciseId)))));
 	server.registerTool("athlete_exercise_stats", {
 		title: "Exercise stats (last performance + PR)",
-		description: "Last performance and PR for an exercise as of a date (YYYY-MM-DD, required by the API).",
+		description: "A point-in-time snapshot for an exercise: last performance and PR as of a date (YYYY-MM-DD, required by the API). Not a range query — for the all-time board use athlete_personal_records, for progress over time use athlete_exercise_history. Get the exercise id from athlete_exercises.",
 		inputSchema: {
 			exerciseId: idParam,
 			date: dateString
@@ -1120,7 +1265,7 @@ function registerAthleteTrainingTools(server, ctx) {
 }
 //#endregion
 //#region package.json
-var version = "0.4.1";
+var version = "0.6.2";
 //#endregion
 //#region src/server.ts
 async function main() {

package/package.json

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