Provides LLM-based text parsing for workout logs, using OpenAI models to extract structured data from freeform text.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@RepStack normalize this workout: Bench 135x5, Squat 225x5"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
RepStack is a stateless MCP server that normalizes strength training logs into a deterministic canonical schema.
It does not store users or logs. It does not persist data. It does not act as an analytics backend.
Consumers are responsible for storing canonical output and building analytics downstream.
RepStack is designed to be embedded into larger fitness applications as a normalization layer.
Normalize workout logs (CSV, JSON, or freeform text) into a canonical schema
Optionally use an LLM for text pre-parsing (output still goes through deterministic validation)
Compute deterministic metrics over provided canonical sessions or logs
Provide exercise search / registry lookup
RepStack is a canonicalization + deterministic compute engine. All storage responsibility belongs to the consuming application.
Related MCP server: strength-training-mcp
RepStack is deterministic.
Canonical structure is enforced via schema validation.
LLM parsing (optional) is only used for text extraction; canonical correctness is never defined by LLM output.
All analytics must operate on canonical sessions passed explicitly to the tool (e.g. repstack.compute_metrics with sessions or logs in the payload).
Uncertain matches → exercise_id: "unmapped:<slug>"; no fuzzy auto-mapping. Candidates can be provided for partial matches.
Run the MCP server
pip install -r requirements.txt
python -m repstack.serverOr after editable install: repstack
Call the ingest tool
For text logs you can use the LLM to pre-parse: set content_type: "text" and options.allow_llm: true. The server will use an LLM if one is configured (see Configuring the LLM); otherwise it adds a warning and falls back to the deterministic parser. The response includes meta.llm_available and meta.llm_used.
Example payload (CSV):
{
"user": { "default_unit": "lb", "timezone": "UTC" },
"log_input": {
"content_type": "csv",
"content": "exercise,weight,reps\nBench Press,135,5\nSquat,225,5"
},
"options": { "session_date_hint": "2025-01-15" }
}Example output shape:
status: "ok" | "needs_clarification" | "error"
log_id: request-scoped id when ok (client may use as storage key)
canonical_log: { "sessions": [ { "date", "exercises": [ { "exercise_id", "sets": [...] } ] } ] }
issues: list of { severity, type, location, message, ... }
summary: { sessions_detected, exercises_detected, sets_detected, confidence }
meta: { "llm_available": bool, "llm_used": bool } (when LLM is relevant)
Example payload for text + LLM:
{
"user": { "default_unit": "lb", "timezone": "UTC" },
"log_input": {
"content_type": "text",
"content": "Bench 135x5 145x4, Squat 225x5x3, RDL 135x8"
},
"options": { "session_date_hint": "2025-01-15", "allow_llm": true }
}Call compute_metrics
Send canonical data in the request (no server-side storage):
{
"sessions": [ { "date": "2025-01-15", "exercises": [ { "exercise_id": "barbell_bench_press", "sets": [ { "weight": 135, "unit": "lb", "reps": 5, "load_type": "weighted" } ] } ] } ],
"range": { "start": "2025-01-01", "end": "2025-01-31" }
}Or send logs: array of { "canonical_json": { "sessions": [...] } }.
Response: status, range, weekly (volume, tonnage, hard_sets, flags), exercise_summaries, issues (e.g. payload_too_large if over limits).
Input: user (optional user_id, default_unit, timezone), log_input (content_type: "csv" | "json" | "text", content), optional options (session_date_hint, allow_llm, strictness, …).
Output: status, user_id, log_id (when ok), canonical_log, issues, summary, signature, meta (llm_available, llm_used). No persistence.
Input: either sessions (array of canonical session objects) or logs (array of { canonical_json: { sessions } }). Optional range: { start, end } (YYYY-MM-DD). Optional options (e1rm_formula, include_prs, …).
Output: Deterministic metrics only: status, range, weekly, exercise_summaries, issues (e.g. payload_too_large), signature. No user identity; no storage access.
Input: query, optional equipment, movement_pattern, limit.
Output: query, count, results with exercise_id, display, match (strategy, score, matched_text, normalized_query), is_exact_match.
repstack.ingest_log — Normalize a workout log. Returns canonical log, issues, summary. Stateless.
repstack.compute_metrics — Compute metrics from provided sessions or logs. Stateless; guardrails for payload size.
repstack.search_exercises — Search exercise registry by query; optional filters.
There are no MCP resources (no log://, no user://). Tool-only.
The LLM is server-side and provider-agnostic: you choose which provider to use via env or by registering a parser. The tool payload cannot pass an API key or provider.
Option 1: Env — swappable provider
Set REPSTACK_LLM_PROVIDER to the name of a registered provider (e.g. openai). The server will call that provider’s loader when the ingest tool first needs a parser.
Built-in provider: openai
REPSTACK_LLM_PROVIDER=openai (or leave unset and set only the key below; it defaults to openai)
REPSTACK_OPENAI_API_KEY — your API key
REPSTACK_OPENAI_MODEL — optional; default gpt-4o-mini
Requires the openai package: pip install openai or pip install repstack[llm].
Adding another provider (e.g. Anthropic, local model)
Register a loader that reads its own env and returns a parser (or None):
from repstack.llm_parser import register_llm_provider, parse_llm_workout_json, WORKOUT_EXTRACTION_SYSTEM
def load_anthropic_parser():
api_key = os.environ.get("ANTHROPIC_API_KEY", "").strip()
if not api_key:
return None
# ... create client, then return a function (content, session_date_hint) -> raw_sessions
# that calls your API and returns parse_llm_workout_json(response_text)
return my_anthropic_parser_fn
register_llm_provider("anthropic", load_anthropic_parser)Then set REPSTACK_LLM_PROVIDER=anthropic (and the provider’s env vars). The shared contract is the JSON shape and parse_llm_workout_json() / WORKOUT_EXTRACTION_SYSTEM in repstack.llm_parser.
Option 2: Embedding — set_llm_parser(fn)
If you run RepStack inside your own app, you can set the parser directly (overrides env):
from repstack.llm_parser import set_llm_parser
set_llm_parser(my_parser_fn) # (content: str, session_date_hint: str | None) -> raw_sessionsParser signature: return list[tuple[str | None, list[tuple[str, list[dict]]]]] — each tuple is (date or None, [(exercise_name, [set_dict, ...]), ...]); each set_dict has at least weight, reps, unit, and optionally load_type, added_weight.
Each session: session_id, date (YYYY-MM-DD), title, notes, exercises[].
Each exercise: exercise_raw, exercise_id (snake_case or unmapped:<slug>), exercise_display, sets[].
Each set: set_index, reps, load_type (weighted | bodyweight | bodyweight_plus | assisted). For weighted: weight, unit. For bodyweight_plus: added_load: { value, unit }. Optional: rpe, set_type, notes.
Unmapped or uncertain data is reported in issues, not silently coerced.
No user identity model
No data persistence
No background jobs
No automatic history tracking
No fuzzy AI exercise mapping (exact alias/display only; otherwise unmapped:<slug>)
Run ingestion on samples (stateless)
python scripts/test_ingest.py
python scripts/test_ingest.py path/to/samplesRun metrics on sample-derived sessions
python scripts/test_metrics.pyRun tests
pytestMIT
Compute deterministic metrics from provided canonical data (stateless).
Provide either sessions (array of canonical session objects) or logs (array of { canonical_json: { sessions } }).
Optional range: { start, end } (YYYY-MM-DD) to filter; if omitted, all provided sessions are used.
Returns weekly volume, tonnage, e1rm, PRs, volume_spike flags. Payloads exceeding max_sessions or max_sets return needs_clarification.
| Name | Required | Description | Default |
|---|---|---|---|
| payload | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden and does well: it declares statelessness/determinism, the output summary, and the needs_clarification behavior for oversized payloads. It does not disclose limits like the actual max_sessions/max_sets values, but the core behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is packed into four sentences with the core action and statelessness front-loaded, followed by input options, filtering, and outputs. No filler is present, though it would be slightly easier to scan with light structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description need not enumerate return values; it covers inputs, optional filtering, and overflow behavior. The only notable gap is the lack of concrete canonical-session field definitions or the numeric limits, but for a tool with a mostly self-describing domain the description is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is a single opaque 'payload' object with 0% description coverage, so the description must compensate. It does so by explaining the two payload variants, the shape of logs entries, and the optional range object. It could still define the canonical session object, but the main calling contract is clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pair: 'Compute deterministic metrics from provided canonical data.' It also lists the exact outputs (weekly volume, tonnage, e1rm, PRs, volume_spike flags), which distinguishes it from the ingest and search siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly defines acceptable inputs ('sessions' or 'logs') and an optional 'range' filter, so an agent knows what shape to pass. It implies the tool is for post-ingestion analysis over already-canonical data, but it never explicitly names ingest_log or search_exercises as alternatives or states when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ingest a workout log (text, CSV, or JSON). Returns canonical structured JSON, issues, and summary. Stateless: does not store anything. Set allow_llm=true for text and configure an LLM parser to use it; response includes meta.llm_available and meta.llm_used.
| Name | Required | Description | Default |
|---|---|---|---|
| payload | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it does well: it explicitly discloses statelessness, the shape of the response, and the presence of meta.llm_available and meta.llm_used. It does not mention failure modes or exact behavior when allow_llm is false, but the key behavioral traits are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action and return value, followed by the most important behavioral and configuration notes. Every sentence earns its place and there is no redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the input formats, the stateless contract, the LLM requirement, and the key response fields. With an output schema present and a single flexible parameter, this is mostly complete, though the vague payload semantics prevent a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has only one payload object with no property descriptions and 0% schema coverage, so the description must compensate. It partially does by mentioning allow_llm=true and the three input formats, but it does not specify the exact payload structure or how text/CSV/JSON content should be placed inside the payload. This leaves significant room for ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb 'Ingest' and a clear resource ('a workout log'), explicitly listing accepted formats (text, CSV, JSON) and the expected output (canonical structured JSON, issues, summary). It also differentiates itself from the sibling tools by framing itself as the ingestion step versus compute_metrics and search_exercises.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: it is stateless, and text inputs require allow_llm=true along with an LLM parser configuration. However, it does not explicitly state when to prefer this tool over its siblings or include when-not-to-use guidance, so it falls short of a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the local exercise registry by query (matches display and aliases). Returns { query, count, results } with match metadata (strategy, score, matched_text, normalized_query) and is_exact_match. Optional filters: equipment, movement_pattern. Optional limit (default 20).
| Name | Required | Description | Default |
|---|---|---|---|
| payload | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses matching semantics, the exact return shape with metadata fields, is_exact_match, optional filters, and the default limit. It stops short of explicitly stating that the operation is read-only with no side effects, but 'search' and 'local registry' strongly imply that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence earns its place: purpose, return shape, and optional parameters. The description is front-loaded with the core action and remains compact without filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and an opaque input schema, the description covers the key operational details: what is searched, what is returned, which filters exist, and the limit default. An output schema exists to formalize return values, so the remaining gaps—such as exact payload nesting and requiredness of query—are relatively minor but still prevent a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is an opaque payload object with additionalProperties true and 0% schema description coverage, so the description is the only source of parameter meaning. It names query, equipment, movement_pattern, and limit, including the default of 20. It does not specify types or show how these map inside the payload object, but it compensates substantially for the generic schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Search'), a concrete resource ('local exercise registry'), and the matching behavior ('matches display and aliases'). This distinguishes it from sibling tools like repstack.ingest_log and repstack.compute_metrics without needing to open schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is implied: use when you need to search the local exercise registry. However, the description does not explicitly state when to prefer this tool over alternatives, nor does it mention any exclusions or prerequisites. The sibling names imply the distinction but the description itself provides no direct routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0repstack.compute_metricsrepstack.ingest_logrepstack.search_exercisesScored across 3 tools
Each tool has a clearly distinct purpose: ingest_log parses and normalizes workout data, compute_metrics derives analytics from canonical data, and search_exercises queries the exercise registry. There is no overlap or ambiguity between them.
All tool names follow a consistent verb_noun snake_case pattern: ingest_log, compute_metrics, search_exercises. The naming is predictable and clearly indicates what each tool does.
Three tools is well-scoped for a stateless workout log processing server. Each tool covers a necessary step in the workflow without redundancy or bloat.
The tool set covers the full intended pipeline: ingest raw logs into canonical JSON, compute metrics from canonical sessions, and search exercises for enrichment or validation. Since the design is explicitly stateless, no persistence/retrieval tools are needed.
Remote MCP server for training, nutrition, wellness, and performance data with OAuth 2.0.
MCP server for Withings health data — sleep, activity, heart, and body metrics.
Multi-tenant hosted MCP server for Oura Ring — 21 read-only tools, OAuth per user.
Private health and fitness analytics through a secure remote MCP connection.