Roadmap — from seed to latex-mcp architecture

Your staged path for Track 3: grow the working seed (the starter that renders LaTeX) into the MCP-first architecture on the project page — a latex-mcp server driving a Dockerized pipeline, ready to scale to other modules. Each stage has a goal, steps, and a clear “done when”. Build spec-first (brainstorm → plan → execute → test) with Claude Code.

Stage 0 — Run the seed

Goal: see the starter work, unchanged.

• Open the workspace (Track 3 runbook).
• npm install → npm run smoke → see latex.svg.
• cp .env.example .env, add your OLLAMA_API_KEY, npm run dev, click Run agent.
• Done when: a maths prompt produces a rendered image in the UI.

Stage 1 — Understand the seed

Goal: know how the pipeline fits together — it’s latex-mcp in miniature.

• Trace one request: public/index.html → POST /agents/studio/:id (src/agents/studio.ts) → render_latex (src/shared/render-tools.ts) → renderLatex() (src/shared/render.ts, the LaTeX→SVG pipeline) → served by src/app.ts.
• Done when: you can explain each of those five files out loud, and point to the part that is the “pipeline” (render.ts) vs the “tool” (render-tools.ts).

Stage 2 — Expose the render as an MCP server (latex-mcp)

Goal: lift the render capability out of the one app and into an MCP server.

• Stand up a latex-mcp FastMCP server that exposes render_latex() as an MCP tool wrapping the same compile pipeline (LaTeX → TeX Live → SVG/PDF).
• Add a second tool, render_tikz_diagram(), to prove the server holds more than one capability.
• Done when: an MCP client can list the latex-mcp tools and call render_latex to get an SVG back — the render no longer lives only inside the Flue app.

Stage 3 — Put a client and an orchestrator in front

Goal: drive latex-mcp the way the architecture does.

• Connect Claude Code (a dev-time MCP client) to latex-mcp and call the tool from there.
• Then have an orchestration agent call the same MCP tool at runtime to produce content from a prompt. The orchestrator can be Flue (the seed already uses it), the OpenAI Agents SDK, or LangGraph — the MCP tool is the same either way.
• Done when: both a dev-time client (Claude Code) and a runtime agent can drive the same latex-mcp tool — no bespoke glue per consumer.

Stage 4 — Design for scale

Goal: make the pattern repeatable, not a one-off.

• Factor anything common (prompts, the math dataset, helpers) toward a shared-mcp / shared-lib, the way the architecture splits shared concerns.
• Write a short note: “to add manim-mcp, you copy this shape — a FastMCP server over a Dockerized pipeline.” (You are not building Manim here — only proving the route generalizes.)
• Done when: you can describe, concretely, how a second module slots in without redesigning latex-mcp.

Stage 5 — Test + a review gate

Goal: quality before “ship”, like the diagram’s Review → Ship step.

• promptfoo: a working starter ships in latex-starter/promptfooconfig.yaml (+ promptfoo/render-provider.mjs). Run and extend it:

  npx promptfoo@latest eval     # then: npx promptfoo@latest view

  Add cases (incl. a deliberately-broken one) and, harder, a provider that tests the whole path (prompt → agent/MCP → render).
• Add a simple human review / QA checkpoint before content is “shippable”.
• Done when: npx promptfoo eval runs your suite as expected, and there’s a clear “reviewed → shippable” step.

Companion goal — automate the basic job (Track 1)

Track 3 builds the infrastructure; Track 1 automates the work: getting Hermes to run the basic LaTeX job on a daily schedule. That’s Automate with Hermes.

Guiding rule (from the spec): no spec, no merge — fix the spec, not the code.