intervals-icu-mcp-server 0.4.0 → 0.5.0

package/README.md

@@ -78,10 +78,16 @@ Add to `~/.claude/settings.json`:
 ### Athlete
 | Tool | Description |
 |------|-------------|
+| `list_athletes` | List athletes you follow or coach (including yourself) — find athlete IDs for a coach account |
 | `get_athlete_profile` | FTP, LTHR, weight, VO2max, resting HR |
 | `get_athlete_zones` | Power, HR and pace training zones |
 | `get_athlete_summary` | Current CTL, ATL, TSB and ramp rate snapshot |
 
+**Coach accounts:** every tool accepts an optional `athlete_id` argument that overrides the
+`ATHLETE_ID` env var for that call. Log in with a coach's `API_KEY`, call `list_athletes` to get
+IDs for the athletes they coach, then pass `athlete_id: "iXXXXX"` on any tool call to work with
+that specific athlete — no need to swap accounts or `.env` files.
+
 ### Calendar Events
 | Tool | Description |
 |------|-------------|

package/dist/client.d.ts

@@ -498,6 +498,8 @@ export declare const AthleteSchema: z.ZodObject<{
     country: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     icu_resting_hr: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     icu_weight: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    icu_coach: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    icu_permission: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
     id: z.ZodOptional<z.ZodString>;
     name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -509,6 +511,8 @@ export declare const AthleteSchema: z.ZodObject<{
     country: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     icu_resting_hr: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     icu_weight: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    icu_coach: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    icu_permission: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
     id: z.ZodOptional<z.ZodString>;
     name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -520,6 +524,8 @@ export declare const AthleteSchema: z.ZodObject<{
     country: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     icu_resting_hr: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     icu_weight: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    icu_coach: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    icu_permission: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.ZodTypeAny, "passthrough">>;
 export type Athlete = z.infer<typeof AthleteSchema>;
 export declare const SportSettingsSchema: z.ZodObject<{
@@ -678,6 +684,7 @@ export declare function createEvent(config: ClientConfig, input: EventInput): Pr
 export declare function updateEvent(config: ClientConfig, eventId: string, input: EventInput): Promise<Event>;
 export declare function deleteEvent(config: ClientConfig, eventId: string): Promise<void>;
 export declare function getAthleteProfile(config: ClientConfig): Promise<Athlete>;
+export declare function listAthletes(config: ClientConfig): Promise<Athlete[]>;
 export declare function getAthleteZones(config: ClientConfig): Promise<SportSettings[]>;
 export declare function getAthleteSummary(config: ClientConfig): Promise<AthleteFitness | undefined>;
 export declare function getWellnessDay(config: ClientConfig, date: string): Promise<Wellness>;

package/dist/client.js

@@ -161,6 +161,10 @@ export const AthleteSchema = z.object({
     country: z.string().nullable().optional(),
     icu_resting_hr: z.number().nullable().optional(),
     icu_weight: z.number().nullable().optional(),
+    icu_coach: z.boolean().nullable().optional(),
+    // Present only on entries returned by /athletes: the caller's access level on this athlete
+    // (NONE/READ/WRITE for someone they follow/coach, absent for their own profile).
+    icu_permission: z.string().nullable().optional(),
 }).passthrough();
 export const SportSettingsSchema = z.object({
     types: z.array(z.string()).nullable().optional(),
@@ -293,6 +297,12 @@ export async function getAthleteProfile(config) {
     const data = await request(`/athlete/${config.athleteId}`, config);
     return AthleteSchema.parse(data);
 }
+// Requires an API_KEY (not a bearer token). Athlete ID in `config` is ignored — this call
+// is not athlete-scoped, it lists everyone the key's account follows or coaches.
+export async function listAthletes(config) {
+    const data = await request(`/athletes`, config);
+    return z.array(AthleteSchema).parse(data);
+}
 export async function getAthleteZones(config) {
     const data = await request(`/athlete/${config.athleteId}/sport-settings`, config);
     return z.array(SportSettingsSchema).parse(data);

package/dist/index.js

@@ -4,7 +4,7 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
-import { getActivities, getActivityDetails, getActivityIntervals, getWellness, getEvents, getEventById, getNotesByDate, createEvent, updateEvent, deleteEvent, getAthleteProfile, getAthleteZones, getAthleteSummary, getWellnessDay, updateWellness, getActivityStreams, getActivityPowerCurves, listWorkouts, createWorkout, bulkCreateEvents, bulkDeleteEvents, getAthleteFitness, getActivityMessages, addActivityMessage, deleteActivityMessage, updateActivityMessage, } from "./client.js";
+import { getActivities, getActivityDetails, getActivityIntervals, getWellness, getEvents, getEventById, getNotesByDate, createEvent, updateEvent, deleteEvent, getAthleteProfile, getAthleteZones, getAthleteSummary, listAthletes, getWellnessDay, updateWellness, getActivityStreams, getActivityPowerCurves, listWorkouts, createWorkout, bulkCreateEvents, bulkDeleteEvents, getAthleteFitness, getActivityMessages, addActivityMessage, deleteActivityMessage, updateActivityMessage, } from "./client.js";
 import { formatActivity, formatWellness, formatEvent, formatIntervalRow, formatSportZones, formatMessage, } from "./format.js";
 function getConfig(args) {
     const apiKey = args["api_key"] ?? process.env.API_KEY ?? "";
@@ -17,6 +17,14 @@ function getConfig(args) {
         throw new Error("No athlete ID provided. Set ATHLETE_ID in .env or pass athlete_id.");
     return { apiKey, athleteId };
 }
+// list_athletes isn't athlete-scoped (it lists everyone the key's account can access), so it
+// only needs the API key — requiring athlete_id here would break coaches with no default athlete.
+function getApiKey(args) {
+    const apiKey = args["api_key"] ?? process.env.API_KEY ?? "";
+    if (!apiKey)
+        throw new Error("No API key provided. Set API_KEY in .env or pass api_key.");
+    return apiKey;
+}
 function toDateStr(d) {
     const y = d.getFullYear();
     const m = String(d.getMonth() + 1).padStart(2, "0");
@@ -175,6 +183,16 @@ const TOOLS = [
             },
         },
     },
+    {
+        name: "list_athletes",
+        description: "List athletes you follow or coach, including yourself. Use this with a coach account to find athlete IDs, then pass athlete_id on other tools (get_activities, get_wellness_data, get_events, etc.) to work with a specific athlete under that same account.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                api_key: { type: "string", description: "API key (defaults to API_KEY env var)" },
+            },
+        },
+    },
     {
         name: "get_athlete_profile",
         description: "Get athlete profile: name, sex, DOB, weight, resting HR, city/country. For FTP/LTHR/zones use get_athlete_zones.",
@@ -602,6 +620,19 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 await deleteEvent(config, eventId);
                 return { content: [{ type: "text", text: `Event ${eventId} deleted.` }] };
             }
+            case "list_athletes": {
+                const apiKey = getApiKey(args);
+                const athletes = await listAthletes({ apiKey, athleteId: "" });
+                if (!athletes.length)
+                    return { content: [{ type: "text", text: "No athletes found." }] };
+                const lines = athletes.map((a) => {
+                    const perm = a.icu_permission ? ` [${a.icu_permission}]` : " (self)";
+                    const coach = a.icu_coach ? " · coach" : "";
+                    const email = a.email ? ` · ${a.email}` : "";
+                    return `- **${a.name ?? "Unnamed"}** — id: ${a.id}${perm}${coach}${email}`;
+                });
+                return { content: [{ type: "text", text: lines.join("\n") }] };
+            }
             case "get_athlete_profile": {
                 const config = getConfig(args);
                 const athlete = await getAthleteProfile(config);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "intervals-icu-mcp-server",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "MCP server for Intervals.icu — 26 tools for activities, wellness, calendar events, workouts and more",
   "type": "module",
   "bin": {