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.

Files changed (71) hide show
  1. fartlek_mcp-0.1.0/.cursor/mcp.json +8 -0
  2. fartlek_mcp-0.1.0/.dockerignore +21 -0
  3. fartlek_mcp-0.1.0/.env.example +2 -0
  4. fartlek_mcp-0.1.0/.github/workflows/ci.yml +18 -0
  5. fartlek_mcp-0.1.0/.github/workflows/release.yml +27 -0
  6. fartlek_mcp-0.1.0/.gitignore +48 -0
  7. fartlek_mcp-0.1.0/.mcp.json +8 -0
  8. fartlek_mcp-0.1.0/CLAUDE.md +48 -0
  9. fartlek_mcp-0.1.0/Dockerfile +20 -0
  10. fartlek_mcp-0.1.0/LICENSE +21 -0
  11. fartlek_mcp-0.1.0/PKG-INFO +166 -0
  12. fartlek_mcp-0.1.0/README.md +140 -0
  13. fartlek_mcp-0.1.0/ROADMAP.md +58 -0
  14. fartlek_mcp-0.1.0/claude_desktop_config.json +8 -0
  15. fartlek_mcp-0.1.0/docs/DESIGN.md +678 -0
  16. fartlek_mcp-0.1.0/fartlek/__init__.py +0 -0
  17. fartlek_mcp-0.1.0/fartlek/analytics/__init__.py +0 -0
  18. fartlek_mcp-0.1.0/fartlek/analytics/alerts.py +192 -0
  19. fartlek_mcp-0.1.0/fartlek/analytics/baselines.py +129 -0
  20. fartlek_mcp-0.1.0/fartlek/analytics/fusion.py +399 -0
  21. fartlek_mcp-0.1.0/fartlek/analytics/load.py +152 -0
  22. fartlek_mcp-0.1.0/fartlek/analytics/matcher.py +191 -0
  23. fartlek_mcp-0.1.0/fartlek/analytics/pmc.py +192 -0
  24. fartlek_mcp-0.1.0/fartlek/cli.py +225 -0
  25. fartlek_mcp-0.1.0/fartlek/health/__init__.py +0 -0
  26. fartlek_mcp-0.1.0/fartlek/health/adapters/__init__.py +0 -0
  27. fartlek_mcp-0.1.0/fartlek/health/adapters/garmin_connect.py +247 -0
  28. fartlek_mcp-0.1.0/fartlek/health/domain.py +20 -0
  29. fartlek_mcp-0.1.0/fartlek/health/exceptions.py +15 -0
  30. fartlek_mcp-0.1.0/fartlek/health/ports.py +25 -0
  31. fartlek_mcp-0.1.0/fartlek/health/service.py +252 -0
  32. fartlek_mcp-0.1.0/fartlek/mcp_server/__init__.py +0 -0
  33. fartlek_mcp-0.1.0/fartlek/mcp_server/context.py +188 -0
  34. fartlek_mcp-0.1.0/fartlek/mcp_server/server.py +298 -0
  35. fartlek_mcp-0.1.0/fartlek/mcp_server/tools/__init__.py +22 -0
  36. fartlek_mcp-0.1.0/fartlek/mcp_server/tools/activities.py +273 -0
  37. fartlek_mcp-0.1.0/fartlek/mcp_server/tools/activity.py +670 -0
  38. fartlek_mcp-0.1.0/fartlek/mcp_server/tools/athlete.py +300 -0
  39. fartlek_mcp-0.1.0/fartlek/mcp_server/tools/brief.py +479 -0
  40. fartlek_mcp-0.1.0/fartlek/mcp_server/tools/log_tool.py +257 -0
  41. fartlek_mcp-0.1.0/fartlek/mcp_server/tools/raw.py +317 -0
  42. fartlek_mcp-0.1.0/fartlek/mcp_server/tools/set_profile.py +197 -0
  43. fartlek_mcp-0.1.0/fartlek/mcp_server/tools/sync_tool.py +81 -0
  44. fartlek_mcp-0.1.0/fartlek/paths.py +26 -0
  45. fartlek_mcp-0.1.0/fartlek/render/__init__.py +0 -0
  46. fartlek_mcp-0.1.0/fartlek/render/renderer.py +287 -0
  47. fartlek_mcp-0.1.0/fartlek/store/__init__.py +3 -0
  48. fartlek_mcp-0.1.0/fartlek/store/schema.sql +168 -0
  49. fartlek_mcp-0.1.0/fartlek/store/store.py +361 -0
  50. fartlek_mcp-0.1.0/fartlek/sync/__init__.py +0 -0
  51. fartlek_mcp-0.1.0/fartlek/sync/engine.py +1059 -0
  52. fartlek_mcp-0.1.0/pyproject.toml +63 -0
  53. fartlek_mcp-0.1.0/tests/conftest.py +37 -0
  54. fartlek_mcp-0.1.0/tests/test_alerts.py +197 -0
  55. fartlek_mcp-0.1.0/tests/test_baselines.py +235 -0
  56. fartlek_mcp-0.1.0/tests/test_context.py +222 -0
  57. fartlek_mcp-0.1.0/tests/test_fusion.py +413 -0
  58. fartlek_mcp-0.1.0/tests/test_guardrails.py +91 -0
  59. fartlek_mcp-0.1.0/tests/test_load.py +213 -0
  60. fartlek_mcp-0.1.0/tests/test_matcher.py +180 -0
  61. fartlek_mcp-0.1.0/tests/test_pmc.py +272 -0
  62. fartlek_mcp-0.1.0/tests/test_renderer.py +292 -0
  63. fartlek_mcp-0.1.0/tests/test_store.py +422 -0
  64. fartlek_mcp-0.1.0/tests/test_sync.py +727 -0
  65. fartlek_mcp-0.1.0/tests/test_tool_activities.py +165 -0
  66. fartlek_mcp-0.1.0/tests/test_tool_activity.py +343 -0
  67. fartlek_mcp-0.1.0/tests/test_tool_athlete.py +171 -0
  68. fartlek_mcp-0.1.0/tests/test_tool_brief.py +334 -0
  69. fartlek_mcp-0.1.0/tests/test_tool_raw.py +262 -0
  70. fartlek_mcp-0.1.0/tests/test_tool_writes.py +340 -0
  71. fartlek_mcp-0.1.0/uv.lock +942 -0
@@ -0,0 +1,8 @@
1
+ {
2
+ "mcpServers": {
3
+ "fartlek": {
4
+ "command": "uvx",
5
+ "args": ["fartlek-mcp"]
6
+ }
7
+ }
8
+ }
@@ -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,2 @@
1
+ ANTHROPIC_API_KEY=sk-ant-...
2
+ LOG_LEVEL=INFO
@@ -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,8 @@
1
+ {
2
+ "mcpServers": {
3
+ "fartlek": {
4
+ "command": "uv",
5
+ "args": ["run", "fartlek-mcp"]
6
+ }
7
+ }
8
+ }
@@ -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.
@@ -0,0 +1,8 @@
1
+ {
2
+ "mcpServers": {
3
+ "fartlek": {
4
+ "command": "uvx",
5
+ "args": ["fartlek-mcp"]
6
+ }
7
+ }
8
+ }