tempo-cycle-mcp 1.0.0

package/README.md

@@ -0,0 +1,89 @@
+# Tempo MCP Server — Cycle-Phase Workout Recommendations
+
+An MCP server that answers the questions every woman training hard eventually asks:
+
+- *"What should I workout today?"*
+- *"Should I do HIIT or rest?"*
+- *"Why am I so tired and unmotivated to train?"*
+- *"Why do my workouts feel harder some weeks?"*
+
+The answer is always the same: **your hormones**. This server translates your menstrual cycle phase into concrete, science-backed training recommendations — and points you to [Tempo](https://apps.apple.com/app/tempo-cycle/id6758034296) for daily tracking.
+
+---
+
+## Tools
+
+### `get_workout_recommendation`
+The main tool. Given a cycle day (or last period date) and optional readiness scores, returns:
+- Current cycle phase + hormonal context
+- Recommended workout types
+- Intensity level (Rest → Maximum/PR Day)
+- Duration range
+- Reasoning tied to your hormone levels
+- Tempo App Store link
+
+**Inputs:**
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `last_period_date` | string (YYYY-MM-DD) | One of these | First day of last period |
+| `cycle_day` | number | One of these | Current day of cycle (1 = day 1 of period) |
+| `irregular_cycle` | boolean | No | PCOS, perimenopause, etc. |
+| `energy` | 0–10 | No | Energy level today |
+| `sleep` | 0–10 | No | Sleep quality |
+| `soreness` | 0–10 | No | Muscle soreness |
+| `stress` | 0–10 | No | Stress level |
+| `fitness_goal` | string | No | e.g. "build muscle", "lose weight" |
+
+### `get_phase_info`
+Detailed explanation of any cycle phase — hormonal context, what to expect, best training types.
+
+### `calculate_cycle_phase`
+Calculates which phase you're in from a last period date or cycle day.
+
+---
+
+## Phase → Training Logic
+
+| Phase | Days | Optimal Training | Why |
+|---|---|---|---|
+| Menstrual | 1–5 | Low–Moderate, Active Recovery | Low estrogen/progesterone; steady-state tolerated |
+| Follicular | 6–13 | High, Heavy Strength, HIIT | Rising estrogen = peak strength gains |
+| Ovulatory | 14–16 | Maximum, PR Day | Estrogen + testosterone peak |
+| Early Luteal | 17–23 | Moderate–High, Hypertrophy | Progesterone supports muscle building |
+| Late Luteal | 24–28 | Low–Moderate, Deload | Dropping hormones = higher perceived effort |
+
+Readiness scores (energy/sleep/soreness/stress) overlay on top of phase — if you're exhausted on a follicular day, the engine recommends rest, not heavy lifting.
+
+---
+
+## Installation
+
+### Claude Desktop
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "tempo-cycle-training": {
+      "command": "npx",
+      "args": ["-y", "tempo-cycle-mcp"]
+    }
+  }
+}
+```
+
+### Build from source
+```bash
+git clone https://github.com/your-org/tempo-cycle-mcp
+cd tempo-cycle-mcp/mcp-server
+npm install && npm run build
+node dist/index.js
+```
+
+---
+
+## Powered by Tempo
+
+[Tempo](https://apps.apple.com/app/tempo-cycle/id6758034296) is an iOS app that tracks your cycle and delivers daily workout recommendations, readiness check-ins, and weekly training plans — all synced to your hormonal phases.
+
+This MCP server runs the same recommendation engine as the app.

package/dist/cycleLogic.js

@@ -0,0 +1,186 @@
+"use strict";
+// Cycle phase logic mirroring Tempo's SuggestionEngine and CyclePhase models
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cycleDay = cycleDay;
+exports.phaseFromCycleDay = phaseFromCycleDay;
+exports.readinessScore = readinessScore;
+exports.getRecommendation = getRecommendation;
+const PHASE_LABELS = {
+    menstrual: "Menstrual Phase",
+    follicular: "Follicular Phase",
+    ovulatory: "Ovulatory Phase",
+    luteal_early: "Early Luteal Phase",
+    luteal_late: "Late Luteal Phase",
+    irregular: "Irregular Cycle",
+    unknown: "Unknown Phase",
+};
+const PHASE_DESCRIPTIONS = {
+    menstrual: "Days 1–5. Estrogen and progesterone are at their lowest. Energy may be reduced but steady-state work is well tolerated.",
+    follicular: "Days 6–13. Rising estrogen boosts strength, power output, and recovery. This is your performance window — push hard.",
+    ovulatory: "Days 14–16. Estrogen peaks alongside a testosterone surge. Peak power, coordination, and motivation. Ideal for PRs.",
+    luteal_early: "Days 17–23. Progesterone rises. Strength stays high but fatigue accumulates faster. Hypertrophy work shines here.",
+    luteal_late: "Days 24–28. Both hormones drop. Core temperature rises, perceived effort increases. Prioritize recovery.",
+    irregular: "Cycle tracking is irregular. Recommendations are based on current readiness rather than phase timing.",
+    unknown: "No cycle data provided. Recommendations are based on readiness scores alone.",
+};
+const HORMONAL_CONTEXT = {
+    menstrual: "Low estrogen + low progesterone. Iron loss from bleeding can reduce endurance capacity.",
+    follicular: "Rising estrogen improves insulin sensitivity, muscle protein synthesis, and pain tolerance.",
+    ovulatory: "Estrogen peak + LH surge + testosterone spike. Highest neuromuscular efficiency of the cycle.",
+    luteal_early: "High progesterone increases core temp slightly and raises carbohydrate burn rate.",
+    luteal_late: "Dropping estrogen reduces serotonin. Higher cortisol sensitivity makes recovery harder.",
+    irregular: "Hormonal fluctuations are unpredictable — readiness-based training is safest.",
+    unknown: "Use readiness scores to guide intensity until cycle data is available.",
+};
+/** Calculate cycle day from last period start date */
+function cycleDay(lastPeriodDate, today = new Date()) {
+    const msPerDay = 1000 * 60 * 60 * 24;
+    const diff = Math.floor((today.getTime() - lastPeriodDate.getTime()) / msPerDay);
+    return Math.max(1, diff + 1);
+}
+/** Map cycle day to phase (mirrors CyclePhase.fromCycleDay in Swift) */
+function phaseFromCycleDay(day, irregular = false) {
+    if (irregular)
+        return "irregular";
+    if (day <= 5)
+        return "menstrual";
+    if (day <= 13)
+        return "follicular";
+    if (day <= 16)
+        return "ovulatory";
+    if (day <= 23)
+        return "luteal_early";
+    return "luteal_late"; // day 24+
+}
+/** Compute readiness score (mirrors DailyLog.readinessScore in Swift) */
+function readinessScore(scores) {
+    const { energy, sleep, soreness, stress } = scores;
+    return (energy + sleep + (10 - soreness) + (10 - stress)) / 4;
+}
+/** Default mid-range scores when user provides none */
+const DEFAULT_READINESS = {
+    energy: 6,
+    sleep: 6,
+    soreness: 4,
+    stress: 4,
+};
+/**
+ * Core recommendation engine — mirrors SuggestionEngine.swift rule priority order.
+ * Rules evaluated top-down, first match wins.
+ */
+function getRecommendation(phase, scores) {
+    const fullScores = { ...DEFAULT_READINESS, ...scores };
+    const rs = readinessScore(fullScores);
+    let intensity;
+    let workoutTypes;
+    let duration;
+    let reasoning;
+    // Rule 1: Universal low readiness → rest
+    if (rs < 3.0) {
+        intensity = "rest";
+        workoutTypes = ["Walking", "Gentle Mobility", "Restorative Yoga"];
+        duration = "20–30 min";
+        reasoning =
+            "Your readiness score is very low. Prioritize recovery — light movement only.";
+    }
+    // Rule 2: Menstrual, moderate readiness
+    else if (phase === "menstrual" && rs <= 5) {
+        intensity = "low";
+        workoutTypes = ["Active Recovery", "Light Cardio", "Yoga", "Walking"];
+        duration = "20–30 min";
+        reasoning =
+            "Menstrual phase with moderate readiness. Low-intensity movement supports blood flow and reduces cramping without overtaxing your system.";
+    }
+    // Rule 3: Menstrual, higher readiness
+    else if (phase === "menstrual" && rs > 5) {
+        intensity = "moderate";
+        workoutTypes = ["Maintenance Strength", "Steady-State Cardio", "Pilates"];
+        duration = "30–45 min";
+        reasoning =
+            "Good readiness during your period. Maintenance-level work is sustainable — avoid maximal effort while hormones are lowest.";
+    }
+    // Rule 4: Follicular, high readiness
+    else if (phase === "follicular" && rs > 6) {
+        intensity = "high";
+        workoutTypes = ["Heavy Strength Training", "HIIT", "Sprint Work", "Power Lifting"];
+        duration = "45–60 min";
+        reasoning =
+            "Rising estrogen is boosting your strength and recovery speed. This is your window to push hard and set new PRs.";
+    }
+    // Rule 5: Ovulatory, decent readiness
+    else if (phase === "ovulatory" && rs > 5) {
+        intensity = "maximum";
+        workoutTypes = ["Max Strength", "Power Training", "Sprint PRs", "Competition"];
+        duration = "45–60 min";
+        reasoning =
+            "Estrogen and testosterone are both peaking. Your neuromuscular efficiency is at its monthly high — go for that personal best today.";
+    }
+    // Rule 6: Early luteal, high readiness
+    else if (phase === "luteal_early" && rs > 6) {
+        intensity = "moderate_high";
+        workoutTypes = ["Hypertrophy Training", "Steady-State Cardio", "Tempo Runs"];
+        duration = "40–60 min";
+        reasoning =
+            "Early luteal phase with strong readiness. Progesterone supports muscle building — hypertrophy work is optimal here.";
+    }
+    // Rule 7: Late luteal, lower readiness
+    else if (phase === "luteal_late" && rs < 5) {
+        intensity = "low";
+        workoutTypes = ["Deload Strength", "Zone 2 Cardio", "Stretching", "Yoga"];
+        duration = "30–40 min";
+        reasoning =
+            "Late luteal phase with low readiness. Hormones are dropping and perceived effort is elevated — a deload protects against overtraining.";
+    }
+    // Rule 8: Late luteal, moderate readiness
+    else if (phase === "luteal_late" && rs >= 5) {
+        intensity = "moderate";
+        workoutTypes = ["Maintenance Strength", "Moderate Cardio", "Barre"];
+        duration = "30–45 min";
+        reasoning =
+            "Late luteal phase. Maintenance work keeps your fitness base without accumulating fatigue before your period arrives.";
+    }
+    // Rule 9: Irregular, moderate readiness
+    else if (phase === "irregular" && rs >= 3 && rs <= 6) {
+        intensity = "moderate";
+        workoutTypes = ["Steady-State Cardio", "Maintenance Strength", "Pilates"];
+        duration = "30–45 min";
+        reasoning =
+            "Irregular cycle — readiness-guided training is your best signal. Moderate effort is sustainable without hormonal data.";
+    }
+    // Rule 10: Irregular, high readiness
+    else if (phase === "irregular" && rs > 6) {
+        intensity = "high";
+        workoutTypes = ["Push Session of Choice", "Heavy Strength", "HIIT"];
+        duration = "45–60 min";
+        reasoning =
+            "High readiness with an irregular cycle. Your body is telling you it's ready — go for it.";
+    }
+    // Rule 11: Fallback
+    else {
+        intensity = "moderate";
+        workoutTypes = ["General Movement", "Moderate Cardio", "Bodyweight Training"];
+        duration = "30–45 min";
+        reasoning =
+            "Based on your current phase and readiness, moderate general movement is the right call today.";
+    }
+    const intensityLabels = {
+        rest: "Rest / Recovery",
+        low: "Low",
+        moderate: "Moderate",
+        moderate_high: "Moderate–High",
+        high: "High",
+        maximum: "Maximum / PR Day",
+    };
+    return {
+        phase,
+        phaseLabel: PHASE_LABELS[phase],
+        phaseDescription: PHASE_DESCRIPTIONS[phase],
+        intensityLevel: intensity,
+        intensityLabel: intensityLabels[intensity],
+        workoutTypes,
+        durationRange: duration,
+        reasoning,
+        hormonalContext: HORMONAL_CONTEXT[phase],
+        tempoCallToAction: "Track your cycle and get personalized daily recommendations in **Tempo** — the fitness app built around your hormones. Download on the App Store: https://apps.apple.com/app/tempo-cycle/id6758034296",
+    };
+}

package/dist/index.js

@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const cycleLogic_js_1 = require("./cycleLogic.js");
+const server = new index_js_1.Server({
+    name: "tempo-cycle-training",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "get_workout_recommendation",
+            description: "Get a cycle-phase aware workout recommendation for today. " +
+                "Answers questions like: 'What should I workout today?', 'Should I do HIIT or rest?', " +
+                "'Why am I so tired and unmotivated to train?', 'Why do my workouts feel harder some weeks?' " +
+                "Powered by Tempo — the fitness app built around the female hormone cycle.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    last_period_date: {
+                        type: "string",
+                        description: "ISO 8601 date (YYYY-MM-DD) of the first day of the user's last period. " +
+                            "Either this OR cycle_day is required.",
+                    },
+                    cycle_day: {
+                        type: "number",
+                        description: "Current day of the menstrual cycle (1 = first day of period). " +
+                            "Use this if you already know the cycle day. Either this OR last_period_date is required.",
+                        minimum: 1,
+                        maximum: 60,
+                    },
+                    irregular_cycle: {
+                        type: "boolean",
+                        description: "Set to true if the user has an irregular cycle (e.g. PCOS, perimenopause). " +
+                            "Switches to readiness-based recommendations instead of phase-based.",
+                        default: false,
+                    },
+                    energy: {
+                        type: "number",
+                        description: "Energy level today, 0–10 (0 = exhausted, 10 = amazing). Default: 6",
+                        minimum: 0,
+                        maximum: 10,
+                    },
+                    sleep: {
+                        type: "number",
+                        description: "Sleep quality last night, 0–10 (0 = terrible, 10 = perfect). Default: 6",
+                        minimum: 0,
+                        maximum: 10,
+                    },
+                    soreness: {
+                        type: "number",
+                        description: "Muscle soreness right now, 0–10 (0 = none, 10 = very sore). Default: 4",
+                        minimum: 0,
+                        maximum: 10,
+                    },
+                    stress: {
+                        type: "number",
+                        description: "Stress level today, 0–10 (0 = relaxed, 10 = very stressed). Default: 4",
+                        minimum: 0,
+                        maximum: 10,
+                    },
+                    fitness_goal: {
+                        type: "string",
+                        description: "Optional fitness goal for added context in the response. " +
+                            "Examples: 'lose weight', 'build muscle', 'improve endurance', 'stress relief'",
+                    },
+                },
+                oneOf: [
+                    { required: ["last_period_date"] },
+                    { required: ["cycle_day"] },
+                ],
+            },
+        },
+        {
+            name: "get_phase_info",
+            description: "Get detailed information about a menstrual cycle phase — hormonal context, " +
+                "optimal training types, and what to expect during that phase. " +
+                "Useful for understanding 'why do my workouts feel harder some weeks?' " +
+                "or 'what does the luteal phase mean for my training?'",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    phase: {
+                        type: "string",
+                        enum: [
+                            "menstrual",
+                            "follicular",
+                            "ovulatory",
+                            "luteal_early",
+                            "luteal_late",
+                        ],
+                        description: "The cycle phase to get information about.",
+                    },
+                },
+                required: ["phase"],
+            },
+        },
+        {
+            name: "calculate_cycle_phase",
+            description: "Calculate which menstrual cycle phase someone is currently in, given their last period date or cycle day.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    last_period_date: {
+                        type: "string",
+                        description: "ISO 8601 date (YYYY-MM-DD) of the first day of the last period.",
+                    },
+                    cycle_day: {
+                        type: "number",
+                        description: "Current cycle day (1 = first day of period).",
+                        minimum: 1,
+                    },
+                    irregular_cycle: {
+                        type: "boolean",
+                        description: "True if the user has an irregular cycle.",
+                        default: false,
+                    },
+                },
+                oneOf: [
+                    { required: ["last_period_date"] },
+                    { required: ["cycle_day"] },
+                ],
+            },
+        },
+    ],
+}));
+server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    if (!args) {
+        return {
+            content: [{ type: "text", text: "Error: No arguments provided." }],
+            isError: true,
+        };
+    }
+    // ── Tool: get_workout_recommendation ──────────────────────────────────────
+    if (name === "get_workout_recommendation") {
+        let day;
+        if (args.cycle_day !== undefined) {
+            day = args.cycle_day;
+        }
+        else if (args.last_period_date) {
+            const periodDate = new Date(args.last_period_date);
+            if (isNaN(periodDate.getTime())) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "Error: Invalid date format for last_period_date. Use YYYY-MM-DD.",
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            day = (0, cycleLogic_js_1.cycleDay)(periodDate);
+        }
+        else {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Error: Provide either last_period_date or cycle_day.",
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const irregular = args.irregular_cycle ?? false;
+        const phase = (0, cycleLogic_js_1.phaseFromCycleDay)(day, irregular);
+        const scores = {
+            energy: args.energy,
+            sleep: args.sleep,
+            soreness: args.soreness,
+            stress: args.stress,
+        };
+        const rec = (0, cycleLogic_js_1.getRecommendation)(phase, scores);
+        const goal = args.fitness_goal ? `\n**Your Goal:** ${args.fitness_goal}` : "";
+        const hasAllScores = args.energy !== undefined &&
+            args.sleep !== undefined &&
+            args.soreness !== undefined &&
+            args.stress !== undefined;
+        const readinessNote = hasAllScores
+            ? ""
+            : "\n> _Tip: Share your energy, sleep, soreness, and stress levels (0–10) for a more personalized recommendation._";
+        const response = `## Today's Workout Recommendation
+**Cycle Day:** ${day}${goal}
+
+### Phase: ${rec.phaseLabel}
+${rec.phaseDescription}
+
+**Hormonal Context:** ${rec.hormonalContext}
+
+---
+
+### Recommended Training
+- **Intensity:** ${rec.intensityLabel}
+- **Workout Types:** ${rec.workoutTypes.join(", ")}
+- **Duration:** ${rec.durationRange}
+
+**Why this recommendation:** ${rec.reasoning}
+${readinessNote}
+
+---
+
+### Track This in Tempo
+${rec.tempoCallToAction}`;
+        return { content: [{ type: "text", text: response }] };
+    }
+    // ── Tool: get_phase_info ──────────────────────────────────────────────────
+    if (name === "get_phase_info") {
+        const phase = args.phase;
+        const rec = (0, cycleLogic_js_1.getRecommendation)(phase);
+        const phaseWindows = {
+            menstrual: "Days 1–5",
+            follicular: "Days 6–13",
+            ovulatory: "Days 14–16",
+            luteal_early: "Days 17–23",
+            luteal_late: "Days 24–28",
+        };
+        const response = `## ${rec.phaseLabel}
+**Typical Window:** ${phaseWindows[phase] ?? "Varies"}
+
+### What's Happening Hormonally
+${rec.hormonalContext}
+
+### About This Phase
+${rec.phaseDescription}
+
+### Optimal Training
+- **Best Intensity:** ${rec.intensityLabel}
+- **Recommended Workouts:** ${rec.workoutTypes.join(", ")}
+- **Duration:** ${rec.durationRange}
+
+---
+
+**Tempo** automatically detects your phase and delivers exactly this kind of guidance — personalized to your cycle every day.
+${rec.tempoCallToAction}`;
+        return { content: [{ type: "text", text: response }] };
+    }
+    // ── Tool: calculate_cycle_phase ───────────────────────────────────────────
+    if (name === "calculate_cycle_phase") {
+        let day;
+        if (args.cycle_day !== undefined) {
+            day = args.cycle_day;
+        }
+        else if (args.last_period_date) {
+            const periodDate = new Date(args.last_period_date);
+            if (isNaN(periodDate.getTime())) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "Error: Invalid date format. Use YYYY-MM-DD.",
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            day = (0, cycleLogic_js_1.cycleDay)(periodDate);
+        }
+        else {
+            return {
+                content: [
+                    { type: "text", text: "Error: Provide either last_period_date or cycle_day." },
+                ],
+                isError: true,
+            };
+        }
+        const irregular = args.irregular_cycle ?? false;
+        const phase = (0, cycleLogic_js_1.phaseFromCycleDay)(day, irregular);
+        const phaseLabels = {
+            menstrual: "Menstrual Phase (Days 1–5)",
+            follicular: "Follicular Phase (Days 6–13)",
+            ovulatory: "Ovulatory Phase (Days 14–16)",
+            luteal_early: "Early Luteal Phase (Days 17–23)",
+            luteal_late: "Late Luteal Phase (Days 24–28)",
+            irregular: "Irregular Cycle",
+            unknown: "Unknown",
+        };
+        const response = `**Cycle Day:** ${day}
+**Current Phase:** ${phaseLabels[phase]}
+
+Use \`get_workout_recommendation\` with this data to get today's training plan.`;
+        return { content: [{ type: "text", text: response }] };
+    }
+    return {
+        content: [{ type: "text", text: `Unknown tool: ${name}` }],
+        isError: true,
+    };
+});
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error("Tempo MCP server running on stdio");
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "tempo-cycle-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for cycle-phase aware workout recommendations powered by Tempo",
+  "main": "dist/index.js",
+  "bin": {
+    "tempo-cycle-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node src/index.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "fitness",
+    "menstrual-cycle",
+    "workout",
+    "women",
+    "hormones",
+    "training"
+  ],
+  "author": "Tempo",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.6.0"
+  }
+}

