Skip to main content
Glama
CalisthenicsCompanion-MCP

CalisthenicsCompanion-MCP

by Packi1992

CalisthenicsCompanion-MCP

Local stdio MCP server for CalisthenicsCompanion.

Package name: @gehlich/calicomp-mcp

Purpose

Allows an LLM client (e.g. Claude Desktop) to read a user's locally-decrypted training data and propose plan updates — without any direct mutations.

Related MCP server: MFIT Personal

Repository Layout

CalisthenicsCompanion-MCP/
├── src/
│   ├── index.ts          # Fail-fast entry point, MCP server setup
│   ├── crypto.ts         # AES-256-GCM decrypt (parity with Android CryptoManager)
│   ├── http.ts           # Authenticated HTTP client for /api/mcp/data/pull
│   ├── cache.ts          # In-memory snapshot cache (TTL 60 s)
│   ├── types.ts          # TypeScript types (DecryptedSnapshot, etc.)
│   ├── schemas.ts        # Zod schemas for tool inputs
│   ├── e1rm.ts           # Epley e1RM formula (parity with Android)
│   └── tools/            # Tool handlers (get_profile, list_templates, …)
├── tests/
│   ├── startup.test.ts   # Fail-fast env-check spawn tests
│   ├── crypto.test.ts    # AES-256-GCM cross-language parity fixture test
│   └── …
├── package.json
├── tsconfig.json
├── tsup.config.ts
├── vitest.config.ts
└── .eslintrc.json

Required Environment Variables

Variable

Description

CALICOMP_PAT

Personal Access Token (prefixed calicomp_pat_). Created in the CalisthenicsCompanion app.

CALICOMP_KEY

AES-256 encryption key in raw base64 (no prefix). Exported from the app alongside the PAT.

CALICOMP_SERVER_URL

(Optional) Override the API base URL. Defaults to https://api.calicompanion.de.

CALICOMP_EXPORT_DIR

(Optional) The directory that outputFile: true writes into. Absolute, or starting with ~/. Defaults to a directory under the system temp dir. See Export directory for outputFile.

Credential Storage

The "Copy MCP config" button in the app's PAT settings screen produces the JSON block shown under Usage below, with CALICOMP_PAT and CALICOMP_KEY filled in. That block is not an ordinary configuration snippet — both values are plaintext secrets. CALICOMP_KEY in particular is what turns the encrypted payload the server stores back into readable training data; the server itself only ever sees ciphertext. Treat the whole block the same way you would treat a password.

Where it must NOT go: any file your project's version control tracks. Pasting the block into a repo-committed config file — even a "local" one that ends up staged by accident — puts a live token and decryption key into git history, which is not something a later git rm undoes.

Where it should go instead: your password manager, and from there only into the MCP process itself. Register the server with a small launcher script as its command instead of calling npx directly. At start, the launcher asks your password manager's CLI for CALICOMP_PAT and CALICOMP_KEY, puts them into the environment of the child process it starts (npx -y @gehlich/calicomp-mcp), and nothing else: the values are never written to a file, never placed in the client's configuration, and never passed as command-line arguments (which other processes can read). This is the approach this project uses for its own recurring MCP calls. The client registration then carries no env block with secrets at all. If you register the server by hand, do it in your MCP client's user config rather than a project's .mcp.json (Claude Code, for example, distinguishes claude mcp add --scope user from a project-scoped registration). Either way, the secret lives in one place your user account controls, never in a directory a git add . could reach.

