Rhylthyme

Rhylthyme MCP server

[Claude Connectors Directory] [Listed on mcpservers.org]

A Model Context Protocol server for schedules that a person executes: cooking several dishes so they finish together, running a bench protocol with overlapping incubations, calling an event, running a workout. An agent describes the process, the server validates and analyzes the resulting program, and publishes it as a live timeline on rhylthyme.com that the person follows on their phone.

This repository is the source of the server that runs at mcp.rhylthyme.com. It is the same code as mcp-api/ in the rhylthyme-server application, copied here with the static assets it needs so it can be read, tested and self-hosted.

Try it: ask for a workout

Connect the server (in claude.ai, Claude Desktop or mobile, add Rhylthyme from the Claude Connectors Directory; in Claude Code, /plugin marketplace add rhylthyme/rhylthyme-mcp then /plugin install rhylthyme@rhylthyme; anywhere else, add https://mcp.rhylthyme.com/gym/mcp as a connector), then say what you want in plain words:

Two of us in a garage gym: one kettlebell, one pull-up bar, one jump rope. Thirty minutes, two rounds, and nobody stands around waiting for equipment. Make it a Rhylthyme timeline.

You write no JSON. The assistant does, and the server keeps it honest. With that prompt Claude made three tool calls:

                0                       15m                    30mAlex           │░Warm-…░▒S…▒░Pu…░▒Ju…▒░░░▒Sw…▒░Pu…░▒Ju…▒░░░▒St…▒│Sam            │░Warm-…░▒P…▒░Ju…░▒Sw…▒░░░▒Pu…▒░Ju…░▒Sw…▒░░░▒St…▒│

Ask "show me a picture" and preview_timeline returns an image in the chat. For one coloured by station, which makes the rotation obvious, save the program the assistant wrote (ours is examples/recipe/garage-circuit.json) and run:

npx -y github:rhylthyme/rhylthyme-timeline garage-circuit.json -o garage-circuit.png \  --style web --palette tableau --color-by task

[Garage circuit for two, coloured by station: the kettlebell, the bar and the rope are never double-booked]

Then push on it: "add a third person", "we only have 20 minutes", "swap the rope for burpees". The assistant edits the program and the server checks it again.

This repository and rhylthyme

Two repositories do related things and are easy to confuse. This one is the server an AI assistant talks to. rhylthyme (formerly rhylthyme-cli-runner) is the command a person types.

How they fit together: the command-line tool is one of this server's clients. rhylthyme analyze, publish, generate and mcp-test are MCP calls to mcp.rhylthyme.com; rhylthyme validate, run, runs and calibrate never touch the network. Each has its own validator for the same program schema (JavaScript here, Python there), so a program is checked again when it is published.

Use this repository to connect an assistant, to read or self-host the server, or to change a tool. Use rhylthyme if you have a program file and a terminal, want timers in the terminal, or keep run records.

Two names to keep apart: rhylthyme-mcp on PyPI is this server's stdio bridge (command rhylthyme-mcp, source in python/); rhylthyme on PyPI is the command-line tool (command rhylthyme; it was published as rhylthyme-cli-runner before 0.5.0). The program format itself is defined in rhylthyme-spec, with examples in rhylthyme-examples.

Endpoints

Transport: Streamable HTTP, stateless. No sign-in is needed for the public catalog or the pure tools; account tools use the person's Rhylthyme account through OAuth 2.1, or a pasted token from the login tool in clients without OAuth. Server instructions describing the workflow are sent at initialize.

Quickstart: timelines from the command line

The rhylthyme CLI can drive this server directly: describe what you need in plain language and get back a live timeline URL, a program file, or both.

pip install rhylthyme                        # Python 3.12+rhylthyme login                              # opens rhylthyme.com in your browserrhylthyme generate "roast chicken, potatoes and green beans for 6" \    -e kitchen --by 19:00 --with "one oven, four burners, one cook"

login signs you in through the browser and hands the session back to a one-shot listener on 127.0.0.1. It is stored in ~/.config/rhylthyme/credentials.json (mode 0600) and renews itself, so you only log in once. generate then calls two tools on this server:

1. import_text on the endpoint for -e (/kitchen/mcp, /lab/mcp, …) turns the request into a validated multi-track program. It runs four model turns server-side, which is why it needs a sign-in; it takes 20–60 seconds and is capped per day.
2. visualize_schedule publishes that program and returns the live-timeline URL on the matching subdomain.

It prints the ASCII Gantt, the itinerary and the URL. More examples:

# A lab protocol from a file; save the program and run it in the terminalrhylthyme generate -e lab -f western_blot.txt -o blot.json --run
# Pipe a run sheet in; print only the URLpbpaste | rhylthyme generate -e events --by "doors at 18:30" -q
# Program JSON only, no published timeline; machine-readable outputrhylthyme generate -e gym "45 minute upper-body circuit, two people, one bench" --no-publish --json

To check a server (this one, or your own deployment) end to end:

rhylthyme mcp-test                                   # all five hosted endpoints, read-onlyrhylthyme mcp-test --url http://localhost:3000/mcp -e generic --publish

rhylthyme whoami shows the stored sign-in; rhylthyme logout forgets it. On a machine without a browser, set RHYLTHYME_TOKEN to an access token from https://www.rhylthyme.com/mcp/auth (it lasts about an hour), or run rhylthyme login --token <token>. RHYLTHYME_MCP_URL points the CLI at a self-hosted server.

Connect

Claude Code

claude mcp add --transport http rhylthyme https://mcp.rhylthyme.com/mcpclaude mcp add --transport http rhylthyme-kitchen https://mcp.rhylthyme.com/kitchen/mcp

Claude Desktop / claude.ai: Customize → Connectors, search for Rhylthyme and click Connect. For one of the other URLs above: Customize → Connectors → Add → Add custom connector → paste the URL → Continue. Public tools work immediately; run login only to save to your own account.

Claude Code plugin (the hosted server plus a skill that teaches Claude to author, validate and analyze schedules):

These are two commands. Send the first on its own:

/plugin marketplace add rhylthyme/rhylthyme-mcp

then, once it says the marketplace was added, the second:

/plugin install rhylthyme@rhylthyme

ChatGPT: Settings → Apps & Connectors → Advanced settings → turn on Developer mode, then Create a connector with one of the URLs above as the MCP server URL. Without a connector ChatGPT cannot call these tools and falls back to browsing the website.

Cursor (.cursor/mcp.json):

{ "mcpServers": { "rhylthyme": { "url": "https://mcp.rhylthyme.com/kitchen/mcp" } } }

Claude API (MCP connector, one request):

import anthropicclient = anthropic.Anthropic()resp = client.beta.messages.create(    model="claude-opus-5", max_tokens=16000,    betas=["mcp-client-2025-11-20"],    mcp_servers=[{"type": "url", "url": "https://mcp.rhylthyme.com/kitchen/mcp", "name": "rhylthyme"}],    tools=[{"type": "mcp_toolset", "mcp_server_name": "rhylthyme"}],    messages=[{"role": "user", "content": "Plan Thanksgiving for 8 with one oven, dinner at 6pm."}],)

Reviewing an import. review_program (an account tool) has a model read an imported program against its source and return findings: wrong durations, dropped steps, bad ordering, a total that disagrees with the source. Call it after import_from_source or import_text, apply what it says, and validate again.

Clients that can only launch a command: pip install rhylthyme-mcp gives a rhylthyme-mcp command, a stdio bridge that passes every request through to the hosted server (source in python/):

{ "mcpServers": { "rhylthyme": { "command": "rhylthyme-mcp", "args": ["kitchen"] } } }

No MCP client at all (an agent with a shell, a script): the server is stateless, so one POST works with no handshake and no account.

curl -s https://mcp.rhylthyme.com/mcp \  -H 'Content-Type: application/json' -H 'Accept: application/json' \  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",       "params":{"name":"validate_program","arguments":{"program":{"programId":"x","name":"x","tracks":[]}}}}'

visualize_schedule called the same way returns the live-timeline URL in result.structuredContent.url. Or use the CLI in the quickstart above.

Tools

Annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) are set on every tool; four tools also declare an outputSchema and return structuredContent. Failures set isError and say what to do next.