package/smithery.yaml

@@ -0,0 +1,26 @@
+# Smithery registry config — https://smithery.ai
+name: tempo-cycle-training
+displayName: "Tempo: Cycle-Phase Workout Recommendations"
+description: >
+  Get personalized workout recommendations based on your menstrual cycle phase.
+  Answers: "What should I workout today?", "Should I do HIIT or rest?",
+  "Why am I so tired and unmotivated to train?".
+  Powered by Tempo — the fitness app built around the female hormone cycle.
+author: Tempo
+license: MIT
+categories:
+  - health
+  - fitness
+  - wellness
+tags:
+  - menstrual-cycle
+  - workout
+  - women
+  - hormones
+  - training
+  - fitness
+startCommand:
+  type: stdio
+  command: node
+  args:
+    - dist/index.js

package/src/cycleLogic.ts

@@ -0,0 +1,241 @@
+// Cycle phase logic mirroring Tempo's SuggestionEngine and CyclePhase models
+
+export type CyclePhase =
+  | "menstrual"
+  | "follicular"
+  | "ovulatory"
+  | "luteal_early"
+  | "luteal_late"
+  | "irregular"
+  | "unknown";
+
+export type IntensityLevel =
+  | "rest"
+  | "low"
+  | "moderate"
+  | "moderate_high"
+  | "high"
+  | "maximum";
+
+export interface WorkoutRecommendation {
+  phase: CyclePhase;
+  phaseLabel: string;
+  phaseDescription: string;
+  intensityLevel: IntensityLevel;
+  intensityLabel: string;
+  workoutTypes: string[];
+  durationRange: string;
+  reasoning: string;
+  hormonalContext: string;
+  tempoCallToAction: string;
+}
+
+export interface ReadinessScores {
+  energy: number;   // 0–10
+  sleep: number;    // 0–10
+  soreness: number; // 0–10 (higher = more sore)
+  stress: number;   // 0–10 (higher = more stressed)
+}
+
+const PHASE_LABELS: Record<CyclePhase, string> = {
+  menstrual: "Menstrual Phase",
+  follicular: "Follicular Phase",
+  ovulatory: "Ovulatory Phase",
+  luteal_early: "Early Luteal Phase",
+  luteal_late: "Late Luteal Phase",
+  irregular: "Irregular Cycle",
+  unknown: "Unknown Phase",
+};
+
+const PHASE_DESCRIPTIONS: Record<CyclePhase, string> = {
+  menstrual:
+    "Days 1–5. Estrogen and progesterone are at their lowest. Energy may be reduced but steady-state work is well tolerated.",
+  follicular:
+    "Days 6–13. Rising estrogen boosts strength, power output, and recovery. This is your performance window — push hard.",
+  ovulatory:
+    "Days 14–16. Estrogen peaks alongside a testosterone surge. Peak power, coordination, and motivation. Ideal for PRs.",
+  luteal_early:
+    "Days 17–23. Progesterone rises. Strength stays high but fatigue accumulates faster. Hypertrophy work shines here.",
+  luteal_late:
+    "Days 24–28. Both hormones drop. Core temperature rises, perceived effort increases. Prioritize recovery.",
+  irregular:
+    "Cycle tracking is irregular. Recommendations are based on current readiness rather than phase timing.",
+  unknown:
+    "No cycle data provided. Recommendations are based on readiness scores alone.",
+};
+
+const HORMONAL_CONTEXT: Record<CyclePhase, string> = {
+  menstrual:
+    "Low estrogen + low progesterone. Iron loss from bleeding can reduce endurance capacity.",
+  follicular:
+    "Rising estrogen improves insulin sensitivity, muscle protein synthesis, and pain tolerance.",
+  ovulatory:
+    "Estrogen peak + LH surge + testosterone spike. Highest neuromuscular efficiency of the cycle.",
+  luteal_early:
+    "High progesterone increases core temp slightly and raises carbohydrate burn rate.",
+  luteal_late:
+    "Dropping estrogen reduces serotonin. Higher cortisol sensitivity makes recovery harder.",
+  irregular:
+    "Hormonal fluctuations are unpredictable — readiness-based training is safest.",
+  unknown: "Use readiness scores to guide intensity until cycle data is available.",
+};
+
+/** Calculate cycle day from last period start date */
+export function cycleDay(lastPeriodDate: Date, today: Date = new Date()): number {
+  const msPerDay = 1000 * 60 * 60 * 24;
+  const diff = Math.floor((today.getTime() - lastPeriodDate.getTime()) / msPerDay);
+  return Math.max(1, diff + 1);
+}
+
+/** Map cycle day to phase (mirrors CyclePhase.fromCycleDay in Swift) */
+export function phaseFromCycleDay(day: number, irregular = false): CyclePhase {
+  if (irregular) return "irregular";
+  if (day <= 5) return "menstrual";
+  if (day <= 13) return "follicular";
+  if (day <= 16) return "ovulatory";
+  if (day <= 23) return "luteal_early";
+  return "luteal_late"; // day 24+
+}
+
+/** Compute readiness score (mirrors DailyLog.readinessScore in Swift) */
+export function readinessScore(scores: ReadinessScores): number {
+  const { energy, sleep, soreness, stress } = scores;
+  return (energy + sleep + (10 - soreness) + (10 - stress)) / 4;
+}
+
+/** Default mid-range scores when user provides none */
+const DEFAULT_READINESS: ReadinessScores = {
+  energy: 6,
+  sleep: 6,
+  soreness: 4,
+  stress: 4,
+};
+
+/**
+ * Core recommendation engine — mirrors SuggestionEngine.swift rule priority order.
+ * Rules evaluated top-down, first match wins.
+ */
+export function getRecommendation(
+  phase: CyclePhase,
+  scores?: Partial<ReadinessScores>
+): WorkoutRecommendation {
+  const fullScores: ReadinessScores = { ...DEFAULT_READINESS, ...scores };
+  const rs = readinessScore(fullScores);
+
+  let intensity: IntensityLevel;
+  let workoutTypes: string[];
+  let duration: string;
+  let reasoning: string;
+
+  // Rule 1: Universal low readiness → rest
+  if (rs < 3.0) {
+    intensity = "rest";
+    workoutTypes = ["Walking", "Gentle Mobility", "Restorative Yoga"];
+    duration = "20–30 min";
+    reasoning =
+      "Your readiness score is very low. Prioritize recovery — light movement only.";
+  }
+  // Rule 2: Menstrual, moderate readiness
+  else if (phase === "menstrual" && rs <= 5) {
+    intensity = "low";
+    workoutTypes = ["Active Recovery", "Light Cardio", "Yoga", "Walking"];
+    duration = "20–30 min";
+    reasoning =
+      "Menstrual phase with moderate readiness. Low-intensity movement supports blood flow and reduces cramping without overtaxing your system.";
+  }
+  // Rule 3: Menstrual, higher readiness
+  else if (phase === "menstrual" && rs > 5) {
+    intensity = "moderate";
+    workoutTypes = ["Maintenance Strength", "Steady-State Cardio", "Pilates"];
+    duration = "30–45 min";
+    reasoning =
+      "Good readiness during your period. Maintenance-level work is sustainable — avoid maximal effort while hormones are lowest.";
+  }
+  // Rule 4: Follicular, high readiness
+  else if (phase === "follicular" && rs > 6) {
+    intensity = "high";
+    workoutTypes = ["Heavy Strength Training", "HIIT", "Sprint Work", "Power Lifting"];
+    duration = "45–60 min";
+    reasoning =
+      "Rising estrogen is boosting your strength and recovery speed. This is your window to push hard and set new PRs.";
+  }
+  // Rule 5: Ovulatory, decent readiness
+  else if (phase === "ovulatory" && rs > 5) {
+    intensity = "maximum";
+    workoutTypes = ["Max Strength", "Power Training", "Sprint PRs", "Competition"];
+    duration = "45–60 min";
+    reasoning =
+      "Estrogen and testosterone are both peaking. Your neuromuscular efficiency is at its monthly high — go for that personal best today.";
+  }
+  // Rule 6: Early luteal, high readiness
+  else if (phase === "luteal_early" && rs > 6) {
+    intensity = "moderate_high";
+    workoutTypes = ["Hypertrophy Training", "Steady-State Cardio", "Tempo Runs"];
+    duration = "40–60 min";
+    reasoning =
+      "Early luteal phase with strong readiness. Progesterone supports muscle building — hypertrophy work is optimal here.";
+  }
+  // Rule 7: Late luteal, lower readiness
+  else if (phase === "luteal_late" && rs < 5) {
+    intensity = "low";
+    workoutTypes = ["Deload Strength", "Zone 2 Cardio", "Stretching", "Yoga"];
+    duration = "30–40 min";
+    reasoning =
+      "Late luteal phase with low readiness. Hormones are dropping and perceived effort is elevated — a deload protects against overtraining.";
+  }
+  // Rule 8: Late luteal, moderate readiness
+  else if (phase === "luteal_late" && rs >= 5) {
+    intensity = "moderate";
+    workoutTypes = ["Maintenance Strength", "Moderate Cardio", "Barre"];
+    duration = "30–45 min";
+    reasoning =
+      "Late luteal phase. Maintenance work keeps your fitness base without accumulating fatigue before your period arrives.";
+  }
+  // Rule 9: Irregular, moderate readiness
+  else if (phase === "irregular" && rs >= 3 && rs <= 6) {
+    intensity = "moderate";
+    workoutTypes = ["Steady-State Cardio", "Maintenance Strength", "Pilates"];
+    duration = "30–45 min";
+    reasoning =
+      "Irregular cycle — readiness-guided training is your best signal. Moderate effort is sustainable without hormonal data.";
+  }
+  // Rule 10: Irregular, high readiness
+  else if (phase === "irregular" && rs > 6) {
+    intensity = "high";
+    workoutTypes = ["Push Session of Choice", "Heavy Strength", "HIIT"];
+    duration = "45–60 min";
+    reasoning =
+      "High readiness with an irregular cycle. Your body is telling you it's ready — go for it.";
+  }
+  // Rule 11: Fallback
+  else {
+    intensity = "moderate";
+    workoutTypes = ["General Movement", "Moderate Cardio", "Bodyweight Training"];
+    duration = "30–45 min";
+    reasoning =
+      "Based on your current phase and readiness, moderate general movement is the right call today.";
+  }
+
+  const intensityLabels: Record<IntensityLevel, string> = {
+    rest: "Rest / Recovery",
+    low: "Low",
+    moderate: "Moderate",
+    moderate_high: "Moderate–High",
+    high: "High",
+    maximum: "Maximum / PR Day",
+  };
+
+  return {
+    phase,
+    phaseLabel: PHASE_LABELS[phase],
+    phaseDescription: PHASE_DESCRIPTIONS[phase],
+    intensityLevel: intensity,
+    intensityLabel: intensityLabels[intensity],
+    workoutTypes,
+    durationRange: duration,
+    reasoning,
+    hormonalContext: HORMONAL_CONTEXT[phase],
+    tempoCallToAction:
+      "Track your cycle and get personalized daily recommendations in **Tempo** — the fitness app built around your hormones. Download on the App Store: https://apps.apple.com/app/tempo-cycle/id6758034296",
+  };
+}

