Kaiord

io.github.pablo-albaladejoPublished by GitHub account pablo-albaladejov10.5.0Updated Oct 30, 2026

Convert, validate, and inspect workout files (FIT, TCX, ZWO, Garmin Connect) for AI agents.

VerifiedStreamable HTTPWeb executableLocation & LifestyleFiles & StorageData & Analytics

Overview

AI-generated overview

Kaiord converts, validates, inspects and diffs fitness workout files (FIT, TCX, ZWO, GCN, KRD) through a canonical JSON format, as a remote endpoint or local…

What you can do
  • List supported fitness formats and read the KRD format specification before authoring documents
  • Convert between FIT, TCX, ZWO, GCN and KRD, with FIT output returned as base64 text
  • Validate KRD JSON against the schema and round-trip check FIT to KRD to FIT for tolerance violations
  • Inspect a fitness file for a human-readable summary, extract its structured workout as JSON, and diff two files
When to use it
Useful when an assistant needs to work with cycling, running or swimming workout files: converting between trainer and watch formats, checking that a generated workout is valid, or comparing two versions of a session.
Requirements
Either the remote endpoint at kaiord.com or the local npm package @kaiord/mcp over stdio, which needs Node.js. No accounts, API keys or environment variables are declared. Content is passed inline, with FIT as base64.
Before you install
Only structured workouts are accepted, and on the remote endpoint ZWO input is checked for well-formedness only, not against the XSD. FIT output arrives as base64 text, so large files are unwieldy. The training_peaks_tss duration type is not yet implemented in the FIT converter.

Installation

In SourceWeft

  1. Open Kaiord in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.pablo-albaladejo%2Fkaiord/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "kaiord": {
      "type": "http",
      "url": "https://kaiord.com/mcp"
    }
  }
}

README

Kaiord — Open-Source Health & Fitness Data Framework

kaiord.com | Editor | npm

[License: MIT] [TypeScript]

[CI] [codecov] [npm version] [npm version] [MCP Registry] [Glama MCP server] [Sponsor]

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.

✨ Features

  • Visual Workout Editor - Create and edit workouts in your browser
  • Unified JSON-based format .krd (Kaiord Representation Definition)
  • Schema validation (Zod)
  • Round-trip safe conversions between FIT / TCX / ZWO / GCN / KRD
  • Hexagonal architecture & fully typed API

Supported FIT Fields

Workout Metadata
  • Sub-sport categorization: Detailed sport types (trail running, indoor cycling, lap swimming, etc.)
  • Pool dimensions: Pool length and unit for swimming workouts
Workout Steps
  • Coaching notes: Instructional text for each step (max 256 characters)
  • Swimming equipment: Fins, kickboard, paddles, pull buoy, snorkel
Duration Types
  • Time & distance: Standard interval durations
  • 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
  • Architecture - Hexagonal architecture, ports & adapters pattern, and design principles
  • Testing - Testing strategy, TDD workflow, and coverage requirements
  • Deployment - CI/CD pipeline, GitHub Pages deployment, and npm publishing
  • Contributing - Contribution guidelines, development workflow, and code standards
  • KRD Format - Complete specification of the Kaiord Representation Definition format
  • AI Agents - Guidance for AI-assisted development

🧩 Tech Stack

LayerTooling
CoreTypeScript, tsdown, Zod
CLIyargs
Web AppReact, Zustand, Tailwind, Radix UI
TestingVitest, Playwright
Package managerpnpm

🏗 Monorepo Layout

kaiord/├─ packages/│  ├─ core/                → domain types, schemas, ports & use cases│  ├─ fit/                 → Garmin FIT format adapter│  ├─ tcx/                 → Training Center XML adapter│  ├─ zwo/                 → Zwift ZWO format adapter│  ├─ garmin/              → Garmin Connect API adapter│  ├─ cli/                 → command-line interface│  ├─ mcp/                 → MCP server for AI/LLM integration│  └─ workout-spa-editor/  → web application (https://kaiord.com/app/)├─ docs/   → documentation├─ LICENSE├─ README.md└─ pnpm-workspace.yaml

🚀 Quick Start

Try the Web App

Launch Workout Editor →

Create and edit workouts visually in your browser. No installation required.

Use the Library

bash
pnpm installpnpm -r buildpnpm -r test
# Example usagepnpm kaiord --help

For detailed installation instructions and usage examples, see the Getting Started Guide.

🚀 CI/CD Pipeline

Kaiord uses GitHub Actions for continuous integration and deployment:

  • Automated Testing: Multi-version testing on Node.js 22.x (Maintenance LTS) and 24.x (Active LTS)
  • Code Quality: ESLint, Prettier, and TypeScript strict mode validation
  • Release Automation: Changesets for version management and npm publishing
  • Security: Weekly dependency vulnerability audits, CodeQL static analysis, and automated dependency updates

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:

  1. Fork and clone the repository
  2. Create a feature branch: git checkout -b feature/my-feature
  3. Make your changes following the code style guidelines
  4. Add a changeset: pnpm exec changeset (for version-worthy changes)
  5. Test locally: pnpm -r test and pnpm -r build
  6. Submit a PR: All checks must pass before merging

For detailed contribution guidelines, development workflow, and code standards, see Contributing.

📚 References & Resources

Format Specifications

❤️ Support

If you find Kaiord useful, consider supporting its development:

Your support helps maintain and improve Kaiord for the fitness community!

Built by Pablo Albaladejo

📜 License

MIT © 2025 Pablo Albaladejo See LICENSE for details.

Source: README.md at commit 9aa0caf

Tools

8

kaiord_get_format_spec

Get the KRD format specification. Call this before creating or editing KRD documents.

Takes no parameters.

kaiord_list_formats

List all supported fitness data formats with capabilities

Takes no parameters.

kaiord_convert

Convert between fitness data formats (FIT, TCX, ZWO, GCN, KRD). FIT output is returned as base64 text unless output_file is given. On the remote endpoint, ZWO input is checked for well-formedness only, not against the XSD, and only structured workouts are accepted.

Parametersftpinput_formatinput_contentoutput_formatrequired

kaiord_validate

Validate a KRD JSON document against the schema On the remote endpoint, ZWO input is checked for well-formedness only, not against the XSD, and only structured workouts are accepted.

Parametersinput_content

kaiord_round_trip_validate

Validate round-trip FIT conversion (FIT → KRD → FIT) and report tolerance violations

Parametersinput_content

kaiord_inspect

Inspect a fitness file and return a human-readable summary

Parametersinput_formatinput_content

kaiord_extract_workout

Extract the structured workout from a fitness file as JSON

Parametersinput_formatinput_content

kaiord_diff

Compare two fitness files and show differences

Parametersformat1format2content1content2

Version history

3
  1. v10.5.0LatestOct 30, 2026
  2. v10.4.0Oct 29, 2026
  3. v10.0.0Sep 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts