@trainheroic-unofficial/core 1.1.0 → 1.2.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/README.md +9 -11
- package/dist/index.mjs +53 -12
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# @trainheroic-unofficial/core
|
|
2
2
|
|
|
3
3
|
The shared [MCP](https://modelcontextprotocol.io) (Model Context Protocol) tool layer for
|
|
4
|
-
TrainHeroic. Each tool
|
|
4
|
+
TrainHeroic. Each tool (a function an AI assistant can call) is defined once here and reused
|
|
5
5
|
by both servers: the local stdio server (`@trainheroic-unofficial/coach-mcp`) and the hosted
|
|
6
6
|
Cloudflare worker (`@trainheroic-unofficial/cloudflare`). You only need this package if you
|
|
7
7
|
are building your own MCP server; to _use_ the tools, run one of those servers.
|
|
@@ -20,8 +20,8 @@ A server builds a `ToolContext` and passes it, along with its MCP server instanc
|
|
|
20
20
|
`registerXxxTools(server, ctx)` functions (the `register*` names below are the real exports;
|
|
21
21
|
`registerXxxTools` is shorthand for all of them). `ToolContext` is `{ client, index }`: an
|
|
22
22
|
authenticated `TrainHeroicClient` (from `@trainheroic-unofficial/js`) and anything implementing
|
|
23
|
-
the `ExerciseIndex` interface
|
|
24
|
-
D1-backed store.
|
|
23
|
+
the `ExerciseIndex` interface (the in-memory `ExerciseLibrary` here, or the hosted worker's
|
|
24
|
+
D1-backed store).
|
|
25
25
|
|
|
26
26
|
Install it alongside the MCP SDK and the `js` client (both peers you construct from):
|
|
27
27
|
|
|
@@ -66,26 +66,24 @@ Each `register*` function registers a group of tools, and the individual tool na
|
|
|
66
66
|
sees are snake_case (e.g. `analytics_query`, `exercise_resolve`). The groups:
|
|
67
67
|
|
|
68
68
|
- coach reads (profile, athletes, teams, programs, notifications, analytics catalog)
|
|
69
|
-
- athlete management (`registerAthleteTools
|
|
69
|
+
- athlete management (`registerAthleteTools`, the coach's _roster_ view: invite, archive, restore)
|
|
70
70
|
- team management (create, rename, delete, join codes)
|
|
71
71
|
- analytics report pulls (`analytics_query`: readiness, 1RM (one-rep max) and working-max history, training summary, compliance, lift progress)
|
|
72
72
|
- exercise library operations (resolve, search, get, sync, create, forget, stats)
|
|
73
73
|
- the workout/session lifecycle (build a draft, read it back, publish, unpublish, copy, save as template, remove)
|
|
74
74
|
- messaging (list, read, draft, send, delete)
|
|
75
75
|
|
|
76
|
-
|
|
76
|
+
Every endpoint reaches the model through a typed tool; the surface has no raw-request escape hatch.
|
|
77
77
|
(`registerAthleteTools` here is the coach's roster view, distinct from the athlete's own
|
|
78
78
|
training tools that the athlete server registers.)
|
|
79
79
|
|
|
80
80
|
Tools return their result in-band. A failure comes back as an error result the model can read
|
|
81
|
-
and correct
|
|
81
|
+
and self-correct from. Reads are annotated read-only. Athlete-facing or
|
|
82
82
|
destructive actions (publish, unpublish, remove, send, delete, archive, team/code delete) pass
|
|
83
|
-
through a confirmation gate
|
|
84
|
-
an explicit `confirm: true` argument
|
|
85
|
-
is satisfied.
|
|
83
|
+
through a confirmation gate. The gate prefers MCP elicitation; when the client cannot elicit,
|
|
84
|
+
it accepts an explicit `confirm: true` argument. It fails closed if neither condition is met.
|
|
86
85
|
|
|
87
|
-
The D1-backed warehouse sync tools
|
|
88
|
-
because they depend on its storage.
|
|
86
|
+
The D1-backed warehouse sync tools live in the `cloudflare` package because they depend on its storage.
|
|
89
87
|
|
|
90
88
|
## Develop
|
|
91
89
|
|
package/dist/index.mjs
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
import { blockSpecSchema, coachLogSessionArgsSchema, coachLogSetArgsSchema, commentDraftSchema, dateString, exerciseCreateSchema, idArgSchema, logSessionArgsSchema, logSetArgsSchema, parseWorkoutDate } from "@trainheroic-unofficial/dto";
|
|
1
|
+
import { blockSpecSchema, coachLogSessionArgsSchema, coachLogSetArgsSchema, coachPrescribeSetArgsSchema, commentDraftSchema, dateString, exerciseCreateSchema, idArgSchema, logSessionArgsSchema, logSetArgsSchema, parseWorkoutDate, swapAthleteExerciseArgsSchema } from "@trainheroic-unofficial/dto";
|
|
2
2
|
import { z } from "zod";
|
|
3
|
-
import { ANALYTICS_METRIC_KEYS, addExercisesToWorkout, buildCommentPayload, buildSession, coerceInt, collectAdvisories, copySession, createPersonalWorkout, definedProps, deleteComment, exerciseUnits, fetchAthletePrefs, fetchAthleteProfileSummary, fetchAthleteUser, fetchAthleteWorkouts, fetchCoachAthleteCalendarSummary, fetchCoachAthleteWorkouts, fetchExerciseHistoryDetail, fetchExerciseHistoryList, fetchExerciseStats, fetchLeaderboard, fetchPersonalRecords, fetchRosterActivity, fetchStreams, fetchTeamAthleteIds, fetchWorkingMaxes, inviteAthletes, isRecord, logAdHocSession, logAthleteSet, logForAthlete, logSessionForAthlete, presentAthleteWorkouts, presentCoachAthleteTraining, presentExerciseHistory, publishSession, queryAnalytics, readLive, readSession, removeSession, searchExerciseHistory, selectWorkouts, sendComment, summarizeAthleteWorkouts, teamVolume } from "@trainheroic-unofficial/js";
|
|
3
|
+
import { ANALYTICS_METRIC_KEYS, addExercisesToWorkout, buildCommentPayload, buildSession, coerceInt, collectAdvisories, copySession, createPersonalWorkout, definedProps, deleteComment, exerciseUnits, fetchAthletePrefs, fetchAthleteProfileSummary, fetchAthleteUser, fetchAthleteWorkouts, fetchCoachAthleteCalendarSummary, fetchCoachAthleteWorkouts, fetchExerciseHistoryDetail, fetchExerciseHistoryList, fetchExerciseStats, fetchLeaderboard, fetchPersonalRecords, fetchRosterActivity, fetchStreams, fetchTeamAthleteIds, fetchWorkingMaxes, inviteAthletes, isRecord, logAdHocSession, logAthleteSet, logForAthlete, logSessionForAthlete, prescribeForAthlete, presentAthleteWorkouts, presentCoachAthleteTraining, presentExerciseHistory, publishSession, queryAnalytics, readLive, readSession, removeSession, searchExerciseHistory, selectWorkouts, sendComment, summarizeAthleteWorkouts, swapAthleteExercise, teamVolume, toSetResults } from "@trainheroic-unofficial/js";
|
|
4
4
|
//#region src/context.ts
|
|
5
5
|
/** A tool argument that accepts a numeric id as a number or a string of digits. */
|
|
6
6
|
const idParam = idArgSchema;
|
|
@@ -719,6 +719,8 @@ function registerAthleteTools(server, ctx) {
|
|
|
719
719
|
}
|
|
720
720
|
}, ({ athleteIds }) => apiCall(ctx, "PUT", "/v5/athletes/restore", { body: { athleteIds: athleteIds.map(toId) } }));
|
|
721
721
|
registerAthleteLogTools(server, ctx);
|
|
722
|
+
registerAthleteSwapTool(server, ctx);
|
|
723
|
+
registerAthletePrescribeTool(server, ctx);
|
|
722
724
|
}
|
|
723
725
|
/**
|
|
724
726
|
* Coach "Log for Athlete": read a roster athlete's saved workouts (to get the log ids), then
|
|
@@ -753,20 +755,11 @@ function registerAthleteLogTools(server, ctx) {
|
|
|
753
755
|
}, ({ athleteId, date, savedWorkoutSetId, results, confirm }, extra) => attempt(async () => {
|
|
754
756
|
const aId = toId(athleteId);
|
|
755
757
|
if (!await confirmGate(server, extra.requestId, `Log results to athlete ${aId}'s saved workout set ${toId(savedWorkoutSetId)} on ${date}? This writes to their coach-visible training log.`, confirm)) return errorResult(NOT_CONFIRMED);
|
|
756
|
-
const mapped = results.map((r) => ({
|
|
757
|
-
savedWorkoutSetExerciseId: toId(r.savedWorkoutSetExerciseId),
|
|
758
|
-
sets: r.sets.map((s) => {
|
|
759
|
-
const slot = {};
|
|
760
|
-
if (s.param1 !== void 0) slot.param1 = s.param1;
|
|
761
|
-
if (s.param2 !== void 0) slot.param2 = s.param2;
|
|
762
|
-
return slot;
|
|
763
|
-
})
|
|
764
|
-
}));
|
|
765
758
|
return jsonResult(await logForAthlete(ctx.client, {
|
|
766
759
|
athleteId: aId,
|
|
767
760
|
date,
|
|
768
761
|
savedWorkoutSetId: toId(savedWorkoutSetId),
|
|
769
|
-
results:
|
|
762
|
+
results: toSetResults(results)
|
|
770
763
|
}));
|
|
771
764
|
}));
|
|
772
765
|
server.registerTool("coach_log_session", {
|
|
@@ -787,6 +780,54 @@ function registerAthleteLogTools(server, ctx) {
|
|
|
787
780
|
}));
|
|
788
781
|
}));
|
|
789
782
|
}
|
|
783
|
+
/**
|
|
784
|
+
* Coach per-athlete exercise swap, kept in its own function so registerAthleteLogTools stays
|
|
785
|
+
* under the oxlint max-lines-per-function cap.
|
|
786
|
+
*/
|
|
787
|
+
function registerAthleteSwapTool(server, ctx) {
|
|
788
|
+
server.registerTool("swap_athlete_exercise", {
|
|
789
|
+
title: "Swap one exercise in a roster athlete's prescribed workout",
|
|
790
|
+
description: "Coach-facing write: replace one exercise in a roster athlete's scheduled workout with a different one, for that athlete only — the API equivalent of the app's per-athlete \"swap exercise\". The team/program prescription is left untouched, so other athletes on the same program keep the original exercise. Give savedWorkoutSetExerciseId (the athlete's own slot, from athlete_saved_workouts with raw:true) and exerciseId (the replacement, from exercise_resolve / exercise_search). Seeded demo athletes are read-only and will fail; use a real (invited) athlete. Requires confirmation (elicitation or confirm:true).",
|
|
791
|
+
inputSchema: {
|
|
792
|
+
...swapAthleteExerciseArgsSchema.shape,
|
|
793
|
+
confirm: z.boolean().optional()
|
|
794
|
+
},
|
|
795
|
+
annotations: DESTRUCTIVE
|
|
796
|
+
}, ({ savedWorkoutSetExerciseId, exerciseId, confirm }, extra) => attempt(async () => {
|
|
797
|
+
const sweId = toId(savedWorkoutSetExerciseId);
|
|
798
|
+
const exId = toId(exerciseId);
|
|
799
|
+
if (!await confirmGate(server, extra.requestId, `Swap the exercise in saved workout slot ${sweId} to exercise ${exId}? This changes what this athlete is prescribed (their copy only).`, confirm)) return errorResult(NOT_CONFIRMED);
|
|
800
|
+
return jsonResult(await swapAthleteExercise(ctx.client, {
|
|
801
|
+
savedWorkoutSetExerciseId: sweId,
|
|
802
|
+
exerciseId: exId
|
|
803
|
+
}));
|
|
804
|
+
}));
|
|
805
|
+
}
|
|
806
|
+
/**
|
|
807
|
+
* Coach prescription override, kept in its own function so registerAthleteTools stays under the
|
|
808
|
+
* oxlint max-lines-per-function cap. Lets a coach set the prescribed reps/weight for one of a
|
|
809
|
+
* roster athlete's saved workout sets without marking it done — "prescribe weights for an athlete".
|
|
810
|
+
*/
|
|
811
|
+
function registerAthletePrescribeTool(server, ctx) {
|
|
812
|
+
server.registerTool("prescribe_athlete_set", {
|
|
813
|
+
title: "Prescribe reps/weight for a roster athlete's set",
|
|
814
|
+
description: "Coach-facing write: set the prescribed reps and/or weight for one of a roster athlete's scheduled workout sets, for that athlete only, WITHOUT marking it done — the API equivalent of the app's editing an athlete's prescribed values (\"prescribe weights for an athlete\"). The set stays open for the athlete to log against, and the team/program prescription is left untouched, so other athletes keep the original targets. param1 is reps, param2 is weight; pass one sets[] entry per prescribed set. The write REPLACES the slot's prescribed values (the sets you pass become the whole prescription, and an omitted param is cleared), so give the full per-set prescription you want. Get athleteId from list_athletes; get savedWorkoutSetId + savedWorkoutSetExerciseId from athlete_saved_workouts (raw:true) for that athlete/day. To record a set as PERFORMED instead, use log_athlete_set. Seeded demo athletes are read-only and will fail; use a real (invited) athlete. Requires confirmation (elicitation or confirm:true).",
|
|
815
|
+
inputSchema: {
|
|
816
|
+
...coachPrescribeSetArgsSchema.shape,
|
|
817
|
+
confirm: z.boolean().optional()
|
|
818
|
+
},
|
|
819
|
+
annotations: DESTRUCTIVE
|
|
820
|
+
}, ({ athleteId, date, savedWorkoutSetId, results, confirm }, extra) => attempt(async () => {
|
|
821
|
+
const aId = toId(athleteId);
|
|
822
|
+
if (!await confirmGate(server, extra.requestId, `Set prescribed values on athlete ${aId}'s saved workout set ${toId(savedWorkoutSetId)} on ${date}? This changes what this athlete is prescribed (their copy only); it does not mark the set done.`, confirm)) return errorResult(NOT_CONFIRMED);
|
|
823
|
+
return jsonResult(await prescribeForAthlete(ctx.client, {
|
|
824
|
+
athleteId: aId,
|
|
825
|
+
date,
|
|
826
|
+
savedWorkoutSetId: toId(savedWorkoutSetId),
|
|
827
|
+
results: toSetResults(results)
|
|
828
|
+
}));
|
|
829
|
+
}));
|
|
830
|
+
}
|
|
790
831
|
//#endregion
|
|
791
832
|
//#region src/tools/teams.ts
|
|
792
833
|
const ADDITIVE = {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@trainheroic-unofficial/core",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.2.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/sdk": "^1.29.0",
|
|
27
27
|
"zod": "^4.4.3",
|
|
28
|
-
"@trainheroic-unofficial/dto": "1.
|
|
29
|
-
"@trainheroic-unofficial/js": "1.
|
|
28
|
+
"@trainheroic-unofficial/dto": "1.2.0",
|
|
29
|
+
"@trainheroic-unofficial/js": "1.2.0"
|
|
30
30
|
},
|
|
31
31
|
"devDependencies": {
|
|
32
32
|
"@types/node": "^26.0.0",
|