@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 +41 -8
- package/dist/server.mjs +16 -2
- package/package.json +3 -3
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.
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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.
|
|
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.
|
|
25
|
-
"@trainheroic-unofficial/js": "0.
|
|
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",
|