intervals-icu-mcp-server 0.4.0 → 0.6.0

package/README.md

@@ -78,10 +78,18 @@ 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_coach_ticks` | Get coach-tick presets on an athlete's profile (in practice a fixed 1-5 rating scale) |
+| `set_activity_coach_tick` | Set or clear the coach's 1-5 rating on a specific activity |
 | `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

@@ -99,6 +99,7 @@ export declare const ActivitySchema: z.ZodObject<{
     carbs_used: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     carbs_ingested: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     avg_lr_balance: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    coach_tick: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
 }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
     id: z.ZodString;
     name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -195,6 +196,7 @@ export declare const ActivitySchema: z.ZodObject<{
     carbs_used: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     carbs_ingested: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     avg_lr_balance: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    coach_tick: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
 }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
     id: z.ZodString;
     name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -291,8 +293,20 @@ export declare const ActivitySchema: z.ZodObject<{
     carbs_used: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     carbs_ingested: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     avg_lr_balance: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    coach_tick: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
 }, z.ZodTypeAny, "passthrough">>;
 export type Activity = z.infer<typeof ActivitySchema>;
+export declare const CoachTickSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    text: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    id: z.ZodOptional<z.ZodNumber>;
+    text: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    id: z.ZodOptional<z.ZodNumber>;
+    text: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.ZodTypeAny, "passthrough">>;
+export type CoachTick = z.infer<typeof CoachTickSchema>;
 export declare const WellnessSchema: z.ZodObject<{
     id: z.ZodOptional<z.ZodString>;
     ctl: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
@@ -498,6 +512,18 @@ 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>>;
+    coach_ticks: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodNumber>;
+        text: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        id: z.ZodOptional<z.ZodNumber>;
+        text: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        id: z.ZodOptional<z.ZodNumber>;
+        text: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.ZodTypeAny, "passthrough">>, "many">>>;
 }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
     id: z.ZodOptional<z.ZodString>;
     name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -509,6 +535,18 @@ 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>>;
+    coach_ticks: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodNumber>;
+        text: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        id: z.ZodOptional<z.ZodNumber>;
+        text: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        id: z.ZodOptional<z.ZodNumber>;
+        text: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.ZodTypeAny, "passthrough">>, "many">>>;
 }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
     id: z.ZodOptional<z.ZodString>;
     name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -520,6 +558,18 @@ 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>>;