Resources and prompt

• rhylthyme://schema/program: the program JSON Schema (0.3.0-alpha)
• rhylthyme://guide/authoring: one-page authoring rules, trigger vocabulary, how to make tracks finish together, repeated work (replicates, per-instance instances: "each" chains, "all" barriers and maxInFlight), choice branching
• rhylthyme://guide/tools: the long form of every tool description. The tool list itself is kept to about 3,600 tokens so it is cheap to keep connected
• rhylthyme://examples/{breakfast_schedule, lab_experiment, stir_fry_with_choice, hiit_cardio_workout, corporate_presentation, cookies_three_trays}: complete valid programs (cookies_three_trays is the 0.3.0-alpha per-instance / in-flight worked example)
• prompt plan_schedule(goal, finishAt?, constraints?): walks the model through search → build → validate → analyze → visualize, and names replicates / instances / maxInFlight in its constraints step

What a program looks like

{  "schemaVersion": "0.1.0",  "programId": "eggs-and-toast",  "name": "Eggs and toast",  "tracks": [    { "trackId": "eggs", "name": "Eggs", "steps": [      { "stepId": "whisk", "name": "Whisk", "task": "prep",        "duration": { "type": "fixed", "seconds": 60 },        "startTrigger": { "type": "programStart" } },      { "stepId": "cook", "name": "Cook", "task": "stove",        "duration": { "type": "variable", "minSeconds": 120, "maxSeconds": 240, "defaultSeconds": 180 },        "startTrigger": { "type": "afterStep", "stepId": "whisk" } } ] },    { "trackId": "toast", "name": "Toast", "steps": [      { "stepId": "toast", "name": "Toast", "task": "toaster",        "duration": { "type": "fixed", "seconds": 180 },        "startTrigger": { "type": "afterStep", "stepId": "cook", "event": "start", "offsetSeconds": 60 } } ] }  ],  "resourceConstraints": [    { "task": "prep", "maxConcurrent": 1 },    { "task": "stove", "maxConcurrent": 2 },    { "task": "toaster", "maxConcurrent": 1 }  ]}

