@etweisberg/garmin-connect-mcp 0.1.14 → 0.1.16

package/README.md

@@ -59,51 +59,85 @@ Session cookies expire after a few hours. Re-run the login flow when they do.
 ## Available Tools
 
 ### Session & Auth
-| Tool | Description |
-|------|-------------|
-| `garmin-login` | Returns login instructions for the Playwright MCP browser |
-| `check-session` | Validates the saved session is still active |
-| `run-tests` | Returns a test plan to verify all tools work |
+
+| Tool            | Description                                               |
+| --------------- | --------------------------------------------------------- |
+| `garmin-login`  | Returns login instructions for the Playwright MCP browser |
+| `check-session` | Validates the saved session is still active               |
+| `run-tests`     | Returns a test plan to verify all tools work              |
 
 ### Activities
-| Tool | Description |
-|------|-------------|
-| `list-activities` | List activities with pagination |
-| `get-activity` | Full activity summary (distance, duration, HR, calories) |
-| `get-activity-details` | Time-series metrics (HR, cadence, elevation over time) |
-| `get-activity-splits` | Lap/split data |
-| `get-activity-hr-zones` | Heart rate time-in-zone breakdown |
-| `get-activity-polyline` | Full-resolution GPS track |
-| `get-activity-weather` | Weather conditions during activity |
-| `download-fit` | Download original FIT file |
+
+| Tool                    | Description                                              |
+| ----------------------- | -------------------------------------------------------- |
+| `list-activities`       | List activities with pagination                          |
+| `get-activity`          | Full activity summary (distance, duration, HR, calories) |
+| `get-activity-details`  | Time-series metrics (HR, cadence, elevation over time)   |
+| `get-activity-splits`   | Lap/split data                                           |
+| `get-activity-hr-zones` | Heart rate time-in-zone breakdown                        |
+| `get-activity-polyline` | Full-resolution GPS track                                |
+| `get-activity-weather`  | Weather conditions during activity                       |
+| `download-fit`          | Download original FIT file                               |
 
 ### Daily Health
-| Tool | Description |
-|------|-------------|
-| `get-daily-summary` | Steps, calories, distance, intensity minutes |
-| `get-daily-heart-rate` | Heart rate data throughout the day |
-| `get-daily-stress` | Stress levels throughout the day |
-| `get-daily-summary-chart` | Combined wellness chart data |
-| `get-daily-intensity-minutes` | Intensity minutes for a date |
-| `get-daily-movement` | Movement/activity data |
-| `get-daily-respiration` | Respiration rate data |
+
+| Tool                          | Description                                  |
+| ----------------------------- | -------------------------------------------- |
+| `get-daily-summary`           | Steps, calories, distance, intensity minutes |
+| `get-daily-heart-rate`        | Heart rate data throughout the day           |
+| `get-daily-stress`            | Stress levels throughout the day             |
+| `get-daily-summary-chart`     | Combined wellness chart data                 |
+| `get-daily-intensity-minutes` | Intensity minutes for a date                 |
+| `get-daily-movement`          | Movement/activity data                       |
+| `get-daily-respiration`       | Respiration rate data                        |
 
 ### Sleep / Body Battery / HRV
-| Tool | Description |
-|------|-------------|
-| `get-sleep` | Sleep score, duration, stages, SpO2 |
+
+| Tool               | Description                         |
+| ------------------ | ----------------------------------- |
+| `get-sleep`        | Sleep score, duration, stages, SpO2 |
 | `get-body-battery` | Body battery charged/drained values |
-| `get-hrv` | Heart rate variability data |
+| `get-hrv`          | Heart rate variability data         |
+
+### Training & Recovery
+
+| Tool                     | Description                                      |
+| ------------------------ | ------------------------------------------------ |
+| `get-training-readiness` | Training readiness score (sleep, recovery, load) |
+| `get-sleep-stats`        | Sleep statistics over a date range               |
+| `get-hydration`          | Daily hydration/water intake data                |
 
 ### Weight / Records / Fitness
