fartlek-mcp 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Potentially problematic release.
This version of fartlek-mcp might be problematic. Click here for more details.
- fartlek_mcp-0.1.0/.cursor/mcp.json +8 -0
- fartlek_mcp-0.1.0/.dockerignore +21 -0
- fartlek_mcp-0.1.0/.env.example +2 -0
- fartlek_mcp-0.1.0/.github/workflows/ci.yml +18 -0
- fartlek_mcp-0.1.0/.github/workflows/release.yml +27 -0
- fartlek_mcp-0.1.0/.gitignore +48 -0
- fartlek_mcp-0.1.0/.mcp.json +8 -0
- fartlek_mcp-0.1.0/CLAUDE.md +48 -0
- fartlek_mcp-0.1.0/Dockerfile +20 -0
- fartlek_mcp-0.1.0/LICENSE +21 -0
- fartlek_mcp-0.1.0/PKG-INFO +166 -0
- fartlek_mcp-0.1.0/README.md +140 -0
- fartlek_mcp-0.1.0/ROADMAP.md +58 -0
- fartlek_mcp-0.1.0/claude_desktop_config.json +8 -0
- fartlek_mcp-0.1.0/docs/DESIGN.md +678 -0
- fartlek_mcp-0.1.0/fartlek/__init__.py +0 -0
- fartlek_mcp-0.1.0/fartlek/analytics/__init__.py +0 -0
- fartlek_mcp-0.1.0/fartlek/analytics/alerts.py +192 -0
- fartlek_mcp-0.1.0/fartlek/analytics/baselines.py +129 -0
- fartlek_mcp-0.1.0/fartlek/analytics/fusion.py +399 -0
- fartlek_mcp-0.1.0/fartlek/analytics/load.py +152 -0
- fartlek_mcp-0.1.0/fartlek/analytics/matcher.py +191 -0
- fartlek_mcp-0.1.0/fartlek/analytics/pmc.py +192 -0
- fartlek_mcp-0.1.0/fartlek/cli.py +225 -0
- fartlek_mcp-0.1.0/fartlek/health/__init__.py +0 -0
- fartlek_mcp-0.1.0/fartlek/health/adapters/__init__.py +0 -0
- fartlek_mcp-0.1.0/fartlek/health/adapters/garmin_connect.py +247 -0
- fartlek_mcp-0.1.0/fartlek/health/domain.py +20 -0
- fartlek_mcp-0.1.0/fartlek/health/exceptions.py +15 -0
- fartlek_mcp-0.1.0/fartlek/health/ports.py +25 -0
- fartlek_mcp-0.1.0/fartlek/health/service.py +252 -0
- fartlek_mcp-0.1.0/fartlek/mcp_server/__init__.py +0 -0
- fartlek_mcp-0.1.0/fartlek/mcp_server/context.py +188 -0
- fartlek_mcp-0.1.0/fartlek/mcp_server/server.py +298 -0
- fartlek_mcp-0.1.0/fartlek/mcp_server/tools/__init__.py +22 -0
- fartlek_mcp-0.1.0/fartlek/mcp_server/tools/activities.py +273 -0
- fartlek_mcp-0.1.0/fartlek/mcp_server/tools/activity.py +670 -0
- fartlek_mcp-0.1.0/fartlek/mcp_server/tools/athlete.py +300 -0
- fartlek_mcp-0.1.0/fartlek/mcp_server/tools/brief.py +479 -0
- fartlek_mcp-0.1.0/fartlek/mcp_server/tools/log_tool.py +257 -0
- fartlek_mcp-0.1.0/fartlek/mcp_server/tools/raw.py +317 -0
- fartlek_mcp-0.1.0/fartlek/mcp_server/tools/set_profile.py +197 -0
- fartlek_mcp-0.1.0/fartlek/mcp_server/tools/sync_tool.py +81 -0
- fartlek_mcp-0.1.0/fartlek/paths.py +26 -0
- fartlek_mcp-0.1.0/fartlek/render/__init__.py +0 -0
- fartlek_mcp-0.1.0/fartlek/render/renderer.py +287 -0
- fartlek_mcp-0.1.0/fartlek/store/__init__.py +3 -0
- fartlek_mcp-0.1.0/fartlek/store/schema.sql +168 -0
- fartlek_mcp-0.1.0/fartlek/store/store.py +361 -0
- fartlek_mcp-0.1.0/fartlek/sync/__init__.py +0 -0
- fartlek_mcp-0.1.0/fartlek/sync/engine.py +1059 -0
- fartlek_mcp-0.1.0/pyproject.toml +63 -0
- fartlek_mcp-0.1.0/tests/conftest.py +37 -0
- fartlek_mcp-0.1.0/tests/test_alerts.py +197 -0
- fartlek_mcp-0.1.0/tests/test_baselines.py +235 -0
- fartlek_mcp-0.1.0/tests/test_context.py +222 -0
- fartlek_mcp-0.1.0/tests/test_fusion.py +413 -0
- fartlek_mcp-0.1.0/tests/test_guardrails.py +91 -0
- fartlek_mcp-0.1.0/tests/test_load.py +213 -0
- fartlek_mcp-0.1.0/tests/test_matcher.py +180 -0
- fartlek_mcp-0.1.0/tests/test_pmc.py +272 -0
- fartlek_mcp-0.1.0/tests/test_renderer.py +292 -0
- fartlek_mcp-0.1.0/tests/test_store.py +422 -0
- fartlek_mcp-0.1.0/tests/test_sync.py +727 -0
- fartlek_mcp-0.1.0/tests/test_tool_activities.py +165 -0
- fartlek_mcp-0.1.0/tests/test_tool_activity.py +343 -0
- fartlek_mcp-0.1.0/tests/test_tool_athlete.py +171 -0
- fartlek_mcp-0.1.0/tests/test_tool_brief.py +334 -0
- fartlek_mcp-0.1.0/tests/test_tool_raw.py +262 -0
- fartlek_mcp-0.1.0/tests/test_tool_writes.py +340 -0
- fartlek_mcp-0.1.0/uv.lock +942 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
.git
|
|
2
|
+
.github
|
|
3
|
+
.env
|
|
4
|
+
.venv
|
|
5
|
+
.pytest_cache
|
|
6
|
+
__pycache__
|
|
7
|
+
*.pyc
|
|
8
|
+
*.pyo
|
|
9
|
+
*.egg-info
|
|
10
|
+
.coverage
|
|
11
|
+
htmlcov
|
|
12
|
+
.mypy_cache
|
|
13
|
+
.ruff_cache
|
|
14
|
+
*.db
|
|
15
|
+
*.db-journal
|
|
16
|
+
data/
|
|
17
|
+
scratchpad/
|
|
18
|
+
private/
|
|
19
|
+
.fartlek/
|
|
20
|
+
garmin_tokens.json
|
|
21
|
+
.DS_Store
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
name: ci
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
|
|
8
|
+
jobs:
|
|
9
|
+
test:
|
|
10
|
+
runs-on: ubuntu-latest
|
|
11
|
+
steps:
|
|
12
|
+
- uses: actions/checkout@v4
|
|
13
|
+
- uses: astral-sh/setup-uv@v5
|
|
14
|
+
with:
|
|
15
|
+
python-version: "3.12"
|
|
16
|
+
- run: uv sync --frozen
|
|
17
|
+
- run: uv run ruff check fartlek/ tests/
|
|
18
|
+
- run: uv run pytest -q
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
name: release
|
|
2
|
+
|
|
3
|
+
# Publish to PyPI via trusted publishing (OIDC) on version tags.
|
|
4
|
+
# Requires a one-time PyPI trusted-publisher setup — see README.
|
|
5
|
+
# No API tokens: identity is proven by GitHub Actions to PyPI directly.
|
|
6
|
+
on:
|
|
7
|
+
push:
|
|
8
|
+
tags: ["v*"]
|
|
9
|
+
|
|
10
|
+
jobs:
|
|
11
|
+
publish:
|
|
12
|
+
runs-on: ubuntu-latest
|
|
13
|
+
environment: pypi # must match the environment name configured on PyPI
|
|
14
|
+
permissions:
|
|
15
|
+
id-token: write # required for trusted publishing (OIDC)
|
|
16
|
+
steps:
|
|
17
|
+
- uses: actions/checkout@v4
|
|
18
|
+
- uses: astral-sh/setup-uv@v5
|
|
19
|
+
with:
|
|
20
|
+
python-version: "3.12"
|
|
21
|
+
# Gate the release on the same checks as CI — a bad version can't be
|
|
22
|
+
# re-uploaded, so don't ship one that fails its own tests.
|
|
23
|
+
- run: uv sync --frozen
|
|
24
|
+
- run: uv run ruff check fartlek/ tests/
|
|
25
|
+
- run: uv run pytest -q
|
|
26
|
+
- run: uv build
|
|
27
|
+
- run: uv publish
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Python
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*$py.class
|
|
5
|
+
*.so
|
|
6
|
+
.Python
|
|
7
|
+
*.egg
|
|
8
|
+
*.egg-info/
|
|
9
|
+
build/
|
|
10
|
+
dist/
|
|
11
|
+
|
|
12
|
+
# Virtual environments
|
|
13
|
+
.venv/
|
|
14
|
+
venv/
|
|
15
|
+
env/
|
|
16
|
+
|
|
17
|
+
# Environment / secrets
|
|
18
|
+
.env
|
|
19
|
+
.env.local
|
|
20
|
+
*.pem
|
|
21
|
+
*.key
|
|
22
|
+
|
|
23
|
+
# uv
|
|
24
|
+
.uv-cache/
|
|
25
|
+
|
|
26
|
+
# IDE
|
|
27
|
+
.vscode/
|
|
28
|
+
.idea/
|
|
29
|
+
*.swp
|
|
30
|
+
*.swo
|
|
31
|
+
|
|
32
|
+
# macOS
|
|
33
|
+
.DS_Store
|
|
34
|
+
|
|
35
|
+
# Logs
|
|
36
|
+
*.log
|
|
37
|
+
|
|
38
|
+
# Test artifacts
|
|
39
|
+
.pytest_cache/
|
|
40
|
+
.coverage
|
|
41
|
+
htmlcov/
|
|
42
|
+
.mypy_cache/
|
|
43
|
+
.ruff_cache/
|
|
44
|
+
|
|
45
|
+
# Local data
|
|
46
|
+
*.db
|
|
47
|
+
*.sqlite
|
|
48
|
+
*.sqlite3
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Fartlek — Garmin MCP server
|
|
2
|
+
|
|
3
|
+
*A coach's morning report from your Garmin data, for any LLM via MCP.* Open-source project. The authoritative spec is `docs/DESIGN.md`; the phase plan is `ROADMAP.md`. Currently in Phase 0 (foundation).
|
|
4
|
+
|
|
5
|
+
## Git discipline — commit as you go
|
|
6
|
+
|
|
7
|
+
**Commit incrementally, as soon as a coherent change is done and verified.** Do not accumulate a large uncommitted working tree.
|
|
8
|
+
|
|
9
|
+
- One logical change = one commit (a module, a new tool, a fix — not "misc").
|
|
10
|
+
- Verify before committing (run the relevant tests; for the MCP server, the standalone JSON-RPC check below).
|
|
11
|
+
- Concise imperative messages, scoped: `analytics: add PMC engine`, `store: fix WAL busy timeout`.
|
|
12
|
+
- Never commit secrets or tokens (`~/.fartlek/`, `garmin_tokens.json`).
|
|
13
|
+
|
|
14
|
+
## Architecture
|
|
15
|
+
|
|
16
|
+
- `fartlek/health/` — Garmin data access. `ports.py` (GarminPort protocol) → `adapters/garmin_connect.py` (`garminconnect` lib, sync calls in `asyncio.to_thread` behind a lock + cross-process fcntl token lock) → `service.py` (field filtering). Consumers go through HealthService, never the adapter.
|
|
17
|
+
- `fartlek/mcp_server/server.py` — FastMCP stdio server. stdout is reserved for JSON-RPC; log to stderr only.
|
|
18
|
+
- `fartlek/cli.py` — `fartlek auth/doctor/accounts/reset`. The only place credentials are typed.
|
|
19
|
+
- `fartlek/paths.py` — filesystem layout (`~/.fartlek/`, override `FARTLEK_HOME`; tokens override `GARMINTOKENS`).
|
|
20
|
+
- Phase 0 adds: `fartlek/store/` (per-account SQLite), `fartlek/sync/` (fetch + digestion engine), `fartlek/analytics/` (deterministic metrics), `fartlek/render/` (budgeted verdict renderer). Specs: DESIGN.md §3 and §5.
|
|
21
|
+
|
|
22
|
+
## Commands
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
uv sync # install (dev group included)
|
|
26
|
+
uv run fartlek auth # one-time Garmin login (email/password + MFA)
|
|
27
|
+
uv run fartlek doctor # health check
|
|
28
|
+
uv run fartlek-mcp # run MCP server (stdio) — Claude Code auto-starts it via .mcp.json
|
|
29
|
+
uv run pytest # tests
|
|
30
|
+
uv run ruff check fartlek/ # lint
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Standalone MCP smoke check:
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
printf '%s\n' \
|
|
37
|
+
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"0"}}}' \
|
|
38
|
+
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
|
|
39
|
+
'{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
|
|
40
|
+
| (cat; sleep 2) | uv run fartlek-mcp 2>/dev/null
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Notes
|
|
44
|
+
|
|
45
|
+
- `garth` is deprecated (Garmin broke its login in 2026) — use `garminconnect` for all Garmin API access; its source in `.venv/.../garminconnect/` is the ground truth for endpoints.
|
|
46
|
+
- Python ≥ 3.12, managed by `uv`. PyPI name: `fartlek-mcp`.
|
|
47
|
+
- The design doc's formulas (PMC constants, ACWR EWMA, MAD scaling 1.4826, Foster monotony) are contracts — implement exactly, test against known values.
|
|
48
|
+
- Live testing against the maintainer's real Garmin account is possible: tokens in the session scratchpad or via `GARMINTOKENS`. Be polite with call volume (sequential, backoff on 429).
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# syntax=docker/dockerfile:1
|
|
2
|
+
FROM python:3.12-slim
|
|
3
|
+
|
|
4
|
+
# Install uv
|
|
5
|
+
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv
|
|
6
|
+
|
|
7
|
+
WORKDIR /app
|
|
8
|
+
|
|
9
|
+
# Copy project metadata and install dependencies first (better layer caching)
|
|
10
|
+
COPY pyproject.toml README.md LICENSE ./
|
|
11
|
+
COPY fartlek/ ./fartlek/
|
|
12
|
+
|
|
13
|
+
RUN uv pip install --system .
|
|
14
|
+
|
|
15
|
+
# Data and tokens live on a volume, not in the image
|
|
16
|
+
ENV FARTLEK_HOME=/data
|
|
17
|
+
VOLUME /data
|
|
18
|
+
|
|
19
|
+
# The MCP server speaks stdio
|
|
20
|
+
ENTRYPOINT ["fartlek-mcp"]
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Matis Despujols
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: fartlek-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Fartlek — a coach's morning report from your Garmin data, for any LLM via MCP
|
|
5
|
+
Project-URL: Homepage, https://github.com/matisdsp/fartlek
|
|
6
|
+
Project-URL: Repository, https://github.com/matisdsp/fartlek
|
|
7
|
+
Project-URL: Documentation, https://github.com/matisdsp/fartlek/blob/main/docs/DESIGN.md
|
|
8
|
+
Project-URL: Issues, https://github.com/matisdsp/fartlek/issues
|
|
9
|
+
Author: Fartlek contributors
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: coaching,garmin,llm,mcp,running,training
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Intended Audience :: End Users/Desktop
|
|
15
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Topic :: Scientific/Engineering :: Information Analysis
|
|
21
|
+
Classifier: Topic :: Utilities
|
|
22
|
+
Requires-Python: >=3.12
|
|
23
|
+
Requires-Dist: garminconnect>=0.3.6
|
|
24
|
+
Requires-Dist: mcp[cli]>=1.27.1
|
|
25
|
+
Description-Content-Type: text/markdown
|
|
26
|
+
|
|
27
|
+
# Fartlek
|
|
28
|
+
|
|
29
|
+
*A coach's morning report from your Garmin data, for any LLM via MCP.*
|
|
30
|
+
|
|
31
|
+
Every other Garmin MCP server hands the LLM a filing cabinet of raw JSON — one night of sleep is ~52K tokens, one activity stream ~155K. The model can't read it, so it skims and improvises. Fartlek does the synthesis server-side: computed sports-science metrics (CTL/ATL/TSB, ACWR, monotony, calibrated training load), personal baselines with significance floors, safety alerts — delivered as compact, verdict-first reports the model can actually reason about.
|
|
32
|
+
|
|
33
|
+
**The token contract (v0.1):** calling every tool in the catalog once, at default arguments, costs **under 9K tokens** — a sixth of one raw Garmin sleep payload. Excluding the `garmin_raw` escape hatch, the whole synthesis surface sums to **under 4K**. Hard caps are enforced per response by the renderer, with disclosed truncation.
|
|
34
|
+
|
|
35
|
+
> **Status: v0.1 (Phase 1).** 8 synthesis tools; the trend suite (weekly review, multi-week load, fitness/race outlook, recovery audit) ships with v0.2. Design: [`docs/DESIGN.md`](docs/DESIGN.md) · plan: [`ROADMAP.md`](ROADMAP.md).
|
|
36
|
+
|
|
37
|
+
## The tools
|
|
38
|
+
|
|
39
|
+
| Tool | What it answers | Cap |
|
|
40
|
+
|---|---|---|
|
|
41
|
+
| `garmin_brief` | "How am I today — can I train hard?" Fused GREEN/AMBER/RED verdict vs your own baselines | 600 |
|
|
42
|
+
| `garmin_activities` | Browse the log, get activity IDs | 1,300 |
|
|
43
|
+
| `garmin_activity` | One session in depth: reps, fade, comparison to your most similar past session | 1,000–4,000 |
|
|
44
|
+
| `garmin_athlete` | Reference card: zones, PRs, goal, data coverage | 600 |
|
|
45
|
+
| `garmin_set_profile` | Tell it your goal race / phase / availability (local only) | 200 |
|
|
46
|
+
| `garmin_log` | Log RPE, wellness, illness/injury — the athlete outranks the sensors | 120 |
|
|
47
|
+
| `garmin_sync` | Force refresh / deepen history backfill | 150 |
|
|
48
|
+
| `garmin_raw` | Bounded, compacted escape hatch to named raw sources | 5,000 |
|
|
49
|
+
|
|
50
|
+
First call on a fresh install runs the cold start automatically (~30 API calls, ≈1 minute): 180 days of history, warm CTL/ATL from day 0, then background sleep/HRV backfill.
|
|
51
|
+
|
|
52
|
+
## Quickstart
|
|
53
|
+
|
|
54
|
+
Install with either:
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
# uv (recommended) — runs without cloning
|
|
58
|
+
uvx fartlek-mcp
|
|
59
|
+
|
|
60
|
+
# or pipx
|
|
61
|
+
pipx install fartlek-mcp
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Or clone and run from source (requires Python ≥ 3.12 and [uv](https://docs.astral.sh/uv/)):
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
git clone https://github.com/matisdsp/fartlek && cd fartlek
|
|
68
|
+
uv sync
|
|
69
|
+
|
|
70
|
+
# One-time Garmin login (email/password + MFA if enabled).
|
|
71
|
+
# Credentials are never stored; OAuth tokens go to ~/.fartlek/tokens/.
|
|
72
|
+
uv run fartlek auth
|
|
73
|
+
|
|
74
|
+
# Optional but recommended: warm the local store now instead of on first use
|
|
75
|
+
uv run fartlek sync --nights 60
|
|
76
|
+
|
|
77
|
+
uv run fartlek doctor # check everything is healthy
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Then point your MCP client at the server.
|
|
81
|
+
|
|
82
|
+
> **Any MCP-compatible client works** — the server speaks standard JSON-RPC over stdio, so it is client-agnostic. The snippets below are just the per-client config formats; Claude Desktop, Claude Code, Cursor, Continue, Cline, Windsurf, Zed, VS Code (Copilot Chat), and Gemini CLI all work. The universal invocation is `uvx fartlek-mcp`.
|
|
83
|
+
|
|
84
|
+
**Claude Code** — from this directory, `.mcp.json` is picked up automatically. From anywhere else:
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
claude mcp add fartlek -- uvx fartlek-mcp
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
**Claude Desktop** — `claude_desktop_config.json`:
|
|
91
|
+
|
|
92
|
+
```json
|
|
93
|
+
{
|
|
94
|
+
"mcpServers": {
|
|
95
|
+
"fartlek": {
|
|
96
|
+
"command": "uvx",
|
|
97
|
+
"args": ["fartlek-mcp"]
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
**Cursor** — `.cursor/mcp.json`, same `command`/`args` block as above.
|
|
104
|
+
|
|
105
|
+
**Continue / Cline / Windsurf / Zed** — same pattern: wherever the client keeps its MCP server list, add a `fartlek` entry with `command: "uvx"`, `args: ["fartlek-mcp"]`. Most editors adopt the Claude Desktop format verbatim.
|
|
106
|
+
|
|
107
|
+
**Any other stdio MCP client** — invoke the server binary directly:
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
fartlek-mcp # speaks JSON-RPC over stdin/stdout
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Ask things like *"can I go hard today?"*, *"analyze my last run"*, *"how did I sleep this week?"* — and tell it how sessions felt: your reported RPE and illness notes gate the readiness verdict.
|
|
114
|
+
|
|
115
|
+
## Docker
|
|
116
|
+
|
|
117
|
+
Build and run locally:
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
docker build -t fartlek-mcp .
|
|
121
|
+
# Tokens and store are persisted in ./fartlek-data on the host
|
|
122
|
+
mkdir -p fartlek-data
|
|
123
|
+
docker run -i --rm -v "$PWD/fartlek-data:/data" fartlek-mcp
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
For `fartlek auth`, run it interactively once to populate the volume, then use the image as the MCP server:
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
docker run -it --rm -v "$PWD/fartlek-data:/data" --entrypoint fartlek fartlek-mcp auth
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
## CLI
|
|
133
|
+
|
|
134
|
+
| Command | What it does |
|
|
135
|
+
|---|---|
|
|
136
|
+
| `fartlek auth` | one-time Garmin Connect login (MFA supported), tokens stored locally |
|
|
137
|
+
| `fartlek sync [--nights N]` | manual sync (tier 0+1, optional N-night sleep/HRV backfill) |
|
|
138
|
+
| `fartlek doctor` | check tokens, Garmin connectivity, local store health |
|
|
139
|
+
| `fartlek accounts` | list local accounts |
|
|
140
|
+
| `fartlek export [dir]` | export the store (consistent SQLite snapshot + CSV per table) |
|
|
141
|
+
| `fartlek reset` | wipe all local tokens and data (asks confirmation) |
|
|
142
|
+
|
|
143
|
+
Environment: `GARMINTOKENS` overrides the token location, `FARTLEK_HOME` the data directory (default `~/.fartlek`).
|
|
144
|
+
|
|
145
|
+
### Releasing to PyPI (maintainers)
|
|
146
|
+
|
|
147
|
+
Releases are published via **trusted publishing** (OIDC) — no API tokens anywhere.
|
|
148
|
+
|
|
149
|
+
1. On pypi.org → Account settings → Publishing → add a GitHub publisher:
|
|
150
|
+
- PyPI project name: `fartlek-mcp` · owner: `matisdsp` · repo: `fartlek`
|
|
151
|
+
- Workflow: `release.yml` · environment: `pypi`
|
|
152
|
+
2. Bump `version` in `pyproject.toml`, commit, then tag and push:
|
|
153
|
+
|
|
154
|
+
```bash
|
|
155
|
+
git tag v0.1.0 && git push origin v0.1.0
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
The `release` workflow builds, runs tests, and uploads to PyPI. A published version can't be overwritten — to fix a mistake, bump to the next patch (`0.1.1`).
|
|
159
|
+
|
|
160
|
+
## Privacy
|
|
161
|
+
|
|
162
|
+
Local-first: stdio transport, your credentials and health data never leave your machine. The server only talks to Garmin's API with your own tokens, sequentially and rate-limited. `fartlek export` gives you everything; `fartlek reset` removes everything.
|
|
163
|
+
|
|
164
|
+
## License & trademark
|
|
165
|
+
|
|
166
|
+
MIT. Fartlek is an independent open-source project, **not affiliated with, endorsed by, or sponsored by Garmin Ltd.** "Garmin" is used only to describe compatibility with Garmin Connect data.
|
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
# Fartlek
|
|
2
|
+
|
|
3
|
+
*A coach's morning report from your Garmin data, for any LLM via MCP.*
|
|
4
|
+
|
|
5
|
+
Every other Garmin MCP server hands the LLM a filing cabinet of raw JSON — one night of sleep is ~52K tokens, one activity stream ~155K. The model can't read it, so it skims and improvises. Fartlek does the synthesis server-side: computed sports-science metrics (CTL/ATL/TSB, ACWR, monotony, calibrated training load), personal baselines with significance floors, safety alerts — delivered as compact, verdict-first reports the model can actually reason about.
|
|
6
|
+
|
|
7
|
+
**The token contract (v0.1):** calling every tool in the catalog once, at default arguments, costs **under 9K tokens** — a sixth of one raw Garmin sleep payload. Excluding the `garmin_raw` escape hatch, the whole synthesis surface sums to **under 4K**. Hard caps are enforced per response by the renderer, with disclosed truncation.
|
|
8
|
+
|
|
9
|
+
> **Status: v0.1 (Phase 1).** 8 synthesis tools; the trend suite (weekly review, multi-week load, fitness/race outlook, recovery audit) ships with v0.2. Design: [`docs/DESIGN.md`](docs/DESIGN.md) · plan: [`ROADMAP.md`](ROADMAP.md).
|
|
10
|
+
|
|
11
|
+
## The tools
|
|
12
|
+
|
|
13
|
+
| Tool | What it answers | Cap |
|
|
14
|
+
|---|---|---|
|
|
15
|
+
| `garmin_brief` | "How am I today — can I train hard?" Fused GREEN/AMBER/RED verdict vs your own baselines | 600 |
|
|
16
|
+
| `garmin_activities` | Browse the log, get activity IDs | 1,300 |
|
|
17
|
+
| `garmin_activity` | One session in depth: reps, fade, comparison to your most similar past session | 1,000–4,000 |
|
|
18
|
+
| `garmin_athlete` | Reference card: zones, PRs, goal, data coverage | 600 |
|
|
19
|
+
| `garmin_set_profile` | Tell it your goal race / phase / availability (local only) | 200 |
|
|
20
|
+
| `garmin_log` | Log RPE, wellness, illness/injury — the athlete outranks the sensors | 120 |
|
|
21
|
+
| `garmin_sync` | Force refresh / deepen history backfill | 150 |
|
|
22
|
+
| `garmin_raw` | Bounded, compacted escape hatch to named raw sources | 5,000 |
|
|
23
|
+
|
|
24
|
+
First call on a fresh install runs the cold start automatically (~30 API calls, ≈1 minute): 180 days of history, warm CTL/ATL from day 0, then background sleep/HRV backfill.
|
|
25
|
+
|
|
26
|
+
## Quickstart
|
|
27
|
+
|
|
28
|
+
Install with either:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
# uv (recommended) — runs without cloning
|
|
32
|
+
uvx fartlek-mcp
|
|
33
|
+
|
|
34
|
+
# or pipx
|
|
35
|
+
pipx install fartlek-mcp
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Or clone and run from source (requires Python ≥ 3.12 and [uv](https://docs.astral.sh/uv/)):
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
git clone https://github.com/matisdsp/fartlek && cd fartlek
|
|
42
|
+
uv sync
|
|
43
|
+
|
|
44
|
+
# One-time Garmin login (email/password + MFA if enabled).
|
|
45
|
+
# Credentials are never stored; OAuth tokens go to ~/.fartlek/tokens/.
|
|
46
|
+
uv run fartlek auth
|
|
47
|
+
|
|
48
|
+
# Optional but recommended: warm the local store now instead of on first use
|
|
49
|
+
uv run fartlek sync --nights 60
|
|
50
|
+
|
|
51
|
+
uv run fartlek doctor # check everything is healthy
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Then point your MCP client at the server.
|
|
55
|
+
|
|
56
|
+
> **Any MCP-compatible client works** — the server speaks standard JSON-RPC over stdio, so it is client-agnostic. The snippets below are just the per-client config formats; Claude Desktop, Claude Code, Cursor, Continue, Cline, Windsurf, Zed, VS Code (Copilot Chat), and Gemini CLI all work. The universal invocation is `uvx fartlek-mcp`.
|
|
57
|
+
|
|
58
|
+
**Claude Code** — from this directory, `.mcp.json` is picked up automatically. From anywhere else:
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
claude mcp add fartlek -- uvx fartlek-mcp
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
**Claude Desktop** — `claude_desktop_config.json`:
|
|
65
|
+
|
|
66
|
+
```json
|
|
67
|
+
{
|
|
68
|
+
"mcpServers": {
|
|
69
|
+
"fartlek": {
|
|
70
|
+
"command": "uvx",
|
|
71
|
+
"args": ["fartlek-mcp"]
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
**Cursor** — `.cursor/mcp.json`, same `command`/`args` block as above.
|
|
78
|
+
|
|
79
|
+
**Continue / Cline / Windsurf / Zed** — same pattern: wherever the client keeps its MCP server list, add a `fartlek` entry with `command: "uvx"`, `args: ["fartlek-mcp"]`. Most editors adopt the Claude Desktop format verbatim.
|
|
80
|
+
|
|
81
|
+
**Any other stdio MCP client** — invoke the server binary directly:
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
fartlek-mcp # speaks JSON-RPC over stdin/stdout
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Ask things like *"can I go hard today?"*, *"analyze my last run"*, *"how did I sleep this week?"* — and tell it how sessions felt: your reported RPE and illness notes gate the readiness verdict.
|
|
88
|
+
|
|
89
|
+
## Docker
|
|
90
|
+
|
|
91
|
+
Build and run locally:
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
docker build -t fartlek-mcp .
|
|
95
|
+
# Tokens and store are persisted in ./fartlek-data on the host
|
|
96
|
+
mkdir -p fartlek-data
|
|
97
|
+
docker run -i --rm -v "$PWD/fartlek-data:/data" fartlek-mcp
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
For `fartlek auth`, run it interactively once to populate the volume, then use the image as the MCP server:
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
docker run -it --rm -v "$PWD/fartlek-data:/data" --entrypoint fartlek fartlek-mcp auth
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
## CLI
|
|
107
|
+
|
|
108
|
+
| Command | What it does |
|
|
109
|
+
|---|---|
|
|
110
|
+
| `fartlek auth` | one-time Garmin Connect login (MFA supported), tokens stored locally |
|
|
111
|
+
| `fartlek sync [--nights N]` | manual sync (tier 0+1, optional N-night sleep/HRV backfill) |
|
|
112
|
+
| `fartlek doctor` | check tokens, Garmin connectivity, local store health |
|
|
113
|
+
| `fartlek accounts` | list local accounts |
|
|
114
|
+
| `fartlek export [dir]` | export the store (consistent SQLite snapshot + CSV per table) |
|
|
115
|
+
| `fartlek reset` | wipe all local tokens and data (asks confirmation) |
|
|
116
|
+
|
|
117
|
+
Environment: `GARMINTOKENS` overrides the token location, `FARTLEK_HOME` the data directory (default `~/.fartlek`).
|
|
118
|
+
|
|
119
|
+
### Releasing to PyPI (maintainers)
|
|
120
|
+
|
|
121
|
+
Releases are published via **trusted publishing** (OIDC) — no API tokens anywhere.
|
|
122
|
+
|
|
123
|
+
1. On pypi.org → Account settings → Publishing → add a GitHub publisher:
|
|
124
|
+
- PyPI project name: `fartlek-mcp` · owner: `matisdsp` · repo: `fartlek`
|
|
125
|
+
- Workflow: `release.yml` · environment: `pypi`
|
|
126
|
+
2. Bump `version` in `pyproject.toml`, commit, then tag and push:
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
git tag v0.1.0 && git push origin v0.1.0
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
The `release` workflow builds, runs tests, and uploads to PyPI. A published version can't be overwritten — to fix a mistake, bump to the next patch (`0.1.1`).
|
|
133
|
+
|
|
134
|
+
## Privacy
|
|
135
|
+
|
|
136
|
+
Local-first: stdio transport, your credentials and health data never leave your machine. The server only talks to Garmin's API with your own tokens, sequentially and rate-limited. `fartlek export` gives you everything; `fartlek reset` removes everything.
|
|
137
|
+
|
|
138
|
+
## License & trademark
|
|
139
|
+
|
|
140
|
+
MIT. Fartlek is an independent open-source project, **not affiliated with, endorsed by, or sponsored by Garmin Ltd.** "Garmin" is used only to describe compatibility with Garmin Connect data.
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# Fartlek — Roadmap
|
|
2
|
+
|
|
3
|
+
> Condensed from [`docs/DESIGN.md`](docs/DESIGN.md) §6 (the authoritative spec — every item below is specified there).
|
|
4
|
+
> Fartlek: *a coach's morning report from your Garmin data, for any LLM via MCP.*
|
|
5
|
+
|
|
6
|
+
## Done — 2026-07-20
|
|
7
|
+
|
|
8
|
+
- [x] Migrate Garmin access from deprecated `garth` to `garminconnect` (multi-strategy login, MFA)
|
|
9
|
+
- [x] Integrated login CLI (`ai-coach-login` — becomes `fartlek auth` in Phase 0)
|
|
10
|
+
- [x] Adapter hardened after adversarial review (self-heal on re-login, cross-process token lock, connect-failure backoff)
|
|
11
|
+
- [x] Full design document (`docs/DESIGN.md`) — synthesis layer, 15-tool surface, metrics engine, token-budget contract
|
|
12
|
+
- [x] Name check + decision: **Fartlek** (PyPI `fartlek-mcp` free; "Garmin Coach" is Garmin's own product)
|
|
13
|
+
|
|
14
|
+
## Phase 0 — Foundation (~2 weeks) · nothing user-visible, half the real effort
|
|
15
|
+
|
|
16
|
+
- [x] Rename: package `ai-coach` → `fartlek`, CLI → `fartlek auth`, repo restructure around the MCP server (FastAPI dropped, recoverable from git history)
|
|
17
|
+
- [x] Per-account SQLite store (`~/.fartlek/<account>/store.db`, WAL, sync lock, lifecycle commands)
|
|
18
|
+
- [x] Sync engine: staleness checks, 429 backoff, resumable cursor, capability probes (plans, goals, running tolerance, native RPE)
|
|
19
|
+
- [x] Cold start Tier 0+1; daily-load ledger with calibration + terminal fallback
|
|
20
|
+
- [x] Core metrics: PMC (CTL/ATL/TSB), form ratio, ACWR, monotony/strain; baseline engine; alerts table
|
|
21
|
+
- [x] Planned-vs-executed workout matcher
|
|
22
|
+
- [x] Shared response renderer: verdict grammar, token budgets, drop order, safety banner
|
|
23
|
+
- [ ] CI guardrails incl. real-tokenizer budget regression gate *(basic CI — ruff + 244 tests — in place; tokenizer budget gate lands with the Phase-1 tools that have golden renders)*
|
|
24
|
+
|
|
25
|
+
## Phase 1 — Core read surface (3–4 weeks) · **ships v0.1**
|
|
26
|
+
|
|
27
|
+
- [x] Tools: `garmin_brief`, `garmin_activities`, `garmin_activity`, `garmin_athlete`, `garmin_set_profile`, `garmin_log`, `garmin_sync`, `garmin_raw`
|
|
28
|
+
- [x] Readiness fusion with subjective gate + acute override; corrective error messages
|
|
29
|
+
- [x] README publishes the token-budget contract
|
|
30
|
+
|
|
31
|
+
### Distribution workstream (parallel, lands with v0.1) — not optional polish
|
|
32
|
+
|
|
33
|
+
- [x] `fartlek auth` (full MFA flow, error taxonomy) + `fartlek doctor` + `accounts/switch/export/reset`
|
|
34
|
+
- [x] Install paths: `uvx`/`pipx` one-liner, Docker image (`.mcpb`/`.dxt` Desktop extension packaging TBD)
|
|
35
|
+
- [x] Client config snippets: Claude Code, Claude Desktop, Cursor
|
|
36
|
+
- [ ] Open-sourcing basics: MIT LICENSE, English README with "not affiliated with Garmin Ltd." disclaimer, PyPI `fartlek-mcp` publish, MCP registry submissions
|
|
37
|
+
|
|
38
|
+
## Phase 2 — Trend suite & engine completion (4–5 weeks) · **ships v0.2, the flagship**
|
|
39
|
+
|
|
40
|
+
- [ ] Tools: `garmin_whats_changed`, `garmin_week`, `garmin_load`, `garmin_fitness` (incl. race projection + taper window), `garmin_recovery`, `garmin_reference` (metrics glossary)
|
|
41
|
+
- [ ] Engine: Tier-2 history backfill, EF/decoupling/durability, sleep timeline + SRI, TID mapping, race triangulation, trend significance (per-metric SWC), overtraining convergence audit, attribution rules
|
|
42
|
+
- [ ] MCP prompts + resources (progressive enhancement)
|
|
43
|
+
- [ ] Evaluation harness: ~30 multi-tool coaching tasks across clients, token/calls regression gates; engine validation vs. intervals.icu golden data
|
|
44
|
+
- [ ] Anomaly-scanner threshold tuning on real multi-month data
|
|
45
|
+
|
|
46
|
+
## Phase 3 — The closed loop (3 weeks) · **ships v0.3**
|
|
47
|
+
|
|
48
|
+
- [ ] `garmin_apply_plan`: dry-run-first structured workouts pushed to the watch, guardrail simulation, token-bound confirmation
|
|
49
|
+
- [ ] `garmin_reference` workout-schema topic; prescription-side compliance in the debrief
|
|
50
|
+
- [ ] `setup_athlete` elicitation flow
|
|
51
|
+
|
|
52
|
+
## Phase 4 — Depth extensions (ongoing)
|
|
53
|
+
|
|
54
|
+
Cycling power depth · swim CSS · menstrual-cycle-aware baselines (clinician-reviewed) · body-composition verdicts · Body Battery event attribution · hosted streamable-HTTP mode · MCP Apps dashboard
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
**Total to v0.3: ~3–3.5 months solo.** Each phase ships a working, useful server.
|