@trainheroic-unofficial/athlete-mcp 3.4.0 → 3.5.0

package/dist/server.mjs

@@ -271,6 +271,15 @@ const athleteWorkoutNoteObject = z.object({
 	rpe: z.number().int().min(1).max(10).optional()
 });
 const athleteWorkoutNoteArgsSchema = athleteWorkoutNoteObject.refine((v) => v.notes !== void 0 || v.rpe !== void 0, { message: "Provide notes and/or rpe" });
+/**
+* Args for the athlete per-exercise note write (the "Add exercise note" box on the exercise
+* screen — band color, etc.). `savedWorkoutSetExerciseId` is the slot id from athlete_log_targets.
+* Empty `notes` clears the note. Distinct from {@link athleteWorkoutNoteArgsSchema} (session note).
+*/
+const athleteExerciseNoteArgsSchema = z.object({
+	savedWorkoutSetExerciseId: idArgSchema,
+	notes: z.string()
+});
 const presentedNullNumber = z.number().nullable();
 const presentedNullString = z.string().nullable();
 /** Flattened exercise within a presented workout: prescriptions, logged results, units. */
@@ -278,6 +287,7 @@ const athleteWorkoutExerciseSchema = z.object({
 	exerciseId: presentedNullNumber,
 	title: z.string(),
 	instruction: presentedNullString,
+	notes: presentedNullString,
 	units: z.array(presentedNullString),
 	prescribed: z.array(z.string()),
 	performed: z.array(z.string())
@@ -387,6 +397,7 @@ z.array(rosterActivityRowSchema);
 const presentedExerciseSessionSchema = z.object({
 	date: z.string(),
 	abr: presentedNullString,
+	notes: presentedNullString,
 	estimated1RM: presentedNullNumber,
 	sets: z.array(z.object({
 		setNumber: z.number(),
@@ -523,6 +534,7 @@ const logSetTargetOutputSchema = z.object({
 		savedWorkoutSetExerciseId: z.number(),
 		title: z.string(),
 		units: z.array(nullableString),
+		notes: nullableString,
 		prescribed: z.array(z.string()),
 		performed: z.array(z.string())
 	}))
@@ -597,6 +609,10 @@ const athleteWorkoutNoteOutputSchema = z.object({
 	notes: z.string(),
 	rpe: nullableNumber
 });
+const athleteExerciseNoteOutputSchema = z.object({
+	savedWorkoutSetExerciseId: z.number(),
+	notes: z.string()
+});
 const workoutReadExerciseOutputSchema = z.object({
 	order: z.number(),
 	title: z.string(),
@@ -1397,6 +1413,16 @@ function performedSlotsByExerciseId(sets) {
 	}
 	return map;
 }
+/** Per-exercise athlete notes keyed by the prescription template id (`workout_set_exercise_id`). */
+function notesByTemplateId(sets) {
+	const map = /* @__PURE__ */ new Map();
+	for (const { exercises } of sets) for (const ex of exercises) {
+		const id = coerceInt(ex.workout_set_exercise_id);
+		const notes = str(ex.notes);
+		if (id !== null && notes !== null) map.set(id, notes);
+	}
+	return map;
+}
 /** Align an exercise's prescribed slots with the slots the athlete logged, per set index. */
 function mergeExercise(prescribed, performed, meta) {
 	const indices = [.../* @__PURE__ */ new Set([...prescribed.keys(), ...performed.keys()])].sort((a, b) => a - b);
@@ -1410,7 +1436,7 @@ function mergeExercise(prescribed, performed, meta) {
 	};
 }
 /** A prescription block, each exercise aligned with the slots the athlete logged against it. */
-function mergePrescriptionBlock(set, performedById) {
+function mergePrescriptionBlock(set, performedById, notesById) {
 	const exercises = Array.isArray(set.workoutSetExercises) ? set.workoutSetExercises : [];
 	return {
 		order: coerceInt(set.order) ?? 0,
@@ -1424,6 +1450,7 @@ function mergePrescriptionBlock(set, performedById) {
 				exerciseId: coerceInt(ex.exercise_id),
 				title: typeof ex.title === "string" ? ex.title : "",
 				instruction: str(ex.instruction),
+				notes: id !== null ? notesById.get(id) ?? null : null,
 				units: exerciseUnits(ex.param_1_type, ex.param_2_type)
 			});
 		})
@@ -1440,6 +1467,7 @@ function mergeSavedBlock(set, exercises) {
 			exerciseId: coerceInt(ex.exercise_id),
 			title: typeof ex.exercise_title === "string" ? ex.exercise_title : "",
 			instruction: str(ex.instruction),
+			notes: str(ex.notes),
 			units: exerciseUnits(ex.param_1_type, ex.param_2_type)
 		}))
 	};
@@ -1458,7 +1486,8 @@ function mergeAthleteWorkout(raw) {
 	const prescriptionSets = (Array.isArray(workout.workoutSets) ? workout.workoutSets : []).filter(isRecord);
 	const logged = savedSets(saved);
 	const performedById = performedSlotsByExerciseId(logged);
-	const blocks = prescriptionSets.map((s) => mergePrescriptionBlock(s, performedById)).sort((a, b) => a.order - b.order);
+	const notesById = notesByTemplateId(logged);
+	const blocks = prescriptionSets.map((s) => mergePrescriptionBlock(s, performedById, notesById)).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 : [];
@@ -1504,6 +1533,7 @@ function toStringExercise(ex) {
 		exerciseId: ex.exerciseId,
 		title: ex.title,
 		instruction: ex.instruction,
+		notes: ex.notes,
 		units: ex.units,
 		prescribed: sideStrings(ex.sets, (s) => s.prescribed),
 		performed: sideStrings(ex.sets, (s) => s.performed)
@@ -1598,6 +1628,7 @@ function presentLogTargets(list) {
 					savedWorkoutSetExerciseId: id,
 					title: exerciseTitle(ex),
 					units: exerciseUnits(ex.param_1_type, ex.param_2_type),
+					notes: str(ex.notes),
 					prescribed: prescribedStrings(ex),
 					performed: performedStrings(ex)
 				};
@@ -1665,6 +1696,7 @@ function presentExerciseHistory(detail) {
 		sessions: (detail.history ?? []).map((h) => ({
 			date: h.dateCompleted,
 			abr: h.abr ?? null,
+			notes: str(h.notes),
 			estimated1RM: h.bestEstimated1RM ?? null,
 			sets: (h.sets ?? []).map((s) => ({
 				setNumber: s.setNumber,
@@ -2253,6 +2285,28 @@ async function setAthleteWorkoutNote(client, args) {
 	};
 }
 //#endregion
+//#region ../js/src/athlete-exercise-note.ts
+/**
+* PUT /1.0/athlete/savedworkoutsetexercise/{id} — set the athlete's per-exercise note (the
+* "Add exercise note" box on the exercise screen). A notes-only body leaves logged reps/weight
+* untouched. Empty `notes` clears the note. GET on that path 405s; the range read and exercise
+* history both echo the stored string. Coach-visible.
+*/
+async function setAthleteExerciseNote(client, args) {
+	const savedWorkoutSetExerciseId = coerceInt(args.savedWorkoutSetExerciseId);
+	if (savedWorkoutSetExerciseId === null) throw new Error(`Invalid savedWorkoutSetExerciseId ${String(args.savedWorkoutSetExerciseId)}.`);
+	const res = await client.request("PUT", `/1.0/athlete/savedworkoutsetexercise/${savedWorkoutSetExerciseId}`, { body: {
+		id: savedWorkoutSetExerciseId,
+		notes: args.notes
+	} });
+	if (!res.ok) throw new Error(`Set exercise note failed (HTTP ${res.status}).`);
+	const data = isRecord(res.data) ? res.data : {};
+	return {
+		savedWorkoutSetExerciseId,
+		notes: typeof data.notes === "string" ? data.notes : args.notes
+	};
+}
+//#endregion
 //#region ../core/src/history.ts
 /**
 * Trim a presented exercise history's session time-series to an inclusive YYYY-MM-DD window.
@@ -2332,9 +2386,9 @@ function registerProfileTools(server, ctx, whoami, userId) {
 		return jsonResult(await fetchLeaderboard(ctx.client, toId(workoutId), opts));
 	}));
 }
-const ATHLETE_WORKOUTS_DESC = "Workouts on the AUTHENTICATED user's own athlete calendar in an inclusive YYYY-MM-DD window, flattened to blocks/exercises. When a coach account calls this, it returns the coach's own training schedule — not a roster athlete's. To inspect a roster athlete use athlete_saved_workouts (or athlete_training for a month overview); to verify a coach-published team session from the calendar side use workout_read. 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. Session `notes` and `rpe` are the athlete's own note/RPE on that workout (null when unset), distinct from coach `instruction`. 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 a high-level overview ('what's on my schedule this week', 'what have I been training lately') set summary:true to get one compact row per session (date, program, title, logged flag, and exerciseCount/performedCount — read performedCount against exerciseCount, e.g. 1 of 12 logged) instead of every set — a multi-program week of full detail is large, so prefer summary first, then re-query a single day without it to drill into that day's sets. 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_LOG_TARGETS_DESC = "The savedWorkoutSetId + savedWorkoutSetExerciseId that athlete_log_set needs, read straight off your scheduled/logged workouts in an inclusive YYYY-MM-DD window — no raw needed. This is the self-service path for logging into a COACH-SCHEDULED workout: read the ids here, then pass them to athlete_log_set. The default view is COMPACT: one row per saved set, each carrying its program/programId, the savedWorkoutSetId, and every exercise's savedWorkoutSetExerciseId with prescribed/performed values. When several workouts fall on the same day (you're on more than one program), narrow to one with program (a case-insensitive title substring, e.g. 'bodybuilding' — no id lookup needed), or programId/teamId if you have the id. raw:true returns the untouched API objects, but that blob is large and can be truncated when several workouts share a date — prefer the program filter + the default view. For reading what you actually did (not the log ids), use athlete_workouts.";
-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. estimated1RM is a formula off the session's best set and reads high when a session mixes a heavy single with high-rep backdown work, so treat it as approximate, not a logged single. `liftPRs` are always all-time and ignore since/until, but each carries the date it was set, so filter those dates yourself to answer 'PRs set this year'. Set raw:true for the untouched API object. Get the exercise id from athlete_exercises.";
+const ATHLETE_WORKOUTS_DESC = "Workouts on the AUTHENTICATED user's own athlete calendar in an inclusive YYYY-MM-DD window, flattened to blocks/exercises. When a coach account calls this, it returns the coach's own training schedule — not a roster athlete's. To inspect a roster athlete use athlete_saved_workouts (or athlete_training for a month overview); to verify a coach-published team session from the calendar side use workout_read. 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. Session `notes` and `rpe` are the athlete's own note/RPE on that workout (null when unset), distinct from coach `instruction`. Each exercise may also carry `notes` (the per-exercise box on the exercise screen; null when unset). 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 a high-level overview ('what's on my schedule this week', 'what have I been training lately') set summary:true to get one compact row per session (date, program, title, logged flag, and exerciseCount/performedCount — read performedCount against exerciseCount, e.g. 1 of 12 logged) instead of every set — a multi-program week of full detail is large, so prefer summary first, then re-query a single day without it to drill into that day's sets. 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_LOG_TARGETS_DESC = "The savedWorkoutSetId + savedWorkoutSetExerciseId that athlete_log_set needs, read straight off your scheduled/logged workouts in an inclusive YYYY-MM-DD window — no raw needed. This is the self-service path for logging into a COACH-SCHEDULED workout: read the ids here, then pass them to athlete_log_set. The default view is COMPACT: one row per saved set, each carrying its program/programId, the savedWorkoutSetId, and every exercise's savedWorkoutSetExerciseId with prescribed/performed values and any per-exercise `notes`. When several workouts fall on the same day (you're on more than one program), narrow to one with program (a case-insensitive title substring, e.g. 'bodybuilding' — no id lookup needed), or programId/teamId if you have the id. raw:true returns the untouched API objects, but that blob is large and can be truncated when several workouts share a date — prefer the program filter + the default view. For reading what you actually did (not the log ids), use athlete_workouts.";
+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. estimated1RM is a formula off the session's best set and reads high when a session mixes a heavy single with high-rep backdown work, so treat it as approximate, not a logged single. Each session may carry `notes` (the per-exercise athlete note). `liftPRs` are always all-time and ignore since/until, but each carries the date it was set, so filter those dates yourself to answer 'PRs set this year'. 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). Call with no arguments to get the athlete's complete catalog, which often runs to several hundred entries; leave limit off when you want the whole list, since a no-q call returns everything by default. Pass q to free-text search by name (returns the top ranked matches, capped by limit, default 20). Use a returned id with athlete_exercise_history, athlete_personal_records, or athlete_exercise_stats (all of which require an exercise id). If a no-q result comes back wrapped with a __truncated marker, you passed a limit smaller than the catalog and are seeing a partial list; re-call without limit for all of it. A common name returns several variants (e.g. plain 'Bench Press' id 1162 vs 'BARBELL BENCH PRESS'); each variant keeps its own separate history and PR board, so prefer the plain canonical entry, and if a PR or trend looks incomplete, the work may be split across variants, so check the others.";
 function runAthleteWorkouts(ctx, args) {
 	return attempt(async () => {
@@ -2507,7 +2561,7 @@ function registerSessionTools(server, ctx) {
 function registerWorkoutNoteTool(server, ctx) {
 	server.registerTool("athlete_workout_note", {
 		title: "Set your session note or RPE",
-		description: "Athlete-facing write: set the free-text note (and/or session RPE 1–10) on a workout. This is the note box on the workout screen, not the coach's Instructions. programWorkoutId is the `id` from athlete_workouts for that date. Pass notes (empty string clears) and/or rpe; a notes-only write leaves rpe untouched and vice versa. Visible to your coach. Requires confirmation (elicitation or confirm:true).",
+		description: "Athlete-facing write: set the free-text note (and/or session RPE 1–10) on a workout. This is the note box on the workout screen, not the coach's Instructions and not the per-exercise note (use athlete_exercise_note for that). programWorkoutId is the `id` from athlete_workouts for that date. Pass notes (empty string clears) and/or rpe; a notes-only write leaves rpe untouched and vice versa. Visible to your coach. Requires confirmation (elicitation or confirm:true).",
 		inputSchema: {
 			...athleteWorkoutNoteObject.shape,
 			confirm: z.boolean().optional()
@@ -2526,6 +2580,27 @@ function registerWorkoutNoteTool(server, ctx) {
 		return jsonResult(await setAthleteWorkoutNote(ctx.client, patch));
 	}));
 }
+/** Set the athlete's per-exercise note on a saved slot (coach-visible). */
+function registerExerciseNoteTool(server, ctx) {
+	server.registerTool("athlete_exercise_note", {
+		title: "Set a per-exercise note",
+		description: "Athlete-facing write: set the free-text note on one exercise in a workout (the 'Add exercise note' box on the exercise screen). Use this for things the weight field cannot hold, such as which band you used. Distinct from athlete_workout_note, which writes the session-level note. savedWorkoutSetExerciseId is the slot id from athlete_log_targets. Empty notes clears the note. Visible to your coach. Requires confirmation (elicitation or confirm:true).",
+		inputSchema: {
+			...athleteExerciseNoteArgsSchema.shape,
+			confirm: z.boolean().optional()
+		},
+		outputSchema: toolOutputSchema(athleteExerciseNoteOutputSchema),
+		annotations: DESTRUCTIVE
+	}, ({ savedWorkoutSetExerciseId, notes, confirm }, extra) => attempt(async () => {
+		const patch = athleteExerciseNoteArgsSchema.parse({
+			savedWorkoutSetExerciseId,
+			notes
+		});
+		const blocked = confirmGate(extra, `Set the exercise note on slot ${toId(patch.savedWorkoutSetExerciseId)}? This is visible to your coach.`, confirm);
+		if (blocked) return blocked;
+		return jsonResult(await setAthleteExerciseNote(ctx.client, patch));
+	}));
+}
 /** Map validated logSession exercises to the SDK's SessionExercise[] (ids coerced, slots trimmed). */
 function mapSessionExercises(exercises) {
 	return exercises.map((e) => {
@@ -2678,12 +2753,13 @@ function registerAthleteTrainingTools(server, ctx) {
 	registerLogTargetsTool(server, ctx);
 	registerSessionTools(server, ctx);
 	registerWorkoutNoteTool(server, ctx);
+	registerExerciseNoteTool(server, ctx);
 	registerLogTool(server, ctx);
 	registerSwapTool(server, ctx);
 }
 //#endregion
 //#region package.json
-var version = "3.4.0";
+var version = "3.5.0";
 //#endregion
 //#region src/server.ts
 function main() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trainheroic-unofficial/athlete-mcp",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -21,8 +21,8 @@
   "dependencies": {
     "@modelcontextprotocol/server": "2.0.0",
     "zod": "^4.4.3",
-    "@trainheroic-unofficial/core": "3.4.0",
-    "@trainheroic-unofficial/js": "3.4.0"
+    "@trainheroic-unofficial/core": "3.5.0",
+    "@trainheroic-unofficial/js": "3.5.0"
   },
   "devDependencies": {
     "@types/node": "^26.3.0",