@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 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/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.4.1",
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.1",
29
- "@trainheroic-unofficial/js": "0.4.1"
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",