ourpr-mcp-server 0.2.0 → 0.4.0

package/build/index.js

@@ -1,61 +1,26 @@
 #!/usr/bin/env node
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { McpServer } from "@modelcontextprotocol/server";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { z } from "zod";
-import { ApiError, day, duration, feet, get, miles, pathId, stamp } from "./api.js";
-import { cell, fenced } from "./safe.js";
-/**
- * ourpr-mcp-server — an agent reads your own running history.
- *
- * WHY THIS EXISTS. Every authenticated read in ourpr is gated by a session
- * that lives about an hour, so nothing outside a browser could hold one.
- * Personal access tokens changed that, and this is what they were for: your
- * training data, in whatever agent you already use, with a credential you
- * issued to yourself and can revoke.
- *
- * READ ONLY, and not by omission. A token's default scope is read, and every
- * route behind these tools is a GET. Nothing here can change a run, plan a
- * week, or mint another token.
- *
- * THE TOOL SET WAS CHOSEN BY AN EVALUATION, not by listing the API. Ten
- * verified questions were written first (`backend/scripts/mcp_eval_oracle.py`)
- * and they said what matters: nine of ten need the activity window, three need
- * one run in full, two need a second source. So the window is the tool that
- * has to be excellent, and a `training_summary` tool that seemed obvious when
- * guessing turned out to answer nothing and was not built.
- *
- * CONTEXT IS THE REAL CONSTRAINT. A window can hold 800 runs, and handing an
- * agent 800 full activity objects destroys the context it needs to think. So
- * `ourpr_list_runs` returns a COMPACT table and one run in full is a separate
- * tool. That is the same lesson the backend learned when `laps` turned out to
- * be 36% of a payload nothing rendered — an agent's context is more expensive
- * than egress, not less.
- */
-/** The watch or app that recorded a run, as one readable name.
- *
- *  `device` is an OBJECT and its keys vary — measured across all 7,911
- *  production rows: {make,model,raw} 2,064, {app,raw} 718, {app,make,model}
- *  684, {make,raw} 373, {model,raw} 81, and 3,986 null. So prefer the human
- *  pair, fall back to whichever single name exists, and only then to `raw`,
- *  which is a slug like "garmin/fr255" and is the last resort rather than the
- *  answer. */
+import { ApiError, METERS_PER_MILE, addDays, clock, day, duration, feet, get, localDay, miles, pathId, post, stamp, weekOf, } from "./api.js";
+import { cell, fenced, note } from "./safe.js";
+// Ten reads and one write. The write needs a token made with the write
+// scope and ourpr create behind it; every other tool is a GET.
+// device keys vary: the human pair first, then a single name, then the raw slug.
 function deviceLabel(d) {
     if (!d)
         return null;
     const named = [d.make, d.model].filter(Boolean).join(" ").trim();
     return cell(named || d.app || d.raw, 40) || null;
 }
-const server = new McpServer({ name: "ourpr-mcp-server", version: "0.1.0" });
-// A window can hold years. This bounds ONE answer, and when it bites the
-// answer says so — a silent truncation reads as "that is all there was",
-// which is the difference between a short answer and a wrong one.
+// Bounds one answer; when it bites, the answer says so.
 const DEFAULT_LIMIT = 100;
 const MAX_LIMIT = 500;
 const ok = (text, structured) => ({
     content: [{ type: "text", text }],
     structuredContent: structured,
 });
