@trainheroic-unofficial/coach-mcp 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,13 +1,20 @@
1
1
  # @trainheroic-unofficial/coach-mcp
2
2
 
3
- Local single-user MCP server for a TrainHeroic coach. Runs on your machine over stdio; credentials come from the environment.
3
+ Local single-user [MCP](https://modelcontextprotocol.io) server for a TrainHeroic coach — it exposes a [TrainHeroic](https://www.trainheroic.com) coaching account to an AI assistant (Claude Code, Claude Desktop, or any MCP client) as a set of callable tools. It runs on your machine and speaks the MCP stdio transport, so the assistant launches it as a subprocess.
4
4
 
5
- For the hosted version (no install, OAuth login), see the [root README](../../README.md).
5
+ It reads two environment variables, both required:
6
+
7
+ - `TRAINHEROIC_EMAIL` and `TRAINHEROIC_PASSWORD` — your existing TrainHeroic login.
8
+
9
+ These are your real credentials in plaintext; the config examples below put them in a file or in shell history, so treat them as secrets. For a version that holds credentials server-side behind OAuth, use the hosted server in the [root README](../../README.md).
6
10
 
7
11
  ---
8
12
 
9
13
  ## Install
10
14
 
15
+ Needs Node (>= 18); the commands below fetch the package with `npx` on first run. The server
16
+ caches the exercise library as a JSON file under `~/.trainheroic/`.
17
+
11
18
  ### Claude Code
12
19
 
13
20
  ```bash
@@ -19,7 +26,11 @@ claude mcp add trainheroic \
19
26
 
20
27
  ### Claude Desktop / `.mcp.json` / other stdio clients
21
28
 
22
- ```jsonc
29
+ Put this in your client's MCP config — for Claude Desktop that's `claude_desktop_config.json`
30
+ (macOS: `~/Library/Application Support/Claude/`; Windows: `%APPDATA%\Claude\`); for a
31
+ project-scoped Claude Code setup it's `.mcp.json` at the repo root.
32
+
33
+ ```json
23
34
  {
24
35
  "mcpServers": {
25
36
  "trainheroic": {
@@ -27,19 +38,41 @@ claude mcp add trainheroic \
27
38
  "args": ["-y", "@trainheroic-unofficial/coach-mcp"],
28
39
  "env": {
29
40
  "TRAINHEROIC_EMAIL": "coach@example.com",
30
- "TRAINHEROIC_PASSWORD": "yourpassword",
31
- },
32
- },
33
- },
41
+ "TRAINHEROIC_PASSWORD": "yourpassword"
42
+ }
43
+ }
44
+ }
34
45
  }
35
46
  ```
36
47
 
48
+ After it connects, ask the assistant something like "list my athletes" to confirm the tools are available.
49
+
50
+ ---
51
+
52
+ ## Tools
53
+
54
+ The full coaching surface, grouped by area:
55
+
56
+ - **Reads** — profile, athletes, teams, programs, notifications, analytics catalog
57
+ - **Athletes** — invite, archive, restore
58
+ - **Teams** — create, rename, delete, manage join codes
59
+ - **Analytics** — readiness, 1RM and working-max history, training summary, compliance, lift progress
60
+ - **Exercise library** — resolve, search, get, sync, create, forget, stats
61
+ - **Workouts** — build a draft, read it back, publish, unpublish, copy, save as template, remove
62
+ - **Messaging** — list streams, read, draft, send, delete
63
+
64
+ A TrainHeroic coach account also has its own athlete-side data, so the athlete training tools (history, workouts, PRs, working maxes) are available here too. Destructive or athlete-facing actions (publish, remove, send, delete, archive) confirm before they run: the server asks the client to confirm, falling back to an explicit `confirm: true` tool argument when the client can't prompt.
65
+
66
+ The individual tool names the assistant calls are snake_case (e.g. `list_athletes`, `exercise_resolve`, `workout_publish`); their parameters are described in each tool's schema, which your MCP client surfaces.
67
+
37
68
  ---
38
69
 
39
70
  ## Develop
40
71
 
72
+ Run `pnpm install` once at the repo root (Node >= 22, pnpm 10), then from this package. The `pnpm start`/`pnpm inspect` commands need `TRAINHEROIC_EMAIL` and `TRAINHEROIC_PASSWORD` exported in your shell. "MCP Inspector" is the [official MCP debugging UI](https://github.com/modelcontextprotocol/inspector).
73
+
41
74
  ```bash
42
- pnpm start # run from source (needs TRAINHEROIC_EMAIL and TRAINHEROIC_PASSWORD)
75
+ pnpm start # run from source
43
76
  pnpm inspect # MCP Inspector UI against the source server
44
77
  pnpm build # tsdown → dist/server.mjs
45
78
  pnpm typecheck
package/dist/server.mjs CHANGED
@@ -453,6 +453,17 @@ async function confirmGate(server, requestId, message, confirmArg) {
453
453
  }
454
454
  }
455
455
  //#endregion
456
+ //#region ../core/src/instructions.ts
457
+ /**
458
+ * Server-level guidance passed as the MCP `instructions` string. The host model receives it
459
+ * in the initialize result and treats it like a system hint. Its job is to stop tool-layer
460
+ * implementation details from leaking into user-facing replies: by default a model narrates
461
+ * capability using the raw snake_case tool name (e.g. `athlete_session_create`), and the tool
462
+ * descriptions here reference each other by name to drive correct chaining, which primes that
463
+ * leak further. This tells the host to keep that wiring internal and speak in app terms.
464
+ */
465
+ 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.";
466
+ //#endregion
456
467
  //#region ../core/src/tools/reads.ts
457
468
  function enc(value) {
458
469
  return encodeURIComponent(String(value));
@@ -1998,6 +2009,9 @@ var JsonFileLibraryCache = class {
1998
2009
  }
1999
2010
  };
2000
2011
  //#endregion
2012
+ //#region package.json
2013
+ var version = "0.4.1";
2014
+ //#endregion
2001
2015
  //#region src/server.ts
2002
2016
  async function main() {
2003
2017
  const email = process.env.TRAINHEROIC_EMAIL;
@@ -2013,8 +2027,8 @@ async function main() {
2013
2027
  };
2014
2028
  const server = new McpServer({
2015
2029
  name: "trainheroic-local",
2016
- version: "0.2.0"
2017
- });
2030
+ version
2031
+ }, { instructions: SERVER_INSTRUCTIONS });
2018
2032
  registerReadTools(server, ctx);
2019
2033
  registerAthleteTools(server, ctx);
2020
2034
  registerTeamTools(server, ctx);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@trainheroic-unofficial/coach-mcp",
3
- "version": "0.4.1",
3
+ "version": "0.5.0",
4
4
  "license": "MIT",
5
5
  "repository": {
6
6
  "type": "git",
@@ -21,8 +21,8 @@
21
21
  "dependencies": {
22
22
  "@modelcontextprotocol/sdk": "^1.29.0",
23
23
  "zod": "^4.4.3",
24
- "@trainheroic-unofficial/core": "0.4.1",
25
- "@trainheroic-unofficial/js": "0.4.1"
24
+ "@trainheroic-unofficial/core": "0.5.0",
25
+ "@trainheroic-unofficial/js": "0.5.0"
26
26
  },
27
27
  "devDependencies": {
28
28
  "@types/node": "^26.0.0",