-| Tool | Description |
-|------|-------------|
-| `get-weight` | Weight measurements over a date range |
-| `get-personal-records` | All personal records with history |
-| `get-fitness-stats` | Aggregated activity stats by type |
-| `get-vo2max` | Latest VO2 Max estimate |
-| `get-hr-zones-config` | Heart rate zone boundaries |
-| `get-user-profile` | User profile and settings |
+
+| Tool                   | Description                           |
+| ---------------------- | ------------------------------------- |
+| `get-weight`           | Weight measurements over a date range |
+| `get-personal-records` | All personal records with history     |
+| `get-fitness-stats`    | Aggregated activity stats by type     |
+| `get-vo2max`           | Latest VO2 Max estimate               |
+| `get-hr-zones-config`  | Heart rate zone boundaries            |
+| `get-power-zones`      | Power zone config for all sports      |
+| `get-user-profile`     | User profile and settings             |
+
+### Calendar, Goals & Badges
+
+| Tool                    | Description                                 |
+| ----------------------- | ------------------------------------------- |
+| `get-calendar`          | Monthly calendar with activities and events |
+| `get-goals`             | Active, future, or past fitness goals       |
+| `get-badges`            | All earned badges/achievements              |
+| `get-badge-leaderboard` | Badge leaderboard among connections         |
+
+### Workouts
+
+| Tool                   | Description                                        |
+| ---------------------- | -------------------------------------------------- |
+| `list-workouts`        | List saved workouts                                |
+| `get-workout`          | Get workout details (steps, segments)              |
+| `create-workout`       | Create a new workout (warmup, intervals, cooldown) |
+| `schedule-workout`     | Schedule a workout to a date (syncs to device)     |
+| `delete-workout`       | Delete a workout                                   |
+| `download-workout-fit` | Download a workout as a FIT file                   |
 
 ## Architecture
 
@@ -141,13 +175,13 @@ npm run build
 
 ### Scripts
 
-| Command | Description |
-|---------|-------------|
-| `npm run build` | Compile TypeScript |
-| `npm run lint` | Run ESLint |
-| `npm run format` | Format with Prettier |
-| `npm run typecheck` | Type check without emitting |
-| `npm test` | Run integration tests (requires valid session) |
+| Command             | Description                                    |
+| ------------------- | ---------------------------------------------- |
+| `npm run build`     | Compile TypeScript                             |
+| `npm run lint`      | Run ESLint                                     |
+| `npm run format`    | Format with Prettier                           |
+| `npm run typecheck` | Type check without emitting                    |
+| `npm test`          | Run integration tests (requires valid session) |
 
 ### Local Integration Testing
 
@@ -159,7 +193,7 @@ npm test
 
 ## Contributing
 
-1. Fork the repo and create a feature branch
+1. Create a feature branch off `main`
 2. Make your changes
 3. Run checks:
    ```bash
@@ -175,20 +209,14 @@ CI runs lint, format check, typecheck, and build on every PR. Integration tests
 
 ### Releasing
 
-Releases are automated via GitHub Actions:
+Releases are fully automated. Every merge to `main` triggers the release workflow which:
 
-```bash
-# Bump version
-npm version patch  # or minor, major
+1. Runs CI (lint, format, typecheck, build)
+2. Bumps the patch version
+3. Publishes to npm with provenance
+4. Creates a GitHub Release
 
-# Push the tag
-git push --follow-tags
-
-# GitHub Actions will:
-# 1. Build the package
-# 2. Publish to npm with provenance
-# 3. Create a GitHub Release
-```
+No manual version bumping or tagging needed — just merge your PR.
 
 ## License
 

package/dist/garmin-client.js

@@ -142,6 +142,55 @@ export class GarminClient {
         }
         return Buffer.from(result.data, "base64");
     }
+    async post(path, body) {
+        await this.init();
+        const url = `/gc-api/${path}`;
+        const csrfToken = this.csrfToken;
+        const bodyStr = JSON.stringify(body);
+        const result = await this.page.evaluate(async ({ url, csrfToken, bodyStr, }) => {
+            const resp = await fetch(url, {
+                method: "POST",
+                headers: {
+                    "connect-csrf-token": csrfToken,
+                    "Content-Type": "application/json",
+                    Accept: "application/json, */*",
+                },
+                body: bodyStr,
+            });
+            const text = await resp.text();
+            return { status: resp.status, body: text };
+        }, { url, csrfToken, bodyStr });
+        if (result.status === 204 || (result.status === 200 && !result.body)) {
+            return { noData: true, status: result.status, path };
+        }
+        if (result.status < 200 || result.status >= 300) {
+            throw new Error(`Garmin API ${result.status}: ${path} — ${result.body}`);
+        }
+        return JSON.parse(result.body);
+    }
+    async delete(path) {
+        await this.init();
+        const url = `/gc-api/${path}`;
+        const csrfToken = this.csrfToken;
+        const result = await this.page.evaluate(async ({ url, csrfToken }) => {
+            const resp = await fetch(url, {
+                method: "DELETE",
+                headers: {
+                    "connect-csrf-token": csrfToken,
+                    Accept: "*/*",
+                },
+            });
+            const text = await resp.text();
+            return { status: resp.status, body: text };
+        }, { url, csrfToken });
+        if (result.status === 204 || (result.status === 200 && !result.body)) {
+            return { noData: true, status: result.status, path };
+        }
+        if (result.status < 200 || result.status >= 300) {
+            throw new Error(`Garmin API ${result.status}: ${path} — ${result.body}`);
+        }
+        return result.body ? JSON.parse(result.body) : { success: true };
+    }
 }
 // Singleton client for reuse across tool calls
 let _sharedClient = null;

package/dist/test.js

@@ -304,6 +304,154 @@ const tests = [
                 throw new Error("no zones returned");
         },
     },
+    // ── Training & Recovery ─────────────────────────────────────────
+    {
+        name: "get-training-readiness",
+        run: async (server) => {
+            const result = await callTool(server, "get-training-readiness");
+            if (result.isError)
+                throw new Error(getToolText(result));
+        },
+    },
+    {
+        name: "get-sleep-stats",
+        run: async (server) => {
+            const sevenDaysAgo = new Date(Date.now() - 7 * 86400000)
+                .toISOString()
+                .slice(0, 10);
+            const today = new Date().toISOString().slice(0, 10);
+            const result = await callTool(server, "get-sleep-stats", {
+                startDate: sevenDaysAgo,
+                endDate: today,
+            });
+            if (result.isError)
+                throw new Error(getToolText(result));
+        },
+    },
+    // ── Calendar, Goals, Badges ────────────────────────────────────────
+    {
+        name: "get-calendar",
+        run: async (server) => {
+            const result = await callTool(server, "get-calendar", {
+                year: 2026,
+                month: 2,
+            });
+            if (result.isError)
+                throw new Error(getToolText(result));
+        },
+    },
+    {
+        name: "get-goals",
+        run: async (server) => {
+            const result = await callTool(server, "get-goals", { status: "active" });
+            if (result.isError)
+                throw new Error(getToolText(result));
+        },
+    },
+    {
+        name: "get-badges",
+        run: async (server) => {
+            const result = await callTool(server, "get-badges");
+            if (result.isError)
+                throw new Error(getToolText(result));
+        },
+    },
+    {
+        name: "get-badge-leaderboard",
+        run: async (server) => {
+            const result = await callTool(server, "get-badge-leaderboard", {
+                limit: 5,
+            });
+            if (result.isError)
+                throw new Error(getToolText(result));
+        },
+    },
+    // ── Hydration & Power Zones ────────────────────────────────────────
+    {
+        name: "get-hydration",
+        run: async (server) => {
+            const result = await callTool(server, "get-hydration");
+            if (result.isError)
+                throw new Error(getToolText(result));
+        },
+    },
+    {
+        name: "get-power-zones",
+        run: async (server) => {
+            const result = await callTool(server, "get-power-zones");
+            if (result.isError)
+                throw new Error(getToolText(result));
+        },
+    },
+    // ── Workouts ───────────────────────────────────────────────────────
+    {
+        name: "list-workouts",
+        run: async (server) => {
+            const result = await callTool(server, "list-workouts", {
+                start: 0,
+                limit: 5,
+            });
+            if (result.isError)
+                throw new Error(getToolText(result));
+        },
+    },
+    {
+        name: "workout CRUD (create -> schedule -> delete)",
+        run: async (server) => {
+            // Create
+            const workout = {
+                workoutName: "MCP Test Workout (safe to delete)",
+                sportType: { sportTypeId: 1, sportTypeKey: "running" },
+                workoutSegments: [
+                    {
+                        segmentOrder: 1,
+                        sportType: { sportTypeId: 1, sportTypeKey: "running" },
+                        workoutSteps: [
+                            {
+                                type: "ExecutableStepDTO",
+                                stepOrder: 1,
+                                stepType: { stepTypeId: 3, stepTypeKey: "interval" },
+                                endCondition: {
+                                    conditionTypeId: 2,
+                                    conditionTypeKey: "time",
+                                },
+                                endConditionValue: 600,
+                                targetType: {
+                                    workoutTargetTypeId: 1,
+                                    workoutTargetTypeKey: "no.target",
+                                },
+                            },
+                        ],
+                    },
+                ],
+            };
+            const createResult = await callTool(server, "create-workout", {
+                workout: JSON.stringify(workout),
+            });
+            if (createResult.isError)
+                throw new Error(getToolText(createResult));
+            const created = getToolJson(createResult);
+            if (!created.workoutId)
+                throw new Error("no workoutId returned");
+            const wid = String(created.workoutId);
+            // Schedule to tomorrow
+            const tomorrow = new Date(Date.now() + 86400000)
+                .toISOString()
+                .slice(0, 10);
+            const schedResult = await callTool(server, "schedule-workout", {
+                workoutId: wid,
+                date: tomorrow,
+            });
+            if (schedResult.isError)
+                throw new Error(getToolText(schedResult));
+            // Delete (cleanup)
+            const delResult = await callTool(server, "delete-workout", {
+                workoutId: wid,
+            });
+            if (delResult.isError)
+                throw new Error(getToolText(delResult));
+        },
+    },
 ];
 // Resolved during bootstrap
 let activityId = "";

package/dist/tools.js

@@ -336,6 +336,174 @@ To authenticate, you need the Playwright MCP server installed (\`@playwright/mcp
         return jsonResult(data);
     });
     // ══════════════════════════════════════════════════════════════════
+    // Training & Recovery
+    // ══════════════════════════════════════════════════════════════════
+    server.tool("get-training-readiness", "Get training readiness score for a date (based on sleep, recovery, training load)", {
+        date: z.string().optional().describe("YYYY-MM-DD, defaults to today"),
+    }, async ({ date }) => {
+        const client = getClient();
+        const d = date ?? todayDate();
+        const data = await client.get(`metrics-service/metrics/trainingreadiness/${d}`);
+        return jsonResult(data);
+    });
+    server.tool("get-sleep-stats", "Get sleep statistics over a date range (averages, trends)", {
+        startDate: z.string().describe("Start date YYYY-MM-DD"),
+        endDate: z.string().describe("End date YYYY-MM-DD"),
+    }, async ({ startDate, endDate }) => {
+        const client = getClient();
+        const data = await client.get(`sleep-service/stats/sleep/daily/${startDate}/${endDate}`);
+        return jsonResult(data);
+    });
+    // ══════════════════════════════════════════════════════════════════
+    // Calendar, Goals, Badges
+    // ══════════════════════════════════════════════════════════════════
+    server.tool("get-calendar", "Get monthly calendar with activities, workouts, and events", {
+        year: z.number().describe("Year (e.g. 2026)"),
+        month: z.number().describe("Month number 0-11 (0=January, 11=December)"),
+    }, async ({ year, month }) => {
+        const client = getClient();
+        const data = await client.get(`calendar-service/year/${year}/month/${month}`);
+        return jsonResult(data);
+    });
+    server.tool("get-goals", "Get fitness goals", {
+        status: z
+            .string()
+            .default("active")
+            .describe("Goal status: active, future, or past"),
+    }, async ({ status }) => {
+        const client = getClient();
+        const data = await client.get("goal-service/goal/goals", { status });
+        return jsonResult(data);
+    });
+    server.tool("get-badges", "Get all earned badges/achievements", {}, async () => {
+        const client = getClient();
+        const data = await client.get("badge-service/badge/earned");
+        return jsonResult(data);
+    });
+    server.tool("get-badge-leaderboard", "Get badge leaderboard among your connections", {
+        limit: z.number().default(25).describe("Max entries to return"),
+    }, async ({ limit }) => {
+        const client = getClient();
+        const data = await client.get("badge-service/badge/leaderboard", {
+            limit,
+        });
+        return jsonResult(data);
+    });
+    // ══════════════════════════════════════════════════════════════════
+    // Hydration & Power Zones
+    // ══════════════════════════════════════════════════════════════════
+    server.tool("get-hydration", "Get daily hydration/water intake data", {
+        date: z.string().optional().describe("YYYY-MM-DD, defaults to today"),
+    }, async ({ date }) => {
+        const client = getClient();
+        const d = date ?? todayDate();
+        const data = await client.get(`usersummary-service/usersummary/hydration/allData/${d}`);
+        return jsonResult(data);
+    });
+    server.tool("get-power-zones", "Get power zone configuration for all sports", {}, async () => {
+        const client = getClient();
+        const data = await client.get("biometric-service/powerZones/sports/all");
+        return jsonResult(data);
+    });
+    // ══════════════════════════════════════════════════════════════════
+    // Workouts (read + write)
+    // ══════════════════════════════════════════════════════════════════
+    server.tool("list-workouts", "List your saved workouts", {
+        start: z.number().default(0).describe("Pagination offset"),
+        limit: z.number().default(100).describe("Max workouts to return"),
+    }, async ({ start, limit }) => {
+        const client = getClient();
+        const data = await client.get("workout-service/workouts", {
+            start,
+            limit,
+        });
+        return jsonResult(data);
+    });
+    server.tool("get-workout", "Get a single workout by ID with full step/segment details", {
+        workoutId: z.string().describe("The workout ID"),
+    }, async ({ workoutId }) => {
+        const client = getClient();
+        const data = await client.get(`workout-service/workout/${workoutId}`);
+        return jsonResult(data);
+    });
+    server.tool("download-workout-fit", "Download a workout as a FIT file", {
+        workoutId: z.string().describe("The workout ID"),
+        outputDir: z
+            .string()
+            .default("./fit_files")
+            .describe("Directory to save the FIT file"),
+    }, async ({ workoutId, outputDir }) => {
+        const client = getClient();
+        const fitBytes = await client.getBytes(`workout-service/workout/FIT/${workoutId}`);
+        mkdirSync(outputDir, { recursive: true });
+        const outPath = join(outputDir, `workout_${workoutId}.fit`);
+        writeFileSync(outPath, fitBytes);
+        return textResult(`Downloaded workout FIT: ${outPath} (${fitBytes.length} bytes)`);
+    });
+    server.tool("create-workout", `Create a new workout on Garmin Connect. Pass a workout JSON object with workoutName, sportType, and workoutSegments containing steps.
+
+Sport type IDs: 1=running, 2=cycling, 3=swimming, 4=walking, 5=multi, 6=fitness, 7=hiking.
+Step types: warmup (1), cooldown (2), interval (3), recovery (4), rest (5).
+End conditions: distance (1, meters), time (2, seconds), open (7).
+
+Example minimal running workout:
+{
+  "workoutName": "Easy 30min Run",
+  "sportType": {"sportTypeId": 1, "sportTypeKey": "running"},
+  "workoutSegments": [{
+    "segmentOrder": 1,
+    "sportType": {"sportTypeId": 1, "sportTypeKey": "running"},
+    "workoutSteps": [{
+      "type": "ExecutableStepDTO",
+      "stepOrder": 1,
+      "stepType": {"stepTypeId": 1, "stepTypeKey": "warmup"},
+      "endCondition": {"conditionTypeId": 2, "conditionTypeKey": "time"},
+      "endConditionValue": 300,
+      "targetType": {"workoutTargetTypeId": 1, "workoutTargetTypeKey": "no.target"}
+    }, {
+      "type": "ExecutableStepDTO",
+      "stepOrder": 2,
+      "stepType": {"stepTypeId": 3, "stepTypeKey": "interval"},
+      "endCondition": {"conditionTypeId": 2, "conditionTypeKey": "time"},
+      "endConditionValue": 1200,
+      "targetType": {"workoutTargetTypeId": 1, "workoutTargetTypeKey": "no.target"}
+    }, {
+      "type": "ExecutableStepDTO",
+      "stepOrder": 3,
+      "stepType": {"stepTypeId": 2, "stepTypeKey": "cooldown"},
+      "endCondition": {"conditionTypeId": 2, "conditionTypeKey": "time"},
+      "endConditionValue": 300,
+      "targetType": {"workoutTargetTypeId": 1, "workoutTargetTypeKey": "no.target"}
+    }]
+  }]
+}`, {
+        workout: z
+            .string()
+            .describe("JSON string of the workout object to create"),
+    }, async ({ workout }) => {
+        const client = getClient();
+        const workoutObj = JSON.parse(workout);
+        const data = await client.post("workout-service/workout", workoutObj);
+        return jsonResult(data);
+    });
+    server.tool("schedule-workout", "Schedule an existing workout to a date on your calendar. The workout will sync to your device.", {
+        workoutId: z.string().describe("The workout ID"),
+        date: z.string().describe("Date to schedule YYYY-MM-DD"),
+    }, async ({ workoutId, date }) => {
+        const client = getClient();
+        const data = await client.post(`workout-service/schedule/${workoutId}`, {
+            date,
+        });
+        return jsonResult(data);
+    });
+    server.tool("delete-workout", "Delete a workout from Garmin Connect", {
+        workoutId: z.string().describe("The workout ID to delete"),
+    }, async ({ workoutId }) => {
+        const client = getClient();
+        await client.delete(`workout-service/workout/${workoutId}`);
+        return textResult(`Workout ${workoutId} deleted`);
+    });
+    // ══════════════════════════════════════════════════════════════════
     // Testing
     // ══════════════════════════════════════════════════════════════════
     server.tool("run-tests", "Returns a test plan for verifying all garmin-connect-mcp tools work. Call each tool listed and report results.", {}, async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@etweisberg/garmin-connect-mcp",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "MCP server for Garmin Connect — access activities, metrics, and FIT files via Claude Code",
   "type": "module",
   "bin": {