kaiord

CommunityIncomplete39/100Claim

npm @kaiord/mcpstdioupdated 1mo ago

Kaiord is an open-source framework for creating, converting, and managing health & fitness data.

Source Website

What can you do with kaiord?

Kaiord — Open-Source Health & Fitness Data Framework

kaiord.com | Editor | npm

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

Layer	Tooling
Core	TypeScript, tsdown, Zod
CLI	yargs
Web App	React, Zustand, Tailwind, Radix UI
Testing	Vitest, Playwright
Package manager	pnpm

🏗 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

pnpm install
pnpm -r build
pnpm -r test

# Example usage
pnpm 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:

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.

📚 References & Resources

Format Specifications

Garmin FIT SDK (JavaScript) - Official FIT protocol implementation
FIT Workout Files Cookbook - Guide to encoding workout files
FIT File Types: Workout - Workout file type specification
Training Center XML (TCX) - Garmin's XML-based format
TCX Schema (XSD) - Official Garmin TCX schema definition
Zwift Workout Format (ZWO) - Zwift's XML-based workout format

❤️ Support

If you find Kaiord useful, consider supporting its development:

⭐ Star this repo to help others discover it
💖 Sponsor on GitHub
☕ Buy me a coffee

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

Built by Pablo Albaladejo

📜 License

Install

Add kaiord to your client. Pick the one you use.

claude mcp add mcp -- npx -y @kaiord/mcp

codex mcp add mcp -- npx -y @kaiord/mcp

amp mcp add mcp -- npx -y @kaiord/mcp

{
  "mcpServers": {
    "mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@kaiord/mcp"
      ]
    }
  }
}

Add to `claude_desktop_config.json`, then restart Claude Desktop.

{
  "mcpServers": {
    "mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@kaiord/mcp"
      ]
    }
  }
}

Add to `~/.cursor/mcp.json`, or `.cursor/mcp.json` for a single project.

code --add-mcp '{"name":"mcp","command":"npx","args":["-y","@kaiord/mcp"]}'

Or add the block manually to `.vscode/mcp.json` under `servers`.

{
  "mcpServers": {
    "mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@kaiord/mcp"
      ]
    }
  }
}

Add to `~/.codeium/windsurf/mcp_config.json`.

{
  "mcpServers": {
    "mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@kaiord/mcp"
      ]
    }
  }
}

Add to `cline_mcp_settings.json` via the MCP Servers panel.

{
  "mcpServers": {
    "mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@kaiord/mcp"
      ]
    }
  }
}

Add to `~/.gemini/settings.json`.

{
  "mcpServers": {
    "mcp": {
      "type": "local",
      "command": "npx",
      "args": [
        "-y",
        "@kaiord/mcp"
      ],
      "tools": [
        "*"
      ]
    }
  }
}

Add to `~/.copilot/mcp-config.json`, or run `/mcp add` inside the CLI.

{
  "context_servers": {
    "mcp": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@kaiord/mcp"
        ]
      }
    }
  }
}

Add to your Zed `settings.json`.

npx -y @kaiord/mcp

Run `goose configure`, choose **Add Extension → Command-line Extension**, and paste this command.