finalsurge-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| FS_EMAIL | Yes | Final Surge login, and the Keychain account name. Required. | |
| FS_TOKEN | No | Final Surge session token; skips the login. | none |
| FS_BASE_URL | No | Final Surge API root. | https://beta.finalsurge.com/api |
| FS_PASSWORD | No | Final Surge password; overrides the Keychain entry. Avoid it in claude_desktop_config.json, which stores it as plain text. | Keychain |
| FS_USER_KEY | No | Final Surge user key. | from the login or /Profile |
| FS_CONFIG_DIR | No | Directory for the token cache (mode 0600, tied to FS_EMAIL) and backups/. | ~/.config/finalsurge-mcp |
| FS_RULES_FILE | No | Rules file returned to Claude. | src/finalsurge_mcp/rules.md |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| list_workoutsB | List planned workouts in the Final Surge calendar (dates YYYY-MM-DD, inclusive).
Returns coach's text in |
| get_zonesA | Heart-rate zones of the Final Surge profile, for reference only. Steps take heart rate in bpm ('hr'). |
| get_parsing_rulesA | The athlete's conventions for turning coach text into steps. ALWAYS read before building steps. |
| get_examplesB | Recent workouts that already have a structured workout: coach text + the steps the athlete built. Examples flagged OLD STYLE break the current rules and must not be copied. |
| get_structured_workoutC | Steps currently saved in the builder for a workout (compact form), or null. |
| preview_structured_workoutA | Check compact steps against the hard rules and render a preview. Writes nothing. Step: {kind: warmup|active|rest|cooldown, ONE of distance_km|distance_m|minutes|seconds|time, ONE target: pace "4:30-4:40" (min/km) | hr "120-135" (bpm), optional short English note}. Repeat: {repeat: N, steps: [...]}. Read get_parsing_rules first. Show the text to the athlete; pass preview_token to save_structured_workout after the athlete approves. |
| save_structured_workoutA | Write the previewed steps into the Final Surge Workout Builder; Final Surge syncs them to the watch. preview_token must come from preview_structured_workout for exactly these name and steps, after the athlete approved the preview (or inside the approved nightly task). Refuses past dates, and refuses a workout that already has steps unless overwrite=true; an overwrite saves the old steps to a backup file first. |
| restore_backupB | Restore the builder steps saved before an overwrite. The current steps are backed up first. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 8 tools
Most tools have clearly distinct roles: list_workouts reads the calendar, get_structured_workout reads the builder, preview/save/restore form an unambiguous write pipeline. The only mild overlap is between get_parsing_rules and get_examples, which are both 'reference material to read before building,' though their descriptions clarify the difference (rules vs. concrete examples).
All eight tools follow a strict snake_case verb_noun pattern: list_workouts, get_zones, get_parsing_rules, get_examples, get_structured_workout, preview_structured_workout, save_structured_workout, restore_backup. The shared 'structured_workout' stem across preview/save/get reinforces the pipeline.
Eight tools is well-scoped for a focused workout-builder server, with no filler. Each tool earns its place: calendar read, three reference reads, builder read, validation, write, and undo.
The build → preview → save → restore lifecycle is fully covered, including safety nets like backups and overwrite protection. Minor gaps exist: there is no way to create a new planned workout or clear steps without overwriting with new ones, but these are workable around within the stated workflow.