coros-workout-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Purpose

MCP server that lets Claude design strength workouts and push them to a COROS watch via the reverse-engineered COROS Training Hub API. This is an unofficial project — the API is undocumented and may change without notice.

Build & Test

npm install && npm run build   # TypeScript → dist/
npm test                       # vitest (unit tests only, no API calls)
npm run typecheck              # type-check src, scripts and tests (CI runs this)
npm run test:watch             # vitest watch mode

Build output goes to dist/ via tsc. The server entry point is dist/src/index.ts (compiled to dist/src/index.js).

To run a single test file: npx vitest run src/__tests__/exercise-catalog.test.ts

Architecture

5 source files, clear separation:

• index.ts — MCP server setup. Registers 8 tools (authenticate_coros, check_coros_auth, search_exercises, create_workout, update_exercises, list_workouts, list_activities, get_activity_detail) using @modelcontextprotocol/sdk. STDIO transport only.
• coros-api.ts — COROS API client + payload construction. Handles auth (MD5 password hashing, token storage at ~/.config/coros-workout-mcp/auth.json), and the workout creation flow: resolveExercises() → calculateWorkout() (POST /training/program/calculate) → addWorkout() (POST /training/program/add). Also contains buildCatalogFromRaw() for the update_exercises tool, and the recorded-activity queries queryActivities() (GET /activity/query) and queryActivityDetail() (POST /activity/detail/query). All authenticated calls go through apiRequest().
• activity-format.ts — Formats recorded activities for tool output: formatActivity() for list_activities (includes the labelId/sportType that get_activity_detail needs) and formatStrengthExercises() for the set-by-set breakdown.
• exercise-catalog.ts — In-memory exercise search engine. Loads data/exercises.json lazily, provides findByName() (exact, case-insensitive), searchExercises() (fuzzy name + muscle/bodyPart/equipment filters). The catalog is the single source of truth for exercise names used in create_workout.
• types.ts — All interfaces and enum maps. Numeric code → human-readable name mappings for muscles, body parts, equipment. Key types: CatalogExercise (bundled catalog), ExercisePayload (API payload), ExerciseOverrides (user input), RawExercise (API response).