@trainheroic-unofficial/core 0.4.1 → 0.5.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 +61 -26
- package/dist/index.d.mts +12 -1
- package/dist/index.mjs +12 -1
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,61 +1,96 @@
|
|
|
1
1
|
# @trainheroic-unofficial/core
|
|
2
2
|
|
|
3
|
-
The shared MCP
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
3
|
+
The shared [MCP](https://modelcontextprotocol.io) (Model Context Protocol) tool layer for
|
|
4
|
+
TrainHeroic. Each tool — a function an AI assistant can call — is defined once here and reused
|
|
5
|
+
by both servers: the local stdio server (`@trainheroic-unofficial/coach-mcp`) and the hosted
|
|
6
|
+
Cloudflare worker (`@trainheroic-unofficial/cloudflare`). You only need this package if you
|
|
7
|
+
are building your own MCP server; to _use_ the tools, run one of those servers.
|
|
7
8
|
|
|
8
9
|
Part of the [trainheroic-unofficial](../../README.md) workspace.
|
|
9
10
|
|
|
11
|
+
## Contents
|
|
12
|
+
|
|
13
|
+
- [How a server uses it](#how-a-server-uses-it)
|
|
14
|
+
- [What the tools cover](#what-the-tools-cover)
|
|
15
|
+
- [Develop](#develop)
|
|
16
|
+
|
|
10
17
|
## How a server uses it
|
|
11
18
|
|
|
12
|
-
A server builds a `ToolContext`
|
|
13
|
-
|
|
14
|
-
|
|
19
|
+
A server builds a `ToolContext` and passes it, along with its MCP server instance, to the
|
|
20
|
+
`registerXxxTools(server, ctx)` functions (the `register*` names below are the real exports;
|
|
21
|
+
`registerXxxTools` is shorthand for all of them). `ToolContext` is `{ client, index }`: an
|
|
22
|
+
authenticated `TrainHeroicClient` (from `@trainheroic-unofficial/js`) and anything implementing
|
|
23
|
+
the `ExerciseIndex` interface — the in-memory `ExerciseLibrary` here, or the hosted worker's
|
|
24
|
+
D1-backed store.
|
|
25
|
+
|
|
26
|
+
Install it alongside the MCP SDK and the `js` client (both peers you construct from):
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
npm install @trainheroic-unofficial/core @trainheroic-unofficial/js @modelcontextprotocol/sdk
|
|
30
|
+
```
|
|
15
31
|
|
|
16
32
|
```ts
|
|
33
|
+
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
34
|
+
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
35
|
+
import { TrainHeroicClient, ExerciseLibrary } from "@trainheroic-unofficial/js";
|
|
17
36
|
import {
|
|
18
37
|
registerReadTools,
|
|
19
|
-
registerAthleteTools,
|
|
20
|
-
registerTeamTools,
|
|
21
|
-
registerAnalyticsTools,
|
|
22
38
|
registerExerciseTools,
|
|
23
39
|
registerWorkoutTools,
|
|
24
|
-
registerMessagingTools
|
|
40
|
+
// registerAthleteTools, registerTeamTools, registerAnalyticsTools, registerMessagingTools
|
|
25
41
|
type ToolContext,
|
|
26
42
|
} from "@trainheroic-unofficial/core";
|
|
27
43
|
|
|
44
|
+
const client = new TrainHeroicClient(
|
|
45
|
+
process.env.TRAINHEROIC_EMAIL!,
|
|
46
|
+
process.env.TRAINHEROIC_PASSWORD!,
|
|
47
|
+
);
|
|
48
|
+
const index = new ExerciseLibrary(client);
|
|
49
|
+
const server = new McpServer({ name: "trainheroic", version: "1.0.0" });
|
|
50
|
+
|
|
28
51
|
const ctx: ToolContext = { client, index };
|
|
29
52
|
registerReadTools(server, ctx);
|
|
30
53
|
registerExerciseTools(server, ctx);
|
|
31
|
-
|
|
54
|
+
registerWorkoutTools(server, ctx);
|
|
55
|
+
// ...register the rest, then connect the server to a transport:
|
|
56
|
+
await server.connect(new StdioServerTransport());
|
|
32
57
|
```
|
|
33
58
|
|
|
34
|
-
Because the context depends on the `ExerciseIndex` interface rather than a concrete store,
|
|
35
|
-
|
|
36
|
-
change.
|
|
59
|
+
Because the context depends on the `ExerciseIndex` interface rather than a concrete store, the
|
|
60
|
+
same tools run against the local in-memory library and the hosted [D1](https://developers.cloudflare.com/d1/)
|
|
61
|
+
(Cloudflare's SQLite database) mirror without change.
|
|
37
62
|
|
|
38
63
|
## What the tools cover
|
|
39
64
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
65
|
+
Each `register*` function registers a group of tools, and the individual tool names the model
|
|
66
|
+
sees are snake_case (e.g. `analytics_query`, `exercise_resolve`). The groups:
|
|
67
|
+
|
|
68
|
+
- coach reads (profile, athletes, teams, programs, notifications, analytics catalog)
|
|
69
|
+
- athlete management (`registerAthleteTools` — the coach's _roster_ view: invite, archive, restore)
|
|
70
|
+
- team management (create, rename, delete, join codes)
|
|
71
|
+
- analytics report pulls (`analytics_query`: readiness, 1RM (one-rep max) and working-max history, training summary, compliance, lift progress)
|
|
72
|
+
- exercise library operations (resolve, search, get, sync, create, forget, stats)
|
|
73
|
+
- the workout/session lifecycle (build a draft, read it back, publish, unpublish, copy, save as template, remove)
|
|
74
|
+
- messaging (list, read, draft, send, delete)
|
|
75
|
+
|
|
47
76
|
There is no raw-request escape hatch; every endpoint reaches the model through a typed tool.
|
|
77
|
+
(`registerAthleteTools` here is the coach's roster view, distinct from the athlete's own
|
|
78
|
+
training tools that the athlete server registers.)
|
|
48
79
|
|
|
49
|
-
Tools return their result in-band. A failure comes back as an error result the model can
|
|
50
|
-
|
|
51
|
-
destructive actions (publish, unpublish, remove, send, delete, archive, team/code delete)
|
|
52
|
-
|
|
80
|
+
Tools return their result in-band. A failure comes back as an error result the model can read
|
|
81
|
+
and correct, not a thrown exception. Reads are annotated read-only. Athlete-facing or
|
|
82
|
+
destructive actions (publish, unpublish, remove, send, delete, archive, team/code delete) pass
|
|
83
|
+
through a confirmation gate: it asks the client to confirm via MCP elicitation, falls back to
|
|
84
|
+
an explicit `confirm: true` argument when the client cannot prompt, and fails closed if neither
|
|
85
|
+
is satisfied.
|
|
53
86
|
|
|
54
87
|
The D1-backed warehouse sync tools are not here; they live in the `cloudflare` package
|
|
55
88
|
because they depend on its storage.
|
|
56
89
|
|
|
57
90
|
## Develop
|
|
58
91
|
|
|
92
|
+
Run `pnpm install` once at the repo root (Node >= 22, pnpm 10), then from this package:
|
|
93
|
+
|
|
59
94
|
```bash
|
|
60
95
|
pnpm build # tsdown
|
|
61
96
|
pnpm typecheck
|
package/dist/index.d.mts
CHANGED
|
@@ -59,6 +59,17 @@ declare const NOT_CONFIRMED = "Not confirmed. Re-run with confirm:true, or conne
|
|
|
59
59
|
*/
|
|
60
60
|
declare function confirmGate(server: McpServer, requestId: string | number | undefined, message: string, confirmArg: boolean | undefined): Promise<boolean>;
|
|
61
61
|
//#endregion
|
|
62
|
+
//#region src/instructions.d.ts
|
|
63
|
+
/**
|
|
64
|
+
* Server-level guidance passed as the MCP `instructions` string. The host model receives it
|
|
65
|
+
* in the initialize result and treats it like a system hint. Its job is to stop tool-layer
|
|
66
|
+
* implementation details from leaking into user-facing replies: by default a model narrates
|
|
67
|
+
* capability using the raw snake_case tool name (e.g. `athlete_session_create`), and the tool
|
|
68
|
+
* descriptions here reference each other by name to drive correct chaining, which primes that
|
|
69
|
+
* leak further. This tells the host to keep that wiring internal and speak in app terms.
|
|
70
|
+
*/
|
|
71
|
+
declare const SERVER_INSTRUCTIONS: string;
|
|
72
|
+
//#endregion
|
|
62
73
|
//#region src/tools/reads.d.ts
|
|
63
74
|
/** Read-only coach/athlete queries. Exercise lookups live in the exercise store tools. */
|
|
64
75
|
declare function registerReadTools(server: McpServer, ctx: ToolContext): void;
|
|
@@ -116,4 +127,4 @@ declare function registerWorkoutTools(server: McpServer, ctx: ToolContext): void
|
|
|
116
127
|
/** Live messaging: list/read conversations, draft a message, and the gated send/delete. */
|
|
117
128
|
declare function registerMessagingTools(server: McpServer, ctx: ToolContext): void;
|
|
118
129
|
//#endregion
|
|
119
|
-
export { AthleteContext, BudgetHint, DEFAULT_RESULT_BUDGET, DESTRUCTIVE, NOT_CONFIRMED, READ, SYNC, ToolContext, apiCall, attempt, boundedSerialize, confirmGate, errorResult, idParam, jsonResult, registerAnalyticsTools, registerAthleteTools, registerAthleteTrainingTools, registerExerciseTools, registerMessagingTools, registerReadTools, registerTeamTools, registerWorkoutTools, resultBudget, toId };
|
|
130
|
+
export { AthleteContext, BudgetHint, DEFAULT_RESULT_BUDGET, DESTRUCTIVE, NOT_CONFIRMED, READ, SERVER_INSTRUCTIONS, SYNC, ToolContext, apiCall, attempt, boundedSerialize, confirmGate, errorResult, idParam, jsonResult, registerAnalyticsTools, registerAthleteTools, registerAthleteTrainingTools, registerExerciseTools, registerMessagingTools, registerReadTools, registerTeamTools, registerWorkoutTools, resultBudget, toId };
|
package/dist/index.mjs
CHANGED
|
@@ -188,6 +188,17 @@ async function confirmGate(server, requestId, message, confirmArg) {
|
|
|
188
188
|
}
|
|
189
189
|
}
|
|
190
190
|
//#endregion
|
|
191
|
+
//#region src/instructions.ts
|
|
192
|
+
/**
|
|
193
|
+
* Server-level guidance passed as the MCP `instructions` string. The host model receives it
|
|
194
|
+
* in the initialize result and treats it like a system hint. Its job is to stop tool-layer
|
|
195
|
+
* implementation details from leaking into user-facing replies: by default a model narrates
|
|
196
|
+
* capability using the raw snake_case tool name (e.g. `athlete_session_create`), and the tool
|
|
197
|
+
* descriptions here reference each other by name to drive correct chaining, which primes that
|
|
198
|
+
* leak further. This tells the host to keep that wiring internal and speak in app terms.
|
|
199
|
+
*/
|
|
200
|
+
const SERVER_INSTRUCTIONS = "Speak to the user in plain, everyday language about their training. Describe what you are doing in the TrainHeroic app's own terms (for example, say you are creating a workout rather than naming a tool). Do not surface internal tool names (the snake_case identifiers such as athlete_session_create), raw parameter names, or numeric ids in your replies unless the user explicitly asks for them; they are implementation details. The tool descriptions cross-reference each other by name only so you can chain them correctly. Keep that wiring to yourself.";
|
|
201
|
+
//#endregion
|
|
191
202
|
//#region src/tools/reads.ts
|
|
192
203
|
function enc(value) {
|
|
193
204
|
return encodeURIComponent(String(value));
|
|
@@ -1087,4 +1098,4 @@ function registerMessagingTools(server, ctx) {
|
|
|
1087
1098
|
registerWrites(server, ctx);
|
|
1088
1099
|
}
|
|
1089
1100
|
//#endregion
|
|
1090
|
-
export { DEFAULT_RESULT_BUDGET, DESTRUCTIVE, NOT_CONFIRMED, READ, SYNC, apiCall, attempt, boundedSerialize, confirmGate, errorResult, idParam, jsonResult, registerAnalyticsTools, registerAthleteTools, registerAthleteTrainingTools, registerExerciseTools, registerMessagingTools, registerReadTools, registerTeamTools, registerWorkoutTools, resultBudget, toId };
|
|
1101
|
+
export { DEFAULT_RESULT_BUDGET, DESTRUCTIVE, NOT_CONFIRMED, READ, SERVER_INSTRUCTIONS, SYNC, apiCall, attempt, boundedSerialize, confirmGate, errorResult, idParam, jsonResult, registerAnalyticsTools, registerAthleteTools, registerAthleteTrainingTools, registerExerciseTools, registerMessagingTools, registerReadTools, registerTeamTools, registerWorkoutTools, resultBudget, toId };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@trainheroic-unofficial/core",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.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": "0.
|
|
29
|
-
"@trainheroic-unofficial/js": "0.
|
|
28
|
+
"@trainheroic-unofficial/dto": "0.5.0",
|
|
29
|
+
"@trainheroic-unofficial/js": "0.5.0"
|
|
30
30
|
},
|
|
31
31
|
"devDependencies": {
|
|
32
32
|
"@types/node": "^26.0.0",
|