Serve Runs to Agents & UIs (HTTP + MCP)¶

TrainCraft ships a thin service layer that exposes run state, quality reports and pipeline submission over two transports — a FastAPI HTTP API (for dashboards/scripts) and an MCP server (for AI agents). Both are wrappers over the same functions (traincraft.service.core), so they expose exactly the same capabilities. Nothing else is needed beside the runs directory: state comes from each run's events.jsonl and stage manifests.

pixi install -e service          # fastapi + uvicorn + mcp (optional extras)

HTTP API¶

pixi run -e service traincraft serve runs/            # http://127.0.0.1:8137

Interactive OpenAPI docs at http://127.0.0.1:8137/docs.

Endpoint	Returns
`GET /runs`	all runs with status/last stage/engine (lazy-refreshed index)
`GET /runs/{name}`	per-stage status incl. live labeling progress
`GET /runs/{name}/events`	the raw event log
`GET /runs/{name}/report`	`quality_report.json` (metrics, checks, passed)
`GET /runs/{name}/manifest/{stage}`	a stage manifest (`label`, `train`)
`POST /config/validate`	validate TOML text: `{"toml": "..."}` → `{valid, name, stages, errors}`
`POST /runs`	start a pipeline: `{"config_path": "...", "force": false}`

POST /runs returns immediately: Slurm configs are submitted as dependency-chained jobs; anything else runs as a detached local process (output to <run>/local.log). Track progress with GET /runs/{name}.

Localhost tool — no auth

The service exposes results and can start pipelines from server-side config paths. It binds to 127.0.0.1 by default; keep it there (or put a real authenticating gateway in front). Never expose it raw to a network.

MCP server (agents)¶

The same operations as MCP tools, over stdio:

# register with Claude Code:
claude mcp add traincraft -- pixi run -e service traincraft mcp /abs/path/to/runs

Tool	Purpose
`list_runs`	find runs + status
`run_status(name)`	per-stage state, counts, errors, live label progress
`quality_report(name)`	the validation verdict — read before any model claim
`stage_manifest(name, stage)`	level of theory / training command + counts
`validate_config(toml_text)`	check a config before submitting
`submit_run(config_path, force)`	start a pipeline (confirm cost with the user first)

The tool docstrings encode the working rules (validate before submit; judge models only by their quality report), so any MCP-capable agent inherits them. For richer agent behaviour (config authoring, environment selection, visualisation), pair the MCP server with the TrainCraft skill (skills/traincraft/SKILL.md), which the agent uses via the CLI.

From Python¶

from traincraft.service import core

core.list_runs("runs")
core.get_run("runs", "my_run")
core.get_report("runs", "my_run")
core.validate_config_text(toml_text)
core.submit_config("my_run.toml")

create_app(outdir) / create_mcp(outdir) build the FastAPI app and MCP server if you want to mount them inside a larger application.