@trainheroic-unofficial/athlete-mcp 3.3.2 → 3.4.0

package/dist/server.mjs

@@ -257,6 +257,20 @@ const athleteSessionRemoveArgsSchema = z.object({
 	programWorkoutId: idArgSchema,
 	date: dateString
 });
+/**
+* Args for the athlete session-note write. `programWorkoutId` is the range item's top-level `id`
+* (athlete_workouts); `date` locates that day so the SDK can resolve the saved-workout id the PUT
+* targets. `notes` is the free-text box on the workout screen (empty string clears it). `rpe` is
+* the session RPE (1–10). At least one of `notes` / `rpe` is required — a notes-only PUT leaves
+* rpe untouched and vice versa.
+*/
+const athleteWorkoutNoteObject = z.object({
+	date: dateString,
+	programWorkoutId: idArgSchema,
+	notes: z.string().optional(),
+	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" });
 const presentedNullNumber = z.number().nullable();
 const presentedNullString = z.string().nullable();
 /** Flattened exercise within a presented workout: prescriptions, logged results, units. */
@@ -282,6 +296,8 @@ const athleteWorkoutViewSchema = z.object({
 	program: presentedNullString,
 	team: presentedNullString,
 	instruction: presentedNullString,
+	notes: presentedNullString,
+	rpe: presentedNullNumber,
 	logged: z.boolean(),
 	personal: z.boolean(),
 	blocks: z.array(athleteWorkoutBlockSchema)
@@ -574,6 +590,13 @@ const personalWorkoutCreatedOutputSchema = z.object({
 	groupId: z.number(),
 	date: z.string()
 });
+const athleteWorkoutNoteOutputSchema = z.object({
+	programWorkoutId: z.number(),
+	savedWorkoutId: z.number(),
+	date: z.string(),
+	notes: z.string(),
+	rpe: nullableNumber
+});
 const workoutReadExerciseOutputSchema = z.object({
 	order: z.number(),
 	title: z.string(),
@@ -725,17 +748,17 @@ function toId(value) {
 const READ = {
 	readOnlyHint: true,
 	destructiveHint: false,
-	openWorldHint: true
+	openWorldHint: false
 };
 const ADDITIVE = {
 	readOnlyHint: false,
 	destructiveHint: false,
-	openWorldHint: true
+	openWorldHint: false
 };
 const DESTRUCTIVE = {
 	readOnlyHint: false,
 	destructiveHint: true,
-	openWorldHint: true
+	openWorldHint: false
 };
 /**
 * Run a tool body, converting thrown errors into an in-band tool error. Generic so a caller that
@@ -1202,6 +1225,15 @@ function isPersonalSession(pw) {
 	return isRecord(pw) && pw.personal_cal === true;
 }
 /**
+* The `saved_workout` blob on a program-workout range item, or null if the athlete has no saved
+* copy yet. Session notes, RPE, and set writes all resolve through this.
+*/
+function savedWorkoutOf(pw) {
+	if (!isRecord(pw)) return null;
+	const ssw = isRecord(pw.summarizedSavedWorkout) ? pw.summarizedSavedWorkout : {};
+	return isRecord(ssw.saved_workout) ? ssw.saved_workout : null;
+}
+/**
 * Rank candidate rows for a free-text query (FTS5 replacement). Higher is better:
 * exact title, then prefix, then count of matched tokens, with shorter titles and
 * standard (non-custom) exercises preferred on ties.
@@ -1278,6 +1310,15 @@ function fetchExerciseStats(client, exerciseId, userId, date) {
 function fetchAthleteWorkouts(client, startDate, endDate) {
 	return getArray(client, `/3.0/athlete/programworkout/range?startDate=${startDate}&endDate=${endDate}`, "athlete workouts");
 }
+/**
+* The program-workout row with this id on this date. Throws if that id is not on the day's range;
+* callers should take the id from `athlete_workouts`.
+*/
+async function programWorkoutOnDate(client, date, programWorkoutId) {
+	const target = (await fetchAthleteWorkouts(client, date, date)).find((pw) => coerceInt(pw.id) === programWorkoutId);
+	if (target === void 0) throw new Error(`No workout with id ${programWorkoutId} on ${date}. Get the id and date from athlete_workouts.`);
+	return target;
+}
 function fetchLeaderboard(client, workoutId, opts = {}) {
 	const qs = new URLSearchParams();
 	if (opts.page !== void 0) qs.set("page", String(opts.page));
@@ -1413,7 +1454,7 @@ function mergeAthleteWorkout(raw) {
 	const rec = raw;
 	const ssw = isRecord(rec.summarizedSavedWorkout) ? rec.summarizedSavedWorkout : {};
 	const workout = isRecord(ssw.workout) ? ssw.workout : {};
-	const saved = isRecord(ssw.saved_workout) ? ssw.saved_workout : {};
+	const saved = savedWorkoutOf(rec) ?? {};
 	const prescriptionSets = (Array.isArray(workout.workoutSets) ? workout.workoutSets : []).filter(isRecord);
 	const logged = savedSets(saved);
 	const performedById = performedSlotsByExerciseId(logged);
@@ -1442,6 +1483,8 @@ function mergeAthleteWorkout(raw) {
 		program: str(rec.program_title),
 		team: str(rec.team_title),
 		instruction: str(workout.instruction),
+		notes: str(saved.notes),
+		rpe: coerceInt(saved.rpe),
 		logged: blocks.some((b) => b.exercises.some((e) => e.sets.some((s) => s.performed !== null))),
 		personal: isPersonalSession(rec),
 		blocks
@@ -1489,6 +1532,8 @@ function presentAthleteWorkout(raw) {
 		program: w.program,
 		team: w.team,
 		instruction: w.instruction,
+		notes: w.notes,
+		rpe: w.rpe,
 		logged: w.logged,
 		personal: w.personal,
 		blocks: w.blocks.map(toStringBlock)
@@ -1751,9 +1796,7 @@ function assertUniqueExerciseResults(results) {
 function findSavedWorkoutSet(workouts, savedWorkoutSetId) {
 	const available = [];
 	for (const pw of workouts) {
-		const rec = pw;
-		const ssw = isRecord(rec.summarizedSavedWorkout) ? rec.summarizedSavedWorkout : {};
-		const sw = isRecord(ssw.saved_workout) ? ssw.saved_workout : null;
+		const sw = savedWorkoutOf(pw);
 		if (!sw) continue;
 		const sets = Array.isArray(sw.workoutSets) ? sw.workoutSets : [];
 		for (const s of sets) {
@@ -2002,9 +2045,7 @@ async function addExercisesToWorkout(client, workoutId, exercises) {
 * Throws on a non-ok response.
 */
 async function removePersonalWorkout(client, args) {
-	const target = (await fetchAthleteWorkouts(client, args.date, args.date)).find((pw) => coerceInt(pw.id) === args.programWorkoutId);
-	if (target === void 0) throw new Error(`No workout with id ${args.programWorkoutId} on ${args.date}. Get the id and date from athlete_workouts.`);
-	if (!isPersonalSession(target)) throw new Error(`Workout ${args.programWorkoutId} on ${args.date} is a coach-scheduled workout, not a personal session, so it can't be removed. To change logged results on a scheduled workout, use athlete_log_set.`);
+	if (!isPersonalSession(await programWorkoutOnDate(client, args.date, args.programWorkoutId))) throw new Error(`Workout ${args.programWorkoutId} on ${args.date} is a coach-scheduled workout, not a personal session, so it can't be removed. To change logged results on a scheduled workout, use athlete_log_set.`);
 	const res = await client.request("DELETE", `/v5/programWorkouts/${args.programWorkoutId}`);
 	if (!res.ok) throw new Error(`Remove personal workout failed (HTTP ${res.status}).`);
 }
@@ -2057,8 +2098,7 @@ function eachPrescribedExercise(workouts) {
 	const rows = [];
 	for (const pw of workouts) {
 		const rec = pw;
-		const ssw = isRecord(rec.summarizedSavedWorkout) ? rec.summarizedSavedWorkout : {};
-		const sw = isRecord(ssw.saved_workout) ? ssw.saved_workout : null;
+		const sw = savedWorkoutOf(rec);
 		if (!sw) continue;
 		const sets = [...Array.isArray(sw.workoutSets) ? sw.workoutSets : [], ...Array.isArray(sw.addedWorkoutSets) ? sw.addedWorkoutSets : []];
 		for (const s of sets) {
@@ -2182,6 +2222,37 @@ function definedProps(obj) {
 	return result;
 }
 //#endregion
+//#region ../js/src/athlete-workout-note.ts
+/**
+* PUT /1.0/athlete/savedworkout/{id} — set the athlete's session note (the free-text box on the
+* workout screen) and/or session RPE. The date + programWorkoutId (`athlete_workouts` `id`) locate
+* the saved workout; GET on that path 405s, so the range read is the lookup. A notes-only body
+* leaves rpe untouched and vice versa. Empty `notes` clears the note. Coach-visible.
+*/
+async function setAthleteWorkoutNote(client, args) {
+	if (args.notes === void 0 && args.rpe === void 0) throw new Error("Provide notes and/or rpe.");
+	const programWorkoutId = coerceInt(args.programWorkoutId);
+	if (programWorkoutId === null) throw new Error(`Invalid programWorkoutId ${String(args.programWorkoutId)}.`);
+	const saved = savedWorkoutOf(await programWorkoutOnDate(client, args.date, programWorkoutId));
+	const savedWorkoutId = saved !== null ? coerceInt(saved.id) : null;
+	if (savedWorkoutId === null) throw new Error(`Workout ${programWorkoutId} on ${args.date} has no saved workout to attach a note to.`);
+	const body = definedProps({
+		id: savedWorkoutId,
+		notes: args.notes,
+		rpe: args.rpe
+	});
+	const res = await client.request("PUT", `/1.0/athlete/savedworkout/${savedWorkoutId}`, { body });
+	if (!res.ok) throw new Error(`Set workout note failed (HTTP ${res.status}).`);
+	const data = isRecord(res.data) ? res.data : {};
+	return {
+		programWorkoutId,
+		savedWorkoutId,
+		date: args.date,
+		notes: typeof data.notes === "string" ? data.notes : args.notes ?? "",
+		rpe: coerceInt(data.rpe) ?? (args.rpe !== void 0 ? args.rpe : null)
+	};
+}
+//#endregion
 //#region ../core/src/history.ts
 /**
 * Trim a presented exercise history's session time-series to an inclusive YYYY-MM-DD window.
@@ -2261,7 +2332,7 @@ 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. 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_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_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.";
@@ -2432,6 +2503,29 @@ function registerSessionTools(server, ctx) {
 		});
 	}));
 }
+/** Set the athlete's session note / RPE on a saved workout (coach-visible). */
+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).",
+		inputSchema: {
+			...athleteWorkoutNoteObject.shape,
+			confirm: z.boolean().optional()
+		},
+		outputSchema: toolOutputSchema(athleteWorkoutNoteOutputSchema),
+		annotations: DESTRUCTIVE
+	}, ({ date, programWorkoutId, notes, rpe, confirm }, extra) => attempt(async () => {
+		const patch = athleteWorkoutNoteArgsSchema.parse(definedProps({
+			date,
+			programWorkoutId,
+			notes,
+			rpe
+		}));
+		const blocked = confirmGate(extra, `Set the session note on workout ${toId(patch.programWorkoutId)} on ${patch.date}? This is visible to your coach.`, confirm);
+		if (blocked) return blocked;
+		return jsonResult(await setAthleteWorkoutNote(ctx.client, patch));
+	}));
+}
 /** Map validated logSession exercises to the SDK's SessionExercise[] (ids coerced, slots trimmed). */
 function mapSessionExercises(exercises) {
 	return exercises.map((e) => {
@@ -2583,12 +2677,13 @@ function registerAthleteTrainingTools(server, ctx) {
 	registerCatalogReads(server, ctx);
 	registerLogTargetsTool(server, ctx);
 	registerSessionTools(server, ctx);
+	registerWorkoutNoteTool(server, ctx);
 	registerLogTool(server, ctx);
 	registerSwapTool(server, ctx);
 }
 //#endregion
 //#region package.json
-var version = "3.3.2";
+var version = "3.4.0";
 //#endregion
 //#region src/server.ts
 function main() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trainheroic-unofficial/athlete-mcp",
-  "version": "3.3.2",
+  "version": "3.4.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -21,15 +21,15 @@
   "dependencies": {
     "@modelcontextprotocol/server": "2.0.0",
     "zod": "^4.4.3",
-    "@trainheroic-unofficial/js": "3.3.2",
-    "@trainheroic-unofficial/core": "3.3.2"
+    "@trainheroic-unofficial/core": "3.4.0",
+    "@trainheroic-unofficial/js": "3.4.0"
   },
   "devDependencies": {
-    "@types/node": "^26.2.0",
+    "@types/node": "^26.3.0",
     "tsdown": "^0.22.14",
     "tsx": "^4.23.12",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.11"
   },
   "scripts": {
     "start": "tsx src/server.ts",