Steps in one track run sequentially; parallel work goes in separate tracks; every task needs a resource constraint; durations and offsets take seconds or strings like "5m". Triggers: programStart, programStartOffset, afterStep (end or event: "start", signed offset), afterStepWithBuffer, manual, onAbort, or {logic: all|any, triggers}. Durations: fixed, variable (ended early by the executor), indefinite (ended by the executor).

Self-hosting

git clone https://github.com/rhylthyme/rhylthyme-mcpcd rhylthyme-mcpnpm install            # Node 20 or newernpm test                 # SDK in-memory + HTTP entry-point tests, no networkPORT=3000 npm start      # http://localhost:3000/mcp and the four vertical pathsnpm run stdio            # the same server over stdio (add kitchen, lab, events or gym)

Stdio clients run it as a local process, for example in Claude Desktop: {"command": "node", "args": ["/path/to/rhylthyme-mcp/src/stdio.js"]}.

Docker: docker build -t rhylthyme-mcp . && docker run -p 3000:3000 rhylthyme-mcp. Vercel: vercel in the repository root; vercel.json rewrites the endpoint paths to the function.

What self-hosting does and does not give you: validation, timing analysis, the renderer, resources and prompts run in your process. Catalog search, sharing (visualize_schedule), imports and account tools call the public API at https://www.rhylthyme.com (API_BASE in mcp-api/index.js), so those still depend on the hosted service. The PNG preview route /api/og/timeline.png additionally needs SUPABASE_URL and SUPABASE_ANON_KEY for read access to shared programs; nothing else does.

Layout

• mcp-api/index.js: tool, resource and prompt registration; vertical detection; OG-image route; Vercel handler
• mcp-api/schedule.js: validator and analyzer (pure)
• static/js/timeline-render.js: timing engine and SVG Gantt (also published as @rhylthyme/timeline)
• static/schema/, static/examples/: the resources
• src/index.js: standalone HTTP runner
• src/stdio.js: standalone stdio runner (same tools, resources and prompts)
• mcp-api/server.json: MCP registry manifest
• .claude-plugin/marketplace.json, plugins/rhylthyme/: the Claude plugin marketplace and plugin (claude plugin validate .); the skill in it is a checked copy of skills/rhylthyme in rhylthyme
• python/: the rhylthyme-mcp PyPI package, a stdio bridge to the hosted server (cd python && PYTHONPATH=src pytest tests)

Known limitations

• login hands the user a URL and expects a pasted, short-lived access token that then travels as a tool argument; it is outside MCP's OAuth 2.1 flow. Hosts that require OAuth for authenticated servers can still use every public tool.
• search_public_recipes searches one environment at a time; the generic endpoint defaults to kitchen.
• Tool annotations are self-declared hints; hosts may ignore them.

License

Apache-2.0, like the rest of Rhylthyme. (This repository was MIT until September 2026.)