MCP Server

MCP Server

rf-theia ships an MCP server so Claude Code can run scenarios, list keywords, inspect results, and analyze traces directly — driving the live supervisor + Tracer.hh feed through the same harness a human would use.

Install with the mcp extra; it provides the rf-theia-mcp console script:

pip install 'rf-theia[mcp]'

The server is rf_theia.adapters.mcp_server (a FastMCP app named rf-theia).

Tools

Verified against rf_theia/adapters/mcp_server.py:

Tool	Arguments	What it does
run_scenario	scenario_path, timeout=120, tags="", dryrun=False	Run a .robot file or directory (path relative to the scenarios root). dryrun resolves keywords without executing (smoke test). Returns return code + stdout/stderr.
list_scenarios	—	Discover .robot files under the scenarios root, each with its Documentation line.
list_keywords	—	Enumerate the keywords exposed by TheiaTestLibrary (name + first doc line).
create_scenario	rel_path, content	Write a new .robot file under the scenarios root (creates subdirs).
get_test_results	output_dir=""	Parse the last run's output.xml (default /tmp/rf_theia_output) into a pass/fail summary.
analyze_trace	trace_path	Summarize a Tracer.hh trace file: per-event-kind counts, per-node totals, correlation-pair count, first/last timestamps (JSON).
tail_supervisor_log	path, lines=80	Tail any file — supervisor stderr, FC daemon logs, etc.

Runs land in /tmp/rf_theia_output (output.xml), and robot is invoked from the consuming workspace's .venv/bin/robot so the harness + Robot resolve from the project that owns the scenarios.

Environment resolution

rf-theia is standalone; the scenarios it runs live in the consuming repo. The server resolves both the scenario tree and the venv from the environment that run_mcp.sh exports:

Var	Meaning	Default
RF_THEIA_WORKSPACE	the consuming workspace root (holds .venv/)	the dir holding rf-theia/ (i.e. rf-theia/..)
RF_THEIA_SCENARIOS	the .robot scenario tree	$RF_THEIA_WORKSPACE/testing/scenarios

If RF_THEIA_SCENARIOS is unset, the server falls back to $RF_THEIA_WORKSPACE/testing/scenarios, then legacy in-tree layouts (<pkg>/../scenarios, <pkg>/scenarios). The Robot venv is taken from $RF_THEIA_WORKSPACE/.venv/bin.

The launcher: run_mcp.sh

rf-theia/run_mcp.sh is the bridge between the standalone harness and the consuming repo. It:

1. locates the workspace (the dir holding the rf-theia/ submodule, unless RF_THEIA_WORKSPACE is already set),
2. checks <workspace>/.venv/bin/python exists (errors with setup hints if not),
3. exports RF_THEIA_WORKSPACE, RF_THEIA_SCENARIOS (default <workspace>/testing/scenarios), and prepends the workspace to PYTHONPATH,
4. execs python -m rf_theia.adapters.mcp_server from the workspace venv.

So the workspace needs the harness installed in its venv:

python3 -m venv .venv
./.venv/bin/pip install -e 'rf-theia/[mcp,dev]'

Wiring .mcp.json

Point the workspace-root .mcp.json at the launcher so Claude Code discovers it:

{
  "mcpServers": {
    "rf-theia": {
      "command": "rf-theia/run_mcp.sh"
    }
  }
}

For a non-standard layout, override the scenario tree:

{
  "mcpServers": {
    "rf-theia": {
      "command": "rf-theia/run_mcp.sh",
      "env": {
        "RF_THEIA_SCENARIOS": "/abs/path/to/scenarios"
      }
    }
  }
}

How Claude Code drives tests

A typical loop:

1. list_scenarios / list_keywords — see what's available and the keyword surface.
2. create_scenario — write a focused repro (or edit one in the repo).
3. run_scenario with dryrun=True — confirm keywords resolve.
4. run_scenario (live) — drive the real supervisor + trace feed.
5. get_test_results — read the pass/fail summary.
6. On failure: analyze_trace for an event/node breakdown, tail_supervisor_log for the supervisor's stderr.

Related

• Writing Scenarios — the keyword surface these tools run.
• Home — harness overview and the harness-vs-scenarios split.