Skip to content

MCP: read, create, change and delete programs and their workout days - #167

Open
daniel-bernardino747 wants to merge 1 commit into
TraceApps:devfrom
daniel-bernardino747:feat/mcp-program-tools
Open

daniel-bernardino747 wants to merge 1 commit into
TraceApps:devfrom
daniel-bernardino747:feat/mcp-program-tools

Conversation

@daniel-bernardino747

Copy link
Copy Markdown
Contributor

Refs #154

Summary

An MCP client could list programs and start the day's workout, but not build or adjust a routine. This adds seven tools so an external client (I use Claude) can read, create, change and delete programs and their workout days.

It covers the MCP side of #154 only. Trace's own tools and assigning a template to a weekday are not part of this.

Tools

Tool Gate What it does
get_program mcp:read One program with its days and each exercise's sets, reps, weight, rest and notes
create_program mcp:write A new, empty program (name, goal, duration_weeks, advance_mode, on_complete)
update_program mcp:write Changes only the fields sent
create_template mcp:write Adds a workout day, with its exercises
update_template mcp:write Renames a day or replaces its exercise list
delete_program, delete_template mcp:destroy Delete, after confirm: true

update_template takes the day's whole list, in order: an exercise sent with the uuid from get_program is changed in place, one without a uuid is added, and one left out is removed. An exercise is named by exercise_id or by name; a name that matches a library exercise is linked to it, otherwise it is stored as free text.

How it follows the app

  • Only the account that made a program can change it (program-access.js). A coach's program and the starter programs read with can_edit: false and the write tools refuse them.
  • Program and day fields merge by the newer-wins rule (newer-wins.js), as PUT /api/programs/:id and PUT /api/templates/:id do.
  • A day's exercises go through the same per-uuid merge and tombstones as PUT /api/templates/:id, so a device that still has a removed exercise doesn't bring it back.
  • An exercise changed by uuid keeps what the tools don't expose (superset membership, per-week targets).
  • Deletes are the same row deletes the routes do, so the existing triggers record them for sync.

Changes

  • server/lib/mcp/_program-write.js: shared input schema, stored/public exercise conversion, access checks, the exercise-list replace
  • server/lib/mcp/tools/: get-program.js, create-program.js, update-program.js, create-template.js, update-template.js, delete-program.js
  • server/lib/mcp/tools/index.js: registration behind the read, write and destroy gates
  • scripts/mcp-programs.test.js: 9 integration tests
  • CHANGELOG.md, README.md

No schema changes and no new dependencies.

How to test

  1. Start the server with MCP_ENABLED=1, MCP_WRITE_ENABLED=1 and MCP_DESTROY_ENABLED=1, and create a token with mcp:read, mcp:write and mcp:destroy.
  2. From an MCP client: create a program, add a day with a few exercises, read it back with get_program.
  3. Change one exercise by its uuid, add one and leave one out in update_template; check the day in the app's editor.
  4. Try update_program on a starter program: it is refused.
  5. delete_template and delete_program refuse without confirm: true.

node --test scripts/mcp-programs.test.js covers the same paths.

Tested

  • scripts/mcp-programs.test.js: 9 of 9 pass (Node 24, Linux).
  • The seven tools called over the real /api/mcp endpoint with a real token, including input validation.
  • Used from Claude Code against a local server, checking the results in the web app.
  • Full suite on Node 24 / Linux: one failure, session-version.test.js "a password reset by email link signs every session out" (socket hang up), which fails the same way without this change in my container.

Not done

  • Not tested with a second device syncing; sync behavior is by following the routes and from the database tests.
  • Week 1 targets only. Multi-week plans and supersets made in the app are kept, but these tools don't create or change them.
  • No tool to make a program active, and no REST (/api/v1) equivalents. I can add either if you'd want them in this PR.

This is only a suggestion. Feel free to use all of it, part of it or none of it.
I used AI (Claude Code) to help write these changes; I reviewed and tested them myself.

…raceApps#154)

An MCP client could list programs and start the day's workout, but not
build or adjust a routine. Seven tools close that:

- get_program (mcp:read): one program with its days and each exercise's
  sets, reps, weight, rest and notes.
- create_program, update_program, create_template, update_template
  (mcp:write).
- delete_program, delete_template (mcp:destroy, confirm: true).

The writes follow the app's own routes: only the account that made a
program changes it (program-access.js), fields merge by the newer-wins
rule, and a day's exercises go through the same per-uuid merge and
tombstones as PUT /api/templates/:id. update_template takes the day's
whole list: an exercise sent with its uuid is changed in place and keeps
what the tools don't expose (supersets, per-week targets), one without a
uuid is added, one left out is removed.

Tests: scripts/mcp-programs.test.js.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant