@trainheroic-unofficial/core 2.0.1 → 2.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.mjs +34 -16
- package/package.json +3 -3
package/dist/index.mjs
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { athleteSessionRemoveArgsSchema, blockSpecSchema, coachLogSessionArgsSchema, coachLogSetArgsSchema, coachPrescribeSetArgsSchema, commentDraftSchema, dateString, exerciseCreateSchema, idArgSchema, logSessionArgsSchema, logSetArgsSchema, parseWorkoutDate, swapAthleteExerciseArgsSchema } from "@trainheroic-unofficial/dto";
|
|
2
2
|
import { acceptedContent, inputRequired, inputResponse } from "@modelcontextprotocol/server";
|
|
3
3
|
import { z } from "zod";
|
|
4
|
-
import { ANALYTICS_METRIC_KEYS, addExercisesToWorkout, buildCommentPayload, buildSession, coerceInt, collectAdvisories, copySession, createPersonalWorkout, definedProps, deleteComment, exerciseUnits, fetchAthleteMainLiftPRs, fetchAthletePrefs, fetchAthleteProfileSummary, fetchAthleteUser, fetchAthleteWorkouts, fetchCoachAthleteCalendarSummary, fetchCoachAthleteWorkouts, fetchExerciseHistoryDetail, fetchExerciseHistoryList, fetchExerciseStats, fetchLeaderboard, fetchPersonalRecords, fetchRosterActivity, fetchRosterMainLiftPRs, fetchStreams, fetchTeamAthleteIds, fetchWorkingMaxes, inviteAthletes, isRecord, logAdHocSession, logAthleteSet, logForAthlete, logSessionForAthlete, prescribeForAthlete, presentAthleteWorkouts, presentCoachAthleteTraining, presentExerciseHistory, presentLogTargets, publishSession, queryAnalytics, readLive, readSession, removePersonalWorkout, removeSession, searchExerciseHistory, selectWorkouts, selectWorkoutsByProgram, sendComment, summarizeAthleteWorkouts, swapAthleteExercise, teamVolume, toSetResults } from "@trainheroic-unofficial/js";
|
|
4
|
+
import { ANALYTICS_METRIC_KEYS, addExercisesToWorkout, buildCommentPayload, buildSession, coerceInt, collectAdvisories, copySession, createPersonalWorkout, definedProps, deleteComment, exerciseUnits, fetchAthleteMainLiftPRs, fetchAthletePrefs, fetchAthleteProfileSummary, fetchAthleteUser, fetchAthleteWorkouts, fetchCoachAthleteCalendarSummary, fetchCoachAthleteWorkouts, fetchExerciseHistoryDetail, fetchExerciseHistoryList, fetchExerciseStats, fetchLeaderboard, fetchPersonalRecords, fetchRosterActivity, fetchRosterMainLiftPRs, fetchStreams, fetchTeamAthleteIds, fetchWorkingMaxes, inviteAthletes, isRecord, logAdHocSession, logAthleteSet, logForAthlete, logSessionForAthlete, prescribeForAthlete, presentAthleteWorkouts, presentCoachAthleteTraining, presentExerciseHistory, presentLogTargets, publishSession, queryAnalytics, readLive, readSession, removePersonalWorkout, removeSession, resolveBuildProgramId, searchExerciseHistory, selectWorkouts, selectWorkoutsByProgram, sendComment, summarizeAthleteWorkouts, swapAthleteExercise, teamVolume, toSetResults, updateTeam } from "@trainheroic-unofficial/js";
|
|
5
5
|
//#region src/context.ts
|
|
6
6
|
/** A tool argument that accepts a numeric id as a number or a string of digits. */
|
|
7
7
|
const idParam = idArgSchema;
|
|
@@ -403,7 +403,7 @@ function registerEntityReads(server, ctx) {
|
|
|
403
403
|
}));
|
|
404
404
|
server.registerTool("get_program", {
|
|
405
405
|
title: "Get program detail",
|
|
406
|
-
description: "Full nested program structure (blocks + sessions) live from the API, by program id.",
|
|
406
|
+
description: "Full nested program structure (blocks + sessions) live from the API, by program id. Works for team calendars and athlete coach calendars (type 5 from /v5/calendars/athletes/{id}). Some unrelated ids return HTTP 401 Cannot access program.",
|
|
407
407
|
inputSchema: { programId: idParam },
|
|
408
408
|
annotations: READ
|
|
409
409
|
}, ({ programId }) => apiCall(ctx, "GET", `/3.0/coach/program/${enc(programId)}`, void 0, "This is a large, deep object. If it is truncated, fetch a narrower view (a specific session) instead."));
|
|
@@ -520,7 +520,7 @@ function registerProfileTools(server, ctx, whoami, userId) {
|
|
|
520
520
|
return jsonResult(await fetchLeaderboard(ctx.client, toId(workoutId), opts));
|
|
521
521
|
}));
|
|
522
522
|
}
|
|
523
|
-
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 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.";
|
|
523
|
+
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.";
|
|
524
524
|
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.";
|
|
525
525
|
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.";
|
|
526
526
|
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.";
|
|
@@ -1005,19 +1005,25 @@ const ADDITIVE = {
|
|
|
1005
1005
|
function registerTeamTools(server, ctx) {
|
|
1006
1006
|
server.registerTool("team_create", {
|
|
1007
1007
|
title: "Create a team",
|
|
1008
|
-
description: "Create a team (POST /1.0/coach/team/createWithTitleAndCode). Also creates the team's calendar/program. Returns the new team including its calendar id. Use the team id with athlete_invite.",
|
|
1008
|
+
description: "Create a team (POST /1.0/coach/team/createWithTitleAndCode). Also creates the team's calendar/program. Returns the new team including its calendar id. Use the team id with athlete_invite. To point a new team at an existing calendar instead of its auto-created one, follow up with team_update groupProgram.",
|
|
1009
1009
|
inputSchema: { title: z.string().min(1) },
|
|
1010
1010
|
annotations: ADDITIVE
|
|
1011
1011
|
}, ({ title }) => apiCall(ctx, "POST", "/1.0/coach/team/createWithTitleAndCode", { body: { title } }));
|
|
1012
1012
|
server.registerTool("team_update", {
|
|
1013
|
-
title: "
|
|
1014
|
-
description: "Update a team's
|
|
1013
|
+
title: "Update a team",
|
|
1014
|
+
description: "Update a team's title and/or reassign its calendar (PUT /v5/teams/{teamId}). Pass groupProgram (a program/calendar id — typically another team's group_program from list_teams, or get_team) to point this team at an existing parent program. At least one of title or groupProgram is required; when only groupProgram is set the current title is preserved.",
|
|
1015
1015
|
inputSchema: {
|
|
1016
1016
|
teamId: idParam,
|
|
1017
|
-
title: z.string().min(1)
|
|
1017
|
+
title: z.string().min(1).optional(),
|
|
1018
|
+
groupProgram: idParam.optional()
|
|
1018
1019
|
},
|
|
1019
1020
|
annotations: ADDITIVE
|
|
1020
|
-
}, ({ teamId, title }) =>
|
|
1021
|
+
}, ({ teamId, title, groupProgram }) => attempt(async () => {
|
|
1022
|
+
const args = { teamId: toId(teamId) };
|
|
1023
|
+
if (title !== void 0) args.title = title;
|
|
1024
|
+
if (groupProgram !== void 0) args.groupProgram = toId(groupProgram);
|
|
1025
|
+
return jsonResult(await updateTeam(ctx.client, args));
|
|
1026
|
+
}));
|
|
1021
1027
|
server.registerTool("team_delete", {
|
|
1022
1028
|
title: "Delete a team",
|
|
1023
1029
|
description: "Delete a team (DELETE /v5/teams/{teamId}). Removes the team and its calendar from the live account; hard to undo. Requires confirmation (elicitation, or confirm:true).",
|
|
@@ -1161,13 +1167,14 @@ function registerExerciseTools(server, ctx) {
|
|
|
1161
1167
|
}
|
|
1162
1168
|
//#endregion
|
|
1163
1169
|
//#region src/tools/workout.ts
|
|
1164
|
-
/** Build a draft
|
|
1170
|
+
/** Build a draft session (workout_build). */
|
|
1165
1171
|
function registerBuild(server, ctx) {
|
|
1166
1172
|
server.registerTool("workout_build", {
|
|
1167
1173
|
title: "Build a workout session (draft)",
|
|
1168
|
-
description: "Build an UNPUBLISHED session from a spec (program -> session -> blocks -> exercises). Two exercises in one block become a superset. Add a block 'leaderboard' for a Red-Zone score, or a top-level 'instruction' for the session note (Coach Instructions). Returns the draft ids, a read-back, and unit advisories. Review, then workout_publish.",
|
|
1174
|
+
description: "Build an UNPUBLISHED session from a spec (program -> session -> blocks -> exercises). Pass programId for a team/group calendar (list_teams → group_program), or athleteId to write on that roster athlete's coach calendar (resolved via /v5/calendars/athletes/{id} — the same calendar the coach web app opens from My Athletes). athleteId requires date. Two exercises in one block become a superset. A block with empty exercises and a non-empty block instruction is a text-only Circuit / Conditioning block (type 1). Add a block 'leaderboard' for a Red-Zone score, or a top-level 'instruction' for the session note (Coach Instructions). Returns the draft ids, a read-back, and unit advisories. Review, then workout_publish.",
|
|
1169
1175
|
inputSchema: {
|
|
1170
|
-
programId: z.number(),
|
|
1176
|
+
programId: z.number().optional(),
|
|
1177
|
+
athleteId: idParam.optional(),
|
|
1171
1178
|
date: z.string().optional(),
|
|
1172
1179
|
timelineDay: z.number().optional(),
|
|
1173
1180
|
blocks: z.array(blockSpecSchema),
|
|
@@ -1178,11 +1185,16 @@ function registerBuild(server, ctx) {
|
|
|
1178
1185
|
destructiveHint: false,
|
|
1179
1186
|
openWorldHint: true
|
|
1180
1187
|
}
|
|
1181
|
-
}, ({ programId, date, timelineDay, blocks, instruction }) => attempt(async () => {
|
|
1188
|
+
}, ({ programId, athleteId, date, timelineDay, blocks, instruction }) => attempt(async () => {
|
|
1182
1189
|
if (date === void 0 && timelineDay === void 0) return errorResult("Provide either date (YYYY-M-D) or timelineDay.");
|
|
1190
|
+
const resolveArgs = {};
|
|
1191
|
+
if (programId !== void 0) resolveArgs.programId = programId;
|
|
1192
|
+
if (athleteId !== void 0) resolveArgs.athleteId = toId(athleteId);
|
|
1193
|
+
if (date !== void 0) resolveArgs.date = date;
|
|
1194
|
+
const resolved = await resolveBuildProgramId(ctx.client, resolveArgs);
|
|
1183
1195
|
const typed = blocks;
|
|
1184
1196
|
const opts = {
|
|
1185
|
-
programId,
|
|
1197
|
+
programId: resolved,
|
|
1186
1198
|
blocks: typed,
|
|
1187
1199
|
publish: false
|
|
1188
1200
|
};
|
|
@@ -1191,15 +1203,19 @@ function registerBuild(server, ctx) {
|
|
|
1191
1203
|
if (instruction !== void 0) opts.instruction = instruction;
|
|
1192
1204
|
const advisories = await collectAdvisories(typed, ctx.index);
|
|
1193
1205
|
const built = await buildSession(ctx.client, opts);
|
|
1194
|
-
const readback = opts.date ? await readSession(ctx.client,
|
|
1206
|
+
const readback = opts.date ? await readSession(ctx.client, resolved, opts.date, built.pwId) : null;
|
|
1195
1207
|
return jsonResult({
|
|
1196
1208
|
...built,
|
|
1209
|
+
programId: resolved,
|
|
1197
1210
|
published: false,
|
|
1198
1211
|
advisories,
|
|
1199
1212
|
readback,
|
|
1200
1213
|
note: "Draft created (unpublished). Review, then call workout_publish to make it athlete-facing."
|
|
1201
1214
|
});
|
|
1202
1215
|
}));
|
|
1216
|
+
}
|
|
1217
|
+
/** Read-back and publish for a built session. */
|
|
1218
|
+
function registerReadPublish(server, ctx) {
|
|
1203
1219
|
server.registerTool("workout_read", {
|
|
1204
1220
|
title: "Read a built session",
|
|
1205
1221
|
description: "Read-back a session by programId, date (YYYY-M-D), and programWorkout id.",
|
|
@@ -1233,7 +1249,8 @@ function registerBuild(server, ctx) {
|
|
|
1233
1249
|
await publishSession(ctx.client, pwId);
|
|
1234
1250
|
return jsonResult({
|
|
1235
1251
|
published: pwId,
|
|
1236
|
-
readback: await readSession(ctx.client, programId, parseWorkoutDate(date), pwId)
|
|
1252
|
+
readback: await readSession(ctx.client, programId, parseWorkoutDate(date), pwId),
|
|
1253
|
+
note: "Published. Verify with workout_read (same programId/date/pwId). Do not use athlete_workouts to check a coach-published team session — that tool is the authenticated user's own athlete calendar, not a roster athlete's schedule. For a roster athlete's view use athlete_saved_workouts."
|
|
1237
1254
|
});
|
|
1238
1255
|
}));
|
|
1239
1256
|
}
|
|
@@ -1277,7 +1294,7 @@ function registerLifecycle(server, ctx) {
|
|
|
1277
1294
|
}));
|
|
1278
1295
|
server.registerTool("session_copy", {
|
|
1279
1296
|
title: "Copy a session to a date",
|
|
1280
|
-
description: "Copy/repeat a session to a target date on a program (POST .../copyProgramWorkout). toDate is YYYY-M-D. Creates a new session; review and publish it separately.",
|
|
1297
|
+
description: "Copy/repeat a session to a target date on a program (POST .../copyProgramWorkout). toDate is YYYY-M-D. Creates a new session; review and publish it separately. toProgramId may be a team group_program or an athlete calendar program id (from /v5/calendars/athletes/{athleteId}?year=&month= / workout_build athleteId).",
|
|
1281
1298
|
inputSchema: {
|
|
1282
1299
|
toProgramId: z.number(),
|
|
1283
1300
|
pwId: z.number(),
|
|
@@ -1307,6 +1324,7 @@ function registerLifecycle(server, ctx) {
|
|
|
1307
1324
|
/** Workout building, read-back, publishing, and the session calendar lifecycle. */
|
|
1308
1325
|
function registerWorkoutTools(server, ctx) {
|
|
1309
1326
|
registerBuild(server, ctx);
|
|
1327
|
+
registerReadPublish(server, ctx);
|
|
1310
1328
|
registerLifecycle(server, ctx);
|
|
1311
1329
|
}
|
|
1312
1330
|
//#endregion
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@trainheroic-unofficial/core",
|
|
3
|
-
"version": "2.0
|
|
3
|
+
"version": "2.1.0",
|
|
4
4
|
"license": "MIT",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -25,8 +25,8 @@
|
|
|
25
25
|
"@cfworker/json-schema": "^4.1.1",
|
|
26
26
|
"@modelcontextprotocol/server": "2.0.0",
|
|
27
27
|
"zod": "^4.4.3",
|
|
28
|
-
"@trainheroic-unofficial/dto": "2.0
|
|
29
|
-
"@trainheroic-unofficial/js": "2.0
|
|
28
|
+
"@trainheroic-unofficial/dto": "2.1.0",
|
|
29
|
+
"@trainheroic-unofficial/js": "2.1.0"
|
|
30
30
|
},
|
|
31
31
|
"devDependencies": {
|
|
32
32
|
"@types/node": "^26.1.2",
|