intervals-kit 0.1.1__tar.gz

intervals_kit-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,77 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run tests
+        run: uv run pytest
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          python-version: "3.12"
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    needs: publish-testpypi
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

intervals_kit-0.1.1/.github/workflows/test.yml

@@ -0,0 +1,28 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run tests
+        run: uv run pytest

intervals_kit-0.1.1/.gitignore

@@ -0,0 +1,19 @@
+# Credentials — never commit
+.env
+
+# Virtual environment
+.venv/
+
+# Build artifacts
+dist/
+*.egg-info/
+
+# IDE
+.idea/
+.vscode/
+
+# Python
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/

intervals_kit-0.1.1/.python-version

@@ -0,0 +1 @@
+3.12

intervals_kit-0.1.1/CLAUDE.md

@@ -0,0 +1,105 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this project is
+
+A Python package providing an MCP server and CLI for the Intervals.ICU REST API. See `SPECIFICATIONS.md` for the architecture spec (used to guide adding new endpoints) and `src/intervals_kit/cli_tools.md` for the full CLI reference.
+
+## Commands
+
+```bash
+# Setup (first time)
+uv sync
+
+# Run MCP server
+uv run intervals-icu-mcp
+
+# Run CLI
+uv run intervals-icu-tools --help
+
+# Run all tests
+uv run pytest
+
+# Run a single test
+uv run pytest tests/test_service.py -k test_name
+
+# Run integration tests (real API, requires API key set)
+uv run pytest -m integration
+
+# Build for publishing
+uv build
+```
+
+## Build sequence
+
+Follow this exact order — each phase depends on the previous one importing cleanly:
+
+1. **Phase 1 (Skeleton):** Create dirs, `.python-version`, `pyproject.toml`, run `uv sync`
+2. **Phase 2 (Core):** `errors.py` → `models.py` → `config.py` → `client.py` → `exporters.py` → `service.py`
+   - Verify: `uv run python -c "from myapi_tools.service import MyAPIService; print('ok')"`
+3. **Phase 3 (MCP):** `mcp_server.py`
+   - Verify: `uv run intervals-icu-tools-mcp &; kill %1`
+4. **Phase 4 (CLI):** `cli/__init__.py` → `cli/main.py` → `cli/commands.py`
+   - Verify: `uv run intervals-icu-tools --help`
+5. **Phase 5 (Docs & Tests):** `cli_tools.md`, `tests/`
+6. **Phase 6 (Publish):** `uv build && uv publish`
+
+## Architecture
+
+Three interfaces, one service layer:
+
+```
+MCP Tools (FastMCP)  ──┐
+CLI Commands (Click)  ──┼──▶  service.py  ──▶  client.py  ──▶  Intervals.ICU REST API
+Library API (import) ──┘
+```
+
+- **`service.py`** — all business logic lives here. MCP tools and CLI commands are thin wrappers.
+- **`client.py`** — low-level `httpx` async client (auth, retry, config).
+- **`models.py`** — Pydantic models for API request/response shapes.
+- **`config.py`** — priority chain: env vars > `~/.config/.../config.toml` > defaults.
+- **`exporters.py`** — output formatting (JSON, CSV, markdown).
+- **`mcp_server.py`** — FastMCP wrapper; registers tools calling service methods.
+- **`cli/`** — Click group + commands; thin wrappers calling service methods.
+- **`__init__.py`** — exports only the core layer (`MyAPIService`, `ApiConfig`, models, errors). Never import `mcp_server` or `cli` here.
+
+## Key design rules
+
+1. ALL business logic goes in `service.py`. MCP tools and CLI are thin wrappers.
+2. ALL features are exposed via CLI, MCP, AND as importable Python functions.
+3. MCP tools return small structured data (<100 items, <50KB) — fits in LLM context.
+4. CLI commands handle large/binary data (streams to disk, no size cap).
+5. MCP tool docstrings must include: what it does, when to use it, return shape, and the exact `uvx` CLI command for handoff to bulk/binary operations.
+6. CLI prints structured, parseable output — no progress bars, no ANSI color codes.
+7. MCP tools return error dicts on failure (never raise). CLI prints to stderr and exits with structured codes: 0=success, 1=auth/general, 2=rate limit, 3=download, 4=not found.
+
+## Deciding what gets an MCP tool vs CLI command
+
+| Endpoint type | MCP tool | CLI command |
+|---|---|---|
+| Small structured response (<100 items) | Yes (full data) | Yes |
+| Large dataset (paginated, bulk) | Yes (capped preview, limit=20) | Yes (full download) |
+| Binary/large blob (PDF, ZIP) | Yes (metadata only) | Yes (streaming download) |
+| Async server-side job | Yes (start job, return job ID) | Yes (start + poll + download) |
+| Mutating (POST/PUT/DELETE) | Yes | Yes |
+| Auth/config/health | No — handle in `client.py` | No |
+
+## Testing
+
+- Mock at the HTTP boundary with `respx`, not at the service layer — tests cover the full stack.
+- Test error paths explicitly (LLM relies on structured error output).
+- Test that all MCP tools have docstrings (missing docstring = silent LLM discoverability failure).
+- Test CLI exit codes (they are part of the contract with calling LLM agents).
+- No real API calls in CI — use `respx` mocks. Real API tests use `@pytest.mark.integration`.
+
+## Technology choices
+
+| Package | Role | Notes |
+|---|---|---|
+| `fastmcp>=3.0,<4` | MCP server | Import as `from fastmcp import FastMCP`, not the SDK-bundled version |
+| `httpx>=0.27` | HTTP client | Async-native; use `respx` to mock in tests |
+| `pydantic>=2.0` | Data models | Already a transitive dep of FastMCP |
+| `click>=8.0` | CLI | Lighter than `typer` (no `rich`/`shellingham` pull) |
+| `hatchling` | Build backend | Used via `uv build` |
+| `pytest-asyncio` | Async tests | Use `@pytest.mark.asyncio` on async test functions |

