intervals-icu-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is an MCP (Model Context Protocol) server for Intervals.icu that provides 40+ tools, 1 resource, and 6 prompts for accessing training data, wellness metrics, and performance analysis through Claude and other LLMs.

Development Commands

Setup & Dependencies

# Install dependencies
make install

# Update dependencies
make update

# Setup authentication
make auth

Testing & Linting

# Run all pre-release checks (same as CI)
make can-release

# Run tests
make test

# Run specific test filter
make test/athlete         # runs tests matching "athlete"

# Run tests with verbose output
make test/verbose

# Lint with ruff and pyright
make lint

# Format code
make format

Running Locally

# Run the MCP server
make run

Docker

# Build Docker image
make docker/build

# Run Docker container
make docker/run

Architecture

Core Components

FastMCP Server (server.py)

• Entry point that initializes the FastMCP server
• Registers all tools, resources, and prompts
• Tools are imported from tools/ modules but registered in server.py
• Middleware is added before tools are registered

Middleware (middleware.py)

• ConfigMiddleware runs before every tool call
• Loads and validates Intervals.icu configuration from environment
• Injects ICUConfig into context state via ctx.set_state("config", config)
• Tools access config via ctx.get_state("config")

API Client (client.py)

• ICUClient is an async HTTP client using httpx
• Uses Basic Auth with username "API_KEY" and the API key as password
• All API methods are async and must be used with async context manager
• Handles error responses with ICUAPIError exceptions
• Default timeout is 30 seconds

Authentication (auth.py)

• ICUConfig loads credentials from .env file using pydantic-settings
• load_config() loads configuration from environment
• validate_credentials() checks if credentials are properly set
• Interactive setup script at scripts/setup_auth.py