@rundida/mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 RunDida
+
+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,110 @@
+# @rundida/mcp-server
+
+MCP server for [**RunDida**](https://rundida.com) — the world's most comprehensive running tools platform.
+
+Give your AI assistant access to 86 running calculators, 29 marathon events, pace/time/distance calculations, race time predictions, and heart rate training zones.
+
+[![Website](https://img.shields.io/badge/RunDida.com-86%20Running%20Tools-blue)](https://rundida.com)
+[![npm](https://img.shields.io/npm/v/@rundida/mcp-server)](https://www.npmjs.com/package/@rundida/mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+## Quick Start
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "rundida": {
+      "command": "npx",
+      "args": ["-y", "@rundida/mcp-server"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add rundida -- npx -y @rundida/mcp-server
+```
+
+### Cursor / Windsurf
+
+Add to your MCP configuration:
+
+```json
+{
+  "rundida": {
+    "command": "npx",
+    "args": ["-y", "@rundida/mcp-server"]
+  }
+}
+```
+
+## Available Tools
+
+| Tool | Type | Description |
+|------|------|-------------|
+| `list_tools` | Data | Browse all [86 running calculators](https://rundida.com) with descriptions |
+| `get_tool` | Data | Get details, FAQs, and sources for a specific tool |
+| `list_marathons` | Data | List [29 marathon events](https://rundida.com/marathon/) with dates and locations |
+| `get_marathon` | Data | Get marathon details including weather and course profile |
+| `calculate_pace` | Compute | Calculate pace, time, or distance (provide any 2 of 3) |
+| `predict_race` | Compute | Predict race times using Riegel formula + VO2max estimation |
+| `heart_rate_zones` | Compute | Calculate 5 HR training zones (Karvonen method) |
+| `marathon_countdown` | Compute | Get countdown to a specific marathon event |
+
+**Data tools** fetch from the [RunDida API](https://rundida.com/api/) with 30-minute caching. **Compute tools** run locally with zero latency — no API calls needed.
+
+## Example Usage
+
+Ask your AI assistant:
+
+- "What's my marathon pace if I want to finish in 3:30?"
+- "Predict my marathon time based on my 10K of 45 minutes"
+- "What are my heart rate zones? I'm 32 with a resting HR of 52"
+- "How many days until the Tokyo Marathon?"
+- "Show me all running calculators related to nutrition"
+
+## About RunDida
+
+[**RunDida**](https://rundida.com) (跑滴答) is a free running tools platform for runners of all levels:
+
+- **[86 Interactive Calculators](https://rundida.com)** — Pace, heart rate zones, VO2max, race prediction, nutrition, gear sizing, weather impact, and more
+- **[29 Marathon Countdowns](https://rundida.com/marathon/)** — Live timers with race-day weather forecasts, course profiles, and training tools
+- **[Free JSON API](https://rundida.com/api/)** — No authentication required, CORS enabled, [OpenAPI 3.0 documented](https://rundida.com/api/openapi.json)
+- **Multi-language** — English, Chinese (中文)
+- **Embeddable Widgets** — One-line iframe embed for any calculator
+
+All tools are free, no account required. Try them at [rundida.com](https://rundida.com).
+
+## How It Works
+
+The computation tools use established running science formulas:
+
+| Formula | Used In | Description |
+|---------|---------|-------------|
+| **Riegel formula** | `predict_race` | Race time prediction across distances |
+| **Jack Daniels method** | `predict_race` | VO2max estimation from race performance |
+| **Karvonen method** | `heart_rate_zones` | Heart rate training zones from age and resting HR |
+
+## Requirements
+
+- Node.js >= 18
+- Internet connection (data tools fetch from [rundida.com](https://rundida.com))
+
+## Links
+
+| Resource | URL |
+|----------|-----|
+| **RunDida Website** | [rundida.com](https://rundida.com) |
+| **API Documentation** | [rundida.com/api](https://rundida.com/api/) |
+| **OpenAPI Spec** | [rundida.com/api/openapi.json](https://rundida.com/api/openapi.json) |
+| **NPM Package** | [@rundida/mcp-server](https://www.npmjs.com/package/@rundida/mcp-server) |
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,341 @@
+#!/usr/bin/env node
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+const BASE_URL = 'https://rundida.com';
+const CACHE_TTL = 30 * 60 * 1000; // 30 minutes
+
+// Simple in-memory cache
+const cache = new Map();
+
+async function fetchJSON(url) {
+  const cached = cache.get(url);
+  if (cached && Date.now() - cached.ts < CACHE_TTL) return cached.data;
+
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`HTTP ${res.status}: ${url}`);
+  const data = await res.json();
+  cache.set(url, { data, ts: Date.now() });
+  return data;
+}
+
+// ---- Pace calculation helpers ----
+
+function paceToSeconds(pace) {
+  const [m, s] = pace.split(':').map(Number);
+  return m * 60 + (s || 0);
+}
+
+function secondsToPace(secs) {
+  const m = Math.floor(secs / 60);
+  const s = Math.round(secs % 60);
+  return `${m}:${s.toString().padStart(2, '0')}`;
+}
+
+function timeToSeconds(time) {
+  const parts = time.split(':').map(Number);
+  if (parts.length === 3) return parts[0] * 3600 + parts[1] * 60 + parts[2];
+  if (parts.length === 2) return parts[0] * 60 + parts[1];
+  return parts[0];
+}
+
+function secondsToTime(secs) {
+  const h = Math.floor(secs / 3600);
+  const m = Math.floor((secs % 3600) / 60);
+  const s = Math.round(secs % 60);
+  if (h > 0) return `${h}:${m.toString().padStart(2, '0')}:${s.toString().padStart(2, '0')}`;
+  return `${m}:${s.toString().padStart(2, '0')}`;
+}
+
+const DISTANCES = {
+  '5k': 5,
+  '10k': 10,
+  'half': 21.0975,
+  'half-marathon': 21.0975,
+  'marathon': 42.195,
+  '50k': 50,
+  '100k': 100,
+};
+
+function resolveDistance(input) {
+  const lower = String(input).toLowerCase().trim();
+  if (DISTANCES[lower]) return DISTANCES[lower];
+  const num = parseFloat(lower);
+  if (!isNaN(num) && num > 0) return num;
+  throw new Error(`Unknown distance: ${input}. Use 5k, 10k, half, marathon, or a number in km.`);
+}
+
+// ---- Riegel race prediction ----
+
+function predictTime(knownDist, knownTimeSecs, targetDist, exponent = 1.06) {
+  return knownTimeSecs * Math.pow(targetDist / knownDist, exponent);
+}
+
+// ---- VO2max estimation (Jack Daniels) ----
+
+function estimateVO2max(distKm, timeSecs) {
+  const timeMin = timeSecs / 60;
+  const velocity = distKm * 1000 / timeMin; // meters per minute
+  const pctVO2max = 0.8 + 0.1894393 * Math.exp(-0.012778 * timeMin)
+    + 0.2989558 * Math.exp(-0.1932605 * timeMin);
+  const vo2 = -4.60 + 0.182258 * velocity + 0.000104 * velocity * velocity;
+  return vo2 / pctVO2max;
+}
+
+// ---- Heart Rate Zones (Karvonen) ----
+
+function heartRateZones(age, restingHR, maxHR) {
+  const mhr = maxHR || Math.round(207 - 0.7 * age);
+  const hrr = mhr - restingHR;
+  const zones = [
+    { zone: 1, name: 'Recovery', low: 0.50, high: 0.60 },
+    { zone: 2, name: 'Aerobic', low: 0.60, high: 0.70 },
+    { zone: 3, name: 'Tempo', low: 0.70, high: 0.80 },
+    { zone: 4, name: 'Threshold', low: 0.80, high: 0.90 },
+    { zone: 5, name: 'VO2max', low: 0.90, high: 1.00 },
+  ];
+  return {
+    maxHR: mhr,
+    restingHR,
+    zones: zones.map(z => ({
+      ...z,
+      bpmLow: Math.round(restingHR + hrr * z.low),
+      bpmHigh: Math.round(restingHR + hrr * z.high),
+    })),
+  };
+}
+
+// ---- Create Server ----
+
+const server = new McpServer({
+  name: 'RunDida',
+  version: '1.0.0',
+});
+
+// Tool: list_tools
+server.tool(
+  'list_tools',
+  'List all available running calculators and tools on RunDida',
+  {},
+  async () => {
+    const data = await fetchJSON(`${BASE_URL}/api/tools.json`);
+    const list = data.tools.map(t => `- ${t.title} (${t.slug}): ${t.description}`).join('\n');
+    return {
+      content: [{
+        type: 'text',
+        text: `RunDida has ${data.meta.total} running tools:\n\n${list}\n\nUse get_tool with a slug to see full details.`,
+      }],
+    };
+  }
+);
+
+// Tool: get_tool
+server.tool(
+  'get_tool',
+  'Get detailed information about a specific running tool including FAQs and related tools',
+  { slug: z.string().describe('Tool slug, e.g. "pace-calculator", "heart-rate-zones"') },
+  async ({ slug }) => {
+    const data = await fetchJSON(`${BASE_URL}/api/tools/${slug}.json`);
+    const t = data.tool;
+    let text = `## ${t.title}\n\n${t.description}\n\nURL: ${t.url}\nCategory: ${t.category}\n`;
+    if (t.relatedTools.length) text += `\nRelated tools: ${t.relatedTools.join(', ')}`;
+    if (t.faqs.length) {
+      text += '\n\n### FAQs\n';
+      t.faqs.forEach(f => { text += `\n**Q: ${f.question}**\nA: ${f.answer}\n`; });
+    }
+    return { content: [{ type: 'text', text }] };
+  }
+);
+
+// Tool: list_marathons
+server.tool(
+  'list_marathons',
+  'List all marathon events tracked by RunDida with dates and locations',
+  {},
+  async () => {
+    const data = await fetchJSON(`${BASE_URL}/api/marathons.json`);
+    const list = data.active
+      .sort((a, b) => a.date.localeCompare(b.date))
+      .map(m => `- ${m.name.en} — ${m.date} — ${m.city}`)
+      .join('\n');
+    return {
+      content: [{
+        type: 'text',
+        text: `RunDida tracks ${data.meta.totalActive} upcoming marathons:\n\n${list}\n\nUse get_marathon with an ID for details.`,
+      }],
+    };
+  }
+);
+
+// Tool: get_marathon
+server.tool(
+  'get_marathon',
+  'Get detailed information about a specific marathon including countdown and Schema.org data',
+  { id: z.string().describe('Marathon ID, e.g. "tokyo2026", "boston2026", "berlin2026"') },
+  async ({ id }) => {
+    const data = await fetchJSON(`${BASE_URL}/api/marathons/${id}.json`);
+    const m = data.marathon;
+    const raceDate = new Date(m.date);
+    const now = new Date();
+    const daysUntil = Math.ceil((raceDate - now) / (1000 * 60 * 60 * 24));
+    let text = `## ${m.name.en}\n\nDate: ${m.date}\nCity: ${m.city}\n`;
+    if (m.country) text += `Country/Region: ${m.country}\n`;
+    text += `Timezone: ${m.timezone}\n`;
+    text += `Days until race: ${daysUntil > 0 ? daysUntil : 'Race has passed'}\n`;
+    if (m.weather) {
+      text += `\n### Race Day Weather\nTemperature: ${m.weather.avgTempC}°C / ${m.weather.avgTempF}°F\n`;
+      text += `Humidity: ${m.weather.humidity}% | Wind: ${m.weather.windKmh} km/h | Rain: ${m.weather.precipPct}%\n`;
+      text += `Conditions: ${m.weather.conditions}\n`;
+    }
+    if (m.course) {
+      text += `\n### Course Profile\nType: ${m.course.type} | Elevation: ${m.course.elevationGain}m | Terrain: ${m.course.terrain}\n`;
+      text += `${m.course.profile}\n`;
+    }
+    text += `\nPage: ${m.links.page}\nCountdown: ${m.links.countdown}\n`;
+    return { content: [{ type: 'text', text }] };
+  }
+);
+
+// Tool: calculate_pace
+server.tool(
+  'calculate_pace',
+  'Calculate running pace, finish time, or distance. Provide any two of: distance, time, pace.',
+  {
+    distance: z.string().optional().describe('Distance: "5k", "10k", "half", "marathon", or km value like "15"'),
+    time: z.string().optional().describe('Finish time in H:MM:SS or MM:SS format, e.g. "3:30:00" or "25:00"'),
+    pace: z.string().optional().describe('Pace per km in M:SS format, e.g. "5:00"'),
+  },
+  async ({ distance, time, pace }) => {
+    const given = [distance, time, pace].filter(Boolean).length;
+    if (given < 2) throw new Error('Provide at least 2 of: distance, time, pace');
+
+    let result = {};
+
+    if (distance && time) {
+      const distKm = resolveDistance(distance);
+      const timeSecs = timeToSeconds(time);
+      const paceSecs = timeSecs / distKm;
+      result = {
+        distance: `${distKm} km`,
+        time: secondsToTime(timeSecs),
+        pace: `${secondsToPace(paceSecs)}/km`,
+        speed: `${(distKm / (timeSecs / 3600)).toFixed(2)} km/h`,
+      };
+    } else if (distance && pace) {
+      const distKm = resolveDistance(distance);
+      const paceSecs = paceToSeconds(pace);
+      const timeSecs = distKm * paceSecs;
+      result = {
+        distance: `${distKm} km`,
+        time: secondsToTime(timeSecs),
+        pace: `${secondsToPace(paceSecs)}/km`,
+        speed: `${(distKm / (timeSecs / 3600)).toFixed(2)} km/h`,
+      };
+    } else if (time && pace) {
+      const timeSecs = timeToSeconds(time);
+      const paceSecs = paceToSeconds(pace);
+      const distKm = timeSecs / paceSecs;
+      result = {
+        distance: `${distKm.toFixed(2)} km`,
+        time: secondsToTime(timeSecs),
+        pace: `${secondsToPace(paceSecs)}/km`,
+        speed: `${(distKm / (timeSecs / 3600)).toFixed(2)} km/h`,
+      };
+    }
+
+    return {
+      content: [{
+        type: 'text',
+        text: Object.entries(result).map(([k, v]) => `${k}: ${v}`).join('\n'),
+      }],
+    };
+  }
+);
+
+// Tool: predict_race
+server.tool(
+  'predict_race',
+  'Predict race finish times using the Riegel formula based on a known race result',
+  {
+    known_distance: z.string().describe('Known race distance: "5k", "10k", "half", "marathon", or km value'),
+    known_time: z.string().describe('Known race time in H:MM:SS or MM:SS format'),
+    target_distance: z.string().optional().describe('Target distance to predict (defaults to showing all standard distances)'),
+  },
+  async ({ known_distance, known_time, target_distance }) => {
+    const distKm = resolveDistance(known_distance);
+    const timeSecs = timeToSeconds(known_time);
+    const vo2max = estimateVO2max(distKm, timeSecs);
+
+    const targets = target_distance
+      ? [{ name: target_distance, km: resolveDistance(target_distance) }]
+      : [
+          { name: '5K', km: 5 },
+          { name: '10K', km: 10 },
+          { name: 'Half Marathon', km: 21.0975 },
+          { name: 'Marathon', km: 42.195 },
+        ];
+
+    let text = `Based on ${known_distance} in ${known_time}:\n\nEstimated VO2max: ${vo2max.toFixed(1)} ml/kg/min\n\nPredictions:\n`;
+    targets.forEach(t => {
+      const predicted = predictTime(distKm, timeSecs, t.km);
+      const pace = predicted / t.km;
+      text += `- ${t.name}: ${secondsToTime(predicted)} (pace: ${secondsToPace(pace)}/km)\n`;
+    });
+
+    text += `\nNote: Predictions assume equivalent training for the target distance. Use RunDida's Race Time Predictor for more details: ${BASE_URL}/tools/race-time-predictor/`;
+    return { content: [{ type: 'text', text }] };
+  }
+);
+
+// Tool: heart_rate_zones
+server.tool(
+  'heart_rate_zones',
+  'Calculate heart rate training zones using the Karvonen method',
+  {
+    age: z.number().min(10).max(99).describe('Your age in years'),
+    resting_hr: z.number().min(30).max(120).optional().describe('Resting heart rate in bpm (default: 60)'),
+    max_hr: z.number().min(100).max(220).optional().describe('Known max heart rate in bpm (auto-calculated if omitted)'),
+  },
+  async ({ age, resting_hr, max_hr }) => {
+    const result = heartRateZones(age, resting_hr || 60, max_hr);
+    let text = `Heart Rate Training Zones (Karvonen Method)\n\nAge: ${age} | Resting HR: ${result.restingHR} bpm | Max HR: ${result.maxHR} bpm\n\n`;
+    result.zones.forEach(z => {
+      text += `Zone ${z.zone} (${z.name}): ${z.bpmLow}-${z.bpmHigh} bpm\n`;
+    });
+    text += `\nFor more options: ${BASE_URL}/tools/heart-rate-zones/`;
+    return { content: [{ type: 'text', text }] };
+  }
+);
+
+// Tool: marathon_countdown
+server.tool(
+  'marathon_countdown',
+  'Get a countdown to a specific marathon event',
+  { id: z.string().describe('Marathon ID, e.g. "tokyo2026", "boston2026"') },
+  async ({ id }) => {
+    const data = await fetchJSON(`${BASE_URL}/api/marathons/${id}.json`);
+    const m = data.marathon;
+    const raceDate = new Date(m.date + 'T00:00:00');
+    const now = new Date();
+    const diff = raceDate - now;
+
+    if (diff <= 0) {
+      return { content: [{ type: 'text', text: `${m.name.en} has already taken place on ${m.date}.` }] };
+    }
+
+    const days = Math.floor(diff / (1000 * 60 * 60 * 24));
+    const hours = Math.floor((diff % (1000 * 60 * 60 * 24)) / (1000 * 60 * 60));
+
+    let text = `${m.name.en} Countdown\n\n`;
+    text += `${days} days, ${hours} hours until race day\n`;
+    text += `Date: ${m.date}\nCity: ${m.city}\n`;
+    text += `\nLive countdown: ${m.links.countdown}`;
+    return { content: [{ type: 'text', text }] };
+  }
+);
+
+// Start server
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@rundida/mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for RunDida running tools — marathon data, pace calculations, heart rate zones, and race predictions for AI agents",
+  "main": "index.js",
+  "type": "module",
+  "bin": {
+    "rundida-mcp": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node index.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "running",
+    "marathon",
+    "pace-calculator",
+    "heart-rate-zones",
+    "race-prediction",
+    "vo2max",
+    "ai-tools",
+    "claude",
+    "llm",
+    "fitness"
+  ],
+  "author": "RunDida (https://rundida.com)",
+  "license": "MIT",
+  "homepage": "https://rundida.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/XWeaponX7/rundida-mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/XWeaponX7/rundida-mcp/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.25 || ^4.0"
+  }
+}