@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.
Files changed (2) hide show
  1. package/README.md +61 -26
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -1,61 +1,96 @@
1
1
  # @trainheroic-unofficial/core
2
2
 
3
- The shared MCP tool layer for TrainHeroic. Each tool is defined once here and reused by both
4
- servers: the local stdio server (`@trainheroic-unofficial/coach-mcp`) and the hosted
5
- Cloudflare worker (`@trainheroic-unofficial/cloudflare`). Keeping the tools here is what
6
- makes the two transports behave identically.
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` (an authenticated `TrainHeroicClient` plus something that
13
- implements the `ExerciseIndex` interface) and calls the `registerXxxTools(server, ctx)`
14
- functions:
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
- // ...and the rest
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
- the same tools run against the local in-memory library and the hosted D1 mirror without
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
- The tools group into coach reads (profile, athletes, teams, programs, notifications,
41
- analytics catalog), athlete management (invite, archive, restore), team management (create,
42
- rename, delete, join codes), analytics report pulls (`analytics_query`: readiness, 1RM and
43
- working-max history, training summary, compliance, lift progress), exercise library
44
- operations (resolve, search, get, sync, create,
45
- forget, stats), the workout/session lifecycle (build a draft, read it back, publish,
46
- unpublish, copy, save as template, remove), and messaging (list, read, draft, send, delete).
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
- read and correct, not a thrown exception. Reads are marked read-only. Athlete-facing or
51
- destructive actions (publish, unpublish, remove, send, delete, archive, team/code delete)
52
- pass through a confirmation gate before they run.
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.4.2",
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.4.2",
29
- "@trainheroic-unofficial/js": "0.4.2"
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",