intervals_kit-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Josua Sassen and Helge Esch
+
+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.

intervals_kit-0.1.1/PKG-INFO

@@ -0,0 +1,281 @@
+Metadata-Version: 2.4
+Name: intervals-kit
+Version: 0.1.1
+Summary: MCP server, CLI, and Python library for the Intervals.ICU fitness tracking API
+Project-URL: Homepage, https://github.com/jrsassen/intervals-kit
+Project-URL: Repository, https://github.com/jrsassen/intervals-kit
+Project-URL: Issues, https://github.com/jrsassen/intervals-kit/issues
+Author: Josua Sassen, Helge Esch
+License: MIT License
+        
+        Copyright (c) 2025 Josua Sassen and Helge Esch
+        
+        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.
+License-File: LICENSE
+Keywords: api,cycling,fitness,intervals,intervals.icu,mcp,triathlon
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: fastmcp<4,>=3.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Description-Content-Type: text/markdown
+
+# intervals-kit
+
+MCP server, CLI, and Python library for the [Intervals.ICU](https://intervals.icu) fitness tracking API. Exposes activity data (power curves, HR curves, streams, intervals, segments, file downloads) to AI assistants via the Model Context Protocol, and as a command-line tool for scripting and bulk data access.
+
+## Requirements
+
+- Python 3.10+
+- [uv](https://docs.astral.sh/uv/getting-started/installation/) — recommended for running the package
+
+## Installation
+
+```bash
+pip install intervals-kit
+```
+
+Or with uv:
+
+```bash
+uv pip install intervals-kit
+```
+
+## Configuration
+
+The package reads credentials from environment variables or a config file.
+
+**Environment variables (recommended):**
+
+```bash
+export INTERVALS_API_KEY=your_api_key      # From intervals.icu → Settings → API Key
+export INTERVALS_ATHLETE_ID=iXXXXXX       # Your athlete ID (visible in the URL when logged in)
+```
+
+**Config file** (`~/.config/intervals-kit/config.toml`):
+
+```toml
+api_key = "your_api_key"
+athlete_id = "iXXXXXX"
+base_url = "https://intervals.icu"   # optional
+```
+
+Environment variables take precedence over the config file.
+
+## Usage as MCP Server (Claude Code / Claude Desktop)
+
+The easiest way — no installation needed:
+
+```json
+{
+  "mcpServers": {
+    "intervals-icu": {
+      "command": "uvx",
+      "args": ["intervals-kit"],
+      "env": {
+        "INTERVALS_API_KEY": "your_api_key",
+        "INTERVALS_ATHLETE_ID": "iXXXXXX"
+      }
+    }
+  }
+}
+```
+
+Once configured, Claude can directly query your training data:
+
+> "How many rides did I do last month?"
+> "What was my best 5-minute power in March?"
+> "Download my activities as a CSV for Q1 2025."
+
+### Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_activities` | List activities for a date range |
+| `get_activity` | Get full details for a single activity |
+| `search_activities` | Search by name or tag |
+| `update_activity` | Update name, description, type, or RPE |
+| `get_activity_intervals` | Get lap/split data |
+| `get_activity_streams` | Get second-by-second time-series (power, HR, cadence, …) |
+| `get_power_curve` | Mean-maximal power curve for an activity |
+| `get_hr_curve` | Heart rate curve for an activity |
+| `get_pace_curve` | Pace curve for running/swimming |
+| `get_best_efforts` | Best efforts detected in an activity |
+| `get_activity_segments` | Matched Strava/Intervals segments |
+| `get_activity_map` | GPS track (lat/lon) |
+| `get_athlete_power_curves` | Best power curves across a date range |
+| `get_athlete_hr_curves` | Best HR curves across a date range |
+
+For large data (streams >1 hour, CSV exports, binary files) the MCP tools return metadata and tell Claude to use the CLI for the actual download.
+
+## Usage as CLI
+
+```bash
+uvx --from intervals-kit intervals-icu-tools --help
+```
+
+### Activity commands
+
+```bash
+# List activities for a date range (JSON to stdout)
+uvx --from intervals-kit intervals-icu-tools list-activities --oldest 2025-01-01 --newest 2025-03-31
+
+# Save to a file instead of stdout
+uvx --from intervals-kit intervals-icu-tools -o ./data list-activities --oldest 2025-01-01 --newest 2025-03-31
+
+# Get a single activity
+uvx --from intervals-kit intervals-icu-tools get-activity i136292802
+
+# Search by name or tag (# prefix for exact tag match)
+uvx --from intervals-kit intervals-icu-tools search-activities "long ride"
+uvx --from intervals-kit intervals-icu-tools search-activities "#race" --full
+
+# Update fields
+uvx --from intervals-kit intervals-icu-tools update-activity i136292802 --perceived-exertion 7 --description "Felt strong"
+```
+
+### Sub-resource commands
+
+```bash
+# Lap/interval data
+uvx --from intervals-kit intervals-icu-tools get-intervals i136292802
+
+# Time-series streams (specify types to limit size)
+uvx --from intervals-kit intervals-icu-tools -o ./data get-streams i136292802 --types watts,heartrate,cadence
+
+# Power / HR / pace curves
+uvx --from intervals-kit intervals-icu-tools get-power-curve i136292802
+uvx --from intervals-kit intervals-icu-tools get-hr-curve i136292802
+uvx --from intervals-kit intervals-icu-tools get-pace-curve i136292816  # running activity
+
+# Best efforts, segments, GPS map
+uvx --from intervals-kit intervals-icu-tools get-best-efforts i136292802
+uvx --from intervals-kit intervals-icu-tools get-segments i136292802
+uvx --from intervals-kit intervals-icu-tools -o ./data get-activity-map i136292802
+```
+
+### File download commands
+
+```bash
+# Download original upload / FIT / GPX file
+uvx --from intervals-kit intervals-icu-tools -o ./data download-activity-file i136292802 --type fit
+uvx --from intervals-kit intervals-icu-tools -o ./data download-activity-file i136292802 --type gpx
+
+# Bulk CSV export for a date range
+uvx --from intervals-kit intervals-icu-tools -o ./data download-activities-csv --oldest 2025-01-01 --newest 2025-03-31
+```
+
+### Aggregate curves
+
+```bash
+# Best power/HR/pace curves across all activities in a date range
+uvx --from intervals-kit intervals-icu-tools get-athlete-power-curves --oldest 2025-01-01 --newest 2025-03-31
+uvx --from intervals-kit intervals-icu-tools get-athlete-hr-curves --oldest 2025-01-01 --newest 2025-03-31
+uvx --from intervals-kit intervals-icu-tools get-athlete-pace-curves --oldest 2025-01-01 --newest 2025-03-31
+```
+
+### Global options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-o / --output-dir` | `.` (stdout) | Directory to save output files |
+| `-f / --format` | `json` | Output format: `json` or `csv` |
+
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Auth error or general API error |
+| 2 | Rate limit exceeded (retryable) |
+| 3 | Download / network error (retryable) |
+| 4 | Resource not found |
+
+## Usage as Python Library
+
+```python
+import asyncio
+from intervals_kit import IntervalsService, load_config
+
+async def main():
+    svc = IntervalsService(load_config())
+
+    # List March 2025 activities
+    activities = await svc.list_activities("2025-03-01", "2025-03-31")
+    rides = [a for a in activities if a.type == "Ride"]
+    print(f"Rides: {len(rides)}, Runs: {len(activities) - len(rides)}")
+
+    # Get power curve for first ride
+    if rides:
+        curve = await svc.get_power_curve(rides[0].id)
+        print(f"Power curve keys: {list(curve.keys())}")
+
+asyncio.run(main())
+```
+
+## Development
+
+```bash
+# Clone and install with dev dependencies
+git clone https://github.com/jrsassen/intervals-kit
+cd intervals-kit
+uv sync
+
+# Run tests
+uv run pytest
+
+# Run a single test
+uv run pytest tests/test_service.py -k test_name
+
+# Run integration tests against the real API (requires credentials)
+uv run pytest -m integration
+```
+
+## Architecture
+
+Three interfaces share one service layer — see `SPECIFICATIONS.md` for the full architecture and `src/intervals_kit/cli_tools.md` for the complete CLI reference intended for LLM agents.
+
+```
+MCP Tools (FastMCP)  ──┐
+CLI Commands (Click)  ──┼──▶  service.py  ──▶  client.py  ──▶  Intervals.ICU API
+Python import        ──┘
+```
+
+Source layout:
+
+```
+src/intervals_kit/
+├── errors.py        # Exception types
+├── models.py        # Pydantic models
+├── config.py        # Configuration loading
+├── client.py        # HTTP client (auth, error mapping, streaming)
+├── exporters.py     # JSON serialization
+├── service.py       # All business logic
+├── mcp_server.py    # FastMCP tool definitions
+└── cli/             # Click command definitions
+```