@gehlich/calicomp-mcp 1.3.0 → 1.4.0

package/README.md

@@ -40,6 +40,7 @@ CalisthenicsCompanion-MCP/
 | `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](#export-directory-for-outputfile-since-140). |
 
 ## Credential Storage
 
@@ -103,9 +104,16 @@ returns two kinds of entries, distinguished by the `origin` field:
   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, but it carries **no** muscle, equipment or capability rating —
-  there is nothing to invent, so those fields are always empty. Treat an empty rating as "not
-  rated", never as a measured zero.
+  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
@@ -184,8 +192,10 @@ The athlete can rename a catalog exercise in the app. Such an **override** is pe
 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 — above all, `exerciseName` stays the catalog name,
-byte for byte as before.
+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`](#names-without-lang).
 
 | Tool | New keys |
 |---|---|
@@ -200,14 +210,17 @@ byte for byte as before.
 - **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; `exerciseName` keeps its own rule (`lang`,
-  otherwise English) and never follows `default_language`.
-- **The app language.** `appLanguage` is the value of `default_language` when it is a code of two
-  to three lower-case letters, for example `de`. Otherwise it is `null`, and
-  `appLanguageUnavailableReason` says why: `setting_not_synced` (the setting row is missing; the
-  app syncs the setting only once the athlete has chosen a language), `setting_unreadable` (the
-  setting arrived but could not be decrypted or decoded) or `setting_unrecognized` (readable, but
-  not such a code). The tool never fails because of it.
+  `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`](#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
@@ -216,13 +229,18 @@ byte for byte as before.
   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, not silent.** 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` with `entity: "exerciseNameOverride"`, its
-  `id` and its `reason`, 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 the six tools with an `unreadable` list say the
-  same.
+- **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).
@@ -231,6 +249,168 @@ The contract — the payload form, the conflict rule between devices, the decodi
 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:
+
+```text
+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`](#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](#export-directory-for-outputfile-since-140).
+
+### 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.
+
+## Changelog
+
+### 1.4.0
+
+- **Export directory:** `outputFile: true` can write into a directory you choose with
+  `CALICOMP_EXPORT_DIR`; see
+  [Export directory for outputFile](#export-directory-for-outputfile-since-140).
+- **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](#new-in-phase-166-since-140).
+- **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
 
 ```bash