# intervals.icu Desktop + MCP Server

[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://github.com/kylemabry95/intervals.icu_to_claude_mcp_connection)
[![Python](https://img.shields.io/badge/python-3.10+-green.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
[![API Coverage](https://img.shields.io/badge/API%20coverage-~95%25-brightgreen.svg)](API_REFERENCE.md)
[![Status](https://img.shields.io/badge/status-production%20ready-brightgreen.svg)](.)

> 🏃 **Your AI coaching assistant for intervals.icu training data**

A standalone desktop application + Model Context Protocol (MCP) server that gives you **complete access** to [intervals.icu](https://intervals.icu) training data through Claude AI. Manage every aspect of your training through natural conversation — from logging wellness data to organizing workout libraries to analyzing fitness trends.

---

## �️ Standalone Desktop Application

A self-contained, production-ready desktop application for macOS and Windows. **No manual Claude Desktop configuration needed.** Just install, authenticate, and start asking Claude about your training data.

### 📥 Downloads (v1.0.0)

**✅ macOS** (Ready to download):

- 📦 [IntervalsICU-1.0.0.dmg](dist/macos/IntervalsICU-1.0.0.dmg) (33 MB) — Ready for installation
- 📋 [Build Details](dist/macos/BUILD_MANIFEST.md) — Build information and requirements

#### 🚀 Seamless One-Click Installation

The DMG includes an automated **`install.sh`** script that handles everything automatically:

```bash
# 1. Mount the DMG (or double-click in Finder)
hdiutil attach IntervalsICU-1.0.0.dmg

# 2. Run the install script from the mounted volume
/Volumes/IntervalsICU/install.sh
# Or simply double-click install.sh in Finder
```

The script automatically:

- ✅ Detects and validates the app bundle
- ✅ Copies to `/Applications` folder
- ✅ Removes Gatekeeper quarantine attribute (eliminates "can't scan for malware" warnings)
- ✅ Verifies installation completeness
- ✅ Provides helpful error messages if issues occur

**Installation options**:

```bash
# Standard installation to /Applications
./install.sh

# Custom destination folder
./install.sh --dest ~/Desktop/Apps

# Force replacement if app already exists
./install.sh --force

# Verbose output for troubleshooting
./install.sh --verbose

# Show help
./install.sh --help
```

#### ⚙️ Manual Installation (Alternative)

If you prefer to install manually:

1. Mount the DMG file (double-click)
2. Drag `IntervalsICU.app` to your Applications folder
3. Resolve Gatekeeper warnings (see troubleshooting below)

**Troubleshooting – "Can't be scanned for malware" Error**:

If you see a macOS warning that the app "can't be opened because it can't be scanned for malware":

**Option 1 — Quick Fix (Recommended):**

```bash
# Remove the quarantine attribute (one-time command)
xattr -d com.apple.quarantine /Applications/IntervalsICU.app
```

**Option 2 — Using the Fix Script (from DMG):**

```bash
# From the mounted DMG, run the provided fix script
/Volumes/IntervalsICU/fix-gatekeeper.sh /Applications/IntervalsICU.app
```

**Option 3 — Manual Trust:**

1. Right-click `IntervalsICU.app` and select "Open"
2. Click "Open" in the security dialog (one-time prompt)
3. App will be added to trusted apps

**Windows** (Coming soon): NSIS installer in development

### ✨ Key Features

- 🔐 Secure credential storage via OS-native Keychain (macOS) / Credential Manager (Windows)
- 💬 Conversational interface with Claude for natural-language training queries
- ⚙️ In-app settings management with API key updates and log viewing
- 🔄 Automatic update checking for new releases
- 📊 Performance monitoring and latency tracking
- 🎯 Context-aware help system with error guidance
- 🔒 99.5% uptime SLO with process resilience

### Getting Started

```bash
# 1. Install dependencies
pip install -r requirements.txt

# 2. Configure credentials (interactive on first launch)
# Or use environment variables:
export INTERVALS_API_KEY="your_key_here"
export INTERVALS_ATHLETE_ID="i230309"
export ANTHROPIC_API_KEY="sk-ant-..."

# 3. Launch the desktop app
python -m desktop_app.main
```

### Build & Deploy

**macOS** — ✅ Build Complete

The macOS distribution includes a seamless one-click installation experience:

**Distribution Artifacts:**

- Distributable `.dmg` available: [IntervalsICU-1.0.0.dmg](dist/macos/IntervalsICU-1.0.0.dmg)
- Includes `install.sh` — Automated installation script (handles Gatekeeper quarantine removal)
- Includes `fix-gatekeeper.sh` — Manual Gatekeeper resolution tool
- Build branch: [`build/macos-dmg-v1.0.0`](https://github.com/kylemabry95/intervals.icu_to_claude_mcp_connection/tree/build/macos-dmg-v1.0.0)

**Build Toolchain:**

- PyInstaller 6.11.0+ — Bundles Python app to `.app` format
- create-dmg 1.3.3 — Creates professional DMG distribution
- Code signing with ad-hoc signatures + xattr Gatekeeper bypass

**To rebuild locally:**

```bash
chmod +x packaging/macos/build.sh
./packaging/macos/build.sh --version 1.0.0
# Add --sign --notarize for production builds (requires Developer ID)
```

**Build Output:**

- `dist/macos/IntervalsICU-1.0.0.dmg` (~32 MB, 64.7% compression)
- Contains: IntervalsICU.app, install.sh, fix-gatekeeper.sh, Applications symlink

**Installation Scripts:**

- [packaging/macos/install.sh](packaging/macos/install.sh) — Main automated installer (520 lines, 16 functions)
- [packaging/macos/fix-gatekeeper.sh](packaging/macos/fix-gatekeeper.sh) — Standalone Gatekeeper resolver
- [packaging/macos/README.md](packaging/macos/README.md) — Build documentation and workflow

**Windows** — In Development

- NSIS installer coming soon
- Build script: `packaging/windows/build.ps1`

### Testing

```bash
# Fast unit + integration tests
pytest tests/unit tests/integration -v

# Full test matrix
pytest tests/ -v -m "not e2e"

# All tests including e2e
pytest tests/ -v
```

---

## 📡 MCP Server for Claude Desktop

For users preferring Claude Desktop integration instead of the standalone app, the MCP server is also available:

```bash
# 1. Install and configure
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your intervals.icu and Anthropic credentials

# 2. Run the MCP server
python server.py

# 3. In Claude Desktop config, add to `mcpServers`:
# {
#   "intervals-icu": {
#     "command": "python",
#     "args": ["/path/to/server.py"],
#     "env": {
#       "INTERVALS_API_KEY": "your_key",
#       "INTERVALS_ATHLETE_ID": "i230309",
#       "INTERVALS_API_BASE_URL": "https://intervals.icu/api/v2"
#     }
#   }
# }
```

---

## 📖 Documentation

| File                                         | Purpose                                              |
| -------------------------------------------- | ---------------------------------------------------- |
| **README.md** _(this file)_                  | Feature overview, installation, and usage examples   |
| [QUICKSTART.md](QUICKSTART.md)               | Fast setup guide with troubleshooting tips           |
| [API_REFERENCE.md](API_REFERENCE.md)         | Complete endpoint specifications and parameters      |
| [CHANGELOG.md](CHANGELOG.md)                 | Version history and release notes                    |
| [EXTENSION_SUMMARY.md](EXTENSION_SUMMARY.md) | Technical architecture and implementation details    |
| [PROJECT_SUMMARY.md](PROJECT_SUMMARY.md)     | Project metrics, deliverables, and completion status |

---

## 🖼️ Pre-Download UI Preview

Feature 004 adds a desktop-first browser preview so users can try the core chat UX before downloading the DMG.

### Run locally

```bash
# from repository root
python -m http.server 8000
# then open http://localhost:8000/preview/
```

### What the preview includes

- Interactive chat demo with deterministic simulated responses
- Authentication walkthrough with API-key guidance links
- Settings/help feature tour
- Download CTAs for macOS and Windows
- Fallback banner when preview modules fail to initialize

### Validation tests

```bash
pytest tests/unit/test_preview_templates.py \
  tests/unit/test_preview_no_live_llm.py \
  tests/unit/test_preview_accessibility.py -v

pytest tests/integration/test_preview_*.py -v
pytest tests/e2e/test_preview_*.py -v
```

This preview intentionally uses sample data only and never accepts real credentials.

---

## 🎉 What's New in v1.0.0

**Standalone Desktop Application Release** — ✅ Now Available

A complete rewrite bundling the MCP server with a Claude-powered conversational UI for macOS and Windows:

**📦 Release Status:**

- ✅ macOS (.dmg) — **Available** — [Download v1.0.0](dist/macos/IntervalsICU-1.0.0.dmg)
- ⏳ Windows (NSIS) — In progress
- ✅ Source code — Tagged [v1.0.0](https://github.com/kylemabry95/intervals.icu_to_claude_mcp_connection/releases/tag/v1.0.0)

**Features:**

- ✅ **Standalone Desktop App** — No Claude Desktop configuration needed
- ✅ **Secure Credential Storage** — OS-native Keychain/Credential Manager integration
- ✅ **Conversational AI Interface** — Ask Claude natural-language questions about your training
- ✅ **36 API Tools** — Complete intervals.icu API coverage (~95%)
- ✅ **In-App Settings** — Update credentials, manage logging, check for updates
- ✅ **99.5% SLO** — Process resilience with uptime tracking
- ✅ **SC-004 Compliance** — Response quality evaluation (95% pass threshold)
- ✅ **Comprehensive Testing** — 40+ tests covering unit/integration/performance/evaluation
- ✅ **Production Packaging** — Code-signed releases for macOS; NSIS installers for Windows
- ✅ **Help & Guidance** — Context-aware tooltips, FAQ, error remediation

### v2.1.0 MCP Server (Foundation)

The underlying MCP server that powers the desktop app and can be used with Claude Desktop:

- ✅ Full CRUD operations on all major entities
- ✅ Workout Library management (9 tools)
- ✅ Training Plans support (4 tools)
- ✅ Coaching features (2 tools)
- ✅ Bulk operations and CSV export
- ✅ Complete documentation suite

### Comparison: Desktop App vs MCP-Only

| Feature                 | Desktop App (v1.0) | MCP Server (v2.1) |
| ----------------------- | ------------------ | ----------------- |
| **Total API Tools**     | 36                 | 36                |
| **Installation**        | ✅ One-click       | ⚠️ Manual config  |
| **Claude Integration**  | ✅ Built-in        | ✅ Claude Desktop |
| **Credential Storage**  | ✅ Secure (OS)     | ⚠️ .env file      |
| **Conversational UI**   | ✅ Yes             | ❌ No             |
| **Settings Management** | ✅ In-app          | ❌ Manual         |
| **Update Checking**     | ✅ Automatic       | ❌ Manual         |
| **Help & Guidance**     | ✅ Yes             | ❌ No             |
| **Uptime Monitoring**   | ✅ 99.5% SLO       | ❌ No             |
| **API Coverage**        | ~95%               | ~95%              |
| **Supported Endpoints** | All 36 tools       | All 36 tools      |

---

## ✨ API Features

### 👤 Athlete Profile

- **`get_athlete_profile`** — Retrieve FTP, weight, training zones, and account settings

### 💪 Wellness & Recovery

- **`get_wellness_data`** — Daily wellness metrics for a date range
- **`get_wellness_single`** — Wellness data for a specific date
- **`update_wellness`** — Update a single wellness entry
- **`update_wellness_bulk`** — Batch-update multiple wellness entries

Metrics covered: sleep quality and duration, HRV, resting heart rate, weight, body composition, subjective scores (fatigue, soreness, stress, motivation), readiness, CTL/ATL/TSB.

### 🚴 Training Activities

- **`get_activities`** — Workouts for a date range with key metrics
- **`get_activities_csv`** — Export all activities to CSV
- **`get_activity_details`** — Granular data including power/HR streams and detected intervals
- **`update_activity`** — Modify name, description, or type
- **`delete_activity`** — Remove an activity

### 📊 Fitness Analytics

- **`get_fitness_trends`** — CTL (Fitness), ATL (Fatigue), TSB (Form), and ramp rate
- **`get_power_curve`** — Best power efforts across different durations

### 📅 Calendar & Event Management

- **`get_calendars`** — List all calendars
- **`get_events`** — Planned races, workouts, and notes
- **`get_event`** — Details for a specific event
- **`create_event`** — Add races, workouts, or notes
- **`update_event`** — Modify an existing event
- **`delete_event`** — Remove a calendar event
- **`get_planned_workouts`** — Filter for upcoming scheduled training sessions

### 📚 Workout Library

- **`get_folders`** / **`create_folder`** / **`update_folder`** / **`delete_folder`**
- **`get_workouts`** / **`get_workout`** / **`create_workout`** / **`update_workout`** / **`delete_workout`**

### 📈 Training Plans

- **`get_training_plans`** / **`create_training_plan`** / **`update_training_plan`** / **`delete_training_plan`**

### 👥 Coaching

- **`get_coached_athletes`** — Athletes you coach with current fitness metrics
- **`get_wellness_summary`** — Wellness overview for coached athletes

---

## ⚡ Quick Stats

| Metric                   | Value                               |
| ------------------------ | ----------------------------------- |
| **Total API Tools**      | 36                                  |
| **API Coverage**         | ~95% of public intervals.icu APIs   |
| **CRUD Support**         | Full (Create, Read, Update, Delete) |
| **Code Lines**           | 1,106                               |
| **Documentation**        | 7 comprehensive guides              |
| **Supported Operations** | GET, POST, PUT, DELETE              |

---

## 🚀 Installation

> 💡 For a faster path, see [QUICKSTART.md](QUICKSTART.md). It includes platform-specific notes and a comprehensive troubleshooting section.

### Prerequisites

- Python 3.10 or higher
- [Claude Desktop](https://claude.ai/download)
- An active [intervals.icu](https://intervals.icu) account with API access

### 1. Get Your API Credentials

1. Log in to [intervals.icu](https://intervals.icu)
2. Navigate to **Settings → Developer Settings** (near the bottom)
3. Click **Generate API Key**
4. Note your athlete ID from the URL: `intervals.icu/athlete/{ATHLETE_ID}`  
   ⚠️ The athlete ID must include the `i` prefix (e.g., `i230309`)

### 2. Install Python Dependencies

```bash
cd intervals-icu-mcp
pip install -r requirements.txt
```

Or install in development mode:

```bash
pip install -e .
```

### 3. Test the Server (Recommended)

```bash
export INTERVALS_API_KEY="your_api_key"
export INTERVALS_ATHLETE_ID="your_athlete_id"   # e.g., i230309
export INTERVALS_API_BASE_URL="https://intervals.icu/api/v1"
python test_server.py
```

### 4. Configure Claude Desktop

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows:** `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "intervals-icu": {
      "command": "/usr/local/bin/python3",
      "args": ["/absolute/path/to/intervals-icu-mcp/server.py"],
      "env": {
        "INTERVALS_API_KEY": "your_api_key_here",
        "INTERVALS_ATHLETE_ID": "your_athlete_id_here",
        "INTERVALS_API_BASE_URL": "https://intervals.icu/api/v1"
      }
    }
  }
}
```

> **Important:** Use the full path to Python (e.g., `/usr/local/bin/python3`, not just `python`). On macOS, run `which python3` to find the correct path.

### 5. Restart Claude Desktop

Close and reopen Claude Desktop to load the MCP server.

---

## 💬 Usage Examples

### Wellness & Recovery

- "What's my HRV trend over the past 2 weeks?"
- "Update my wellness for today: weight 70 kg, HRV 65 ms, sleep quality 4"
- "Am I getting enough recovery based on my recent wellness data?"

### Training Analysis

- "Summarize my training volume for the past 30 days"
- "What were my hardest workouts this week?"
- "Export all my activities to CSV"

### Fitness Trends

- "What's my current fitness (CTL) and form (TSB)?"
- "Am I building fitness too quickly? Check my ramp rate"
- "When was I at peak fitness in the last 90 days?"

### Calendar & Planning

- "What races do I have coming up?"
- "Create a workout event for tomorrow: 60 min Z2 ride"
- "Delete the workout planned for next Tuesday"

### Workout Library

- "List all my workout folders"
- "Add a new workout: 4×8 min @ 110% FTP with 4 min rest"
- "Create a folder called 'VO2max Sessions'"

### Coaching

- "List all the athletes I coach"
- "What's the fitness trend for athlete John Doe?"

---

## 🔧 Troubleshooting

### Server not appearing in Claude Desktop

1. Verify the config file path is correct for your OS
2. Validate JSON syntax: `python -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json`
3. Confirm the absolute path to `server.py` is correct
4. Check that all three environment variables are present

### 401 / 403 Authentication Errors

- Confirm you're using v2.0.1 of `server.py` (includes the authentication fix)
- Ensure `INTERVALS_API_BASE_URL` is set
- Verify the athlete ID includes the `i` prefix
- Regenerate your API key in intervals.icu settings if needed

### No Data Returned

- Use `YYYY-MM-DD` date format
- Try a broader date range
- Confirm you have data in intervals.icu for the requested period

For a full troubleshooting guide, see [QUICKSTART.md](QUICKSTART.md).

---

## 🔒 Privacy & Security

- API credentials are stored locally in the Claude Desktop config file
- All requests go directly from your machine to intervals.icu — no third parties
- Claude processes responses locally on your machine
- Proper HTTP Basic Auth encoding (base64) for API key transmission
- All user-supplied IDs and dates are validated before use to prevent injection
- Client-side rate limiting (10 req/sec) protects against accidental API abuse
- HTTP requests enforce timeouts (30s request, 10s connect) and connection pool limits
- Error messages are sanitized — internal paths and stack traces are never exposed to the client
- `.gitignore` prevents accidental commit of `.env` files and credential configs

**Best practices:**

- Never share your API key or config file
- Protect the config file with restrictive permissions: `chmod 600 claude_desktop_config.json`
- Regenerate your API key if you suspect compromise

---

## 🤝 Contributing

~95% of the public intervals.icu API is already covered. Potential areas for future contribution include FIT/GPX/TCX file uploads, workout file downloads (`.zwo`, `.mrc`, `.erg`), real-time activity streams, advanced analytics, and webhook integration.

When contributing:

- Match existing code style and naming conventions
- Add docstrings to all new tools
- Update relevant documentation (README, QUICKSTART, API_REFERENCE)
- Add test cases to `test_server.py`

---

## 📋 Version History

### v2.1.0 - Security Hardening (March 2025)

- ✅ Fixed Basic Auth encoding and removed credential leakage in debug logs
- ✅ Added input validation (dates, IDs), rate limiting, HTTP timeouts
- ✅ Sanitized error responses; added `.gitignore` for secrets protection

### v2.0.0 - Major Release (March 2025)

- ✅ Extended from 8 to 36 API tools (4.5x increase)
- ✅ Added full CRUD operations on all major entities
- ✅ Workout Library management (9 new tools)
- ✅ Training Plans support (4 new tools)
- ✅ Coaching features (2 new tools)
- ✅ Bulk operations and CSV export
- ✅ Comprehensive documentation (7 guides)

### v1.0.0 - Initial Release (March 2025)

- ✅ Basic read-only access to 8 core APIs

See [CHANGELOG.md](CHANGELOG.md) for detailed version history.

---

## 📜 License

MIT License — free to use and modify for your own training analysis needs.

---

## 🙏 Credits

Built for the [Model Context Protocol](https://modelcontextprotocol.io/) to integrate intervals.icu with Claude Desktop.

- [intervals.icu](https://intervals.icu) — comprehensive training analytics platform
- [Anthropic](https://www.anthropic.com) — Claude and the MCP framework
- The intervals.icu community — API feedback and feature requests

---

## 💬 Support

- 📖 **Setup**: [QUICKSTART.md](QUICKSTART.md)
- 📚 **API Reference**: [API_REFERENCE.md](API_REFERENCE.md)
- 📋 **Changelog**: [CHANGELOG.md](CHANGELOG.md)
- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/kylemabry95/intervals.icu_to_claude_mcp_connection/issues)

---

_Made with ❤️ for athletes training smarter, not just harder_

⭐ Star this repo if it's useful for your training!

**v2.1.0** | [Changelog](CHANGELOG.md) | [Quick Start](QUICKSTART.md) | [API Reference](API_REFERENCE.md)