Skip to content
Back to search

athlete-ledger

This repo contains all the code for an MCP server that wil access to a local DB with Germin connect downloade data

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 17 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/luigisaetta/athlete-ledger with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/luigisaetta/athlete-ledger'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/luigisaetta--athlete-ledger/badge.svg)](/listings/luigisaetta--athlete-ledger)

HTML

<a href="/listings/luigisaetta--athlete-ledger"><img src="/api/listings/luigisaetta--athlete-ledger/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 516 lines
  1. # athlete-ledger
  2. **A local-first ledger of your training data, AI-ready via MCP.**
  3. athlete-ledger keeps a faithful, local archive of your own training and wellness data and lets any
  4. AI assistant that speaks the [Model Context Protocol](https://modelcontextprotocol.io) (MCP) answer
  5. questions about it: *"How did I sleep before my long sessions this month?"*,
  6. *"Compare my training volume per sport over the last two blocks"*, and so on.
  7. > **Status: early development.** Nothing is usable yet. Interfaces, schema, and commands will change.
  8. ## Why
  9. - **Official access, no password.** The first data provider is Garmin Connect, via the official
  10. [Personal API](https://developer.garmin.com/gc-developer-program/personal/personal-api) and
  11. Garmin's Python SDK. You create a personal API key in Garmin Connect; your account password is
  12. never used.
  13. - **Local-first archive.** Data is synced incrementally into a database you control, so your history
  14. is available offline, fast to query, and not limited by API quotas or key expiry.
  15. - **AI-ready, standard MCP.** A read-only MCP server (stdio and stateless Streamable HTTP, following
  16. the 2026-07-28 MCP specification) gives assistants compact, aggregated answers instead of raw JSON.
  17. - **Not tied to one sport.** Running, cycling, swimming, triathlon, and any other endurance activity.
  18. The schema is designed so other providers can be added later.
  19. ## How it works
  20. ```
  21. sync CLI ──► Garmin Connect Personal API
  22. │
  23. ▼
  24. database (SQLAlchemy: Oracle Autonomous Database or SQLite)
  25. │ raw JSON responses + normalized daily/activity tables
  26. ▼
  27. MCP server (read-only) ◄── agent (OCI Generative AI, Responses API) ◄── Next.js chat UI
  28. ◄── any other MCP client (desktop assistants, IDEs, …)
  29. ```
  30. | Component | Package | Role |
  31. |---|---|---|
  32. | Core | `athlete-ledger` | Provider access, database schema, sync CLI |
  33. | MCP server | `athlete-ledger-mcp` | Read-only tools over the local database |
  34. | Agent | `athlete-ledger-agent` | OpenAI-compatible agent on OCI Generative AI that uses the MCP tools |
  35. | UI | `ui/` | Chat interface that shows every tool call |
  36. ## MVP scope
  37. - Summary data only: activities, sleep, HRV, and stress.
  38. - Databases: Oracle Autonomous Database (via `python-oracledb`) and SQLite.
  39. - MCP transports: stdio and Streamable HTTP, bound to `localhost` by default.
  40. Planned later: activity files (FIT) and intraday series, training-load analytics (CTL/ATL/TSB),
  41. weekly reports to share with a coach, and more data providers.
  42. ## Privacy
  43. Your data is health data, and athlete-ledger treats it that way:
  44. - It runs on your machine; servers bind to `127.0.0.1` by default.
  45. - No telemetry.
  46. - MCP tools are read-only and query only your local database.
  47. - Logs never contain the values of your data.
  48. When you use the agent, your questions and the aggregated tool results are sent to the language
  49. model you configure (for example OCI Generative AI in your own tenancy).
  50. ## Development
  51. The project uses Python 3.12+, [Conda](https://docs.conda.io/) for the local environment, and
  52. [uv](https://docs.astral.sh/uv/) for the Python workspace and lockfile. From the repository root:
  53. ```sh
  54. conda env create --file environment.yml
  55. conda activate athlete-ledger
  56. export UV_PROJECT_ENVIRONMENT="$CONDA_PREFIX"
  57. uv sync --all-packages --inexact --locked
  58. pre-commit install
  59. ```
  60. If the environment already exists, start at `conda activate athlete-ledger`. Activate it and export
  61. `UV_PROJECT_ENVIRONMENT` in each new shell. This installs all three workspace packages and the shared
  62. development tools into Conda. `--inexact` preserves Conda-managed bootstrap packages. Hooks use the
  63. tools from this environment, so keep it active when committing. `uv.lock` pins workspace dependencies;
  64. `environment.yml` defines the Python and uv bootstrap. No credentials are needed for Phase 0.
  65. Run the local acceptance checks after syncing:
  66. ```sh
  67. uv run --all-packages --no-sync ruff check .
  68. uv run --all-packages --no-sync ruff format --check .
  69. uv run --all-packages --no-sync mypy
  70. uv run --all-packages --no-sync pytest
  71. ```
  72. The reserved commands currently print version `0.0.1` and exit:
  73. ```sh
  74. athlete-ledger
  75. athlete-ledger-mcp
  76. athlete-ledger-agent
  77. ```
  78. The ledger store supports SQLite and Oracle ADB. Provider synchronization, the MCP server and
  79. the agent will be implemented in later phases. Configuration names are listed with empty values
  80. in `.env.example`. API references and verification gaps are in
  81. [docs/reference/README.md](docs/reference/README.md).
  82. Contributors and coding agents: see [AGENTS.md](AGENTS.md).
  83. Acceptance currently uses local checks.
  84. ## Database
  85. For the complete Oracle procedure, follow [Oracle ADB setup](docs/oracle-adb-setup.md):
  86. provisioning, browser-based user/role setup, wallet, `.env`, Python migrations and verification.
  87. SQLcl is optional.
  88. Database commands and setup scripts show a terminal banner and green `[OK]` labels for completed
  89. steps. An unversioned schema is marked `[INFO]`. Redirected output has no banner or ANSI colors;
  90. set `NO_COLOR=1` to disable colors in a terminal. `db sql` always emits only SQL.
  91. Activate the Conda environment as described above. With no database variables set, SQLite uses
  92. `sqlite:///./data/athlete_ledger.db` relative to the current directory. Parent directories are created
  93. when needed. Apply the packaged Alembic migrations, then check the database:
  94. ```sh
  95. athlete-ledger db upgrade
  96. athlete-ledger db check
  97. athlete-ledger --version
  98. ```
  99. Settings are read from environment variables and an optional `.env` in the current directory;
  100. environment variables take precedence and empty environment-file entries are ignored. To use a
  101. different SQLite file, set `ATHLETE_LEDGER_DB_URL` to its SQLAlchemy SQLite URL. Do not set it
  102. together with `ATHLETE_LEDGER_DB_DSN`.
  103. For an **existing Oracle schema**, keep the unzipped wallet outside this repository and configure
  104. the Oracle variables below. From the repository root, with the Conda environment active, run:
  105. ```sh
  106. python scripts/create_tables.py
  107. ```
  108. This creates/upgrades the six ledger tables and the Alembic revision table, then runs `db check`.
  109. It uses Python thin-mode mTLS and requires no SQLcl installation. Re-running it applies only
  110. pending migrations. It refuses the SQLite default when the Oracle DSN is missing, so an incomplete
  111. configuration cannot silently create a local database. The schema owner must already have
  112. `CREATE SESSION`, `CREATE TABLE`, `CREATE SEQUENCE`, `CREATE VIEW` and a quota on `DATA`.
  113. The `ATHLETE_LEDGER_READER` role must also already exist because migrations grant it SELECT;
  114. creating users/roles is an administrator prerequisite, not an action performed by this launcher.
  115. For a **new schema**, the optional SQL bootstrap is available: using SQLcl, connect as `ADMIN`
  116. through the wallet and run [sql/oracle/00_bootstrap.sql](sql/oracle/00_bootstrap.sql). The script
  117. prompts for owner and reader passwords with hidden input, creates `ATHLETE_LEDGER`, the
  118. `ATHLETE_LEDGER_READER` role, and `ATHLETE_LEDGER_RO`. It assigns the owner a 1G quota on `DATA`
  119. and only `CREATE SESSION`, `CREATE TABLE`, `CREATE SEQUENCE`, and `CREATE VIEW`. The reader gets
  120. only `CREATE SESSION` and the reader role. Reruns preserve existing passwords and reapply the
  121. quota/grants; they do not remove pre-existing privileges. Use dedicated accounts and review their
  122. privileges if they already existed. Follow the script's supported password character set and ADB
  123. complexity rules; keep spooling/session recording off during bootstrap.
  124. Configure the following privately in your environment or local `.env`, then run the same
  125. `db upgrade` and `db check` commands as the schema owner:
  126. | Variable | Purpose |
  127. |---|---|
  128. | `ATHLETE_LEDGER_DB_USER` | `ATHLETE_LEDGER` schema owner |
  129. | `ATHLETE_LEDGER_DB_PASSWORD` | Owner password |
  130. | `ATHLETE_LEDGER_DB_DSN` | TNS alias from the wallet's `tnsnames.ora` |
  131. | `ATHLETE_LEDGER_DB_WALLET_DIR` | Directory containing `tnsnames.ora` and `ewallet.pem` |
  132. | `ATHLETE_LEDGER_DB_WALLET_PASSWORD` | Wallet password for thin-mode mTLS |
  133. | `ATHLETE_LEDGER_RO_DB_USER` | `ATHLETE_LEDGER_RO`, reserved for the later MCP server |
  134. | `ATHLETE_LEDGER_RO_DB_PASSWORD` | Reader password, reserved for the later MCP server |
  135. Leave `ATHLETE_LEDGER_DB_URL` unset for Oracle. The engine uses `oracle+oracledb` in thin mode;
  136. the wallet directory is passed as both `config_dir` and `wallet_location`. No Oracle Client
  137. installation or `init_oracle_client()` call is needed. `db check` prints only backend, server
  138. version and Alembic revision. Failures return a nonzero exit status: settings diagnostics list only
  139. the missing or invalid environment variable names; database diagnostics show only an available
  140. `ORA-nnnnn` or `DPY-nnnn` code; filesystem diagnostics show only the `OSError` type. Original error
  141. messages, settings values, paths, SQL and bound parameters are not printed. Successful upgrades
  142. report `0002_activity_training_metrics`; an empty database reports `unversioned`.
  143. **Upgrading an existing database:** activate the project environment and run the upgrade as the
  144. schema owner, then check the revision:
  145. ```sh
  146. athlete-ledger db upgrade
  147. athlete-ledger db check
  148. ```
  149. On ADB, `python scripts/create_tables.py` performs the same upgrade/check sequence. Both fresh
  150. and existing databases reach `0002_activity_training_metrics`; no separate installation path is
  151. needed. This revision adds 19 nullable activity training metric columns, without changing existing
  152. values or reader grants. The existing table-level SELECT grant covers the new columns. They stay
  153. NULL immediately after the schema upgrade. Run `sync rebuild` to populate them from saved raw
  154. responses using the current mapping; new downloads also fill them during normal sync. The MCP activity tools
  155. expose them with the units and plain-sum semantics documented below.
  156. Generate the reviewable Oracle schema from Alembic without connecting:
  157. ```sh
  158. athlete-ledger db sql --dialect oracle > sql/oracle/schema.sql
  159. athlete-ledger db sql --dialect sqlite
  160. ```
  161. The snapshot is checked by tests; regenerate it after migration changes. It is an offline
  162. representation of the same migrations, not an additional script to apply after `db upgrade`.
  163. Oracle DDL auto-commits, so an interrupted migration may require inspection before retrying.
  164. Documents use text storage on SQLite and CLOB with `IS JSON` constraints on Oracle, because the
  165. locked SQLAlchemy 2.0 dialect cannot compile native JSON. Replace JSON documents as a whole;
  166. in-place mutations are not tracked. Fetch/update timestamps round-trip as aware UTC datetimes,
  167. stored as naive UTC (`TIMESTAMP` on Oracle). Activity `start_time_local` is deliberately a naive
  168. provider-local wall time and does not identify a timezone.
  169. Before starting sync development, the maintainer must verify bootstrap and grants on ADB,
  170. wallet mTLS, repeatable `db upgrade`, and `db check`. Also test synthetic object/list JSON
  171. round-trips (including Unicode, SQL NULL and a document larger than 32 KiB), invalid JSON rejection,
  172. UTC timestamps, and reader access: qualified `SELECT` on the owner tables succeeds while DML and
  173. DDL fail. Reader sessions use `ATHLETE_LEDGER.<table>`; no synonyms or default-schema changes are
  174. created. These live Oracle checks have not been run by the test suite.
  175. ## Sync
  176. Apply the database migrations first. Sync runs only in the CLI, using the official Personal API
  177. SDK; the MCP server will read the ledger database only. Work with one sync process per database
  178. at a time. This phase adds no schema changes.
  179. Create a Personal API key for your own account using the
  180. [official Personal API instructions](https://developer.garmin.com/gc-developer-program/personal/personal-faq/).
  181. Set `GARMIN_PERSONAL_API_KEY` privately in your environment or local `.env`; the application passes
  182. that secret explicitly to SDK discovery. With neither configured, the SDK can use its default
  183. key file `~/.config/garmin/connect-personal-api-key`. Protect a key file with mode `0600`. Never
  184. put credentials on the command line. Key validity and expiry are independent of bearer tokens.
  185. The SDK caches bearer tokens in `~/.config/garmin/connect-personal-api-bearer-token.json`, outside
  186. the repository. New cache files are created with mode `0600`; the adapter tightens permissions on
  187. an existing cache before using it. A data request returning 401 triggers one forced token
  188. exchange and retry. A second 401 or a 403 is fatal. Transient 429/5xx/timeout/connection failures
  189. have up to three retries, waiting 2, 4 and 8 seconds. Authentication requests use the same transient
  190. retry budget. Provider error messages never include response bodies, request URLs, keys or tokens.
  191. Activate the Conda environment and run from the repository root. Backfill an explicit historical
  192. range, replacing the sample dates with dates relevant to your own account:
  193. ```sh
  194. athlete-ledger sync backfill --since 2026-01-01 --until 2026-01-14
  195. athlete-ledger sync status
  196. athlete-ledger sync run
  197. ```
  198. `--until` defaults to the machine's local date. Future dates and reversed ranges are rejected.
  199. By default all four datasets run: `activities`, `sleep`, `hrv`, `stress`. Limit a run with one or
  200. more names; repeated `--dataset` options are also accepted:
  201. ```sh
  202. athlete-ledger sync backfill --since 2026-01-01 --until 2026-01-14 --dataset sleep hrv
  203. athlete-ledger sync run --dataset activities --dataset stress
  204. ```
  205. Each dataset needs a successful backfill before its first incremental run. Incremental sync starts
  206. at that dataset's last committed date minus two days, refreshing its last three synced calendar
  207. days plus any newer days through today. If no committed date exists, the command reports that a
  208. backfill is needed. `sync status` reads only dataset progress dates, run timestamps and status;
  209. it does not discover credentials, construct a provider or contact the API.
  210. Rebuild normalized records after upgrading to a version with changed field mappings:
  211. ```sh
  212. athlete-ledger sync rebuild
  213. athlete-ledger sync rebuild --dataset activities
  214. ```
  215. `sync rebuild` uses the **owner** connection and reads only the existing database; it requires
  216. no provider API key, constructs no provider and makes no downloads. It applies every non-empty
  217. raw response in ascending `raw_response.id` order through the same upsert used by sync. The last
  218. applied values win; it does not infer download/chunk boundaries from ranges, offsets or empty
  219. pages. This fills the 19 activity training metric columns from `0002_activity_training_metrics`
  220. when those fields are present in the stored provider summaries. Missing/invalid/negative values
  221. remain NULL, zero is valid, training effects are limited to 0–5, and labels must be non-empty
  222. strings of at most 64 characters (never truncated). Units stay as stored: speed in m/s, moving
  223. and HR-zone durations in seconds, intensity minutes rounded to integers. Location, owner and
  224. device fields are not mapped. Sleep, HRV and stress mappings are unchanged.
  225. Replay is one transaction per dataset. Raw metadata is streamed and only one payload is fetched
  226. at a time; the transaction retains normalized records and their initial scalar values. Every raw
  227. occurrence is applied in order, with writes deferred until the final comparison. Row counters are
  228. **net changes from transaction entry**, rather than historical intermediate transitions. Repeating
  229. rebuild against unchanged raw history and mappings reports zero inserts/updates and preserves
  230. update timestamps and provenance. The command never modifies `raw_response` or `sync_state`, and
  231. never deletes normalized rows; records absent from later responses are retained.
  232. Per dataset, output contains counts for `raw_read`, `empty_skipped`, `rows_inserted`,
  233. `rows_updated`, `rows_unchanged` and `placeholders_skipped`. Empty responses are skipped. Null or
  234. reversed stored ranges, invalid JSON or normalization failures roll back that dataset, continue
  235. the remaining datasets and return nonzero. Failure diagnostics contain only the endpoint and
  236. raw row ID; no payload, values, names, SQL or exception text. Failed-dataset row counters are
  237. zero (rolled back), while raw/empty counts describe attempted reads. **Run only one sync or
  238. rebuild process at a time for a database.** A rebuild does not change sync progress or coverage.
  239. Inspect the downloaded date coverage without contacting the API. Like the other sync commands,
  240. it shows the standard banner in an interactive terminal; redirected output omits the banner:
  241. ```sh
  242. athlete-ledger sync coverage
  243. athlete-ledger sync coverage --dataset sleep hrv
  244. ```
  245. For each dataset, `sync coverage` merges overlapping or adjacent inclusive ranges and prints
  246. `covered` intervals with `from`, `to` and calendar-day counts. It also shows each internal `gap`
  247. and a separate `tail` from the last downloaded day plus one through the machine's local today.
  248. No dates before the first downloaded interval are inferred. A dataset without ranges reports
  249. `nothing downloaded` rather than guessing a historical start date. A single interval without
  250. internal gaps uses `[OK]`; other datasets and gap/tail lines use `[INFO]`. A tail is informational
  251. and may still follow an `[OK]` interval.
  252. Coverage is derived from the committed `raw_response` chunk boundaries, filtered by provider
  253. and dataset endpoint. The query selects only distinct `range_start`/`range_end` pairs, never JSON
  254. payloads or request parameters. Normalized records are not used: a day with no activity, an empty
  255. response or a missing daily summary can still belong to a successfully downloaded interval.
  256. Failed chunks are rolled back and leave no new coverage; unchanged responses already have a
  257. saved range. Coverage describes requested date ranges, not the number or completeness of records
  258. returned by the provider. The progress date shown by `sync status` is only a high-water mark and
  259. cannot reveal holes between older and newer downloads.
  260. Each internal gap is followed by a dataset-specific backfill command. For example, if synthetic
  261. sleep downloads cover January 1–7 and January 10–20, the missing January 8–9 range can be filled by:
  262. ```sh
  263. athlete-ledger sync backfill --since 2026-01-08 --until 2026-01-09 --dataset sleep
  264. athlete-ledger sync coverage --dataset sleep
  265. ```
  266. The coverage command reads only the database, does not discover an API key or construct a
  267. provider, and does not change sync progress. Only the suggested backfill command contacts the
  268. API when you choose to run it. After the Phase 1b real-data checks, verify `sync coverage` on ADB
  269. and confirm that the downloaded ranges, any internal gaps and the unsynced tail match your runs.
  270. Requests use inclusive windows of at most seven days. Activities are paged with limit 100 through
  271. an empty terminating page; the provider rejects pagination that makes no progress. Both sync
  272. and rebuild use **last applied wins** for normalized values: each stored page is applied in order,
  273. and a later occurrence of the same activity overrides earlier values, including repetitions
  274. inside a single response. No cross-page or within-chunk first-occurrence filter is used. Every chunk commits raw responses, normalized rows and state together. On failure, that
  275. chunk is rolled back, previous chunks remain committed, and a separate transaction records
  276. `failed` without advancing its last committed date. Other datasets continue; any failure produces
  277. a nonzero exit code. Older backfills preserve the later stored progress date, so they do not
  278. move the next incremental window backwards; run timestamps and status still reflect the latest
  279. attempt. Re-running an interrupted backfill is safe: completed chunks can be fetched
  280. again, and identical raw responses are skipped. `sync run` resumes from the last committed date
  281. with the normal overlap.
  282. The ledger keeps raw responses append-only and hashes canonical UTF-8 JSON, comparing the latest
  283. response with the same endpoint, range and SDK call parameters. Matching content skips storage
  284. and normalization. Changed responses are stored before normalization; only rows whose normalized
  285. values change get a new update timestamp and source-response reference. Records absent from a
  286. later response are **not deleted**; provider-side deletions are outside this MVP. JSON documents
  287. that are not valid serializable JSON are rejected rather than altering their raw content.
  288. Activity `startTimeLocal` accepts ISO datetime strings with a space or `T` separator and optional
  289. fractional seconds. It remains provider-local naive time: timestamps containing a timezone offset
  290. or `Z` are rejected rather than silently converted or stripped of their timezone.
  291. Output uses the terminal banner and `[OK]`/`[INFO]` helpers. Per dataset it shows chunk and request
  292. counts, raw stored/unchanged counts, normalized rows inserted/updated/unchanged, and skipped
  293. placeholder counts. Request counts include data-request retries and terminating empty activity
  294. pages, but exclude token exchanges. Row counts describe rows actually normalized; responses
  295. skipped by hash increment only `raw_unchanged`. Counts from a rolled-back chunk are discarded,
  296. while its attempted requests remain in the request count. Metric values, activity names and
  297. payloads are never printed. Full SDK logs are suppressed because their diagnostics can include
  298. cache paths; only sanitized endpoint/method/status errors are displayed.
  299. Local tests use fake clients and synthetic SQLite data, with guards against real HTTP calls and
  300. credential discovery. Before Phase 2, the maintainer should verify on ADB a 14-day backfill,
  301. repeat `sync run` against stable provider data and check `rows_updated=0`, then inspect
  302. `sync status`. New/recalculated provider data can legitimately produce inserts or updates; zero
  303. updates is expected only when normalized source values have not changed. See the SDK evidence in
  304. [the reference notes](docs/reference/README.md#personal-api-sdk-source-verification-phase-1b).
  305. ## MCP server
  306. `athlete-ledger-mcp` serves exactly four read-only, structured data tools over **stdio**.
  307. It reads the ledger only; it never imports the sync adapter, discovers a provider key or
  308. contacts the provider. Tool results contain data, not training advice or narrative analysis.
  309. | Tool | Returned data |
  310. |---|---|
  311. | `ledger_status()` | Local today, per-dataset downloaded intervals and gaps, sync progress, first/last record dates and sports with activity counts. |
  312. | `list_activities(start, end, sport=None, limit=50)` | Local-date activity summaries, optional exact sport filter, stable ordering, total match count, truncation and clipped download coverage. Limit: 1–200. |
  313. | `activity_totals(start, end, group_by)` | Groups by ISO week (with Monday), calendar month or sport, overall totals, missing-value counts, duration-weighted HR and clipped coverage. |
  314. | `daily_wellness(start, end, areas=None)` | Every day in an inclusive range of at most 92 days, with sleep/HRV/stress metrics and download/record state for each requested area. |
  315. Dates use `YYYY-MM-DD` and include both endpoints. Activity start times are provider-local wall
  316. time without a timezone. Results use km (2 decimals), minutes (1), hours (2), HR in beats/minute,
  317. respiration in breaths/minute and HRV in milliseconds; averages have 1 decimal. Null means
  318. unavailable; zero remains valid. Totals skip nulls and report missing counts for each input
  319. metric. An empty/all-null sum is null. Weighted HR excludes activities missing either HR or
  320. duration and is null when the eligible total duration is zero. Unknown sport groups use
  321. `unknown`; actual sport fields remain null when unknown.
  322. `list_activities` additionally returns these stored activity training metrics:
  323. | Field | Units and precision |
  324. |---|---|
  325. | `moving_duration_min`, `avg_speed_kmh` | Minutes (1 decimal); km/h from m/s × 3.6 (1 decimal) |
  326. | `max_hr_bpm`, `elevation_gain_m`, `elevation_loss_m` | Beats/minute and metres, all 1 decimal |
  327. | `training.aerobic_effect`, `training.anaerobic_effect` | Provider per-activity effects on 0–5, 1 decimal |
  328. | `training.effect_label`, `training.load` | Provider label as stored; provider load units, 1 decimal |
  329. | `training.stress_score`, `training.intensity_factor`, `training.normalized_power_w` | TSS points (1 decimal), dimensionless IF ratio (2), watts (0) |
  330. | `intensity_minutes.moderate`, `intensity_minutes.vigorous` | Separate integer minutes |
  331. | `hr_zone_min.zone_1` through `zone_5` | Minutes in each heart-rate zone, 1 decimal |
  332. `activity_totals` adds the following to **every group and `overall`**: `training_load`
  333. (provider load units, 1 decimal), `training_stress_score` (TSS points, 1), `moving_duration_h`
  334. (hours, 2), `elevation_gain_m` (metres, 1), separate integer sums in
  335. `intensity_minutes.moderate`/`vigorous`, and `hr_zone_h.zone_1` through `zone_5` (hours, 2).
  336. Sums skip nulls and are converted/rounded **after** summation. Empty/all-null sums stay null;
  337. measured zero remains zero. The `missing` object adds activity counts for `training_load`,
  338. `training_stress_score`, `moving_duration`, `elevation_gain` and `hr_zones`; an activity lacks
  339. zones only when all five stored zone times are null. A partially populated or zero-valued zone
  340. set is not counted as missing zones.
  341. The new nested objects are always present, with null members when data is missing. Names retain
  342. the same opt-in behavior. Training effect, labels and load are the provider's own per-activity
  343. values. TSS, IF and normalized power are available mostly for activities recorded with a power
  344. meter. These data are exposed and, where specified, **summed without interpretation**: there
  345. are no effect/IF averages, label interpretations, derived load scores or weighted combinations
  346. of intensity minutes. The existing duration-weighted average HR keeps its previous meaning.
  347. Wellness states distinguish `not_downloaded` (outside coverage), `no_record` (downloaded but no
  348. normalized row) and `ok` (row exists; individual metrics may be null). `areas` defaults to all
  349. three areas; an empty list returns dated rows with no selected areas. Requested-range coverage
  350. includes missing dates at either edge as gaps; `ledger_status` shows internal gaps only.
  351. Install/sync from the repository in the active Conda environment:
  352. ```sh
  353. conda activate athlete-ledger
  354. export UV_PROJECT_ENVIRONMENT="$CONDA_PREFIX"
  355. uv sync --all-packages --inexact --locked
  356. command -v athlete-ledger-mcp
  357. ```
  358. Keep a private settings file outside source control, based on `.env.example`. For SQLite,
  359. `ATHLETE_LEDGER_DB_URL` must identify an **existing** ledger file. Use an absolute SQLite path
  360. when a desktop client may start in another directory, and quote a dotenv URL containing spaces
  361. or `#`. Relative paths are resolved against the process working directory, not the settings
  362. file's directory. SQLite is opened with URI `mode=ro`; missing files are rejected and never
  363. created. Create/migrate/populate the ledger separately with the regular CLI.
  364. For Oracle, configure `ATHLETE_LEDGER_RO_DB_USER` and `ATHLETE_LEDGER_RO_DB_PASSWORD` for the
  365. separately provisioned **ATHLETE_LEDGER_RO** reader, plus the existing DSN, wallet directory and
  366. wallet password variables. Both reader fields are required: owner credentials are ignored and
  367. never used as fallback. `ATHLETE_LEDGER_DB_SCHEMA` defaults to `ATHLETE_LEDGER`; it accepts only
  368. uppercase unquoted identifiers beginning with A–Z, followed by A–Z/0–9/underscore, at most 128
  369. characters. Each new reader connection sets `CURRENT_SCHEMA` to this validated owner schema.
  370. The reader must have SELECT grants on the ledger tables as provided by the bootstrap/migration.
  371. The MCP process never runs migrations or grants.
  372. Start the server with an absolute private settings-file path:
  373. ```sh
  374. /absolute/path/to/conda/envs/athlete-ledger/bin/athlete-ledger-mcp --env-file /absolute/private/path/ledger.env
  375. ```
  376. The default settings file is `.env` in the current directory if present. There is **no banner**
  377. and no human-readable stdout: stdout is reserved for MCP. Warnings/diagnostics go to stderr,
  378. with configuration/connection failures sanitized and returning nonzero. Database failures during
  379. a tool call produce a tool error with only a fixed message and an optional ORA/DPY code. No SQL,
  380. parameters, record values, credentials or tracebacks are logged. No telemetry exporter or HTTP
  381. transport is configured; the process uses a no-op tracer provider.
  382. In a desktop client's MCP server configuration, use the executable path reported above and an
  383. absolute `--env-file` argument. A typical configuration is:
  384. ```json
  385. {
  386. "mcpServers": {
  387. "athlete-ledger": {
  388. "command": "/absolute/path/to/conda/envs/athlete-ledger/bin/athlete-ledger-mcp",
  389. "args": ["--env-file", "/absolute/private/path/ledger.env"]
  390. }
  391. }
  392. }
  393. ```
  394. Keep secrets out of the client configuration. With Node.js/npm available, launch the official
  395. [MCP Inspector](https://github.com/modelcontextprotocol/inspector) against the same command:
  396. ```sh
  397. npx @modelcontextprotocol/inspector /absolute/path/to/conda/envs/athlete-ledger/bin/athlete-ledger-mcp --env-file /absolute/private/path/ledger.env
  398. ```
  399. The Inspector is a separate local development client; the ledger server still uses stdio.
  400. Verify that exactly the four tools appear with read-only annotations and output schemas. Test
  401. both the Inspector and a desktop client against a populated local SQLite ledger and then ADB
  402. as **ATHLETE_LEDGER_RO**. Ask, for example: “Which periods are downloaded?”, “List activities
  403. between these dates”, “Show activity totals by ISO week” and “Show sleep and HRV day by day”.
  404. Check gaps, nulls, units, truncated lists, ISO-week boundaries and days without records against
  405. your own ledger. Keep real results and credentials private when reporting test outcomes.
  406. **Privacy:** tool results are sent to whatever model the client uses. Activity names may contain
  407. places or people; they are not selected and the `activity_name` key is absent by default.
  408. Set `ATHLETE_LEDGER_MCP_INCLUDE_ACTIVITY_NAMES=true` in the private settings only if you intend
  409. to include them. Metric values remain part of requested tool results even with names disabled.
  410. Choose a client/model whose data handling meets your requirements.
  411. ## Disclaimer
  412. athlete-ledger is an independent open-source project. It is **not affiliated with, endorsed by,
  413. or sponsored by Garmin**. Garmin and Garmin Connect are trademarks of Garmin Ltd. or its
  414. subsidiaries. Use of the Personal API is subject to Garmin's terms; it is intended for individuals
  415. accessing their own data.
  416. ## License
  417. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.