intervals-icu-mcp-server 0.1.0 → 0.1.2

package/README.md

@@ -1,49 +1,33 @@
-# intervals-mcp
+# intervals-icu-mcp-server
 
 MCP server for [Intervals.icu](https://intervals.icu) — connects Claude / Claude Code to your training data.
 
-## Tools
-
-| Tool | Description |
-|------|-------------|
-| `get_activities` | List activities with power, HR, training load, etc. |
-| `get_activity_details` | Full metrics for a specific activity |
-| `get_activity_intervals` | Per-interval breakdown (power, HR, speed, elevation) |
-| `get_wellness_data` | Weight, HRV, sleep, CTL/ATL, subjective scores |
-| `get_events` | Calendar events (workouts, races) |
-| `get_event_by_id` | Full details for a specific event |
-
-## Setup
-
-### 1. Install & build
+## Installation
 
 ```bash
-npm install
-npm run build
+npx -y intervals-icu-mcp-server
 ```
 
-### 2. Configure credentials
+Or install globally:
 
 ```bash
-cp .env.example .env
-# Edit .env and fill in your API_KEY and ATHLETE_ID
+npm install -g intervals-icu-mcp-server
 ```
 
-- **API_KEY**: Settings → API → Generate key on intervals.icu
-- **ATHLETE_ID**: The `i12345` part of your intervals.icu profile URL
+## Setup
 
-### 3. Add to Claude Code
+### Claude Desktop
 
-Add this to your `~/.claude/settings.json` (or project `.claude/settings.json`):
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
 ```json
 {
   "mcpServers": {
-    "intervals": {
-      "command": "node",
-      "args": ["/Users/spirohov/work/intervals/dist/index.js"],
+    "intervals-icu": {
+      "command": "npx",
+      "args": ["-y", "intervals-icu-mcp-server"],
       "env": {
-        "API_KEY": "your_key_here",
+        "API_KEY": "your_api_key",
         "ATHLETE_ID": "i12345"
       }
     }
@@ -51,20 +35,18 @@ Add this to your `~/.claude/settings.json` (or project `.claude/settings.json`):
 }
 ```
 
-Or use a `.env` file — the server loads it automatically from the project root.
-
-### 4. Add to Claude Desktop
+### Claude Code
 
-In `~/Library/Application Support/Claude/claude_desktop_config.json`:
+Add to `~/.claude/settings.json`:
 
 ```json
 {
   "mcpServers": {
-    "intervals": {
-      "command": "node",
-      "args": ["/Users/spirohov/work/intervals/dist/index.js"],
+    "intervals-icu": {
+      "command": "npx",
+      "args": ["-y", "intervals-icu-mcp-server"],
       "env": {
-        "API_KEY": "your_key_here",
+        "API_KEY": "your_api_key",
         "ATHLETE_ID": "i12345"
       }
     }
@@ -72,9 +54,58 @@ In `~/Library/Application Support/Claude/claude_desktop_config.json`:
 }
 ```
 
+- **API_KEY**: Settings → API → Generate key on intervals.icu
+- **ATHLETE_ID**: The `i12345` part of your intervals.icu profile URL
+
+## Tools
+
+### Activities
+| Tool | Description |
+|------|-------------|
+| `get_activities` | List activities with power, HR, training load, etc. |
+| `get_activity_details` | Full metrics for a specific activity |
+| `get_activity_intervals` | Per-interval breakdown (power, HR, speed, elevation) |
+| `get_activity_streams` | Raw per-second data streams (watts, HR, cadence, speed, altitude) |
+| `get_activity_power_curves` | Best power for all durations (5s, 1min, 5min, 20min, etc.) |
+
+### Wellness & Fitness
+| Tool | Description |
+|------|-------------|
+| `get_wellness_data` | Weight, HRV, sleep, CTL/ATL, subjective scores for a date range |
+| `get_wellness_day` | Wellness data for a single date |
+| `update_wellness` | Log weight, HRV, sleep, mood, soreness, etc. |
+
+### Athlete
+| Tool | Description |
+|------|-------------|
+| `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 |
+
+### Calendar Events
+| Tool | Description |
+|------|-------------|
+| `get_events` | Calendar events (workouts, races) for a date range |
+| `get_event_by_id` | Full details for a specific event |
+| `create_event` | Create a new event (workout, note, race) |
+| `update_event` | Update event fields or move it to a new date |
+| `delete_event` | Delete an event |
+| `bulk_create_events` | Create multiple events at once |
+| `bulk_delete_events` | Delete multiple events at once |
+
+### Workout Library
+| Tool | Description |
+|------|-------------|
+| `list_workouts` | List all workouts in the library |
+| `create_workout` | Save a new structured workout to the library |
+
 ## Development
 
 ```bash
+git clone https://github.com/SergeyPirogov/intervals-mcp.git
+cd intervals-mcp
+npm install
+npm run build
 npm run dev          # watch mode
 npm run inspector    # MCP inspector UI
 ```

package/dist/client.d.ts

@@ -202,6 +202,7 @@ export interface EventInput {
     race?: boolean;
     distance?: number;
     sub_type?: string;
+    workout_doc?: unknown;
 }
 export declare const AthleteSchema: z.ZodObject<{
     id: z.ZodOptional<z.ZodString>;
@@ -346,6 +347,7 @@ export declare function getEvents(config: ClientConfig, params: {
     endDate: string;
 }): Promise<Event[]>;
 export declare function getEventById(config: ClientConfig, eventId: string): Promise<Event>;
+export declare function getNotesByDate(config: ClientConfig, date: string): Promise<Event[]>;
 export declare function createEvent(config: ClientConfig, input: EventInput): Promise<Event>;
 export declare function updateEvent(config: ClientConfig, eventId: string, input: EventInput): Promise<Event>;
 export declare function deleteEvent(config: ClientConfig, eventId: string): Promise<void>;
@@ -360,3 +362,39 @@ export declare function listWorkouts(config: ClientConfig): Promise<Workout[]>;
 export declare function createWorkout(config: ClientConfig, input: WorkoutInput): Promise<Workout>;
 export declare function bulkCreateEvents(config: ClientConfig, events: EventInput[]): Promise<Event[]>;
 export declare function bulkDeleteEvents(config: ClientConfig, eventIds: (string | number)[]): Promise<void>;
+export declare const AthleteFitnessSchema: z.ZodObject<{
+    date: z.ZodOptional<z.ZodString>;
+    fitness: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    fatigue: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    form: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    rampRate: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    training_load: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    eftp: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    eftpPerKg: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    weight: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    date: z.ZodOptional<z.ZodString>;
+    fitness: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    fatigue: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    form: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    rampRate: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    training_load: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    eftp: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    eftpPerKg: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    weight: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    date: z.ZodOptional<z.ZodString>;
+    fitness: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    fatigue: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    form: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    rampRate: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    training_load: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    eftp: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    eftpPerKg: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    weight: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.ZodTypeAny, "passthrough">>;
+export type AthleteFitness = z.infer<typeof AthleteFitnessSchema>;
+export declare function getAthleteFitness(config: ClientConfig, params: {
+    startDate: string;
+    endDate: string;
+}): Promise<AthleteFitness[]>;

package/dist/client.js

@@ -155,9 +155,17 @@ export async function getEvents(config, params) {
     return z.array(EventSchema).parse(data);
 }
 export async function getEventById(config, eventId) {
-    const data = await request(`/athlete/${config.athleteId}/event/${eventId}`, config);
+    const data = await request(`/athlete/${config.athleteId}/events/${eventId}`, config);
     return EventSchema.parse(data);
 }
+export async function getNotesByDate(config, date) {
+    const data = await request(`/athlete/${config.athleteId}/events`, config, { oldest: date, newest: date });
+    const events = z.array(EventSchema).parse(data);
+    return events.filter((e) => {
+        const raw = e;
+        return raw["category"] === "NOTE" || (!e.race && !e.workout);
+    });
+}
 async function mutate(method, path, config, body) {
     const url = `${BASE_URL}${path}`;
     const res = await fetch(url, {
@@ -234,3 +242,19 @@ export async function bulkCreateEvents(config, events) {
 export async function bulkDeleteEvents(config, eventIds) {
     await mutate("POST", `/athlete/${config.athleteId}/events/bulk-delete`, config, eventIds);
 }
+export const AthleteFitnessSchema = z.object({
+    date: z.string().optional(),
+    fitness: z.number().nullable().optional(),
+    fatigue: z.number().nullable().optional(),
+    form: z.number().nullable().optional(),
+    rampRate: z.number().nullable().optional(),
+    training_load: z.number().nullable().optional(),
+    eftp: z.number().nullable().optional(),
+    eftpPerKg: z.number().nullable().optional(),
+    weight: z.number().nullable().optional(),
+}).passthrough();
+export async function getAthleteFitness(config, params) {
+    const data = await request(`/athlete/${config.athleteId}/athlete-summary.json`, config, { oldest: params.startDate, newest: params.endDate, athleteId: config.athleteId });
+    const all = z.array(AthleteFitnessSchema).parse(data);
+    return all.filter((e) => e["athlete_id"] === config.athleteId);
+}

package/dist/index.d.ts

@@ -1 +1,2 @@
+#!/usr/bin/env node
 import "dotenv/config";

package/dist/index.js

@@ -1,9 +1,10 @@
+#!/usr/bin/env node
 import "dotenv/config";
 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, createEvent, updateEvent, deleteEvent, getAthleteProfile, getAthleteZones, getAthleteSummary, getWellnessDay, updateWellness, getActivityStreams, getActivityPowerCurves, listWorkouts, createWorkout, bulkCreateEvents, bulkDeleteEvents, } from "./client.js";
+import { getActivities, getActivityDetails, getActivityIntervals, getWellness, getEvents, getEventById, getNotesByDate, createEvent, updateEvent, deleteEvent, getAthleteProfile, getAthleteZones, getAthleteSummary, getWellnessDay, updateWellness, getActivityStreams, getActivityPowerCurves, listWorkouts, createWorkout, bulkCreateEvents, bulkDeleteEvents, getAthleteFitness, } from "./client.js";
 import { formatActivity, formatWellness, formatEvent, formatIntervalRow, } from "./format.js";
 function getConfig(args) {
     const apiKey = args["api_key"] ?? process.env.API_KEY ?? "";
@@ -125,6 +126,7 @@ const TOOLS = [
                 race: { type: "boolean", description: "Mark as a race event (default: false)" },
                 distance: { type: "number", description: "Distance in meters (e.g. 100000 for 100km)" },
                 sub_type: { type: "string", description: "Race category/sub-type (e.g. A, B, C)" },
+                workout_doc: { type: "object", description: "Structured workout definition (Intervals.icu workout_doc format) to attach steps/intervals to this event" },
                 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)" },
             },
@@ -146,6 +148,7 @@ const TOOLS = [
                 race: { type: "boolean", description: "Toggle race flag" },
                 distance: { type: "number", description: "Distance in meters (e.g. 100000 for 100km)" },
                 sub_type: { type: "string", description: "Race category/sub-type (e.g. A, B, C)" },
+                workout_doc: { type: "object", description: "New structured workout definition (Intervals.icu workout_doc format)" },
                 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)" },
             },
@@ -298,6 +301,32 @@ const TOOLS = [
             },
         },
     },
+    {
+        name: "get_athlete_fitness",
+        description: "Get Fitness (CTL), Fatigue (ATL), Form (TSB), ramp rate and eFTP from the Fitness chart for a date range. Matches what you see on the Intervals.icu Fitness page.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                start_date: { type: "string", description: "Start date YYYY-MM-DD (default: 30 days ago)" },
+                end_date: { type: "string", description: "End date YYYY-MM-DD (default: today)" },
+                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_note",
+        description: "Get a specific note/event by ID, or list all notes for a given date.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                event_id: { type: "string", description: "Event/note ID to fetch by ID" },
+                date: { type: "string", description: "Date YYYY-MM-DD to list all notes for that day" },
+                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: "bulk_create_events",
         description: "Create multiple calendar events at once.",
@@ -317,6 +346,7 @@ const TOOLS = [
                             category: { type: "string" },
                             type: { type: "string" },
                             race: { type: "boolean" },
+                            workout_doc: { type: "object", description: "Structured workout definition (Intervals.icu workout_doc format)" },
                         },
                     },
                 },
@@ -432,6 +462,49 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 const event = await getEventById(config, eventId);
                 return { content: [{ type: "text", text: formatEvent(event) }] };
             }
+            case "get_athlete_fitness": {
+                const config = getConfig(args);
+                const startDate = args["start_date"] ?? daysAgo(30);
+                const endDate = args["end_date"] ?? today();
+                const entries = await getAthleteFitness(config, { startDate, endDate });
+                if (!entries.length) {
+                    return { content: [{ type: "text", text: "No fitness data found for the specified date range." }] };
+                }
+                const lines = entries.map((e) => {
+                    const ctl = e.fitness != null ? e.fitness.toFixed(1) : "N/A";
+                    const atl = e.fatigue != null ? e.fatigue.toFixed(1) : "N/A";
+                    const tsb = e.form != null ? e.form.toFixed(1) : "N/A";
+                    const ramp = e.rampRate != null ? e.rampRate.toFixed(1) : "N/A";
+                    const eftp = e.eftp != null ? `${e.eftp.toFixed(0)}W` : "N/A";
+                    const eftpKg = e.eftpPerKg != null ? `${e.eftpPerKg.toFixed(2)} W/kg` : "N/A";
+                    const tl = e.training_load != null ? e.training_load.toFixed(0) : "N/A";
+                    return [
+                        `**${e.date ?? "N/A"}**`,
+                        `  CTL (Fitness): ${ctl} | ATL (Fatigue): ${atl} | TSB (Form): ${tsb}`,
+                        `  Ramp Rate: ${ramp} | eFTP: ${eftp} (${eftpKg}) | TL: ${tl}`,
+                    ].join("\n");
+                });
+                return { content: [{ type: "text", text: lines.join("\n\n") }] };
+            }
+            case "get_note": {
+                const config = getConfig(args);
+                const eventId = args["event_id"];
+                const date = args["date"];
+                if (eventId) {
+                    const event = await getEventById(config, eventId);
+                    return { content: [{ type: "text", text: formatEvent(event) }] };
+                }
+                else if (date) {
+                    const notes = await getNotesByDate(config, date);
+                    if (!notes.length)
+                        return { content: [{ type: "text", text: `No notes found for ${date}.` }] };
+                    const text = notes.map(formatEvent).join("\n\n---\n\n");
+                    return { content: [{ type: "text", text }] };
+                }
+                else {
+                    return { content: [{ type: "text", text: "Provide either event_id or date." }], isError: true };
+                }
+            }
             case "create_event": {
                 const config = getConfig(args);
                 const event = await createEvent(config, {
@@ -443,6 +516,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     race: args["race"],
                     distance: args["distance"],
                     sub_type: args["sub_type"],
+                    workout_doc: args["workout_doc"],
                 });
                 return { content: [{ type: "text", text: `Created event:\n\n${formatEvent(event)}` }] };
             }
@@ -450,7 +524,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 const eventId = z.string().parse(args["event_id"]);
                 const config = getConfig(args);
                 const input = {};
-                for (const key of ["name", "description", "start_date_local", "category", "type", "race", "distance", "sub_type"]) {
+                for (const key of ["name", "description", "start_date_local", "category", "type", "race", "distance", "sub_type", "workout_doc"]) {
                     if (args[key] !== undefined)
                         input[key] = args[key];
                 }

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "intervals-icu-mcp-server",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "MCP server for Intervals.icu — 20 tools for activities, wellness, calendar events, workouts and more",
   "type": "module",
   "bin": {
-    "intervals-icu-mcp": "./dist/index.js"
+    "intervals-icu-mcp": "dist/index.js"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && chmod +x dist/index.js",
     "dev": "tsc --watch",
     "start": "node dist/index.js",
     "inspector": "npx @modelcontextprotocol/inspector node dist/index.js",