-/** Errors reach the agent as an error result with copy it can act on. */
+// An error reaches the agent as an error result with copy it can act on.
 const fail = (err) => ({
     content: [
         {
@@ -65,12 +30,10 @@ const fail = (err) => ({
     ],
     isError: true,
 });
-/** One activity, flattened to what an agent reasons about. */
 function summarise(a) {
     return {
         id: String(a.id),
         date: day(a.date),
-        // RUNNER-AUTHORED TEXT. Cleaned at the one boundary it crosses.
         name: cell(a.name),
         type: cell(a.activity_type, 24),
         miles: miles(a.distance_meters),
@@ -80,8 +43,7 @@ function summarise(a) {
         avg_hr: a.avg_heartrate ?? null,
     };
 }
-/** A markdown table. Agents read these far more reliably than raw JSON, and
- *  it costs a fraction of the tokens the same rows cost as objects. */
+// A markdown table costs fewer tokens than the same rows as objects.
 function table(rows) {
     const head = "| date | name | type | mi | pace | time | ft | hr |\n" +
         "|---|---|---|---|---|---|---|---|";
@@ -92,331 +54,624 @@ function table(rows) {
         .join("\n");
     return `${head}\n${body}`;
 }
-// ─── The window ─────────────────────────────────────────────────────────────
-server.registerTool("ourpr_list_runs", {
-    title: "List runs in a date range",
-    description: "Training history between two dates, newest first: date, name, type, " +
-        "miles, pace, time, elevation, average heart rate. Start here for " +
-        "totals, streaks, trends, or finding a run. For one run's splits, use " +
-        "ourpr_get_run with an id from here.",
-    inputSchema: {
-        start_date: z
-            .string()
-            .describe("First day to include, YYYY-MM-DD. Example: 2026-01-01"),
-        end_date: z
-            .string()
-            .describe("Last day to include, YYYY-MM-DD. Example: 2026-06-30"),
-        include_non_runs: z
-            .boolean()
-            .default(false)
-            .describe("Include rides, gym and other types. Runs only by default."),
-        limit: z
-            .number()
-            .int()
-            .min(1)
-            .max(MAX_LIMIT)
-            .default(DEFAULT_LIMIT)
-            .describe("Most rows to return. The answer says what it left out."),
-    },
-    outputSchema: {
-        runs: z.array(z.record(z.string(), z.unknown())),
-        returned: z.number(),
-        total_in_window: z.number(),
-        truncated: z.boolean(),
-    },
-    annotations: { readOnlyHint: true, openWorldHint: true },
-}, async ({ start_date, end_date, include_non_runs, limit }) => {
-    try {
-        const data = await get(`/users/me/activities?after=${stamp(start_date, "start")}` +
-            `&before=${stamp(end_date, "end")}` +
-            `&include_non_runs=${include_non_runs}`);
-        const all = data.activities.map(summarise);
-        const shown = all.slice(0, limit);
-        const truncated = all.length > shown.length;
-        const header = `${all.length} ${include_non_runs ? "activities" : "runs"} between ` +
-            `${cell(start_date, 10)} and ${cell(end_date, 10)}.` +
-            (truncated
-                ? ` Showing the ${shown.length} newest — ${all.length - shown.length} ` +
-                    "older ones are not listed. Narrow the dates or raise `limit` to see them."
-                : "");
-        return ok(`${header}\n\n` + fenced(shown.length ? table(shown) : "No activities in that window."), {
-            runs: shown,
-            returned: shown.length,
-            total_in_window: all.length,
-            truncated,
-        });
-    }
-    catch (err) {
-        return fail(err);
-    }
-});
-// ─── One run ────────────────────────────────────────────────────────────────
-server.registerTool("ourpr_get_run", {
-    title: "Get one run in full",
-    description: "One activity in full: mile splits, heart rate, cadence, calories, " +
-        "device. Id comes from ourpr_list_runs. For the profile along the " +
-        "route, use ourpr_run_stream.",
-    inputSchema: {
-        activity_id: z
-            .string()
-            .describe("Run id from ourpr_list_runs."),
-    },
-    outputSchema: {
-        run: z.record(z.string(), z.unknown()),
-        splits: z.array(z.record(z.string(), z.unknown())),
-    },
-    annotations: { readOnlyHint: true, openWorldHint: true },
-}, async ({ activity_id }) => {
-    try {
-        const a = await get(`/users/me/activities/${pathId(activity_id)}`);
-        const splits = (a.splits ?? []).map((s) => ({
-            mile: s.split_number,
-            pace: s.pace_per_mile ?? null,
-            elevation_change_ft: feet(s.elevation_difference_meters),
-        }));
-        const run = {
-            ...summarise(a),
-            max_hr: a.max_heartrate ?? null,
-            avg_cadence_spm: a.avg_cadence ?? null,
-            calories: a.calories ?? null,
-            device: deviceLabel(a.device),
-            has_route: Boolean(a.summary_polyline),
-        };
-        const lines = [
-            `**${run.name || "Untitled"}** — ${run.date}`,
-            `${run.miles ?? "—"} mi · ${run.pace_per_mile ?? "—"}/mi · ` +
-                `${run.moving_time ?? "—"} · ${run.elevation_ft ?? "—"} ft climb`,
-            run.avg_hr ? `Heart rate ${run.avg_hr} avg, ${run.max_hr ?? "—"} max` : "",
-            splits.length
-                ? `\n| mile | pace | ± ft |\n|---|---|---|\n` +
-                    splits.map((s) => `| ${s.mile} | ${s.pace ?? "—"} | ${s.elevation_change_ft ?? "—"} |`).join("\n")
-                : "\nNo mile splits recorded for this run.",
-        ].filter(Boolean);
-        return ok(fenced(lines.join("\n")), { run, splits });
-    }
-    catch (err) {
-        return fail(err);
-    }
-});
-// ─── The profile ────────────────────────────────────────────────────────────
-server.registerTool("ourpr_run_stream", {
-    title: "Get a run's elevation and sensor profile",
-    description: "A run's profile on a 10 m grid — elevation, heart rate, power, " +
-        "cadence — as min, average, max and coverage per channel, not every " +
-        "sample. No profile is a normal answer for an indoor run.",
-    inputSchema: {
-        activity_id: z.string().describe("Run id from ourpr_list_runs."),
-    },
-    outputSchema: {
-        grid_m: z.number(),
-        total_miles: z.number(),
-        samples: z.number(),
-        channels: z.record(z.string(), z.unknown()),
-    },
-    annotations: { readOnlyHint: true, openWorldHint: true },
-}, async ({ activity_id }) => {
-    try {
-        const s = await get(`/users/me/activities/${pathId(activity_id)}/stream`);
-        // SUMMARY AND NOT THE SAMPLES. A 10 mile run is ~1,600 points per
-        // channel and five channels. Handing an agent 8,000 numbers spends its
-        // context on data it will only reduce anyway.
-        const stats = (values, scale = 1) => {
-            const nums = (values ?? []).filter((v) => v != null);
-            if (!nums.length)
-                return null;
-            const sum = nums.reduce((a, b) => a + b, 0);
-            return {
-                min: Math.round((Math.min(...nums) * scale) * 10) / 10,
-                max: Math.round((Math.max(...nums) * scale) * 10) / 10,
-                avg: Math.round(((sum / nums.length) * scale) * 10) / 10,
-                coverage: Math.round((nums.length / (values?.length || 1)) * 100),
+// One instance for each connection. serveStdio calls this once the opening
+// message says which protocol era the client speaks.
+function buildServer() {
+    const server = new McpServer({ name: "ourpr-mcp-server", version: "0.4.0" });
+    // ─── The window ─────────────────────────────────────────────────────────────
+    server.registerTool("ourpr_list_runs", {
+        title: "List runs in a date range",
+        description: "Training history between two dates, newest first: date, name, type, " +
+            "miles, pace, time, elevation, average heart rate. Start here for " +
+            "totals, streaks, trends, or finding a run. For one run's splits, use " +
+            "ourpr_get_run with an id from here.",
+        inputSchema: {
+            start_date: z
+                .string()
+                .describe("First day to include, YYYY-MM-DD. Example: 2026-01-01"),
+            end_date: z
+                .string()
+                .describe("Last day to include, YYYY-MM-DD. Example: 2026-06-30"),
+            include_non_runs: z
+                .boolean()
+                .default(false)
+                .describe("Include rides, gym and other types. Runs only by default."),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(MAX_LIMIT)
+                .default(DEFAULT_LIMIT)
+                .describe("Most rows to return. The answer says what it left out."),
+        },
+        outputSchema: {
+            runs: z.array(z.record(z.string(), z.unknown())),
+            returned: z.number(),
+            total_in_window: z.number(),
+            truncated: z.boolean(),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async ({ start_date, end_date, include_non_runs, limit }) => {
+        try {
+            const data = await get(`/users/me/activities?after=${stamp(start_date, "start")}` +
+                `&before=${stamp(end_date, "end")}` +
+                `&include_non_runs=${include_non_runs}`);
+            const all = data.activities.map(summarise);
+            const shown = all.slice(0, limit);
+            const truncated = all.length > shown.length;
+            const header = `${all.length} ${include_non_runs ? "activities" : "runs"} between ` +
+                `${cell(start_date, 10)} and ${cell(end_date, 10)}.` +
+                (truncated
+                    ? ` Showing the ${shown.length} newest — ${all.length - shown.length} ` +
+                        "older ones are not listed. Narrow the dates or raise `limit` to see them."
+                    : "");
+            return ok(`${header}\n\n` + fenced(shown.length ? table(shown) : "No activities in that window."), {
+                runs: shown,
+                returned: shown.length,
+                total_in_window: all.length,
+                truncated,
+            });
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    // ─── One run ────────────────────────────────────────────────────────────────
+    server.registerTool("ourpr_get_run", {
+        title: "Get one run in full",
+        description: "One activity in full: mile splits, heart rate, cadence, calories, " +
+            "device. Id comes from ourpr_list_runs. For the profile along the " +
+            "route, use ourpr_run_stream.",
+        inputSchema: {
+            activity_id: z
+                .string()
+                .describe("Run id from ourpr_list_runs."),
+        },
+        outputSchema: {
+            run: z.record(z.string(), z.unknown()),
+            splits: z.array(z.record(z.string(), z.unknown())),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async ({ activity_id }) => {
+        try {
+            const a = await get(`/users/me/activities/${pathId(activity_id)}`);
+            const splits = (a.splits ?? []).map((s) => ({
+                mile: s.split_number,
+                pace: s.pace_per_mile ?? null,
+                elevation_change_ft: feet(s.elevation_difference_meters),
+            }));
+            const run = {
+                ...summarise(a),
+                max_hr: a.max_heartrate ?? null,
+                avg_cadence_spm: a.avg_cadence ?? null,
+                calories: a.calories ?? null,
+                device: deviceLabel(a.device),
+                has_route: Boolean(a.summary_polyline),
             };
-        };
-        const channels = {
-            // Stored in centimetres; feet is what the app speaks.
-            elevation_ft: stats(s.elev_cm, 0.0328084),
-            heart_rate_bpm: stats(s.hr_bpm),
-            power_w: stats(s.power_w),
-            cadence_spm: stats(s.cadence_spm),
-        };
-        const present = Object.entries(channels)
-            .filter(([, v]) => v)
-            .map(([k, v]) => `- ${k}: min ${v.min}, avg ${v.avg}, max ${v.max} (${v.coverage}% of samples)`)
-            .join("\n");
-        const total_miles = miles(s.total_m) ?? 0;
-        return ok(`Profile over ${total_miles} mi, ${s.points} samples every ${s.grid_m} m` +
-            (s.source ? ` (from ${cell(s.source, 24)})` : "") +
-            ".\n\n" +
-            (present || "No sensor channels were recorded for this run."), { grid_m: s.grid_m, total_miles, samples: s.points, channels });
-    }
-    catch (err) {
-        return fail(err);
-    }
-});
-// ─── Laps ───────────────────────────────────────────────────────────────────
-server.registerTool("ourpr_run_laps", {
-    title: "Get a run's laps",
-    description: "The laps the watch recorded for one run — the runner's own button " +
-        "presses. Laps follow the workout; mile splits follow the mile.",
-    inputSchema: {
-        activity_id: z.string().describe("Run id from ourpr_list_runs."),
-    },
-    outputSchema: { laps: z.array(z.record(z.string(), z.unknown())) },
-    annotations: { readOnlyHint: true, openWorldHint: true },
-}, async ({ activity_id }) => {
-    try {
-        const raw = await get(`/users/me/activities/${pathId(activity_id)}/laps`);
-        const laps = raw.map((l, i) => {
-            const mi = miles(l.distance_meters);
-            // THE PACE IS DERIVED HERE, because the payload does not carry one.
-            // Moving seconds, not elapsed: standing at the line between reps is
-            // not part of the rep, and the whole app measures pace this way.
-            const secs = l.moving_seconds ?? l.duration_seconds ?? null;
-            const perMile = mi && secs ? secs / mi : null;
-            return {
-                // THE API COUNTS FROM ZERO AND A RUNNER COUNTS FROM ONE. A watch
-                // says "Lap 1" on the first press, so a table headed lap 0 is
-                // describing a different session from the one they remember.
-                lap: (l.index ?? i) + 1,
-                miles: mi,
-                time: duration(secs),
-                pace: perMile
-                    ? `${Math.floor(perMile / 60)}:${String(Math.round(perMile % 60)).padStart(2, "0")}`
-                    : null,
+            const lines = [
+                `**${run.name || "Untitled"}** — ${run.date}`,
+                `${run.miles ?? "—"} mi · ${run.pace_per_mile ?? "—"}/mi · ` +
+                    `${run.moving_time ?? "—"} · ${run.elevation_ft ?? "—"} ft climb`,
+                run.avg_hr ? `Heart rate ${run.avg_hr} avg, ${run.max_hr ?? "—"} max` : "",
+                splits.length
+                    ? `\n| mile | pace | ± ft |\n|---|---|---|\n` +
+                        splits.map((s) => `| ${s.mile} | ${s.pace ?? "—"} | ${s.elevation_change_ft ?? "—"} |`).join("\n")
+                    : "\nNo mile splits recorded for this run.",
+            ].filter(Boolean);
+            return ok(fenced(lines.join("\n")), { run, splits });
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    // ─── The profile ────────────────────────────────────────────────────────────
+    server.registerTool("ourpr_run_stream", {
+        title: "Get a run's elevation and sensor profile",
+        description: "A run's profile on a 10 m grid — elevation, heart rate, power, " +
+            "cadence — as min, average, max and coverage per channel, not every " +
+            "sample. No profile is a normal answer for an indoor run.",
+        inputSchema: {
+            activity_id: z.string().describe("Run id from ourpr_list_runs."),
+        },
+        outputSchema: {
+            grid_m: z.number(),
+            total_miles: z.number(),
+            samples: z.number(),
+            channels: z.record(z.string(), z.unknown()),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async ({ activity_id }) => {
+        try {
+            const s = await get(`/users/me/activities/${pathId(activity_id)}/stream`);
+            // A summary, not the samples: a 10 mile run is about 8,000 numbers.
+            const stats = (values, scale = 1) => {
+                const nums = (values ?? []).filter((v) => v != null);
+                if (!nums.length)
+                    return null;
+                const sum = nums.reduce((a, b) => a + b, 0);
+                return {
+                    min: Math.round((Math.min(...nums) * scale) * 10) / 10,
+                    max: Math.round((Math.max(...nums) * scale) * 10) / 10,
+                    avg: Math.round(((sum / nums.length) * scale) * 10) / 10,
+                    coverage: Math.round((nums.length / (values?.length || 1)) * 100),
+                };
             };
-        });
-        const text = laps.length
-            ? `${laps.length} laps.\n\n| lap | mi | time | pace |\n|---|---|---|---|\n` +
-                laps.map((l) => `| ${l.lap} | ${l.miles ?? "—"} | ${l.time ?? "—"} | ${l.pace ?? "—"} |`).join("\n")
-            : "No laps recorded for this run.";
-        return ok(text, { laps });
-    }
-    catch (err) {
-        return fail(err);
-    }
-});
-// ─── Rep sessions ───────────────────────────────────────────────────────────
-server.registerTool("ourpr_rep_workouts", {
-    title: "Find rep workouts across the history",
-    description: "Interval sessions found across the history, with reps and distances. " +
-        "Detection is conservative, so a session it misses is still in " +
-        "ourpr_list_runs.",
-    inputSchema: {
-        limit: z
-            .number()
-            .int()
-            .min(10)
-            .max(1000)
-            .default(200)
-            .describe("How many recent activities to read."),
-    },
-    outputSchema: {
-        workouts: z.array(z.record(z.string(), z.unknown())),
-        scanned: z.number(),
-    },
-    annotations: { readOnlyHint: true, openWorldHint: true },
-}, async ({ limit }) => {
-    try {
-        const data = await get(`/users/me/activities/rep-workouts?limit=${limit}`);
-        const workouts = (data.workouts ?? []).map((w) => ({
-            activity_id: String(w.activity_id),
-            date: day(w.date),
-            name: cell(w.name),
-            sets: (w.groups ?? []).map((g) => ({
-                reps: g.count,
-                rep_meters: g.rep_meters,
-                times_s: g.times_s ?? null,
-            })),
-        }));
-        // AN EMPTY ANSWER SAYS WHAT WAS READ. "None found" and "none exist" are
-        // different claims, and only the first one is true here.
-        const text = workouts.length
-            ? `${workouts.length} rep sessions in the ${data.scanned} activities read.\n\n` +
-                workouts
-                    .map((w) => `- ${w.date} · ${w.name || "Untitled"} · ` +
-                    w.sets.map((s) => `${s.reps} x ${s.rep_meters}m`).join(", "))
-                    .join("\n")
-            : `No rep sessions in the ${data.scanned} most recent activities. ` +
-                "Raise `limit` to read further back.";
-        return ok(fenced(text), { workouts, scanned: data.scanned });
-    }
-    catch (err) {
-        return fail(err);
-    }
-});
-// ─── Detection on one run ───────────────────────────────────────────────────
-server.registerTool("ourpr_detect_reps", {
-    title: "Look for reps in one run",
-    description: "Whether one particular run was an interval session, and its reps.",
-    inputSchema: {
-        activity_id: z.string().describe("Run id from ourpr_list_runs."),
-    },
-    outputSchema: { detection: z.record(z.string(), z.unknown()) },
-    annotations: { readOnlyHint: true, openWorldHint: true },
-}, async ({ activity_id }) => {
-    try {
-        const detection = await get(`/users/me/activities/${pathId(activity_id)}/workout-detection`);
-        // BOUNDED. This was an unbounded pretty-printed dump, which is the one
-        // shape that can spend an agent's context without anyone choosing to.
-        const json = JSON.stringify(detection);
-        return ok(json.length > 4000
-            ? `${json.slice(0, 4000)}… (truncated; read the structured result)`
-            : json, { detection });
-    }
-    catch (err) {
-        return fail(err);
-    }
-});
-// ─── Terrain ────────────────────────────────────────────────────────────────
-server.registerTool("ourpr_similar_terrain", {
-    title: "Find runs over comparable ground",
-    description: "Stretches of past runs matching a distance and climb — what the " +
-        "runner has already done that resembles a race they are training for.",
-    inputSchema: {
-        miles: z.number().min(0.1).max(200).describe("Target distance in miles."),
-        gain_ft: z.number().min(0).max(30000).describe("Target climb in feet."),
-        limit: z.number().int().min(1).max(25).default(8).describe("How many to return."),
-        tolerance_ft: z
-            .number()
-            .min(1)
-            .max(200)
-            .default(15)
-            .describe("Climb tolerance, feet."),
-    },
-    outputSchema: {
-        matches: z.array(z.record(z.string(), z.unknown())),
-        scanned: z.number(),
-    },
-    annotations: { readOnlyHint: true, openWorldHint: true },
-}, async ({ miles: mi, gain_ft, limit, tolerance_ft }) => {
-    try {
-        const data = await get(`/users/me/terrain/similar?miles=${mi}&gain_ft=${gain_ft}` +
-            `&limit=${limit}&tolerance_ft=${tolerance_ft}`);
-        const matches = data.matches ?? [];
-        const text = matches.length
-            ? `${matches.length} stretches near ${mi} mi with about ${gain_ft} ft ` +
-                `of climb, from ${data.scanned} runs read.\n\n` +
-                "| date | run | from mi | to mi | climb ft | grade |\n|---|---|---|---|---|---|\n" +
-                matches
-                    .map((m) => `| ${m.date.slice(0, 10)} | ${cell(m.name, 28)} | ${m.from_mi} | ` +
-                    `${m.to_mi} | ${m.gain_ft} | ${m.grade_pct}% |`)
-                    .join("\n")
-            : `Nothing near ${mi} mi with about ${gain_ft} ft of climb in the ` +
-                `${data.scanned} runs read. Widen \`tolerance_ft\`.`;
-        return ok(fenced(text), { matches, scanned: data.scanned });
-    }
-    catch (err) {
-        return fail(err);
-    }
-});
-// ─── Start ──────────────────────────────────────────────────────────────────
-async function main() {
-    await server.connect(new StdioServerTransport());
-    // STDERR, ALWAYS. On a stdio server stdout is the protocol stream and one
-    // `console.log` corrupts it.
-    console.error("[ourpr-mcp-server] ready");
+            const channels = {
+                // Stored in centimetres; the app speaks feet.
+                elevation_ft: stats(s.elev_cm, 0.0328084),
+                heart_rate_bpm: stats(s.hr_bpm),
+                power_w: stats(s.power_w),
+                cadence_spm: stats(s.cadence_spm),
+            };
+            const present = Object.entries(channels)
+                .filter(([, v]) => v)
+                .map(([k, v]) => `- ${k}: min ${v.min}, avg ${v.avg}, max ${v.max} (${v.coverage}% of samples)`)
+                .join("\n");
+            const total_miles = miles(s.total_m) ?? 0;
+            return ok(`Profile over ${total_miles} mi, ${s.points} samples every ${s.grid_m} m` +
+                (s.source ? ` (from ${cell(s.source, 24)})` : "") +
+                ".\n\n" +
+                (present || "No sensor channels were recorded for this run."), { grid_m: s.grid_m, total_miles, samples: s.points, channels });
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    // ─── Laps ───────────────────────────────────────────────────────────────────
+    server.registerTool("ourpr_run_laps", {
+        title: "Get a run's laps",
+        description: "The laps the watch recorded for one run — the runner's own button " +
+            "presses. Laps follow the workout; mile splits follow the mile.",
+        inputSchema: {
+            activity_id: z.string().describe("Run id from ourpr_list_runs."),
+        },
+        outputSchema: { laps: z.array(z.record(z.string(), z.unknown())) },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async ({ activity_id }) => {
+        try {
+            const raw = await get(`/users/me/activities/${pathId(activity_id)}/laps`);
+            const laps = raw.map((l, i) => {
+                const mi = miles(l.distance_meters);
+                // The payload carries no pace; moving seconds, as the app measures it.
+                const secs = l.moving_seconds ?? l.duration_seconds ?? null;
+                const perMile = mi && secs ? secs / mi : null;
+                return {
+                    // The API counts from zero; a watch counts from one.
+                    lap: (l.index ?? i) + 1,
+                    miles: mi,
+                    time: duration(secs),
+                    pace: perMile
+                        ? `${Math.floor(perMile / 60)}:${String(Math.round(perMile % 60)).padStart(2, "0")}`
+                        : null,
+                };
+            });
+            const text = laps.length
+                ? `${laps.length} laps.\n\n| lap | mi | time | pace |\n|---|---|---|---|\n` +
+                    laps.map((l) => `| ${l.lap} | ${l.miles ?? "—"} | ${l.time ?? "—"} | ${l.pace ?? "—"} |`).join("\n")
+                : "No laps recorded for this run.";
+            return ok(text, { laps });
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    // ─── Rep sessions ───────────────────────────────────────────────────────────
+    server.registerTool("ourpr_rep_workouts", {
+        title: "Find rep workouts across the history",
+        description: "Interval sessions found across the history, with reps and distances. " +
+            "Detection is conservative, so a session it misses is still in " +
+            "ourpr_list_runs.",
+        inputSchema: {
+            limit: z
+                .number()
+                .int()
+                .min(10)
+                .max(1000)
+                .default(200)
+                .describe("How many recent activities to read."),
+        },
+        outputSchema: {
+            workouts: z.array(z.record(z.string(), z.unknown())),
+            scanned: z.number(),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async ({ limit }) => {
+        try {
+            const data = await get(`/users/me/activities/rep-workouts?limit=${limit}`);
+            const workouts = (data.workouts ?? []).map((w) => ({
+                activity_id: String(w.activity_id),
+                date: day(w.date),
+                name: cell(w.name),
+                sets: (w.groups ?? []).map((g) => ({
+                    reps: g.count,
+                    rep_meters: g.rep_meters,
+                    times_s: g.times_s ?? null,
+                })),
+            }));
+            // "None found" and "none exist" differ; only the first is true here.
+            const text = workouts.length
+                ? `${workouts.length} rep sessions in the ${data.scanned} activities read.\n\n` +
+                    workouts
+                        .map((w) => `- ${w.date} · ${w.name || "Untitled"} · ` +
+                        w.sets.map((s) => `${s.reps} x ${s.rep_meters}m`).join(", "))
+                        .join("\n")
+                : `No rep sessions in the ${data.scanned} most recent activities. ` +
+                    "Raise `limit` to read further back.";
+            return ok(fenced(text), { workouts, scanned: data.scanned });
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    // ─── Detection on one run ───────────────────────────────────────────────────
+    server.registerTool("ourpr_detect_reps", {
+        title: "Look for reps in one run",
+        description: "Whether one particular run was an interval session, and its reps.",
+        inputSchema: {
+            activity_id: z.string().describe("Run id from ourpr_list_runs."),
+        },
+        outputSchema: { detection: z.record(z.string(), z.unknown()) },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async ({ activity_id }) => {
+        try {
+            const detection = await get(`/users/me/activities/${pathId(activity_id)}/workout-detection`);
+            // Bounded, so a dump cannot spend the agent's context.
+            const json = JSON.stringify(detection);
+            return ok(json.length > 4000
+                ? `${json.slice(0, 4000)}… (truncated; read the structured result)`
+                : json, { detection });
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    // ─── Terrain ────────────────────────────────────────────────────────────────
+    server.registerTool("ourpr_similar_terrain", {
+        title: "Find runs over comparable ground",
+        description: "Stretches of past runs matching a distance and climb — what the " +
+            "runner has already done that resembles a race they are training for.",
+        inputSchema: {
+            miles: z.number().min(0.1).max(200).describe("Target distance in miles."),
+            gain_ft: z.number().min(0).max(30000).describe("Target climb in feet."),
+            limit: z.number().int().min(1).max(25).default(8).describe("How many to return."),
+            tolerance_ft: z
+                .number()
+                .min(1)
+                .max(200)
+                .default(15)
+                .describe("Climb tolerance, feet."),
+        },
+        outputSchema: {
+            matches: z.array(z.record(z.string(), z.unknown())),
+            scanned: z.number(),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async ({ miles: mi, gain_ft, limit, tolerance_ft }) => {
+        try {
+            const data = await get(`/users/me/terrain/similar?miles=${mi}&gain_ft=${gain_ft}` +
+                `&limit=${limit}&tolerance_ft=${tolerance_ft}`);
+            const matches = data.matches ?? [];
+            const text = matches.length
+                ? `${matches.length} stretches near ${mi} mi with about ${gain_ft} ft ` +
+                    `of climb, from ${data.scanned} runs read.\n\n` +
+                    "| date | run | from mi | to mi | climb ft | grade |\n|---|---|---|---|---|---|\n" +
+                    matches
+                        .map((m) => `| ${m.date.slice(0, 10)} | ${cell(m.name, 28)} | ${m.from_mi} | ` +
+                        `${m.to_mi} | ${m.gain_ft} | ${m.grade_pct}% |`)
+                        .join("\n")
+                : `Nothing near ${mi} mi with about ${gain_ft} ft of climb in the ` +
+                    `${data.scanned} runs read. Widen \`tolerance_ft\`.`;
+            return ok(fenced(text), { matches, scanned: data.scanned });
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    // ─── Blocks and races ───────────────────────────────────────────────────────
+    server.registerTool("ourpr_training_blocks", {
+        title: "Get the goal race and training blocks",
+        description: "The goal race and its Block: race day, distance, goal time, which " +
+            "week of the Block today falls in, and miles for each week. Also the " +
+            "Blocks before past races, each with its result, weeks and peak week. " +
+            "A Block is the race-anchored Monday to Sunday weeks before a race.",
+        inputSchema: {
+            past: z
+                .number()
+                .int()
+                .min(0)
+                .max(30)
+                .default(3)
+                .describe("How many past Blocks to include, newest first."),
+        },
+        outputSchema: {
+            goal: z.record(z.string(), z.unknown()).nullable(),
+            past: z.array(z.record(z.string(), z.unknown())),
+            total_races: z.number(),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async ({ past }) => {
+        try {
+            const data = await get("/users/me/race-arcs");
+            const arcs = data.arcs ?? [];
+            const today = localDay(new Date());
+            const goalArc = arcs.find((a) => a.is_goal) ?? null;
+            let goal = null;
+            let goalText = "No goal race is set in ourpr.";
+            if (goalArc) {
+                const now = weekOf(goalArc.arc_start, goalArc.arc_weeks, today);
+                const weeks = goalArc.weekly_mileage.map((w, i) => {
+                    const begins = addDays(goalArc.arc_start, i * 7);
+                    // A week not yet begun has no miles to report, not zero miles.
+                    const ahead = begins > today;
+                    return {
+                        week: i + 1,
+                        begins,
+                        miles: ahead ? null : w.miles,
+                        runs: ahead ? null : w.runs,
+                        is_now: i + 1 === now,
+                    };
+                });
+                goal = {
+                    race: cell(goalArc.race_name),
+                    race_date: day(goalArc.race_date),
+                    distance: goalArc.distance_category,
+                    goal_time: goalArc.finish_time || null,
+                    block_weeks: goalArc.arc_weeks,
+                    week_now: now,
+                    block_start: goalArc.arc_start,
+                    weeks,
+                };
+                const where = now === 0
+                    ? `The Block opens on ${goalArc.arc_start}.`
+                    : `Today is in week ${now} of ${goalArc.arc_weeks}.`;
+                goalText =
+                    `Goal: ${goal.race || "Untitled"}, ${goalArc.distance_category}, ` +
+                        `race day ${goal.race_date}, goal time ${goal.goal_time ?? "not set"}. ${where}\n\n` +
+                        "| week | begins | mi | runs |\n|---|---|---|---|\n" +
+                        weeks
+                            .map((w) => `| ${w.week}${w.is_now ? " (now)" : ""} | ${w.begins} | ` +
+                            `${w.miles ?? "—"} | ${w.runs ?? "—"} |`)
+                            .join("\n");
+            }
+            const done = arcs
+                .filter((a) => !a.is_goal)
+                .sort((a, b) => b.race_date.localeCompare(a.race_date))
+                .slice(0, past)
+                .map((a) => ({
+                race: cell(a.race_name),
+                race_date: day(a.race_date),
+                distance: a.distance_category,
+                result: a.finish_time || null,
+                block_weeks: a.arc_weeks,
+                total_miles: a.total_miles,
+                total_runs: a.total_runs,
+                peak_week_miles: Math.max(0, ...a.weekly_mileage.map((w) => w.miles)),
+                tune_ups: a.tune_ups.map((t) => ({
+                    race: cell(t.race_name),
+                    race_date: day(t.race_date),
+                    distance: t.distance_category,
+                    result: t.finish_time || null,
+                })),
+            }));
+            const pastText = done.length
+                ? `\n\nPast Blocks, newest first:\n\n` +
+                    "| race | date | distance | result | weeks | mi | peak week mi | runs |\n" +
+                    "|---|---|---|---|---|---|---|---|\n" +
+                    done
+                        .map((b) => `| ${b.race || "Untitled"} | ${b.race_date} | ${b.distance} | ` +
+                        `${b.result ?? "—"} | ${b.block_weeks} | ${b.total_miles} | ` +
+                        `${b.peak_week_miles} | ${b.total_runs} |`)
+                        .join("\n")
+                : "";
+            return ok(fenced(goalText + pastText), {
+                goal,
+                past: done,
+                total_races: data.total_races,
+            });
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    // The distances a race result compares across; an ultra varies too much.
+    const FIXED_DISTANCES = ["5K", "10K", "Half Marathon", "Marathon"];
+    server.registerTool("ourpr_list_races", {
+        title: "List the races in the history",
+        description: "Every race ourpr finds in the history, newest first, tune-ups " +
+            "included: date, name, distance, time, pace and run id. Also the " +
+            "fastest result at 5K, 10K, half marathon and marathon among them.",
+        inputSchema: {
+            distance: z
+                .enum(["5K", "10K", "Half Marathon", "Marathon", "Ultra"])
+                .optional()
+                .describe("Only races at this distance."),
+            limit: z.number().int().min(1).max(500).default(50).describe("Most rows to return."),
+        },
+        outputSchema: {
+            races: z.array(z.record(z.string(), z.unknown())),
+            fastest: z.array(z.record(z.string(), z.unknown())),
+            returned: z.number(),
+            total: z.number(),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async ({ distance, limit }) => {
+        try {
+            const data = await get("/users/me/races");
+            const all = (data.races ?? [])
+                .filter((r) => !distance || r.distance_category === distance)
+                .map((r) => ({
+                activity_id: String(r.activity_id),
+                date: day(r.date),
+                name: cell(r.name),
+                distance: r.distance_category,
+                miles: r.distance_miles,
+                time: clock(r.duration_seconds),
+                seconds: r.duration_seconds || null,
+                pace_per_mile: r.pace_per_mile ?? null,
+            }));
+            const fastest = FIXED_DISTANCES.flatMap((d) => {
+                const timed = all.filter((r) => r.distance === d && r.seconds);
+                if (!timed.length)
+                    return [];
+                const best = timed.reduce((a, b) => (b.seconds < a.seconds ? b : a));
+                return [{ distance: d, time: best.time, date: best.date, activity_id: best.activity_id }];
+            });
+            const shown = all.slice(0, limit);
+            const head = `${all.length} races${distance ? ` at ${distance}` : ""}.` +
+                (all.length > shown.length
+                    ? ` Showing the ${shown.length} newest; raise \`limit\` to see the rest.`
+                    : "") +
+                (fastest.length
+                    ? "\nFastest: " + fastest.map((f) => `${f.distance} ${f.time} (${f.date})`).join(", ") + "."
+                    : "");
+            const body = shown.length
+                ? "| date | race | distance | mi | time | pace | id |\n|---|---|---|---|---|---|---|\n" +
+                    shown
+                        .map((r) => `| ${r.date} | ${r.name || "Race"} | ${r.distance} | ${r.miles} | ` +
+                        `${r.time ?? "—"} | ${r.pace_per_mile ?? "—"} | ${r.activity_id} |`)
+                        .join("\n")
+                : "No races found.";
+            return ok(fenced(`${head}\n\n${body}`), {
+                races: shown,
+                fastest,
+                returned: shown.length,
+                total: all.length,
+            });
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    // ─── The week ───────────────────────────────────────────────────────────────
+    // The list route answers at most this many plans.
+    const PLAN_PAGE = 200;
+    server.registerTool("ourpr_list_plans", {
+        title: "List planned runs in a date range",
+        description: "The runner's planned runs between two dates: day, name, miles, time, " +
+            "tag, the runner's note, whether a logged run fulfilled it, and " +
+            "whether ourpr create wrote it. Read it before ourpr_plan_week so a " +
+            "new plan does not land on a day that already holds one.",
+        inputSchema: {
+            start_date: z
+                .string()
+                .regex(/^\d{4}-\d{2}-\d{2}$/)
+                .optional()
+                .describe("First day, YYYY-MM-DD. Default today."),
+            end_date: z
+                .string()
+                .regex(/^\d{4}-\d{2}-\d{2}$/)
+                .optional()
+                .describe("Last day, YYYY-MM-DD. Default 13 days after the first."),
+        },
+        outputSchema: {
+            plans: z.array(z.record(z.string(), z.unknown())),
+            start_date: z.string(),
+            end_date: z.string(),
+            truncated: z.boolean(),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async ({ start_date, end_date }) => {
+        try {
+            const start = start_date ?? localDay(new Date());
+            const end = end_date ?? addDays(start, 13);
+            const rows = await get(`/users/me/planned-activities?start=${start}&end=${end}`);
+            const plans = rows.map((p) => ({
+                id: String(p.id),
+                date: day(p.planned_date),
+                type: cell(p.activity_type, 24) || "Run",
+                name: cell(p.name),
+                miles: miles(p.distance_meters),
+                time: duration(p.duration_seconds),
+                tag: p.tag ?? null,
+                is_long: p.is_long,
+                note: note(p.note),
+                done_by_run: p.completed_activity_id ?? null,
+                from_ourpr_create: p.source === "token",
+            }));
+            const truncated = rows.length >= PLAN_PAGE;
+            const head = `${plans.length} plans between ${start} and ${end}.` +
+                (truncated ? " ourpr returns at most 200; narrow the dates to see the rest." : "");
+            const body = plans.length
+                ? "| date | name | type | mi | time | tag | done | note |\n|---|---|---|---|---|---|---|---|\n" +
+                    plans
+                        .map((p) => `| ${p.date} | ${p.name || "—"} | ${p.type} | ${p.miles ?? "—"} | ` +
+                        `${p.time ?? "—"} | ${p.tag ?? "—"}${p.is_long ? " · long" : ""} | ` +
+                        `${p.done_by_run ? "yes" : "no"} | ${p.note || "—"} |`)
+                        .join("\n")
+                : "No plans in that window.";
+            return ok(fenced(`${head}\n\n${body}`), { plans, start_date: start, end_date: end, truncated });
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    const PLAN_TAGS = ["easy", "workout", "race"];
+    server.registerTool("ourpr_plan_week", {
+        title: "Put runs on the runner's week",
+        description: "Write one planned run, or a week of them, onto days still ahead. Each " +
+            "lands on the runner's week as a plan they can see, edit and remove. " +
+            "Needs a token made with the write scope and ourpr create. " +
+            "Never logs a run.",
+        inputSchema: {
+            plans: z
+                .array(z.object({
+                date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).describe("YYYY-MM-DD, after today."),
+                miles: z.number().min(0.1).max(200).optional().describe("Planned distance."),
+                minutes: z.number().min(1).max(1440).optional().describe("Planned time."),
+                name: z.string().max(120).optional().describe("A short name for the run."),
+                note: z.string().max(500).optional().describe("A line the runner will read."),
+                tag: z.enum(PLAN_TAGS).optional().describe("How hard: easy, workout or race."),
+                is_long: z.boolean().optional().describe("The week's long run."),
+            }))
+                .min(1)
+                .max(14)
+                .describe("One run, or up to fourteen."),
+        },
+        outputSchema: {
+            written: z.array(z.record(z.string(), z.unknown())),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+    }, async ({ plans }) => {
+        try {
+            const body = {
+                plans: plans.map((p) => ({
+                    planned_date: p.date,
+                    distance_meters: p.miles == null ? null : Math.round(p.miles * METERS_PER_MILE),
+                    duration_seconds: p.minutes == null ? null : Math.round(p.minutes * 60),
+                    name: p.name ?? null,
+                    note: p.note ?? null,
+                    tag: p.tag ?? null,
+                    is_long: p.is_long ?? false,
+                })),
+            };
+            const rows = await post("/users/me/planned-activities/week", body);
+            const written = rows.map((r) => ({
+                id: String(r.id),
+                date: day(r.planned_date),
+                name: cell(r.name),
+                miles: miles(r.distance_meters),
+                time: duration(r.duration_seconds),
+                tag: r.tag ?? null,
+                is_long: r.is_long,
+            }));
+            const text = `${written.length} plan${written.length === 1 ? "" : "s"} on the runner's week.\n\n` +
+                "| date | name | mi | time | tag |\n|---|---|---|---|---|\n" +
+                written
+                    .map((w) => `| ${w.date} | ${w.name || "—"} | ${w.miles ?? "—"} | ${w.time ?? "—"} | ` +
+                    `${w.tag ?? "—"}${w.is_long ? " · long" : ""} |`)
+                    .join("\n");
+            return ok(text, { written });
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    return server;
 }
-main().catch((err) => {
-    console.error("[ourpr-mcp-server] fatal:", err);
-    process.exit(1);
+// ─── Start ──────────────────────────────────────────────────────────────────
+// Both eras: 2026-07-28 per request, and the 2025 handshake for older clients.
+serveStdio(buildServer, {
+    onerror: (err) => console.error("[ourpr-mcp-server] error:", err.message),
 });
+// Stdout is the protocol stream; diagnostics go to stderr.
+console.error("[ourpr-mcp-server] ready");