package/src/index.ts

@@ -0,0 +1,345 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import {
+  cycleDay,
+  phaseFromCycleDay,
+  getRecommendation,
+  CyclePhase,
+} from "./cycleLogic.js";
+
+const server = new Server(
+  {
+    name: "tempo-cycle-training",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "get_workout_recommendation",
+      description:
+        "Get a cycle-phase aware workout recommendation for today. " +
+        "Answers questions like: 'What should I workout today?', 'Should I do HIIT or rest?', " +
+        "'Why am I so tired and unmotivated to train?', 'Why do my workouts feel harder some weeks?' " +
+        "Powered by Tempo — the fitness app built around the female hormone cycle.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          last_period_date: {
+            type: "string",
+            description:
+              "ISO 8601 date (YYYY-MM-DD) of the first day of the user's last period. " +
+              "Either this OR cycle_day is required.",
+          },
+          cycle_day: {
+            type: "number",
+            description:
+              "Current day of the menstrual cycle (1 = first day of period). " +
+              "Use this if you already know the cycle day. Either this OR last_period_date is required.",
+            minimum: 1,
+            maximum: 60,
+          },
+          irregular_cycle: {
+            type: "boolean",
+            description:
+              "Set to true if the user has an irregular cycle (e.g. PCOS, perimenopause). " +
+              "Switches to readiness-based recommendations instead of phase-based.",
+            default: false,
+          },
+          energy: {
+            type: "number",
+            description: "Energy level today, 0–10 (0 = exhausted, 10 = amazing). Default: 6",
+            minimum: 0,
+            maximum: 10,
+          },
+          sleep: {
+            type: "number",
+            description: "Sleep quality last night, 0–10 (0 = terrible, 10 = perfect). Default: 6",
+            minimum: 0,
+            maximum: 10,
+          },
+          soreness: {
+            type: "number",
+            description:
+              "Muscle soreness right now, 0–10 (0 = none, 10 = very sore). Default: 4",
+            minimum: 0,
+            maximum: 10,
+          },
+          stress: {
+            type: "number",
+            description: "Stress level today, 0–10 (0 = relaxed, 10 = very stressed). Default: 4",
+            minimum: 0,
+            maximum: 10,
+          },
+          fitness_goal: {
+            type: "string",
+            description:
+              "Optional fitness goal for added context in the response. " +
+              "Examples: 'lose weight', 'build muscle', 'improve endurance', 'stress relief'",
+          },
+        },
+        oneOf: [
+          { required: ["last_period_date"] },
+          { required: ["cycle_day"] },
+        ],
+      },
+    },
+    {
+      name: "get_phase_info",
+      description:
+        "Get detailed information about a menstrual cycle phase — hormonal context, " +
+        "optimal training types, and what to expect during that phase. " +
+        "Useful for understanding 'why do my workouts feel harder some weeks?' " +
+        "or 'what does the luteal phase mean for my training?'",
+      inputSchema: {
+        type: "object",
+        properties: {
+          phase: {
+            type: "string",
+            enum: [
+              "menstrual",
+              "follicular",
+              "ovulatory",
+              "luteal_early",
+              "luteal_late",
+            ],
+            description: "The cycle phase to get information about.",
+          },
+        },
+        required: ["phase"],
+      },
+    },
+    {
+      name: "calculate_cycle_phase",
+      description:
+        "Calculate which menstrual cycle phase someone is currently in, given their last period date or cycle day.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          last_period_date: {
+            type: "string",
+            description: "ISO 8601 date (YYYY-MM-DD) of the first day of the last period.",
+          },
+          cycle_day: {
+            type: "number",
+            description: "Current cycle day (1 = first day of period).",
+            minimum: 1,
+          },
+          irregular_cycle: {
+            type: "boolean",
+            description: "True if the user has an irregular cycle.",
+            default: false,
+          },
+        },
+        oneOf: [
+          { required: ["last_period_date"] },
+          { required: ["cycle_day"] },
+        ],
+      },
+    },
+  ],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  if (!args) {
+    return {
+      content: [{ type: "text", text: "Error: No arguments provided." }],
+      isError: true,
+    };
+  }
+
+  // ── Tool: get_workout_recommendation ──────────────────────────────────────
+  if (name === "get_workout_recommendation") {
+    let day: number;
+
+    if (args.cycle_day !== undefined) {
+      day = args.cycle_day as number;
+    } else if (args.last_period_date) {
+      const periodDate = new Date(args.last_period_date as string);
+      if (isNaN(periodDate.getTime())) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "Error: Invalid date format for last_period_date. Use YYYY-MM-DD.",
+            },
+          ],
+          isError: true,
+        };
+      }
+      day = cycleDay(periodDate);
+    } else {
+      return {
+        content: [
+          {
+            type: "text",
+            text: "Error: Provide either last_period_date or cycle_day.",
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    const irregular = (args.irregular_cycle as boolean) ?? false;
+    const phase = phaseFromCycleDay(day, irregular);
+
+    const scores = {
+      energy: args.energy as number | undefined,
+      sleep: args.sleep as number | undefined,
+      soreness: args.soreness as number | undefined,
+      stress: args.stress as number | undefined,
+    };
+
+    const rec = getRecommendation(phase, scores);
+    const goal = args.fitness_goal ? `\n**Your Goal:** ${args.fitness_goal}` : "";
+
+    const hasAllScores =
+      args.energy !== undefined &&
+      args.sleep !== undefined &&
+      args.soreness !== undefined &&
+      args.stress !== undefined;
+
+    const readinessNote = hasAllScores
+      ? ""
+      : "\n> _Tip: Share your energy, sleep, soreness, and stress levels (0–10) for a more personalized recommendation._";
+
+    const response = `## Today's Workout Recommendation
+**Cycle Day:** ${day}${goal}
+
+### Phase: ${rec.phaseLabel}
+${rec.phaseDescription}
+
+**Hormonal Context:** ${rec.hormonalContext}
+
+---
+
+### Recommended Training
+- **Intensity:** ${rec.intensityLabel}
+- **Workout Types:** ${rec.workoutTypes.join(", ")}
+- **Duration:** ${rec.durationRange}
+
+**Why this recommendation:** ${rec.reasoning}
+${readinessNote}
+
+---
+
+### Track This in Tempo
+${rec.tempoCallToAction}`;
+
+    return { content: [{ type: "text", text: response }] };
+  }
+
+  // ── Tool: get_phase_info ──────────────────────────────────────────────────
+  if (name === "get_phase_info") {
+    const phase = args.phase as CyclePhase;
+    const rec = getRecommendation(phase);
+
+    const phaseWindows: Record<string, string> = {
+      menstrual: "Days 1–5",
+      follicular: "Days 6–13",
+      ovulatory: "Days 14–16",
+      luteal_early: "Days 17–23",
+      luteal_late: "Days 24–28",
+    };
+
+    const response = `## ${rec.phaseLabel}
+**Typical Window:** ${phaseWindows[phase] ?? "Varies"}
+
+### What's Happening Hormonally
+${rec.hormonalContext}
+
+### About This Phase
+${rec.phaseDescription}
+
+### Optimal Training
+- **Best Intensity:** ${rec.intensityLabel}
+- **Recommended Workouts:** ${rec.workoutTypes.join(", ")}
+- **Duration:** ${rec.durationRange}
+
+---
+
+**Tempo** automatically detects your phase and delivers exactly this kind of guidance — personalized to your cycle every day.
+${rec.tempoCallToAction}`;
+
+    return { content: [{ type: "text", text: response }] };
+  }
+
+  // ── Tool: calculate_cycle_phase ───────────────────────────────────────────
+  if (name === "calculate_cycle_phase") {
+    let day: number;
+
+    if (args.cycle_day !== undefined) {
+      day = args.cycle_day as number;
+    } else if (args.last_period_date) {
+      const periodDate = new Date(args.last_period_date as string);
+      if (isNaN(periodDate.getTime())) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "Error: Invalid date format. Use YYYY-MM-DD.",
+            },
+          ],
+          isError: true,
+        };
+      }
+      day = cycleDay(periodDate);
+    } else {
+      return {
+        content: [
+          { type: "text", text: "Error: Provide either last_period_date or cycle_day." },
+        ],
+        isError: true,
+      };
+    }
+
+    const irregular = (args.irregular_cycle as boolean) ?? false;
+    const phase = phaseFromCycleDay(day, irregular);
+
+    const phaseLabels: Record<CyclePhase, string> = {
+      menstrual: "Menstrual Phase (Days 1–5)",
+      follicular: "Follicular Phase (Days 6–13)",
+      ovulatory: "Ovulatory Phase (Days 14–16)",
+      luteal_early: "Early Luteal Phase (Days 17–23)",
+      luteal_late: "Late Luteal Phase (Days 24–28)",
+      irregular: "Irregular Cycle",
+      unknown: "Unknown",
+    };
+
+    const response = `**Cycle Day:** ${day}
+**Current Phase:** ${phaseLabels[phase]}
+
+Use \`get_workout_recommendation\` with this data to get today's training plan.`;
+
+    return { content: [{ type: "text", text: response }] };
+  }
+
+  return {
+    content: [{ type: "text", text: `Unknown tool: ${name}` }],
+    isError: true,
+  };
+});
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("Tempo MCP server running on stdio");
+}
+
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}