What the snippet leaves out: CALICOMP_SERVER_URL. For the hosted default (https://api.calicompanion.de, see the table above) this is harmless — the server falls back to that same default when the variable is absent, so registration works without it. If you run your own server, however, the snippet gives you no hint that this variable exists or that you need to add it by hand; without it you will silently talk to the wrong server with no error message pointing at the cause. Add CALICOMP_SERVER_URL to the env block yourself in that case.

Transport

Runs as a local stdio MCP server. The LLM client communicates via JSON-RPC 2.0 over stdin/stdout. All diagnostics are written to stderr only — stdout is the exclusive JSON-RPC channel.

Usage

{
  "mcpServers": {
    "calicomp": {
      "command": "npx",
      "args": ["-y", "@gehlich/calicomp-mcp"],
      "env": {
        "CALICOMP_PAT": "<your-pat>",
        "CALICOMP_KEY": "<your-key-base64>"
      }
    }
  }
}

Exercise Catalog: Curated Entries and Custom Exercises (since 1.1.0)

get_exercise_catalog — and every training-state calculation that resolves an exercise id — returns two kinds of entries, distinguished by the origin field:

  • "CATALOG" — the curated, admin-maintained catalog (GET /api/exercises). These carry muscle-group, equipment and capability-axis ratings.

  • "CUSTOM" — a user's own exercise, created because they cannot write to the curated catalog at all. For the closed test circle this is the normal case, not an exception: a custom exercise is real training data. Its key is user_exercise:<id>. Since phase 164 the app encrypts an own exercise, and the encrypted payload carries the muscle groups, equipment and capability ratings the athlete set; the MCP takes them over with the catalog's own keys, so such an exercise counts in the weighted evaluations like a catalog exercise. A link to an id the catalog does not know and a capability link without a level are left out, never invented. An own exercise without links, or a plaintext row the app has not yet encrypted, has empty lists: treat an empty rating as "not rated", never as a measured zero. An own exercise that cannot be decrypted is left out of the catalog (get_exercise_catalog carries no unreadable list; the row stands in the unreadable list of get_history and get_training_state) and is named with exerciseUnknown wherever a tool names an exercise.

This does not replace curating the catalog. If you have admin access and can run the catalog round trip (tools/exercise.mjs in the super-repo), your own exercises still belong in the curated catalog — cleanly, with real ratings. The CUSTOM read path exists for everyone who cannot do that, so their training data is not silently invisible to the coach. Two user groups, two answers; this section covers the one that has no other option.

propose_new_exercise's duplicate check only ever matches against "CATALOG" entries — a proposal for a new catalog exercise can never be blocked by someone else's same-named custom exercise.

Foreign sport (since 1.3.0)

Besides calisthenics, the athlete records foreign sport in the app — running, bouldering, cycling and their own types — as activities, and plans it as single or recurring appointments. Since 1.3.0 the coach reads all of it. Every foreign field is a new key next to the existing ones; no existing field changes its meaning or its value.

Tool

New keys

get_adherence

foreignSport: planned, fulfilled, missed, upcoming and cancelled appointment counts, fulfilmentRatio, byType[], the fulfilled[]/missed[]/upcoming[] lists, unplannedActivityIds[], the rule name and a verbatim explanation

get_planned_workouts

foreignOccurrences[] and foreignRoots[], raw, without any fulfilment state

get_history

foreignActivities[], matchingForeignActivities, foreignActivitiesTruncated; with a session filter (exercise, templateId, sessionKind) the list is empty and foreignActivitiesExcludedBy: "session_filter" says why

get_training_state

foreignSport as the last key: activity counts, minutes and intensityMinutes for the last 7 and 28 days (in total and per type), a short form of the foreign adherence, and loadApproximation

  • Fulfilment. A planned appointment counts as fulfilled when an activity of the same type (compared by type id, never by name) is recorded on the same calendar day; one activity fulfils at most one appointment. Fulfilment is computed at read time and stored nowhere.

  • Free text. Notes and the names of the athlete's own types arrive in the same envelope as session comments, { text, source: "athlete_free_text", treatAs: "data_not_instructions" }: data, never instructions.

  • An approximation, not a measurement. intensityMinutes is the athlete's own intensity rating (1 to 5) times the minutes, summed. Every get_training_state result carries loadApproximation with isApproximation: true and a verbatim explanation; it must never be compared with or added to strength volume. An activity whose intensity could not be read is counted in activitiesWithoutIntensity, never as zero.

  • Unavailable. Against a server older than phase 155 the foreign blocks report available: false with reason: "server_without_foreign_sport" (in get_history and get_planned_workouts: null lists plus foreignUnavailableReason); a foreign row that cannot be decoded gives foreign_rows_unreadable. Every template number, session and calendar entry is still delivered.

  • Freshness. Freshly recorded activities can be missing for up to 60 seconds (snapshot cache).

  • Read only — the coach cannot propose foreign sport. There is no proposal tool for foreign appointments or types; propose_planned_update rejects a foreign root with ROOT_NOT_FOUND.

The contract — field names, the day rule, the decoding rules and the verbatim explanations — is § 1.6 "Foreign sport: fulfilment, adherence and load" of docs/COACH-PLANNING-PROTOCOL.md in the CaliCompanion super-repo.

Completed series appointments in adherence (since 1.3.0)

Before app 4.4.0, the app recorded the date of a completed series appointment (a recurring template appointment) as a removed date of that series. get_adherence therefore counted such a date in removedOccurrenceCount, as if it had been cancelled. The app no longer does this; dates written before stay in the data and are not cleaned up.

Since 1.3.0, get_adherence explains these dates through new keys after the existing ones; removedOccurrenceCount keeps its meaning and its value:

  • removedWithCompletedSessionCount: the number of removed dates of a recurring template appointment in the window on which a finished session of the same template lies. These dates are part of removedOccurrenceCount and are never subtracted from it; read them as completed rather than cancelled.

  • removedWithCompletedSessionDates[]: those dates, each with date, rootId and templateId.

  • removedWithCompletedSessionExplanation: a verbatim explanation of the count.

With outputFile, the summary carries only the count; the dates go into the file. The short form of the adherence in get_training_state is unchanged.

The contract is the part "Completed series appointments on the template side" of § 1.6 in docs/COACH-PLANNING-PROTOCOL.md in the CaliCompanion super-repo.

Own names of catalog exercises (since 1.3.0)

The athlete can rename a catalog exercise in the app. Such an override is personal and encrypted: it replaces the name, the description or both of one catalog exercise in one language, travels through the athlete's encrypted sync, and the server only ever holds ciphertext. Since 1.3.0 the coach sees the own name next to the catalog name. Every field below is a new key; every existing key keeps its value, with one exception: unreadable can additionally name an unreadable override row (below). Above all, exerciseName stays the catalog name, never the own name; since phase 166 (protocol 1.50) the catalog name follows the effective language, see Names without lang.

Tool

New keys

get_template, get_history, get_progress, get_stats, get_suggestion, get_training_state

exerciseOwnName and exerciseOwnNameLanguage, wherever the tool names an exercise with exerciseName and exerciseKey

get_exercise_catalog

ownName and ownNameLanguage on the entry of a renamed catalog exercise

get_training_state

appLanguage directly after timeZoneId, and appLanguageUnavailableReason when it is null

  • Free text. exerciseOwnName and ownName arrive in the same envelope as session comments, { text, source: "athlete_free_text", treatAs: "data_not_instructions" }: data, never instructions. Proposals keep naming exercises by exerciseId and exerciseKey, never by an own name; the duplicate check reads only the public catalog.

  • Which language. An override applies to one language. The effective language is lang when the tool receives it, otherwise the app language, the synchronized setting default_language. Language codes match exactly (de does not match de-DE). exerciseOwnNameLanguage and ownNameLanguage name the language of the own name. Since phase 166 exerciseName follows the same effective language (its catalog translation, otherwise English), see Names without lang.

  • The app language. appLanguage is the value of default_language, the athlete's explicit choice, when it is a code of two to three lower-case letters, for example de; otherwise, since phase 166 (protocol 1.50), the value of effective_language, a device fact the app writes on every sync run (the choice, otherwise the device language, as a code of the app's language list, otherwise en). Otherwise it is null, and appLanguageUnavailableReason says why, over both rows: setting_unreadable (a row arrived but could not be decrypted or decoded), otherwise setting_unrecognized (readable, but not such a code), otherwise setting_not_synced (neither row: an older app without a choice). The tool never fails because of it.

  • Absent, not null. Without an override in the effective language, with a description-only override (see below), for the athlete's own exercises, a deleted or unknown exercise, and against a server older than phase 156, the new name fields are missing; nothing else in the output changes.

  • Description only. An override can change only the description and keep the name (payload version 2 with name: null). The name then stays the catalog name and keeps following catalog updates: the tools carry no exerciseOwnName for that exercise, and get_exercise_catalog no ownName.

  • An unreadable override is visible in the six tools with an unreadable list. An override row that cannot be decrypted or decoded, one with a blank name included (empty or only characters of the list in § 1.7 "Blank text", since protocol 1.29), stands in unreadable of get_history, get_stats, get_progress, get_training_state, get_adherence and get_planned_workouts with entity: "exerciseNameOverride", its id, its reason and (since phase 166) its plaintext routing key "<exerciseId>:<languageCode>", never its content. It takes away only the own name of that exercise in that language; exerciseName, exerciseKey, the own names of every other exercise and every other key stay complete. The descriptions of those six tools say the same (get_adherence and get_planned_workouts output no exercise names, so there it affects nothing). get_template, get_suggestion and get_exercise_catalog carry no unreadable list: there an unreadable override, or without lang an unreadable app language, only leaves the own name out. Call get_history or get_training_state to see the entry.

  • No own description. An overridden description is decoded but not output by any tool of this version; a readable description-only override therefore changes no tool output.

  • Freshness. A freshly entered own name can be missing for up to 60 seconds (snapshot cache).

