Convert, validate, and inspect workout files (FIT, TCX, ZWO, Garmin Connect) for AI agents.
io.github.pablo-albaladejo/kaiord MCP Server
The io.github.pablo-albaladejo/kaiord MCP server converts, validates, and inspects workout files for AI agents. It targets common fitness data formats and sources, including FIT, TCX, ZWO, and Garmin Connect, enabling tooling around workout data processing.
🛠️ Key Features
Convert workout files
Validate workout files
Inspect workout files
Supports: FIT, TCX, ZWO, Garmin Connect
🚀 Use Cases
AI-assisted processing of fitness-data
Working with Garmin-related workout exports
Converting and validating workout files for analysis or review
⚡ Developer Benefits
Built for MCP integrations (“mcp” topic)
TypeScript-oriented project (“typescript” topic)
Local-first and workout-editor oriented workflows (“local-first”, “workout-editor” topics)
⚠️ Limitations
Scope is limited to workout-file conversion, validation, and inspection across the listed formats/sources
Kaiord is an open-source framework for creating, converting, and managing health & fitness data.
It provides:
@kaiord/core: a TypeScript library with format adapters for .fit, .tcx, .zwo, and .krd (Kaiord) files, plus Garmin Connect API integration.
@kaiord/cli: a command-line tool to convert, validate, and compare files across formats.
@kaiord/mcp: an MCP server exposing Kaiord tools to AI agents (Claude Desktop, Claude Code, etc.). Published in the official MCP registry as io.github.pablo-albaladejo/kaiord.
Workout Editor: a web application to create and edit workout files visually.
Calorie-based: Steps ending after burning specified calories
Power-based: Steps ending based on power thresholds (watts)
Heart rate conditionals: Steps ending based on HR thresholds (bpm)
Repeat conditionals: Repeat blocks until time/distance/calories/HR/power targets reached
Known Limitations
Training Stress Score (TSS): The training_peaks_tss duration type is not yet implemented in the FIT converter. This is a TrainingPeaks-specific metric that requires additional mapping logic. Contributions welcome!
🔒 Local-first architecture
Kaiord is local-first: your data lives on your device, because there is no Kaiord server to send it to. There are no accounts and no backend.
Storage is your browser's IndexedDB. The Workout Editor persists every workout, template, profile, and setting in a local Dexie.js / IndexedDB database (new KaiordDatabase() in dexie-database.ts), and the UI reads it reactively through useLiveQuery. Nothing is written to a remote database — see the "Persisted data → Dexie" rule in State Management.
Conversions run entirely on your machine. FIT / TCX / ZWO / GCN ↔ KRD conversion happens in-process — client-side in the editor (import-workout-formats.ts, export-workout-formats.ts) or locally in the @kaiord/cli. Files never leave your device to be converted.
Sync is opt-in and goes to your cloud. Data leaves the device only if you connect Google Drive. The cloud-sync adapter uses the Google Identity Services drive.appdata scope, so synced data lands in your own Drive's app folder; the access token lives only in memory for the session and is never persisted by Kaiord.
Integrations use your logged-in session — no credential proxy. Garmin, WHOOP, and Train2Go connect through browser-extension "bridges" (garmin-bridge, whoop-bridge, train2go-bridge) that piggyback on your existing browser session. Per openspec/specs/adapter-contracts/spec.md, a bridge "SHALL NOT store, transmit, or manage user credentials"; authentication is "delegated entirely to the browser's cookie jar." No third-party server proxies your credentials or your data.
Works offline. Because all logic and storage are client-side, the editor keeps working with no network connection once loaded.
📚 Documentation
Comprehensive documentation is available in the /docs directory:
Getting Started - Installation, basic usage, and quick examples for both library and CLI
For complete CI/CD documentation, deployment guides, and npm publishing instructions, see Deployment.
Mechanical invariant guards
Beyond linting, the repo enforces its architecture and conventions with 60+ purpose-built guard scripts under scripts/, each with its own co-located test suite. They run on every commit (husky pre-commit) and in CI (pnpm test:scripts), and cover, among others:
Hexagonal architecture — layer purity, adapter isolation, and the packages/core/src/ directory allowlist (check-architecture.mjs)
Package dependency graph — every @kaiord/* dependency must match the spec table (check-package-deps.mjs)
Test conventions — should -prefixed titles and Arrange/Act/Assert structure on every test (check-test-title-should.mjs, check-test-aaa.mjs)
Privacy — no runtime values interpolated into toasts or console logs (check-no-pii-leakage.mjs)
State discipline — no Zustand store writes persistence directly (check-no-zustand-writethrough.mjs)
Spec hygiene — OpenSpec format, archive dates, and auto-generated indexes stay in sync (check-spec-format.mjs, check-archive-*.mjs)
If a rule matters here, a script enforces it — documentation describes the rules, but the guards are what make them true.
Contributing
To contribute to Kaiord:
Fork and clone the repository
Create a feature branch: git checkout -b feature/my-feature
Make your changes following the code style guidelines
Add a changeset: pnpm exec changeset (for version-worthy changes)
Test locally: pnpm -r test and pnpm -r build
Submit a PR: All checks must pass before merging
For detailed contribution guidelines, development workflow, and code standards, see Contributing.