+    coach_ticks: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodNumber>;
+        text: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        id: z.ZodOptional<z.ZodNumber>;
+        text: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        id: z.ZodOptional<z.ZodNumber>;
+        text: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.ZodTypeAny, "passthrough">>, "many">>>;
 }, z.ZodTypeAny, "passthrough">>;
 export type Athlete = z.infer<typeof AthleteSchema>;
 export declare const SportSettingsSchema: z.ZodObject<{
@@ -678,6 +728,8 @@ 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 setActivityCoachTick(config: ClientConfig, activityId: string, coachTickId: number | null): Promise<Activity>;
 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

@@ -97,6 +97,14 @@ export const ActivitySchema = z.object({
     carbs_used: z.number().nullable().optional(),
     carbs_ingested: z.number().nullable().optional(),
     avg_lr_balance: z.number().nullable().optional(),
+    // id of one of the athlete's coach_ticks presets (see AthleteSchema), or null if unset.
+    coach_tick: z.number().nullable().optional(),
+}).passthrough();
+// A coach-configured quick-rating preset (e.g. "🔥 Great", "⚠️ Review") an athlete's activities
+// can be tagged with via Activity.coach_tick (which stores just the preset's id).
+export const CoachTickSchema = z.object({
+    id: z.number().optional(),
+    text: z.string().nullable().optional(),
 }).passthrough();
 export const WellnessSchema = z.object({
     id: z.string().optional(),
@@ -161,6 +169,11 @@ 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(),
+    coach_ticks: z.array(CoachTickSchema).nullable().optional(),
 }).passthrough();
 export const SportSettingsSchema = z.object({
     types: z.array(z.string()).nullable().optional(),
@@ -293,6 +306,22 @@ 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);
+}
+// coach_tick is a fixed 1-5 rating scale (verified against the live API — PUT /athlete/{id}
+// with a custom coach_ticks list is accepted but never persists, so presets aren't
+// API-configurable). A JSON null is silently ignored by the server (treated as "no change");
+// -1 is what actually clears an existing rating.
+export async function setActivityCoachTick(config, activityId, coachTickId) {
+    const data = await mutate("PUT", `/activity/${activityId}`, config, {
+        coach_tick: coachTickId ?? -1,
+    });
+    return ActivitySchema.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/format.js

@@ -44,6 +44,9 @@ export function formatActivity(a) {
         }
     }
     lines.push("", "Other:", `  Cadence: ${n(a.average_cadence, " rpm")} | Calories: ${n(a.calories)} | Speed: ${n(a.average_speed, " m/s")} (max ${n(a.max_speed, " m/s")})`, `  Temp: ${n(a.average_temp, "°C")} | Trainer: ${a.trainer ? "Yes" : "No"} | Coasting: ${fmtDuration(a.coasting_time)}`, `  RPE: ${n(a.icu_rpe ?? a.perceived_exertion)}/10 | Feel: ${n(a.feel)}/5 | S-RPE: ${n(a.session_rpe)}`, `  L/R Balance: ${a.avg_lr_balance != null ? `${(100 - a.avg_lr_balance).toFixed(0)}/${a.avg_lr_balance.toFixed(0)}` : "N/A"}`, "", "Fitness:", `  CTL: ${n(a.icu_ctl)} | ATL: ${n(a.icu_atl)} | TRIMP: ${n(a.trimp)} | Polarization Index: ${n(a.polarization_index)}`, `  Power Load: ${n(a.power_load)} | HR Load: ${n(a.hr_load)} | Strain: ${n(a.strain_score)}`, `  SS CP: ${n(a.ss_cp, " W")} | SS W': ${n(a.ss_w_prime)} | SS Pmax: ${n(a.ss_p_max)}`, `  Weight: ${n(a.icu_weight, " kg")} | CHO Used: ${n(a.carbs_used, " g")} | CHO In: ${n(a.carbs_ingested, " g")}`, "", "Equipment:", `  Gear: ${n(a.gear?.name)} | Device: ${n(a.device_name)} | Power Meter: ${n(a.power_meter)}`, `  Source: ${n(a.source)} | Compliance: ${a.compliance != null ? `${a.compliance}%` : "N/A"}`);
+    if (a.coach_tick != null) {
+        lines.push(`  Coach Tick: [${a.coach_tick}] (see get_coach_ticks for the label)`);
+    }
     if (a.description)
         lines.push("", `Description: ${a.description}`);
     return lines.join("\n");

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, setActivityCoachTick, 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,41 @@ 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_coach_ticks",
+        description: "Get the coach-tick rating configured on an athlete's profile presets, if any. In practice coach_tick is a fixed 1-5 rating scale on Intervals.icu — use set_activity_coach_tick to rate an activity.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                athlete_id: { type: "string", description: "Athlete ID (defaults to ATHLETE_ID env var)" },
+                api_key: { type: "string", description: "API key (defaults to API_KEY env var)" },
+            },
+        },
+    },
+    {
+        name: "set_activity_coach_tick",
+        description: "Set or clear the coach's rating on a specific activity (Intervals.icu's coach-tick feature: a 1-5 scale). Pass coach_tick_id 1-5 to rate it, or omit to clear the current rating.",
+        inputSchema: {
+            type: "object",
+            required: ["activity_id"],
+            properties: {
+                activity_id: { type: "string", description: "The activity ID" },
+                coach_tick_id: { type: "number", description: "Rating 1-5. Omit to clear the current rating." },
+                athlete_id: { type: "string", description: "Athlete ID (defaults to ATHLETE_ID env var)" },
+                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 +645,43 @@ 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_coach_ticks": {
+                const config = getConfig(args);
+                const athlete = await getAthleteProfile(config);
+                const ticks = athlete.coach_ticks ?? [];
+                if (!ticks.length) {
+                    return { content: [{ type: "text", text: "No coach-tick presets on this athlete's profile — coach_tick is a fixed 1-5 rating scale. Use set_activity_coach_tick to rate an activity." }] };
+                }
+                const lines = ticks.map((t) => `- [${t.id}] ${t.text ?? ""}`);
+                return { content: [{ type: "text", text: lines.join("\n") }] };
+            }
+            case "set_activity_coach_tick": {
+                const activityId = z.string().parse(args["activity_id"]);
+                const coachTickId = args["coach_tick_id"];
+                const config = getConfig(args);
+                await setActivityCoachTick(config, activityId, coachTickId ?? null);
+                return {
+                    content: [{
+                            type: "text",
+                            text: coachTickId != null
+                                ? `Coach tick ${coachTickId} set on activity ${activityId}.`
+                                : `Coach tick cleared on activity ${activityId}.`,
+                        }],
+                };
+            }
             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.6.0",
   "description": "MCP server for Intervals.icu — 26 tools for activities, wellness, calendar events, workouts and more",
   "type": "module",
   "bin": {