The contract — the payload form, the conflict rule between devices, the decoding rules, the language rule and the field names — is § 1.7 "Own names of catalog exercises" of docs/COACH-PLANNING-PROTOCOL.md (version 1.29) in the CaliCompanion super-repo.

Export directory for outputFile (since 1.4.0)

get_history, get_progress and get_adherence accept outputFile: true: the MCP then writes the full result to a local JSON file and returns only its path, byte size and item count, so the numbers never pass through the model (protocol §1.5, "The Local File Channel").

Where that file lands is the athlete's choice, never the model's. No tool takes a directory or a file name as an argument. The directory comes only from the environment variable CALICOMP_EXPORT_DIR, which you set yourself in the env block of the MCP registration, for example:

CALICOMP_EXPORT_DIR=~/training/personal
  • Without the variable the files go to calicomp-mcp-exports under the system temp directory, as before, and files older than 24 hours are deleted there at every start.

  • With the variable the files go into that directory and stay: the 24-hour cleanup never runs there. The value must be absolute or start with ~/ (your home directory), and it must name an existing directory. It is resolved once at start; a symlinked directory is followed once, so a later change of the link does not move the writes. A relative value, a missing directory or a file stops the start with an error that names the variable but not the path.

  • Every file is named by a random UUID with .json, created new with mode 0600 (owner read and write only), and never written through an existing file or symlink of the same name.

The file holds decrypted training data in plaintext. With CALICOMP_EXPORT_DIR set it stays in your directory after the conversation; it is written only when a tool call says outputFile: true. Keep that directory out of any repository you publish.

New in phase 166 (since 1.4.0)

