ergzone-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mauro Malvestio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# ergzone-mcp
+
+Unofficial MCP server for [ErgZone](https://www.erg.zone) (Concept2 rowing). Manage workouts, results and stats from your AI assistant. **Zero install, zero dependencies** — runs from GitHub via `npx` (Node ≥ 18).
+
+> Not affiliated with ErgZone / Concept2. Personal use.
+
+## Setup
+
+You need a Concept2 Logbook account (the one you use on log.concept2.com).
+
+**Claude Code:**
+
+```bash
+claude mcp add ergzone \
+  -e ERGZONE_LOGBOOK_EMAIL=you@example.com \
+  -e ERGZONE_LOGBOOK_PASSWORD=yourpassword \
+  -- npx -y github:malveo/ergzone-mcp
+```
+
+**Claude Desktop** — add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "ergzone": {
+      "command": "npx",
+      "args": ["-y", "github:malveo/ergzone-mcp"],
+      "env": {
+        "ERGZONE_LOGBOOK_EMAIL": "you@example.com",
+        "ERGZONE_LOGBOOK_PASSWORD": "yourpassword"
+      }
+    }
+  }
+}
+```
+
+The server logs in for you and caches the token (`~/.config/ergzone-mcp/`, refreshed on expiry).
+Prefer not to store your password? Use `ERGZONE_SESSION_TOKEN` instead (copied from
+`localStorage.SESSION_TOKEN` on admin.erg.zone).
+
+## Tools
+
+| Tool | What it does |
+|------|------|
+| `auth_check` | who am I |
+| `list_workouts` / `get_workout` | browse workouts |
+| `create_workout` / `update_workout` / `delete_workout` | manage workouts |
+| `build_intervals` | preview intervals before saving |
+| `list_my_results` / `get_result` | your sessions + telemetry |
+| `my_stats` / `analyze_result` | totals, HR zones, pace/SPI per interval |
+
+Ask in plain language, e.g. *"create an SPM ladder 16 to 30"* or *"analyze my last result"*.
+
+## Settings
+
+| Var | Notes |
+|-----|------|
+| `ERGZONE_LOGBOOK_EMAIL` + `ERGZONE_LOGBOOK_PASSWORD` | auto-login (recommended) |
+| `ERGZONE_SESSION_TOKEN` | alternative to the two above |
+| `ERGZONE_TRACK_ID` | default workout list (optional) |
+| `ERGZONE_ALLOW_WRITE` | `false` = read-only |
+
+## Notes
+
+Auto-login stores your Logbook password and replicates the Logbook sign-in, so it may break if
+Concept2 changes that page, and automating login may be against their Terms of Service.
+
+Works on macOS, Linux and Windows (Node ≥ 18.7). On Windows the `npx github:...` form needs
+[Git](https://git-scm.com) installed; the token cache lives under `%APPDATA%\ergzone-mcp`.
+
+MIT licensed.

package/bin/ergzone-mcp.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { serve } from '../src/mcp.mjs';
+
+serve();

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "ergzone-mcp",
+  "version": "1.0.0",
+  "description": "Unofficial MCP server for ErgZone (Concept2 rowing). Zero runtime dependencies.",
+  "type": "module",
+  "bin": {
+    "ergzone-mcp": "./bin/ergzone-mcp.mjs"
+  },
+  "engines": {
+    "node": ">=18.7"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node bin/ergzone-mcp.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/malveo/ergzone-mcp.git"
+  },
+  "homepage": "https://github.com/malveo/ergzone-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/malveo/ergzone-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ergzone",
+    "concept2",
+    "rowing",
+    "erg"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/auth.mjs

@@ -0,0 +1,220 @@
+// Headless ErgZone login via Concept2 Logbook credentials.
+// Pure Node fetch, zero dependencies. Small composable functions so the flow is
+// easy to follow and to patch if ErgZone changes a single step.
+//
+// Flow (verified):
+//   1. GET  log.concept2.com/login            -> CSRF _token + session cookie
+//   2. POST log.concept2.com/login            -> authenticated session
+//   3. GET  log.concept2.com/oauth/authorize  -> consent page + CSRF _token
+//   4. POST log.concept2.com/oauth/authorize  -> 302 callback?code=...
+//   5. GET  production.erg.zone/auth/logbook/callback?code -> session_id (the SESSION_TOKEN)
+
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync, rmSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+// --- configuration (ErgZone's public OAuth client) ---
+
+export const AUTH_CONFIG = {
+  c2Base: 'https://log.concept2.com',
+  ergApi: 'https://production.erg.zone/api',
+  clientId: 'RDj8SvdqKgPdKAMcDQAuwLjIIOPCYrjHG9tJrqpJ',
+  redirectUri: 'https://production.erg.zone/auth/logbook/callback',
+  scope: 'user:read,results:write',
+  userAgent: 'ergzone-mcp',
+};
+
+export function authorizeUrl(cfg = AUTH_CONFIG) {
+  const q = new URLSearchParams({
+    client_id: cfg.clientId,
+    redirect_uri: cfg.redirectUri,
+    response_type: 'code',
+    scope: cfg.scope,
+  });
+  return `${cfg.c2Base}/oauth/authorize?${q}`;
+}
+
+// --- cookie jar (per-host, in memory) ---
+
+export function createJar() {
+  return { hosts: {} };
+}
+
+function hostOf(url) {
+  return new URL(url).host;
+}
+
+export function storeCookies(jar, url, res) {
+  const host = hostOf(url);
+  const bag = (jar.hosts[host] ||= {});
+  const list = typeof res.headers.getSetCookie === 'function'
+    ? res.headers.getSetCookie()
+    : [res.headers.get('set-cookie')].filter(Boolean);
+  for (const cookie of list) {
+    const [pair] = cookie.split(';');
+    const eq = pair.indexOf('=');
+    if (eq > 0) bag[pair.slice(0, eq).trim()] = pair.slice(eq + 1).trim();
+  }
+}
+
+export function cookieHeader(jar, url) {
+  const bag = jar.hosts[hostOf(url)] || {};
+  return Object.entries(bag).map(([k, v]) => `${k}=${v}`).join('; ');
+}
+
+// One request with the jar, manual redirects (so we can read Location).
+export async function jarFetch(jar, url, opts = {}) {
+  const headers = {
+    'User-Agent': AUTH_CONFIG.userAgent,
+    Accept: 'text/html,application/json',
+    ...(opts.headers || {}),
+  };
+  const cookie = cookieHeader(jar, url);
+  if (cookie) headers.Cookie = cookie;
+  const res = await fetch(url, { ...opts, headers, redirect: 'manual' });
+  storeCookies(jar, url, res);
+  return res;
+}
+
+// --- HTML parsing helpers (no DOM, regex on simple Laravel forms) ---
+
+export function hiddenInput(html, name) {
+  const re = new RegExp(`<input[^>]*name=["']${name}["'][^>]*>`, 'i');
+  const tag = html.match(re)?.[0] || '';
+  return tag.match(/value=["']([^"']*)["']/i)?.[1] ?? null;
+}
+
+export function formAction(html, matcher) {
+  const re = new RegExp(`<form[^>]*action=["']([^"']*${matcher}[^"']*)["']`, 'i');
+  return html.match(re)?.[1]?.replace(/&amp;/g, '&') ?? null;
+}
+
+export class AuthError extends Error {
+  constructor(message, step) {
+    super(message);
+    this.name = 'AuthError';
+    this.step = step;
+  }
+}
+
+// --- individual steps ---
+
+// 1+2: authenticate against Concept2 Logbook. Mutates the jar with the session cookie.
+export async function logbookSignIn(jar, { email, password }, cfg = AUTH_CONFIG) {
+  const loginUrl = `${cfg.c2Base}/login`;
+  const page = await jarFetch(jar, loginUrl);
+  const html = await page.text();
+  const token = hiddenInput(html, '_token');
+  if (!token) throw new AuthError('CSRF token not found on login page', 'login-page');
+
+  const body = new URLSearchParams({ _token: token, username: email, password, remember: '1' });
+  const res = await jarFetch(jar, loginUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded', Referer: loginUrl },
+    body: body.toString(),
+  });
+  if (res.status !== 302) {
+    throw new AuthError('Logbook sign-in failed (wrong credentials, captcha, or form change)', 'login-post');
+  }
+  return true;
+}
+
+// 3+4: approve the ErgZone OAuth consent, return the authorization code.
+export async function authorizeErgZone(jar, cfg = AUTH_CONFIG) {
+  const url = authorizeUrl(cfg);
+  const page = await jarFetch(jar, url);
+
+  // Already consented in this session -> immediate 302 with the code.
+  if (page.status === 302) {
+    const code = new URL(page.headers.get('location'), cfg.c2Base).searchParams.get('code');
+    if (code) return code;
+  }
+
+  const html = await page.text();
+  const token = hiddenInput(html, '_token');
+  if (!token) throw new AuthError('CSRF token not found on consent page', 'consent-page');
+  const action = formAction(html, 'authorize') || url;
+
+  const body = new URLSearchParams({ _token: token, approve: 'Approve Erg Zone' });
+  const res = await jarFetch(jar, action, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded', Referer: url },
+    body: body.toString(),
+  });
+  if (res.status !== 302) throw new AuthError('OAuth approve did not redirect', 'consent-post');
+
+  const code = new URL(res.headers.get('location'), cfg.c2Base).searchParams.get('code');
+  if (!code) throw new AuthError('No authorization code in callback redirect', 'consent-post');
+  return code;
+}
+
+// 5: exchange the code at the ErgZone callback, return the session token.
+export async function exchangeCode(jar, code, cfg = AUTH_CONFIG) {
+  const res = await jarFetch(jar, `${cfg.redirectUri}?code=${encodeURIComponent(code)}`);
+  const text = await res.text();
+  // Webview callback embeds: ...postMessage(JSON.stringify({session_id:'SFMyNTY...'}))
+  const token = text.match(/session_id\s*:\s*['"](SFMyNTY[^'"]+)['"]/)?.[1]
+    || text.match(/\/auth\/(SFMyNTY[^/?#"'\\\s]+)/)?.[1];
+  if (!token) throw new AuthError('Session token not found in callback response', 'callback');
+  return token;
+}
+
+// Full chain: credentials -> session token.
+export async function loginWithLogbook({ email, password }, cfg = AUTH_CONFIG) {
+  if (!email || !password) throw new AuthError('Missing Logbook email/password', 'config');
+  const jar = createJar();
+  await logbookSignIn(jar, { email, password }, cfg);
+  const code = await authorizeErgZone(jar, cfg);
+  return exchangeCode(jar, code, cfg);
+}
+
+// --- token cache (file, 0600) ---
+
+export function cacheDir() {
+  // Platform-aware base: %APPDATA% on Windows, XDG/~/.config elsewhere.
+  const base = process.platform === 'win32'
+    ? (process.env.APPDATA || join(homedir(), 'AppData', 'Roaming'))
+    : (process.env.XDG_CONFIG_HOME || join(homedir(), '.config'));
+  return join(base, 'ergzone-mcp');
+}
+
+export function cachePath(email) {
+  const tag = email ? createHash('sha256').update(email).digest('hex').slice(0, 12) : 'default';
+  return join(cacheDir(), `token-${tag}`);
+}
+
+export function readCachedToken(email) {
+  const file = cachePath(email);
+  try {
+    const t = readFileSync(file, 'utf8').trim();
+    return t || null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeCachedToken(email, token) {
+  const dir = cacheDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+  writeFileSync(cachePath(email), token, { mode: 0o600 });
+}
+
+export function clearCachedToken(email) {
+  try {
+    rmSync(cachePath(email));
+  } catch {
+    /* ignore */
+  }
+}
+
+// Cached token if present, else a fresh login. force=true bypasses the cache.
+export async function getSessionToken({ email, password, force = false }, cfg = AUTH_CONFIG) {
+  if (!force) {
+    const cached = readCachedToken(email);
+    if (cached) return cached;
+  }
+  const token = await loginWithLogbook({ email, password }, cfg);
+  writeCachedToken(email, token);
+  return token;
+}

package/src/client.mjs

@@ -0,0 +1,111 @@
+// GraphQL client for ErgZone. Zero dependencies: uses the global fetch (Node >=18).
+// Token resolution order:
+//   1. ERGZONE_SESSION_TOKEN (explicit, used as-is)
+//   2. ERGZONE_LOGBOOK_EMAIL + ERGZONE_LOGBOOK_PASSWORD (headless auto-login, cached)
+// On an auth failure with Logbook credentials, the token is refreshed once and the call retried.
+
+import { getSessionToken, clearCachedToken, AuthError } from './auth.mjs';
+
+const ENDPOINT = process.env.ERGZONE_ENDPOINT || 'https://production.erg.zone/api';
+
+const EXPLICIT_TOKEN = process.env.ERGZONE_SESSION_TOKEN || null;
+const LOGBOOK = {
+  email: process.env.ERGZONE_LOGBOOK_EMAIL || null,
+  password: process.env.ERGZONE_LOGBOOK_PASSWORD || null,
+};
+
+export const DEFAULT_TRACK_ID = process.env.ERGZONE_TRACK_ID || '';
+export const WRITE_ENABLED = process.env.ERGZONE_ALLOW_WRITE !== 'false';
+
+// Normalized error: kind = config | network | auth | infra | graphql
+export class ErgzoneError extends Error {
+  constructor(message, { kind = 'graphql', detail } = {}) {
+    super(message);
+    this.name = 'ErgzoneError';
+    this.kind = kind;
+    this.detail = detail;
+  }
+}
+
+const hasLogbook = () => Boolean(LOGBOOK.email && LOGBOOK.password);
+
+let cachedToken = EXPLICIT_TOKEN;
+
+// Resolve a usable session token. force=true triggers a fresh Logbook login.
+async function resolveToken(force = false) {
+  if (EXPLICIT_TOKEN) return EXPLICIT_TOKEN;
+  if (!hasLogbook()) {
+    throw new ErgzoneError(
+      'No credentials: set ERGZONE_SESSION_TOKEN, or ERGZONE_LOGBOOK_EMAIL + ERGZONE_LOGBOOK_PASSWORD.',
+      { kind: 'config' },
+    );
+  }
+  if (force) clearCachedToken(LOGBOOK.email);
+  if (!cachedToken || force) {
+    try {
+      cachedToken = await getSessionToken({ ...LOGBOOK, force });
+    } catch (e) {
+      if (e instanceof AuthError) throw new ErgzoneError(`Login failed: ${e.message}`, { kind: 'auth', detail: e.step });
+      throw e;
+    }
+  }
+  return cachedToken;
+}
+
+// Single GraphQL POST with a given token. Returns { data } or throws ErgzoneError.
+async function postGraphQL(token, query, variables) {
+  let res;
+  try {
+    res = await fetch(ENDPOINT, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ query, variables }),
+    });
+  } catch (e) {
+    throw new ErgzoneError(`Network error: ${e.message}`, { kind: 'network' });
+  }
+
+  const text = await res.text();
+  let json;
+  try {
+    json = JSON.parse(text);
+  } catch {
+    // ErgZone returns HTML (non-JSON) when the token is expired or on infra errors.
+    if (res.status === 401 || res.status === 403 || /login|sign\s*in/i.test(text)) {
+      throw new ErgzoneError('Token expired or invalid.', { kind: 'auth', detail: `HTTP ${res.status}` });
+    }
+    throw new ErgzoneError(`Non-JSON response (HTTP ${res.status}).`, { kind: 'infra', detail: text.slice(0, 200) });
+  }
+
+  if (json.errors && json.errors.length) {
+    throw new ErgzoneError(json.errors.map((e) => e.message).join('; '), { kind: 'graphql', detail: json.errors });
+  }
+  return json.data;
+}
+
+export async function gql(query, variables = {}) {
+  const token = await resolveToken(false);
+  try {
+    return await postGraphQL(token, query, variables);
+  } catch (e) {
+    // Refresh once on auth failure, but only when we can re-login (Logbook creds present).
+    if (e instanceof ErgzoneError && e.kind === 'auth' && !EXPLICIT_TOKEN && hasLogbook()) {
+      const fresh = await resolveToken(true);
+      return postGraphQL(fresh, query, variables);
+    }
+    if (e instanceof ErgzoneError && e.kind === 'auth' && EXPLICIT_TOKEN) {
+      throw new ErgzoneError(
+        'Token expired or invalid. Update ERGZONE_SESSION_TOKEN, or switch to ERGZONE_LOGBOOK_EMAIL/PASSWORD for auto-login.',
+        { kind: 'auth' },
+      );
+    }
+    throw e;
+  }
+}
+
+// Today's date as a Date scalar "YYYY-MM-DD".
+export function todayISO() {
+  const d = new Date();
+  const p = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}

package/src/intervals.mjs

@@ -0,0 +1,183 @@
+// Interval builder and validation for ErgZone.
+// Hides the complexity of the "suggested*" fields (intensity / relative target pace):
+//   - suggestedPaceBenchmarkGroup: "INTERVAL" (ref another interval) | "A"/"B"... (PR benchmark)
+//   - suggestedInterval: 0-based index of the referenced interval (< current position)
+//   - suggestedOperator: ONLY "+" (the sign goes into the pace)
+//   - suggestedPace: offset sec/500m (negative = faster)
+
+// "M:SS" or seconds (number/string) => integer seconds.
+export function parseDuration(v) {
+  if (typeof v === 'number') return Math.round(v);
+  if (typeof v === 'string') {
+    const s = v.trim();
+    const m = s.match(/^(\d+):(\d{1,2})$/);
+    if (m) return Number(m[1]) * 60 + Number(m[2]);
+    if (/^\d+(\.\d+)?$/.test(s)) return Math.round(Number(s));
+  }
+  throw new Error(`Invalid duration: ${JSON.stringify(v)} (use "M:SS" or seconds)`);
+}
+
+// A high-level "segment" -> GraphQL IntervalInput.
+// Segment fields:
+//   time | work : duration ("M:SS"/sec)        (default if no distance/cals)
+//   distance    : meters                        -> type "distance"
+//   cals        : calories                      -> type "cals"
+//   spm, spmMax : target stroke rate
+//   rest        : rest after the interval ("M:SS"/sec)
+//   undefRest   : bool (open/undefined rest)
+//   notes, restNotes
+//   fasterThanPrev : N  -> N sec/500m faster than the previous interval
+//   fasterThan     : { interval: <1-based>, seconds: N }  -> relative to a specific interval
+//   benchmark      : { group: "A", offset: N }  -> relative to a PR benchmark (signed offset)
+function segmentToInterval(seg, idx) {
+  const iv = { undefRest: !!seg.undefRest };
+
+  if (seg.distance != null) {
+    iv.type = 'distance';
+    iv.value = Math.round(seg.distance);
+  } else if (seg.cals != null) {
+    iv.type = 'cals';
+    iv.value = Math.round(seg.cals);
+  } else {
+    iv.type = 'time';
+    iv.value = parseDuration(seg.time ?? seg.work);
+  }
+
+  if (seg.spm != null) iv.spm = seg.spm;
+  if (seg.spmMax != null) iv.spmMax = seg.spmMax;
+  if (seg.rest != null) iv.rest = parseDuration(seg.rest);
+  if (seg.notes) iv.notes = seg.notes;
+  if (seg.restNotes) iv.restNotes = seg.restNotes;
+
+  // Intensity
+  if (seg.fasterThanPrev != null) {
+    if (idx === 0) throw new Error('fasterThanPrev is invalid on the first interval (no previous one)');
+    iv.suggestedPaceBenchmarkGroup = 'INTERVAL';
+    iv.suggestedInterval = idx - 1;
+    iv.suggestedOperator = '+';
+    iv.suggestedPace = -Math.abs(seg.fasterThanPrev);
+  } else if (seg.fasterThan) {
+    const ref0 = Number(seg.fasterThan.interval) - 1; // 1-based human -> 0-based
+    if (!(ref0 >= 0) || ref0 >= idx) {
+      throw new Error(`fasterThan.interval must reference a previous interval (1..${idx})`);
+    }
+    iv.suggestedPaceBenchmarkGroup = 'INTERVAL';
+    iv.suggestedInterval = ref0;
+    iv.suggestedOperator = '+';
+    iv.suggestedPace = -Math.abs(seg.fasterThan.seconds);
+  } else if (seg.benchmark) {
+    iv.suggestedPaceBenchmarkGroup = String(seg.benchmark.group);
+    iv.suggestedOperator = '+';
+    iv.suggestedPace = Number(seg.benchmark.offset);
+  }
+
+  return iv;
+}
+
+export function buildIntervals(segments) {
+  if (!Array.isArray(segments) || segments.length === 0) {
+    throw new Error('segments is empty or invalid');
+  }
+  return segments.map((s, i) => segmentToInterval(s, i));
+}
+
+// --- High-level recipes ---
+
+// SPM ladder: e.g. ladder({spmStart:16, spmEnd:30}) -> 16/17, 18/19, ... 30/31, each 1' rest 20s.
+export function ladder({
+  spmStart = 16,
+  spmEnd = 30,
+  step = 2,
+  pairWidth = 1,
+  work = '1:00',
+  rest = '0:20',
+  lastRest = false,
+} = {}) {
+  const segs = [];
+  for (let s = spmStart; s <= spmEnd; s += step) {
+    const seg = { time: work, spm: s, rest };
+    if (pairWidth) seg.spmMax = s + pairWidth;
+    segs.push(seg);
+  }
+  if (!lastRest && segs.length) delete segs[segs.length - 1].rest;
+  return buildIntervals(segs);
+}
+
+// Over/under: base + surge blocks. blocks:[{baseWork,baseSpm,surgeWork,surgeSpm}].
+export function overUnder({ blocks = [], restBetween = '1:00' } = {}) {
+  if (!blocks.length) throw new Error('overUnder: blocks is empty');
+  const segs = [];
+  blocks.forEach((b, i) => {
+    segs.push({ time: b.baseWork, spm: b.baseSpm });
+    const surge = { time: b.surgeWork, spm: b.surgeSpm };
+    if (i < blocks.length - 1) surge.rest = restBetween;
+    segs.push(surge);
+  });
+  return buildIntervals(segs);
+}
+
+// Progressive intensity: each block repeats a pattern of durations; the first interval
+// of every block is "free" (no target), the others are -faster sec/500m vs the previous one.
+export function progressiveIntensity({
+  pattern = ['1:00', '2:00', '1:00', '3:00', '1:00', '4:00'],
+  blocks = 2,
+  faster = 0.1,
+  restBetween = '4:00',
+  restAfterLast = false,
+} = {}) {
+  const segs = [];
+  for (let b = 0; b < blocks; b++) {
+    pattern.forEach((dur, j) => {
+      const seg = { time: dur };
+      if (j > 0) seg.fasterThanPrev = faster; // the first interval of each block stays free
+      segs.push(seg);
+    });
+    const last = segs[segs.length - 1];
+    if (b < blocks - 1) last.rest = restBetween;
+    else if (restAfterLast) last.rest = restBetween;
+  }
+  return buildIntervals(segs);
+}
+
+// Client-side validation: anticipates the server's cryptic errors.
+export function validateIntervals(intervals) {
+  const errs = [];
+  intervals.forEach((iv, i) => {
+    if (!['time', 'distance', 'cals'].includes(iv.type)) errs.push(`#${i + 1}: invalid type (${iv.type})`);
+    if (!(iv.value > 0)) errs.push(`#${i + 1}: missing or <= 0 value`);
+    const hasSuggest = iv.suggestedInterval != null || iv.suggestedPace != null || iv.suggestedPaceBenchmarkGroup != null;
+    if (hasSuggest) {
+      if (iv.suggestedOperator !== '+') errs.push(`#${i + 1}: suggestedOperator must be "+"`);
+      if (iv.suggestedInterval != null && iv.suggestedInterval >= i) {
+        errs.push(`#${i + 1}: suggestedInterval ${iv.suggestedInterval} must be < ${i} (0-based)`);
+      }
+      const g = iv.suggestedPaceBenchmarkGroup;
+      if (g !== 'INTERVAL' && !/^[A-Z]$/.test(g || '')) errs.push(`#${i + 1}: invalid benchmarkGroup (${g})`);
+      if (g === 'INTERVAL' && iv.suggestedInterval == null) errs.push(`#${i + 1}: group INTERVAL requires suggestedInterval`);
+    }
+  });
+  return errs;
+}
+
+// Resolves intervals from one of the formats accepted by the tools: intervals | segments | recipe.
+export function resolveIntervals(args) {
+  if (Array.isArray(args.intervals)) return args.intervals;
+  if (Array.isArray(args.segments)) return buildIntervals(args.segments);
+  if (args.recipe && args.recipe.kind) {
+    const { kind, ...params } = args.recipe;
+    switch (kind) {
+      case 'ladder':
+        return ladder(params);
+      case 'over_under':
+        return overUnder(params);
+      case 'progressive':
+      case 'progressive_intensity':
+        return progressiveIntensity(params);
+      case 'custom':
+        return buildIntervals(params.segments);
+      default:
+        throw new Error(`Unknown recipe.kind: ${kind}`);
+    }
+  }
+  throw new Error('Provide one of: intervals, segments, recipe');
+}

package/src/mcp.mjs

@@ -0,0 +1,100 @@
+// MCP loop over stdio (JSON-RPC 2.0, newline-delimited messages).
+// Implements: initialize, tools/list, tools/call, ping. Zero dependencies.
+
+import readline from 'node:readline';
+import { TOOLS } from './tools.mjs';
+import { ErgzoneError, WRITE_ENABLED } from './client.mjs';
+
+const SERVER_INFO = { name: 'ergzone-mcp', version: '0.1.0' };
+const PROTOCOL_VERSION = '2024-11-05';
+
+function send(msg) {
+  process.stdout.write(JSON.stringify(msg) + '\n');
+}
+function reply(id, result) {
+  send({ jsonrpc: '2.0', id, result });
+}
+function fail(id, code, message, data) {
+  send({ jsonrpc: '2.0', id, error: { code, message, data } });
+}
+function log(...args) {
+  // stdout is reserved for the protocol: logs go to stderr.
+  process.stderr.write('[ergzone-mcp] ' + args.join(' ') + '\n');
+}
+
+async function handle(msg) {
+  const { id, method, params } = msg;
+
+  switch (method) {
+    case 'initialize':
+      return reply(id, {
+        protocolVersion: params?.protocolVersion || PROTOCOL_VERSION,
+        capabilities: { tools: {} },
+        serverInfo: SERVER_INFO,
+      });
+
+    case 'notifications/initialized':
+    case 'initialized':
+      return; // notification, no response
+
+    case 'ping':
+      return reply(id, {});
+
+    case 'tools/list':
+      return reply(id, {
+        tools: TOOLS.map((t) => ({
+          name: t.name,
+          description: t.description,
+          inputSchema: t.inputSchema,
+        })),
+      });
+
+    case 'tools/call': {
+      const tool = TOOLS.find((t) => t.name === params?.name);
+      if (!tool) return fail(id, -32602, `Unknown tool: ${params?.name}`);
+
+      if (tool.write && !WRITE_ENABLED) {
+        return reply(id, {
+          content: [{ type: 'text', text: 'Writes are disabled (ERGZONE_ALLOW_WRITE=false).' }],
+          isError: true,
+        });
+      }
+
+      try {
+        const out = await tool.handler(params.arguments || {});
+        const text = typeof out === 'string' ? out : JSON.stringify(out, null, 2);
+        return reply(id, { content: [{ type: 'text', text }] });
+      } catch (e) {
+        const text =
+          e instanceof ErgzoneError ? `Error [${e.kind}]: ${e.message}` : `Error: ${e.message}`;
+        return reply(id, { content: [{ type: 'text', text }], isError: true });
+      }
+    }
+
+    default:
+      if (id !== undefined) return fail(id, -32601, `Unsupported method: ${method}`);
+  }
+}
+
+export function serve() {
+  const rl = readline.createInterface({ input: process.stdin });
+  rl.on('line', async (line) => {
+    const s = line.trim();
+    if (!s) return;
+    let msg;
+    try {
+      msg = JSON.parse(s);
+    } catch {
+      return log('invalid JSON:', s.slice(0, 80));
+    }
+    try {
+      await handle(msg);
+    } catch (e) {
+      log('handler crash:', e.message);
+      if (msg && msg.id !== undefined) fail(msg.id, -32603, 'Internal error');
+    }
+  });
+  // No process.exit() here: when stdin closes we let in-flight async calls drain;
+  // Node exits on its own once the event loop is empty.
+  log('started. write =', WRITE_ENABLED, 'endpoint =', process.env.ERGZONE_ENDPOINT || 'production');
+}

package/src/tools.mjs

@@ -0,0 +1,346 @@
+// MCP tool definitions (Tier 1: core training + builder + basic analysis).
+// Each tool: { name, description, inputSchema, handler, write?, destructive? }
+
+import { gql, todayISO, DEFAULT_TRACK_ID } from './client.mjs';
+import { resolveIntervals, validateIntervals } from './intervals.mjs';
+
+// ---- analysis helpers ----
+
+// Concept2 watts from pace (sec/500m). Formula: 2.80 / (pace/500)^3.
+function wattsFromPace(paceSecPer500) {
+  if (!paceSecPer500 || paceSecPer500 <= 0) return null;
+  return 2.8 / Math.pow(paceSecPer500 / 500, 3);
+}
+
+function paceString(sec) {
+  if (sec == null) return null;
+  const m = Math.floor(sec / 60);
+  const s = (sec % 60).toFixed(1).padStart(4, '0');
+  return `${m}:${s}`;
+}
+
+function hrZone(pct) {
+  if (pct == null) return null;
+  if (pct < 60) return 'Z1';
+  if (pct < 70) return 'Z2';
+  if (pct < 80) return 'Z3';
+  if (pct < 90) return 'Z4';
+  return 'Z5';
+}
+
+// ---- reusable GraphQL fragments ----
+
+const INTERVAL_DEF = `type value spm spmMax rest undefRest notes restNotes suggestedInterval suggestedOperator suggestedPace suggestedPaceBenchmarkGroup`;
+const INTERVAL_RESULT = `type value rest distance avgPace avgSpm maxSpm avgWatts maxWatts calories avgHr maxHr minHr hrZones strokeCount rateConsistency driveLength driveTime recoveryTime avgForce peakForce avgDragFactor`;
+
+export const TOOLS = [
+  {
+    name: 'auth_check',
+    description: 'Verify the token and show the logged-in user (id, name, email, max/resting HR, weight).',
+    inputSchema: { type: 'object', properties: {} },
+    async handler() {
+      const d = await gql(`query{ currentUser{ id name email maxHeartRate restingHeartRate weight weightUnit } }`);
+      if (!d.currentUser) throw new Error('No user: invalid token.');
+      return d.currentUser;
+    },
+  },
+
+  {
+    name: 'list_workouts',
+    description: 'List the workouts in a track (default: My Workouts). Optional filters: search, limit.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        trackId: { type: 'string', description: 'Track ID (default from ERGZONE_TRACK_ID)' },
+        search: { type: 'string' },
+        limit: { type: 'number', default: 50 },
+      },
+    },
+    async handler({ trackId, search, limit = 50 }) {
+      const t = trackId || DEFAULT_TRACK_ID;
+      if (!t) throw new Error('No trackId (pass trackId or set ERGZONE_TRACK_ID).');
+      const d = await gql(
+        `query($t:[ID],$s:String){ workouts(trackIds:$t, search:$s){ id title status publishedAt intervalsLength workoutResultsCount } }`,
+        { t: [t], s: search || null },
+      );
+      const ws = (d.workouts || []).slice(0, limit);
+      return { count: ws.length, workouts: ws };
+    },
+  },
+
+  {
+    name: 'get_workout',
+    description: 'Full detail of a workout, including all intervals.',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'string' } },
+      required: ['id'],
+    },
+    async handler({ id }) {
+      const d = await gql(
+        `query($id:ID!){ workout(id:$id){ id title status publishedAt description workoutType machineTypes intervals{ ${INTERVAL_DEF} } } }`,
+        { id },
+      );
+      if (!d.workout) throw new Error(`Workout ${id} not found.`);
+      return d.workout;
+    },
+  },
+
+  {
+    name: 'build_intervals',
+    description:
+      'Build and validate intervals WITHOUT saving them (preview). Accepts one of: segments (DSL), recipe (ladder|over_under|progressive), intervals (raw). Returns the ready IntervalInput plus any validation errors.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        segments: { type: 'array', items: { type: 'object' } },
+        recipe: { type: 'object', description: 'e.g. {kind:"ladder", spmStart:16, spmEnd:30} | {kind:"progressive", blocks:2, faster:0.1} | {kind:"over_under", blocks:[...]}' },
+        intervals: { type: 'array', items: { type: 'object' } },
+      },
+    },
+    async handler(args) {
+      const intervals = resolveIntervals(args);
+      const errors = validateIntervals(intervals);
+      return { count: intervals.length, intervals, valid: errors.length === 0, errors };
+    },
+  },
+
+  {
+    name: 'create_workout',
+    description:
+      'Create a new workout. Intervals from segments | recipe | intervals. publishedAt and workoutType are filled automatically. Validates before sending and reads the result back (round-trip).',
+    write: true,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        title: { type: 'string' },
+        description: { type: 'string' },
+        trackId: { type: 'string' },
+        status: { type: 'string', default: 'published', description: 'published | draft' },
+        publishedAt: { type: 'string', description: 'YYYY-MM-DD (default: today)' },
+        workoutType: { type: 'string', default: 'row' },
+        machineTypes: { type: 'array', items: { type: 'string' } },
+        segments: { type: 'array', items: { type: 'object' } },
+        recipe: { type: 'object' },
+        intervals: { type: 'array', items: { type: 'object' } },
+      },
+      required: ['title'],
+    },
+    async handler(args) {
+      const trackId = args.trackId || DEFAULT_TRACK_ID;
+      if (!trackId) throw new Error('No trackId (pass trackId or set ERGZONE_TRACK_ID).');
+      const intervals = resolveIntervals(args);
+      const errors = validateIntervals(intervals);
+      if (errors.length) throw new Error('Invalid intervals: ' + errors.join('; '));
+
+      const workout = {
+        trackId,
+        title: args.title,
+        description: args.description || null,
+        status: args.status || 'published',
+        publishedAt: args.publishedAt || todayISO(),
+        workoutType: args.workoutType || 'row',
+        machineTypes: args.machineTypes || [],
+        amrap: false,
+        hasLeaderboard: false,
+        intervals,
+      };
+      const d = await gql(
+        `mutation($w:WorkoutInput!){ workoutUpsert(workout:$w){ id title status publishedAt intervals{ ${INTERVAL_DEF} } } }`,
+        { w: workout },
+      );
+      return { created: d.workoutUpsert };
+    },
+  },
+
+  {
+    name: 'update_workout',
+    description: 'Update an existing workout (requires id). Same interval formats as create_workout. If no intervals are passed, only the provided metadata is updated.',
+    write: true,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string' },
+        title: { type: 'string' },
+        description: { type: 'string' },
+        trackId: { type: 'string' },
+        status: { type: 'string' },
+        publishedAt: { type: 'string' },
+        segments: { type: 'array', items: { type: 'object' } },
+        recipe: { type: 'object' },
+        intervals: { type: 'array', items: { type: 'object' } },
+      },
+      required: ['id'],
+    },
+    async handler(args) {
+      const trackId = args.trackId || DEFAULT_TRACK_ID;
+      if (!trackId) throw new Error('No trackId.');
+
+      // Fetch the current state for the fields that are not provided.
+      const cur = await gql(`query($id:ID!){ workout(id:$id){ title status publishedAt workoutType description } }`, { id: args.id });
+      if (!cur.workout) throw new Error(`Workout ${args.id} not found.`);
+
+      const workout = {
+        id: args.id,
+        trackId,
+        title: args.title ?? cur.workout.title,
+        description: args.description ?? cur.workout.description,
+        status: args.status ?? cur.workout.status,
+        publishedAt: args.publishedAt ?? cur.workout.publishedAt ?? todayISO(),
+        workoutType: cur.workout.workoutType || 'row',
+        machineTypes: [],
+        amrap: false,
+        hasLeaderboard: false,
+      };
+
+      const hasIntervals = args.intervals || args.segments || args.recipe;
+      if (hasIntervals) {
+        const intervals = resolveIntervals(args);
+        const errors = validateIntervals(intervals);
+        if (errors.length) throw new Error('Invalid intervals: ' + errors.join('; '));
+        workout.intervals = intervals;
+      }
+
+      const d = await gql(
+        `mutation($w:WorkoutInput!){ workoutUpsert(workout:$w){ id title status publishedAt intervals{ ${INTERVAL_DEF} } } }`,
+        { w: workout },
+      );
+      return { updated: d.workoutUpsert };
+    },
+  },
+
+  {
+    name: 'delete_workout',
+    description: 'Delete a workout. Requires confirm:true (irreversible action).',
+    write: true,
+    destructive: true,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string' },
+        confirm: { type: 'boolean', description: 'Must be true to proceed.' },
+      },
+      required: ['id'],
+    },
+    async handler({ id, confirm }) {
+      if (confirm !== true) throw new Error('Deletion not confirmed: pass confirm:true.');
+      const d = await gql(`mutation($id:ID!){ workoutDelete(id:$id){ id title } }`, { id });
+      return { deleted: d.workoutDelete };
+    },
+  },
+
+  {
+    name: 'list_my_results',
+    description: 'List my results within a date range (YYYY-MM-DD). Default: last 30 days.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        startDate: { type: 'string' },
+        endDate: { type: 'string' },
+        timezone: { type: 'string' },
+        limit: { type: 'number', default: 50 },
+      },
+    },
+    async handler({ startDate, endDate, timezone, limit = 50 }) {
+      const d = await gql(
+        `query($s:String,$e:String,$tz:String){ workoutResults(startDate:$s, endDate:$e, timezone:$tz){ id status ergType elapsedTime elapsedDistance scoreValue insertedAt workout{ id title } } }`,
+        { s: startDate || null, e: endDate || null, tz: timezone || null },
+      );
+      const rs = (d.workoutResults || []).slice(0, limit);
+      return { count: rs.length, results: rs };
+    },
+  },
+
+  {
+    name: 'get_result',
+    description: 'Detail of a result with per-interval telemetry (pace, SPM, watts, HR, force).',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'string' } },
+      required: ['id'],
+    },
+    async handler({ id }) {
+      const d = await gql(
+        `query($id:ID!){ workoutResult(id:$id){ id status ergType elapsedTime elapsedDistance scoreValue workout{ id title } intervals{ ${INTERVAL_RESULT} } } }`,
+        { id },
+      );
+      if (!d.workoutResult) throw new Error(`Result ${id} not found.`);
+      return d.workoutResult;
+    },
+  },
+
+  {
+    name: 'my_stats',
+    description: 'Aggregate stats (distance/time/calories/days + HR zones) over a period. time: "week"|"month"|"year"|"all".',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        time: { type: 'string', default: 'month' },
+        ergTypes: { type: 'array', items: { type: 'string' } },
+        timezone: { type: 'string' },
+      },
+    },
+    async handler({ time = 'month', ergTypes, timezone }) {
+      const d = await gql(
+        `query($t:String!,$erg:[String],$tz:String){ myStats(time:$t, ergTypes:$erg, timezone:$tz){ totalDistance totalTime totalCalories totalDays weightedDistance hrZones rates } }`,
+        { t: time, erg: ergTypes || null, tz: timezone || null },
+      );
+      return d.myStats;
+    },
+  },
+
+  {
+    name: 'analyze_result',
+    description:
+      'Coaching analysis of a result: for each interval computes pace, SPI (watts/SPM), %HR and zone. Uses the passed maxHr or the profile value.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string' },
+        maxHr: { type: 'number', description: 'Max HR for the zones (default: user profile)' },
+      },
+      required: ['id'],
+    },
+    async handler({ id, maxHr }) {
+      const d = await gql(
+        `query($id:ID!){ workoutResult(id:$id){ id elapsedTime elapsedDistance workout{ title } intervals{ ${INTERVAL_RESULT} } } }`,
+        { id },
+      );
+      const r = d.workoutResult;
+      if (!r) throw new Error(`Result ${id} not found.`);
+
+      let hrMax = maxHr;
+      if (!hrMax) {
+        const u = await gql(`query{ currentUser{ maxHeartRate } }`);
+        hrMax = u.currentUser?.maxHeartRate || null;
+      }
+
+      const rows = (r.intervals || []).map((iv, i) => {
+        const watts = iv.avgWatts ?? wattsFromPace(iv.avgPace);
+        const spi = watts && iv.avgSpm ? +(watts / iv.avgSpm).toFixed(1) : null;
+        const pct = iv.avgHr && hrMax ? Math.round((iv.avgHr / hrMax) * 100) : null;
+        return {
+          interval: i + 1,
+          type: iv.type,
+          value: iv.value,
+          pace: paceString(iv.avgPace),
+          spm: iv.avgSpm,
+          watts: watts ? Math.round(watts) : null,
+          spi,
+          avgHr: iv.avgHr,
+          hrPct: pct,
+          zone: hrZone(pct),
+          rateConsistency: iv.rateConsistency,
+        };
+      });
+
+      return {
+        workout: r.workout?.title,
+        elapsedTime: r.elapsedTime,
+        elapsedDistance: r.elapsedDistance,
+        maxHrUsed: hrMax,
+        intervals: rows,
+      };
+    },
+  },
+];