@trainheroic-unofficial/coach-mcp 3.0.1 → 3.1.1
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/server.mjs +117 -29
- package/package.json +3 -3
package/dist/server.mjs
CHANGED
|
@@ -201,21 +201,12 @@ const coachLogSetArgsSchema = z.object({
|
|
|
201
201
|
savedWorkoutSetId: idArgSchema,
|
|
202
202
|
results: loggedExerciseResultsSchema
|
|
203
203
|
}).extend({ athleteId: idArgSchema });
|
|
204
|
-
/**
|
|
205
|
-
* Args for the coach prescription-override write. Like {@link coachLogSetArgsSchema}
|
|
206
|
-
* (athleteId + date + savedWorkoutSetId + per-exercise `sets`), but the values are prescribed
|
|
207
|
-
* targets (param1 = reps, param2 = weight) written to the athlete's plan without marking the set
|
|
208
|
-
* performed. The write replaces this athlete's whole prescription for the set, so its sets are
|
|
209
|
-
* positional and sequential by definition: it deliberately omits the log path's `slot` field (a
|
|
210
|
-
* sparse, slot-targeted prescription has no meaning here) by building its results off
|
|
211
|
-
* {@link loggedSetSchema} rather than {@link loggedSetWithSlotSchema}.
|
|
212
|
-
*/
|
|
204
|
+
/** Coach variant of {@link athletePrescribeSetArgsSchema}, with the roster athlete to update. */
|
|
213
205
|
const coachPrescribeSetArgsSchema = z.object({
|
|
214
206
|
date: dateString,
|
|
215
207
|
savedWorkoutSetId: idArgSchema,
|
|
216
|
-
athleteId: idArgSchema,
|
|
217
208
|
results: prescribedExerciseResultsSchema
|
|
218
|
-
});
|
|
209
|
+
}).extend({ athleteId: idArgSchema });
|
|
219
210
|
/**
|
|
220
211
|
* Args for the coach per-athlete exercise swap: replace the exercise prescribed in one of a
|
|
221
212
|
* roster athlete's saved-workout slots with a different exercise, the API equivalent of the
|
|
@@ -288,6 +279,18 @@ const programWorkoutResponseSchema = z.looseObject({
|
|
|
288
279
|
});
|
|
289
280
|
/** The calendar edit-view response we read sessions back from. */
|
|
290
281
|
const programsEditResponseSchema = z.looseObject({ programWorkouts: z.array(programWorkoutResponseSchema).optional() });
|
|
282
|
+
/** A standalone program create response (container id + usable calendar/program id). */
|
|
283
|
+
const programCreateResponseSchema = z.looseObject({
|
|
284
|
+
id: intLike,
|
|
285
|
+
title: z.string(),
|
|
286
|
+
programId: intLike,
|
|
287
|
+
group_program: intLike,
|
|
288
|
+
type: intLike,
|
|
289
|
+
program: z.looseObject({
|
|
290
|
+
id: intLike,
|
|
291
|
+
program_type: intLike
|
|
292
|
+
}).optional()
|
|
293
|
+
});
|
|
291
294
|
//#endregion
|
|
292
295
|
//#region ../dto/src/workout.ts
|
|
293
296
|
/** A single exercise prescription inside a block. */
|
|
@@ -513,15 +516,18 @@ function errorResult(message) {
|
|
|
513
516
|
}]
|
|
514
517
|
};
|
|
515
518
|
}
|
|
519
|
+
/** Format an already-issued TrainHeroic response as a size-bounded tool result. */
|
|
520
|
+
function apiResponseResult(res, hint) {
|
|
521
|
+
if (!res.ok) {
|
|
522
|
+
const detail = hardCap(typeof res.data === "string" ? res.data : JSON.stringify(res.data) ?? "", resultBudget());
|
|
523
|
+
return errorResult(`TrainHeroic API error (HTTP ${res.status}): ${detail}`);
|
|
524
|
+
}
|
|
525
|
+
return jsonResult(res.data, { hint });
|
|
526
|
+
}
|
|
516
527
|
/** Issue a TrainHeroic request and format the outcome as a tool result. */
|
|
517
528
|
async function apiCall(ctx, method, path, options, hint) {
|
|
518
529
|
return attempt(async () => {
|
|
519
|
-
|
|
520
|
-
if (!res.ok) {
|
|
521
|
-
const detail = hardCap(typeof res.data === "string" ? res.data : JSON.stringify(res.data) ?? "", resultBudget());
|
|
522
|
-
return errorResult(`TrainHeroic API error (HTTP ${res.status}): ${detail}`);
|
|
523
|
-
}
|
|
524
|
-
return jsonResult(res.data, { hint });
|
|
530
|
+
return apiResponseResult(await ctx.client.request(method, path, options), hint);
|
|
525
531
|
});
|
|
526
532
|
}
|
|
527
533
|
//#endregion
|
|
@@ -731,7 +737,7 @@ var TrainHeroicClient = class {
|
|
|
731
737
|
session = await this.#ensureSession();
|
|
732
738
|
res = await this.#send(method, url, session, options.body);
|
|
733
739
|
}
|
|
734
|
-
if (!res.ok) notifyHttpError(this.#onHttpError, method, url, res.status);
|
|
740
|
+
if (!res.ok && !options.expectedStatuses?.includes(res.status)) notifyHttpError(this.#onHttpError, method, url, res.status);
|
|
735
741
|
const text = await res.text();
|
|
736
742
|
let data = text;
|
|
737
743
|
if (text.length > 0) try {
|
|
@@ -1719,9 +1725,10 @@ async function swapAthleteExercise(client, args) {
|
|
|
1719
1725
|
};
|
|
1720
1726
|
}
|
|
1721
1727
|
/**
|
|
1722
|
-
* Shared set-write behind {@link logAthleteSet}, {@link
|
|
1723
|
-
* {@link prescribeForAthlete}. `target` selects the surface: `athlete`
|
|
1724
|
-
* `coach` writes `/1.0/coach/...{athleteId}` and stamps `athleteId` into
|
|
1728
|
+
* Shared set-write behind {@link logAthleteSet}, {@link prescribeAthleteSet},
|
|
1729
|
+
* {@link logForAthlete}, and {@link prescribeForAthlete}. `target` selects the surface: `athlete`
|
|
1730
|
+
* writes `/1.0/athlete/...`; `coach` writes `/1.0/coach/...{athleteId}` and stamps `athleteId` into
|
|
1731
|
+
* each body.
|
|
1725
1732
|
*
|
|
1726
1733
|
* Step 1 PUTs each exercise's per-set values to its own endpoint (the only path that actually
|
|
1727
1734
|
* stores reps and weight). `mode` decides what those values mean: `"log"` records them as a
|
|
@@ -2242,6 +2249,45 @@ function readExercise(ex) {
|
|
|
2242
2249
|
instruction: str(ex.instruction)
|
|
2243
2250
|
};
|
|
2244
2251
|
}
|
|
2252
|
+
const PROGRAM_KINDS = ["calendar", "fixed"];
|
|
2253
|
+
/**
|
|
2254
|
+
* Create a standalone ongoing calendar or fixed-length program.
|
|
2255
|
+
*
|
|
2256
|
+
* TrainHeroic returns both a container id and the underlying program id. They are deliberately
|
|
2257
|
+
* named separately here because `/3.0/coach/program/{containerId}` returns 401, while the
|
|
2258
|
+
* `programId` works. This write is not idempotent: callers must not blindly retry an uncertain
|
|
2259
|
+
* result. The live API currently accepts `name` but may generate its own title; `nameApplied`
|
|
2260
|
+
* reports what happened.
|
|
2261
|
+
*/
|
|
2262
|
+
async function createProgram(client, args) {
|
|
2263
|
+
if (!PROGRAM_KINDS.includes(args.kind)) throw new Error(`Unknown program kind: ${String(args.kind)}.`);
|
|
2264
|
+
if (typeof args.name !== "string" || args.name.trim() === "") throw new Error("Program name must not be blank.");
|
|
2265
|
+
const requestedName = args.name.trim();
|
|
2266
|
+
const res = await client.request("POST", "/1.0/coach/programs/create", { body: {
|
|
2267
|
+
finite: args.kind === "fixed",
|
|
2268
|
+
name: requestedName
|
|
2269
|
+
} });
|
|
2270
|
+
if (!res.ok) {
|
|
2271
|
+
const detail = typeof res.data === "string" ? res.data : JSON.stringify(res.data);
|
|
2272
|
+
throw new Error(`Program create failed (HTTP ${res.status}): ${detail}`);
|
|
2273
|
+
}
|
|
2274
|
+
checkResponse(programCreateResponseSchema, res.data, "program create");
|
|
2275
|
+
const rec = isRecord(res.data) ? res.data : {};
|
|
2276
|
+
const nested = isRecord(rec.program) ? rec.program : {};
|
|
2277
|
+
const containerId = coerceInt(rec.id);
|
|
2278
|
+
const programId = coerceInt(rec.programId) ?? coerceInt(rec.group_program) ?? coerceInt(nested.id);
|
|
2279
|
+
if (containerId === null || programId === null) throw new Error("Program create response is missing the container id or program id.");
|
|
2280
|
+
if (typeof rec.title !== "string" || rec.title.trim() === "") throw new Error("Program create response is missing the assigned title.");
|
|
2281
|
+
const title = rec.title;
|
|
2282
|
+
return {
|
|
2283
|
+
containerId,
|
|
2284
|
+
programId,
|
|
2285
|
+
title,
|
|
2286
|
+
kind: args.kind,
|
|
2287
|
+
requestedName,
|
|
2288
|
+
nameApplied: title === requestedName
|
|
2289
|
+
};
|
|
2290
|
+
}
|
|
2245
2291
|
/** Normalize one-or-many emails into a deduped, trimmed list. */
|
|
2246
2292
|
function emailList(emails) {
|
|
2247
2293
|
return [...new Set(emails.map((e) => e.trim()).filter((e) => e.length > 0))];
|
|
@@ -3069,7 +3115,7 @@ const SIMPLE_GETS = [
|
|
|
3069
3115
|
{
|
|
3070
3116
|
name: "list_programs",
|
|
3071
3117
|
title: "List programs",
|
|
3072
|
-
description: "Coach programs (standalone only). This is often empty even for an active coach, because most programming lives as a team's group-program: if it returns [], call list_teams and read each team's group_program — do not conclude the coach has no programs.",
|
|
3118
|
+
description: "Coach programs (standalone only). This is often empty even for an active coach, because most programming lives as a team's group-program: if it returns [], call list_teams and read each team's group_program — do not conclude the coach has no programs. Each standalone row has two ids: id is its container/calendar id; group_program is the underlying program id used by workout writes. get_program accepts either one.",
|
|
3073
3119
|
path: "/1.0/coach/programs"
|
|
3074
3120
|
},
|
|
3075
3121
|
{
|
|
@@ -3196,10 +3242,29 @@ function registerEntityReads(server, ctx) {
|
|
|
3196
3242
|
}));
|
|
3197
3243
|
server.registerTool("get_program", {
|
|
3198
3244
|
title: "Get program detail",
|
|
3199
|
-
description: "
|
|
3245
|
+
description: "Program detail live from the API, by program id. Works for team calendars and athlete coach calendars (type 5 from /v5/calendars/athletes/{id}). For standalone rows from list_programs, accepts either id (the container id) or group_program (the underlying program id); container ids are resolved automatically. If neither detail endpoint is available, returns calendar metadata and next-step guidance instead.",
|
|
3200
3246
|
inputSchema: { programId: idParam },
|
|
3201
3247
|
annotations: READ
|
|
3202
|
-
}, ({ programId }) =>
|
|
3248
|
+
}, ({ programId }) => getProgram(ctx, toId(programId)));
|
|
3249
|
+
}
|
|
3250
|
+
async function getProgram(ctx, programId) {
|
|
3251
|
+
return attempt(async () => {
|
|
3252
|
+
const detail = await ctx.client.request("GET", `/3.0/coach/program/${enc(programId)}`, { expectedStatuses: [401, 403] });
|
|
3253
|
+
if (detail.ok || detail.status !== 401 && detail.status !== 403) return apiResponseResult(detail, "This is a large, deep object. If it is truncated, fetch a narrower view (a specific session) instead.");
|
|
3254
|
+
const programs = await ctx.client.request("GET", "/1.0/coach/programs");
|
|
3255
|
+
const program = Array.isArray(programs.data) ? programs.data.find((item) => isRecord(item) && coerceInt(item.id) === programId) : void 0;
|
|
3256
|
+
if (!programs.ok || !program) return apiResponseResult(detail);
|
|
3257
|
+
const actualProgramId = coerceInt(program.group_program);
|
|
3258
|
+
if (actualProgramId !== null && actualProgramId !== programId) {
|
|
3259
|
+
const actualDetail = await ctx.client.request("GET", `/3.0/coach/program/${enc(actualProgramId)}`, { expectedStatuses: [401, 403] });
|
|
3260
|
+
if (actualDetail.ok || actualDetail.status !== 401 && actualDetail.status !== 403) return apiResponseResult(actualDetail, "This is a large, deep object. If it is truncated, fetch a narrower view (a specific session) instead.");
|
|
3261
|
+
}
|
|
3262
|
+
return jsonResult({
|
|
3263
|
+
program,
|
|
3264
|
+
detailAvailable: false,
|
|
3265
|
+
note: "TrainHeroic recognizes this as a valid standalone calendar, but its nested program-detail endpoint does not expose this calendar type. Use calendar/session reads instead; on the hosted server, programming_sync then programming_stored can read its dated sessions."
|
|
3266
|
+
});
|
|
3267
|
+
});
|
|
3203
3268
|
}
|
|
3204
3269
|
/** Read-only coach/athlete queries. Exercise lookups live in the exercise store tools. */
|
|
3205
3270
|
/** The windowed team-volume read — its own function so registerEntityReads stays under the cap. */
|
|
@@ -3470,7 +3535,7 @@ function registerAthletePrescribeTool(server, ctx) {
|
|
|
3470
3535
|
}
|
|
3471
3536
|
//#endregion
|
|
3472
3537
|
//#region ../core/src/tools/teams.ts
|
|
3473
|
-
const ADDITIVE = {
|
|
3538
|
+
const ADDITIVE$1 = {
|
|
3474
3539
|
readOnlyHint: false,
|
|
3475
3540
|
destructiveHint: false,
|
|
3476
3541
|
openWorldHint: true
|
|
@@ -3484,7 +3549,7 @@ function registerTeamTools(server, ctx) {
|
|
|
3484
3549
|
title: "Create a team",
|
|
3485
3550
|
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.",
|
|
3486
3551
|
inputSchema: { title: z.string().min(1) },
|
|
3487
|
-
annotations: ADDITIVE
|
|
3552
|
+
annotations: ADDITIVE$1
|
|
3488
3553
|
}, ({ title }) => apiCall(ctx, "POST", "/1.0/coach/team/createWithTitleAndCode", { body: { title } }));
|
|
3489
3554
|
server.registerTool("team_update", {
|
|
3490
3555
|
title: "Update a team",
|
|
@@ -3494,7 +3559,7 @@ function registerTeamTools(server, ctx) {
|
|
|
3494
3559
|
title: z.string().min(1).optional(),
|
|
3495
3560
|
groupProgram: idParam.optional()
|
|
3496
3561
|
},
|
|
3497
|
-
annotations: ADDITIVE
|
|
3562
|
+
annotations: ADDITIVE$1
|
|
3498
3563
|
}, ({ teamId, title, groupProgram }) => attempt(async () => {
|
|
3499
3564
|
const args = { teamId: toId(teamId) };
|
|
3500
3565
|
if (title !== void 0) args.title = title;
|
|
@@ -3522,7 +3587,7 @@ function registerTeamTools(server, ctx) {
|
|
|
3522
3587
|
teamId: idParam,
|
|
3523
3588
|
type: z.number().int().optional()
|
|
3524
3589
|
},
|
|
3525
|
-
annotations: ADDITIVE
|
|
3590
|
+
annotations: ADDITIVE$1
|
|
3526
3591
|
}, ({ teamId, type }) => apiCall(ctx, "POST", `/v5/teams/${toId(teamId)}/teamCodes`, { body: { type: type ?? 2 } }));
|
|
3527
3592
|
server.registerTool("team_code_delete", {
|
|
3528
3593
|
title: "Delete a team join code",
|
|
@@ -3540,6 +3605,28 @@ function registerTeamTools(server, ctx) {
|
|
|
3540
3605
|
}));
|
|
3541
3606
|
}
|
|
3542
3607
|
//#endregion
|
|
3608
|
+
//#region ../core/src/tools/programs.ts
|
|
3609
|
+
const ADDITIVE = {
|
|
3610
|
+
readOnlyHint: false,
|
|
3611
|
+
destructiveHint: false,
|
|
3612
|
+
openWorldHint: true
|
|
3613
|
+
};
|
|
3614
|
+
/** Standalone program writes. Program reads live in reads.ts. */
|
|
3615
|
+
function registerProgramTools(server, ctx) {
|
|
3616
|
+
server.registerTool("program_create", {
|
|
3617
|
+
title: "Create a standalone program",
|
|
3618
|
+
description: "Create either an ongoing calendar or a fixed-length standalone program (POST /1.0/coach/programs/create). Returns both containerId (the id shown by list_programs and used by calendar edit/sync reads) and programId (the id used by get_program and workout writes). TrainHeroic may generate a different title; inspect title and nameApplied. This write is not idempotent, so do not retry an uncertain result.",
|
|
3619
|
+
inputSchema: {
|
|
3620
|
+
kind: z.enum(PROGRAM_KINDS),
|
|
3621
|
+
name: z.string().trim().min(1)
|
|
3622
|
+
},
|
|
3623
|
+
annotations: ADDITIVE
|
|
3624
|
+
}, ({ kind, name }) => attempt(async () => jsonResult(await createProgram(ctx.client, {
|
|
3625
|
+
kind,
|
|
3626
|
+
name
|
|
3627
|
+
}))));
|
|
3628
|
+
}
|
|
3629
|
+
//#endregion
|
|
3543
3630
|
//#region ../core/src/tools/analytics.ts
|
|
3544
3631
|
const ANALYTICS_QUERY_DESC = "Read a TrainHeroic analytics report. The `metric` enum below IS the catalog — pick from it directly (analytics_categories lists the API's raw category names, which do NOT match these keys; you rarely need it). Team metrics (readiness-team, compliance-team, lift-progress-team) need teamId; athlete metrics (readiness-athlete, training-summary-athlete, lift-1rm-history, working-max-history) need userIds — get those from list_athletes. userIds takes MANY athletes in ONE call (pass the whole roster's ids at once); the report comes back with a row per athlete, so do not loop one id per call. For team-wide training volume there is no team summary metric: pass every athlete's userId to training-summary-athlete in a single call and the rows cover the team. An athlete with no logged sessions in range simply returns no rows (not an error). Use that for triage: training-summary-athlete with a single athleteId is the fastest 'has this athlete trained at all, and when' check — no rows means no logged training in range, so don't then fan out blind per-lift athlete_lift_history calls. Despite 'athlete' in the name this metric accepts 1–N userIds. readiness-team takes a single `date`; every other metric takes dateStart/dateEnd. lift-1rm-history, lift-progress-team, and working-max-history also need exerciseId. All dates are YYYY-MM-DD.";
|
|
3545
3632
|
/** Analytics report pulls. Read-only despite the POST verb, so ungated. */
|
|
@@ -3895,6 +3982,7 @@ function registerCoachTools(server, ctx) {
|
|
|
3895
3982
|
registerMainLiftTools(server, ctx);
|
|
3896
3983
|
registerAthleteTools(server, ctx);
|
|
3897
3984
|
registerTeamTools(server, ctx);
|
|
3985
|
+
registerProgramTools(server, ctx);
|
|
3898
3986
|
registerAnalyticsTools(server, ctx);
|
|
3899
3987
|
registerExerciseTools(server, ctx);
|
|
3900
3988
|
registerWorkoutTools(server, ctx);
|
|
@@ -3926,7 +4014,7 @@ var JsonFileLibraryCache = class {
|
|
|
3926
4014
|
};
|
|
3927
4015
|
//#endregion
|
|
3928
4016
|
//#region package.json
|
|
3929
|
-
var version = "3.
|
|
4017
|
+
var version = "3.1.1";
|
|
3930
4018
|
//#endregion
|
|
3931
4019
|
//#region src/server.ts
|
|
3932
4020
|
function main() {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@trainheroic-unofficial/coach-mcp",
|
|
3
|
-
"version": "3.
|
|
3
|
+
"version": "3.1.1",
|
|
4
4
|
"license": "MIT",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -21,8 +21,8 @@
|
|
|
21
21
|
"dependencies": {
|
|
22
22
|
"@modelcontextprotocol/server": "2.0.0",
|
|
23
23
|
"zod": "^4.4.3",
|
|
24
|
-
"@trainheroic-unofficial/core": "3.
|
|
25
|
-
"@trainheroic-unofficial/js": "3.
|
|
24
|
+
"@trainheroic-unofficial/core": "3.1.1",
|
|
25
|
+
"@trainheroic-unofficial/js": "3.1.1"
|
|
26
26
|
},
|
|
27
27
|
"devDependencies": {
|
|
28
28
|
"@types/node": "^26.2.0",
|