Phase 166 makes the app and the MCP count the same sets by the same rules (§ 1.11 "Counting rules shared by the app and the MCP" of docs/COACH-PLANNING-PROTOCOL.md, version 1.48, and § 1.6 in version 1.49). Released in 1.4.0.

Existing fields that change meaning

A corrected number changes the existing field in place: there is no parallel field, and the name, the place and the form of every field stay as they are; only the sets it counts change. The tool texts name the rule of each field below.

Tool

Existing field

Before 166

Since 166

get_training_state

muscleBalance

every set of finished sessions, also of exercises whose rated capability axes are only mobility or flexibility

Rule S over Rule P: such stretch-only exercises are left out, the same number as the app's strength heatmap

get_training_state

personalRecords

the hold list by the catalog mode only, the repetition list without any mode

Rule M: by the mode the set was trained in (maxHoldSeconds only from sets that record a time, maxReps only from the others); since protocol 1.52 maxHoldSeconds leaves out station sets

get_stats

by: "exercise", by: "muscle": every field of the aggregate and weightedSetCount

no deletion marks, no endTime, no resolution over workoutExerciseId

Rule P with finished sessions; by: "muscle" still counts stretch-only exercises (no Rule S)

get_stats

by: "capabilities": axes[] with setCount, weightedSetCount, sessionCount, contributingExerciseIds, lastSessionDate

the same three gaps

Rule P with finished sessions

get_adherence

matches[] and unplannedSessionIds

of several sessions of the same template on the same day as an occurrence, the one with the smaller sessionId won

the session with more live sets wins, then the longer one, then the old tie-break; matchedCount and adherenceRatio keep their definition

get_adherence

removedWithCompletedSessionCount and removedWithCompletedSessionDates[]

only over the roots with a live occurrence in the window

over every live recurring template root of the snapshot

removedOccurrenceCount keeps its definition. On the template side it counts only roots with a live occurrence in the window, on the foreign side (foreignSport.removedOccurrenceCount) every live foreign root; the difference is deliberate and stays.

Comparing across the change. The comparison at the measuring point 2026-11-16 computes both periods with the MCP from phase 166 on: the MCP changes no session data, only how it counts, so the earlier period counted again by the new rules is comparable with the later one. A number an MCP before phase 166 returned, also one noted down earlier, is not comparable with one counted after it.

New fields

Tool

New keys

get_training_state

capabilityBalance (windows last7Days, last30Days, allTime, each { setCounts, weighted }, stretching included on purpose) and dataQuality (suspectSetCount, byReason, at most 20 newest), both after the existing keys

get_history

suspect on a set-log that is probably an entry error: a list of { reason, explanation } with reps_on_time_station, zero_set or measured_time_missing; absent on a set without a finding

get_suggestion

for an exercise_update proposal, the top-level exerciseId of the resolved copy is named like every other exercise reference

get_template, get_history, get_progress, get_training_state, get_stats, get_suggestion

exerciseNameFreeText beside exerciseName of an own exercise (key user_exercise:<id>, live or deleted): its shown name in the free-text envelope, because that name is the athlete's free text; exerciseName keeps its value

get_exercise_catalog

nameFreeText on an entry with origin: "CUSTOM": its shown name (localizedName when present, else nameEn) in the free-text envelope; nameEn and localizedName keep their values

get_training_state

personalRecords.repsInTime as the last key of personalRecords, a new record kind (protocol 1.52): entries { exerciseId, exerciseName, durationSeconds, weightKg, value, achievedOn } with the name fields of the other two lists, ordered by exerciseId, then durationSeconds, then weightKg (without weight first); one exercise may stand several times

get_training_state

narrativeNames directly after narrative, only when the sentence names an own exercise: [{ ref, name }] with ref = its exerciseKey in the sentence and name = its name in the free-text envelope (see Names without lang)

get_history, get_progress, get_stats, get_training_state, get_adherence, get_planned_workouts

key on an unreadable entry with entity: "exerciseNameOverride": the row's plaintext routing key "<exerciseId>:<languageCode>", so the coach knows whose own name is missing

get_history, get_planned_workouts

droppedValues after unreadable, only when a stored foreign performedTime or scheduledTime is not HH:mm: that time reads as null, the row stays readable, and the entry names entity, id, field and reason: "not_hh_mm", never the value

Since protocol 1.51 (gap plan 166-21) reps_on_time_station marks only repetitions on an exercise whose catalog mode is TIME (repetitions of a repetition exercise at a TIME station are real counts, recorded before app plan 165-02), and zero_set falls back to the other value when the value of the set's kind is absent.

