@trainheroic-unofficial/core 0.4.2 → 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/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/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",
|