Since protocol 1.52 (gap plan 166-22) such a set is a station set: it records a time, the catalog mode of its exercise is not TIME, and it carries completedReps. A station set never counts for maxHoldSeconds or maxReps; personalRecords.repsInTime keeps the largest completedReps per exercise, duration (the set's own completedTimeSeconds, greater than 0) and weight class (weightUsed in hundredths of a kilogram; null or 0 is the class without weight, reported as weightKg: null), compared only at the same duration and weight.

The marks are hints only: no tool changes or deletes a set, the athlete decides in the app.

New proposals

  • Block ops. propose_plan_update takes the ops updateBlock (the rounds of an existing block, 1 to 100) and addBlock (a new block with its exercises in the shared top-level orderIndex space), for CLASSIC templates only (app 4.5 and later). Every op acts only on rows of the proposal's template.

  • New exercises with links. propose_new_exercise and newExercises[] of both plan tools take the optional fields translations, muscleGroups, capabilities and equipment, keys as get_exercise_catalog shows them; an unknown capability or equipment key is refused with an error that names it. None of the fields is required.

  • Changing an exercise. The new tool propose_exercise_update (proposal type exercise_update) proposes translations, muscleGroups and capabilities for an own exercise, and only translations for a catalog exercise, as the athlete's personal name and description; the shared catalog never changes. It is live once the server has been deployed with the type.

  • Hold sizes. The proposal tools now say how mode behaves: TIME counts down and is a target (a set that ran out stores that target), MAX counts up and is a measurement. A maximal hold, such as a benchmark hold, is proposed with MAX. The reading tools say the same about the stored hold times.

Nothing is applied by the MCP: the athlete accepts, edits or rejects every proposal in the app.

Names without lang

Since protocol 1.50 (the athlete's decision E-16: without lang the coach gets the language set in the app) every name a tool returns follows one effective language: lang, otherwise the app language appLanguage (default_language, otherwise the device fact effective_language the app mirrors on every sync run, so it is known also when the athlete never chose one). This changes the meaning of existing fields in place, without parallel fields:

  • exerciseName in get_template, get_history, get_progress, get_training_state, get_stats and get_suggestion: a catalog exercise's translation in that language, otherwise its English name; an own exercise's translation, otherwise its name.

  • typeName of a predefined foreign sport type in get_history, get_training_state, get_adherence and get_planned_workouts (the last two have no lang and take the app language): German when the language starts with de, otherwise English.

  • localizedName of get_exercise_catalog, present whenever there is an effective language.

  • The name of a catalog exercise in get_training_state.narrative; the prose stays English.

  • Own names, as before, in the same language. When the app language is unknown or unreadable, no own name appears and get_training_state names the reason in appLanguageUnavailableReason; a call with lang shows the own names of that language.

Without lang and without an app language every name is English as before. With lang, lang wins. No athlete free text stands unwrapped in a text field: when narrative names an own exercise, the sentence carries its exerciseKey (user_exercise:<id>), and narrativeNames right after it carries its name in the free-text envelope. Every name tool says this in one shared sentence of its description. Releases before 1.4.0 keep the earlier behaviour.

Export directory

outputFile: true writes into the directory set in CALICOMP_EXPORT_DIR; see Export directory for outputFile.

Tool texts against behaviour

No tool claims any longer to read no encrypted data: every tool that loads the snapshot loads it decrypted, and get_template, get_suggestion and get_exercise_catalog say which of their fields come from encrypted data and when an own name or an own exercise can be missing. A test over the import chain of every tool module keeps that claim out.

New in phase 168 (since 1.5.0)

Phase 168 lets the athlete decide which kinds of proposals the app applies directly (protocol 1.56 of docs/COACH-PLANNING-PROTOCOL.md, §2.8 and §5; the rules themselves are the app contract docs/COACH-PERMISSIONS.md in the super-repo). Prepared in 1.5.0; published by the athlete.

Correcting a finished workout

The new tool propose_history_correction (proposal type history_correction) proposes a correction of a finished, not deleted workout: change reps, timeSec or weight of a set, add a forgotten set after an existing one (afterSetId), or remove a wrong set, 1 to 50 changes per proposal. It never changes the exercise of a set, the notes or the rating. Before it sends, the tool checks against the history it read that the session exists, has ended and is not deleted, that every named set is a live set of that session and that no set id stands twice; otherwise it answers with an error and sends nothing.

Set values are never plaintext on the server, so this is the one proposal type whose content is encrypted with the account key: the server stores only {"v":1,"sessionId":…,"encryptedPayload":…}, and the encrypted inner payload names every live set of the session with its updatedAt so the app can tell whether the proposal still fits. The app accepts it with status accepted only, never accepted_modified. The type is live once the server has been deployed with it.

Proposals may be applied directly

Every propose_* tool description now ends with the same sentence: depending on the athlete's choice in the app, the app may apply a proposal directly. The MCP never learns how the athlete chose, and the tools no longer say that only the athlete applies a proposal. The tools themselves still change nothing: they send the proposal to the app.

Reading back what happened

get_suggestions and get_suggestion carry two new fields: decidedBy ("auto" when the app applied the proposal directly, "user" when the athlete decided, absent when unknown) and undoneAt (epoch ms when the athlete undid a direct apply, absent otherwise). Both tools show only the fields of their own row type; a field that belongs to the app's own list never reaches the coach.

Personal muscles and capabilities, and the section "Reine Kraft" (phase 168.1)

Phase 168.1 adds to the same version (protocol 1.57 of docs/COACH-PLANNING-PROTOCOL.md, §1.11, §1.12 and §2.9).

The new tool propose_catalog_exercise_links (proposal type catalog_exercise_links, tool 22, the ninth that writes) proposes a personal muscle list, a personal capability list or both for a catalog exercise. Such a list replaces the catalog list of its kind completely for this athlete, everywhere and also for old sets; an own exercise stays with propose_exercise_update. The tool checks the exercise and every key against the unchanged catalog and sends nothing otherwise. The type is live once the server has been deployed with it.

The app keeps the personal lists encrypted. The MCP decrypts them and lays them over the catalog in one place, so every tool that reads the catalog counts with them, and a row it cannot read is reported in unreadable while its exercise follows the catalog. get_exercise_catalog shows the effective lists and, only on an entry with a personal list, personalLinks with the kinds that are personal.

get_stats { by: "capabilities" } and each window of get_training_state.capabilityBalance carry a new field pureStrength beside the axes: the section "Reine Kraft", exercises without a capability axis, per exercise { exerciseId, name, setCount, metric, direction }. It is never a key in setCounts and never an eighth axis. setCount counts the raw sets of the period; metric is reps, e1rm or timeSeconds, by its own rule, so a pull-up trained without weight shows a direction and not insufficient-data; direction rests on the last 12 sessions of the whole history, whatever the period. An own exercise also carries exerciseNameFreeText. get_progress is unchanged.

Changelog

1.5.1

  • get_history leaves deleted rows out: sessions and set-logs the athlete deleted no longer appear in sessions, setLogs or matchingSessions, and the exercise filter no longer finds a session through a deleted set. Until now they came along as ordinary entries with a deletedAt field for up to 90 days.

1.5.0

  • Correcting a finished workout: the new tool propose_history_correction with an encrypted payload; see New in phase 168.

  • Direct application: every proposal tool says that the app may apply a proposal directly, depending on the athlete's choice; get_suggestions and get_suggestion show decidedBy and undoneAt.

  • Personal lists of catalog exercises: the new tool propose_catalog_exercise_links, the overlay of the personal lists on every reader of the catalog, and personalLinks in get_exercise_catalog; see Personal muscles and capabilities.

  • Section "Reine Kraft": pureStrength in get_stats { by: "capabilities" } and in each window of get_training_state.capabilityBalance, with its own progress rule.

  • Node: still >=22. No new dependency.

1.4.0

  • Export directory: outputFile: true can write into a directory you choose with CALICOMP_EXPORT_DIR; see Export directory for outputFile.

  • Counting rules shared with the app: some existing fields keep their name, form and place but count different sets, and names follow the effective language; see New in phase 166.

  • Dependencies: @modelcontextprotocol/sdk 1.32.2 and zod 4.6.7. Development tools: Vitest 5 with v8 coverage 5, tsup 9, ESLint 10.14, typescript-eslint 8.72, Stryker 10.1.

  • Node: still >=22.

Building

npm install
npm run build      # tsup → dist/index.js (shebang'd, single-file ESM)
npm run lint       # ESLint no-console gate
npm run typecheck  # tsc --noEmit
npm test           # vitest run

Available Tools

19 tools
get_adherenceGet Plan AdherenceA
Read-only

Answer "how well does the athlete keep to the plan" over a window and tolerance you choose. Without from/to, the window ends today (the athlete's own calendar day) and spans back windowWeeks (default: the coach's own adherenceWindowWeeks parameter). toleranceDays and windowWeeks override the coach's persisted parameters for this one call only, without saving them. The result reports plannedCount, matchedCount, uncertainCount, missedCount, removedOccurrenceCount, adherenceRatio, the matched pairs (with their confidence and, for similarity-derived matches, the similarity value), the missed occurrences, and an explanation sentence describing what removedOccurrenceCount does and does NOT mean (verbatim: "removedOccurrenceCount counts how many planned occurrences the athlete removed from the calendar inside this window. The stored data carries no timestamp for a removal, so it cannot say whether a given occurrence was cancelled ahead of its date on purpose or cleaned up afterward because it was missed — ask the athlete rather than assuming either reading. A planned occurrence that was removed entirely (its whole recurring series, or its only single date) leaves no trace inside this window at all, and this calculation treats it exactly as if nothing had ever been planned on that day."). Set outputFile: true to write the full pair/missed lists to a local file instead of returning them inline.

Inputs: to, from, outputFile, windowWeeks, +1 more.

get_coach_parametersGet Coach ParametersA
Read-only

Report the seven training-state tuning parameters: their default values, allowed ranges, and current values in one call. Call this BEFORE calling set_coach_parameters — it is the right first step to learn what can be set and what it currently is, rather than discovering the ranges by trial and error.

Inputs: no named parameters.

get_exercise_catalogGet Exercise CatalogA
Read-only

Return the full exercise catalog with muscle groups, equipment, and optional localized names. Provide lang (e.g. "de", "fr") to add a localizedName field (falls back to nameEn when no translation exists). Use muscleGroups[].key with get_stats { by: "muscle" } to query aggregates by muscle group.

Inputs: lang.

get_historyGet Workout HistoryA
Read-only

Return sessions and set-logs within a date range (YYYY-MM-DD), newest-first, for a TARGETED detail lookup — a specific window, a specific exercise. For the athlete's overall standing, call get_training_state first; use this tool once you need the underlying raw sessions and set-logs. Optionally filter by exercise UUID. Results are capped by limit (default 200, max 500). Set outputFile: true to write the full result to a local file instead of returning it inline — the tool result then reports only the file path, byte size and item count.

Inputs: to (required), from (required), limit, exercise, +1 more.

get_planned_workoutsGet Planned WorkoutsA
Read-only

Return concrete calendar occurrences and their planned-workout roots for a required date window (from/to, YYYY-MM-DD, both mandatory, span at most 366 days). Cancelled occurrences (deletedOccurrences) are already excluded. Completed occurrences are NOT excluded — a past date alone is not evidence of a missed workout. Each root also carries structured series fields (freq, interval, byDay, until, weekOffset) alongside the raw recurrenceRule, so a series can be described ("every 2 days", "every other week on Monday and Friday") without parsing the RRULE string.

Inputs: to (required), from (required).

get_profileGet User ProfileA
Read-only

Return the authenticated user's profile: email, displayName, avatarUrl, isPremium, and account createdAt epoch.

Inputs: no named parameters.

get_progressGet Training ProgressA
Read-only

Two progress views in one tool, selected by kind. kind: "exercise" returns the per-exercise progress series across ALL sessions the exercise appears in (even sessions without a template) — each point carries the best single set AND the session total, in the metric appropriate to that exercise (e1RM for weighted exercises, reps or hold time for bodyweight exercises), plus a direction label with its own rule and the raw values it was computed from. Omit exerciseId to get the most recently trained exercises instead of one specific exercise. kind: "format" returns the format-specific progression (AMRAP rounds+reps, Death-By highest round, EMOM intervals) for one template, or all format templates if templateId is omitted. points overrides how many recent points each series returns (3-30) for this one call. A call with no matching data returns an empty series, never an error. Set outputFile: true to write the full point series to a local file instead of returning it inline.

Inputs: no named parameters.

get_statsGet Training StatsA
Read-only

Compute app-consistent training statistics (e1RM, volume, set/session counts, trend) for a specific exercise (by: "exercise") or all exercises targeting a muscle group (by: "muscle"), or break down over every capability axis at once with no further argument (by: "capabilities" — balance, mobility, breath, etc.). e1RM uses the same Epley formula as the app. trend.points carries the full per-session e1RM series alongside the existing first-vs-last delta.

Inputs: no named parameters.

get_suggestionGet Coach SuggestionA
Read-only

Return one of the coach's own proposals in full, including payload and — for a modified accept — appliedPayload. Pass an id from get_suggestions. Returns an error if the proposal is not found (unknown id, or an id that is not one of yours).

Inputs: id (required).

get_suggestionsGet Coach SuggestionsA
Read-only

List the coach's own proposals as cheap summary rows, newest first: id, type, status, created date, a human-readable target label, and a short rationale. No payload included. Call this first; call get_suggestion with one id only when you need the full proposal, including its outcome (appliedPayload for a modified accept). Optional status filter (pending, accepted, accepted_modified, rejected, expired, withdrawn, obsolete); optional limit (default 200, clamped to 1..500). Empty array, never an error, when you have no proposals.

Inputs: limit, status.

get_templateGet Workout TemplateA
Read-only

Return one workout template with its blocks and template-exercises joined. Pass the UUID from list_templates. Returns an error if the template is not found.

Inputs: templateId (required).

get_training_stateGet Training StateA
Read-only

The standard entry point for "how is the athlete doing" — a query-time-computed overview, rather than raw session-by-session history. In one call: the current and longest training streak in weeks plus session-frequency counts (consistency); the same radar-chart muscle balance data as the app's Analytics dashboard in all three app windows (muscleBalance); a plan-adherence short form — counts, ratio, and an honesty explanation about what removedOccurrenceCount does and does not mean (adherence); the most recently trained exercises with their direction labels (recentExercises); all-time personal records (personalRecords); and a short, deterministic narrative sentence built from these already-computed numbers, never a second model call. This tool stays narrow on purpose: it carries no point series and no pair lists. For per-exercise or per-format progress series, call get_progress. For the full adherence pair/missed lists, call get_adherence. For raw session history, call get_history. All calendar-day mapping binds to the athlete's own synchronized time zone, never the coach's own clock.

Inputs: no named parameters.

list_templatesList Workout TemplatesA
Read-only

Return all non-deleted workout templates with their block and exercise counts. Use get_template to fetch a specific template's full detail (blocks + exercises).

Inputs: no named parameters.

propose_new_exercisePropose New ExerciseA
Idempotent

Propose a brand-new custom exercise for human review. Never creates it directly — the proposal is transported to the coach inbox for accept/reject. If the name matches an existing catalog exercise, returns the existing UUID instead of proposing a duplicate.

Inputs: mode (required), name (required), rationale (required), usesWeight (required), +1 more.

propose_new_planPropose New PlanA
Idempotent

Propose a brand-new workout plan (blocks + exercises) for human review. Never creates it directly — the proposal is transported to the coach inbox for accept/reject. Inline newExercises[] entries that match an existing catalog exercise are automatically resolved to that catalog UUID instead of being proposed as duplicates.

Inputs: name (required), blocks (required), rationale (required), newExercises.

propose_planned_updatePropose Planned UpdateA
Idempotent

Propose a change to the calendar for human review — name an intent, never a raw envelope. Four intents: move_occurrence (reschedule one occurrence, identified by rootId + occurrenceDate, to newDate), cancel_occurrence (cancel one occurrence, identified by rootId + occurrenceDate), schedule_workout (create a standalone or recurring root for templateId on date, optionally recurrenceRule), and change_series_rule (replace rootId's recurrence rule at scope whole_series or this_and_following — the latter requires cutoffDate and splits the series there). All root/template ids and dates come from get_planned_workouts. Rejects with a named cause — no network call — for an unknown root or template, an occurrenceDate that is not actually an occurrence of that root, a recurrence rule that fails allowlist validation, a root with no recurrence rule to change, or a recurrenceGroupId group that is not fully intact. Never mutates directly — the proposal is transported to the coach inbox for accept/reject.

Inputs: no named parameters.

propose_plan_updatePropose Plan UpdateA
Idempotent

Propose a structural change to an existing workout template for human review. Against a CLASSIC template, pass an ops[] diff (add/remove/update-sets-reps/reorder). Against a format template (CIRCUIT/EMOM/AMRAP/TABATA/LADDER/FOR_TIME/CHIPPER/DEATH_BY — check get_template's workoutType), pass formatParams instead: the complete new authoring parameters for that format, never an ops[] diff — the compiled rows are recomputed from formatParams on every save and an ops[] diff against them would be silently discarded. Exactly one of ops/formatParams may be set. Never mutates directly — the proposal is transported to the coach inbox for accept/reject. Fast-fails with an error (no network call) if the templateId is not found in the local snapshot, or if the proposal shape does not match the target template's own format. Inline newExercises[] entries that match an existing catalog exercise are automatically resolved to that catalog UUID instead of being proposed as duplicates.

Inputs: rationale (required), templateId (required), ops, formatParams, +1 more.

set_coach_parametersSet Coach ParametersA
Idempotent

Set one or more of the seven training-state tuning parameters. Call get_coach_parameters first to learn the defaults, allowed ranges, and current values. Rejects an out-of-range value or an invalid uncertainThreshold/matchThreshold combination before any change reaches the server. Returns the resulting overall parameter state.

Inputs: toleranceDays, matchThreshold, uncertainThreshold, exerciseTrendPoints, +3 more.

withdraw_suggestionWithdraw Coach SuggestionA
Idempotent

Retract one of your own proposals that is still pending — the single named exception to the propose-only boundary. Sets its status to withdrawn; the proposal is NOT deleted, its audit row survives and stays fully readable through get_suggestion. Withdrawing an already-withdrawn proposal is a harmless no-op. Fails with an error, worded identically regardless of cause, for an id that is unknown, not yours, or no longer pending (already accepted, rejected, or expired).

Inputs: id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 19 tools

    Disambiguation4/5

    The read-path tools (get_training_state, get_stats, get_adherence, get_progress, get_history) share statistical scope, but each has explicit carve-outs for what it does and does not return, which prevents serious misselection. The propose_* and suggestion tools are cleanly distinct from each other and from the reads.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern: get_* for reads, list_* for collections, propose_* for proposals, set_* for parameters, and withdraw_* for the one mutating exception. There is no mixed casing or vague verb usage.

    Tool Count4/5

    At 19 tools, the server is slightly above the ideal 3-15 band, but the count is justified by the breadth of the coach workflow: reads, analytics, parameters, proposals, and suggestion management. The set feels dense rather than bloated.

    Completeness5/5

    The tool surface covers the full coach workflow: raw history, computed training state, adherence, progress, templates, planned workouts, catalog, coach parameters, and proposal-based changes for plans, exercises, and calendar events, plus suggestion lifecycle management. Intentional gaps like accept/reject are external to the MCP boundary and clearly documented.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables personal trainers to query and summarize client management data—active clients, workouts, physical assessments, retention, check-ins, feedback, and finances—through MCP-compatible AI clients in read-only mode.
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables authenticated owners to capture, review, correct, and export bodyweight and strength-training data through a ChatGPT interface, including bounded multi-image/multi-session batch review, typed metrics with explicit provenance, pending drafts requiring guarded confirmation, and reversible deletion.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to plan, build, and log calisthenics workouts in a user's own account, including searching exercises, managing custom workouts and plans, reading progress and coaching data, and logging completed sessions. Account mutations require explicit confirmation, and workouts can be displayed as interactive cards in the chat.
      MIT