MCP and Skills

MCP and Skills

Theia ships MCP servers (so an agent like Claude Code can drive the artheia generators and the rf-theia test harness as tools) and Claude Code skills (orientation + workflow knowledge linked into a session). This page covers how they are wired and what each provides.

The .mcp.json wiring

A workspace's .mcp.json at the repo root declares the MCP servers Claude Code discovers automatically. Theia's looks like:

{
  "mcpServers": {
    "artheia":      { "command": "artheia/run_mcp.sh",  "args": [], "type": "stdio" },
    "rf-theia":     { "command": "rf-theia/run_mcp.sh", "args": [], "type": "stdio" },
    "work-with-me": { "command": ".venv/bin/python",
                      "args": [".claude/plugins/work-with-me/server.py"], "type": "stdio" }
  }
}

Each launcher is workspace-relative and runs from the single workspace .venv (no per-server venv). Both run_mcp.sh scripts fail loudly if .venv/bin/python is missing, telling you to create the venv and editable- install the package.

artheia MCP — the generators as tools

artheia/run_mcp.sh execs python -m artheia.adapters.mcp_server. It exposes the artheia CLI as MCP tools, so an agent can validate .art and run the generators without shelling out. It sets THEIA_INVOCATION_CWD to the workspace root so the model's relative .art paths resolve against the dir you are working in (the server chdir's there per call), and runs from a neutral cwd so the installed artheia package wins the import.

Tools exposed (artheia/artheia/adapters/mcp_server.py):

tool	what it does
list_generators	enumerate the available artheia commands
describe	show a command's help/usage
parse	full-tree resolve / validation of a .art file
check_addresses	system-wide TIPC address-uniqueness gate
gen_app	generate the C++ FC scaffold (lib + main + impl)
gen_manifest	.art → the Python manifest module
gen_proto	.proto emission from .art
gen_schema	config schema (digest → type → shape)
gen_netgraph	nodes + compositions → JSON netgraph
gen	escape hatch to run any artheia command by name + args

These map onto the same verbs documented in Deployment-Manifest-Generation-and-Serialization.

rf-theia MCP — run scenarios and keywords

rf-theia/run_mcp.sh execs python -m rf_theia.adapters.mcp_server. rf-theia is a standalone Robot Framework + TPT harness (its own repo, mounted as the rf-theia/ submodule); the .robot scenarios it runs live in the consuming repo at <workspace>/testing/scenarios. The launcher bridges the two: it finds the consuming workspace, exports RF_THEIA_WORKSPACE and RF_THEIA_SCENARIOS, adds the workspace to PYTHONPATH, and execs the server.

It exposes test-harness tools (run against the live supervisor + the Tracer feed):

tool	what it does
list_scenarios	list the available .robot scenarios
list_keywords	list the harness keywords (e.g. T Sup / T Sig)
create_scenario	scaffold a new scenario
run_scenario	run a scenario against the live stack
get_test_results	fetch the last run's results
analyze_trace	inspect the e2e signal flow from the trace feed
tail_supervisor_log	tail the supervisor log

The rf-theia harness regression-tests the artheia generators too — e.g. the fc_regen_stability self-test that enforces "generated files are never hand-edited."

Claude Code skills (contrib/skills/)

Skills are versioned knowledge linked into a session. They are tracked in the repo under contrib/skills/ and linked into the local (gitignored) .claude/skills/ so Claude Code discovers them. First-time setup links each tracked skill:

mkdir -p .claude/skills
for d in contrib/skills/*/; do
    name=$(basename "$d")
    ln -sfn "../../contrib/skills/$name" ".claude/skills/$name"
done

The skills:

Skill	What it's for
theia (contrib/skills/theia/)	the orientation refresher — the .art DSL, the FCs, the runtime, the supervisor, and the .art → manifest → build → deploy pipeline. Start here; load a references/ page for a specific task.
tasks / task-kanban (contrib/skills/tasks/)	the folder-based kanban workflow under docs/tasks/{BACKLOG,TODO,PROGRESS,DONE}. Tasks only ever move forward; they are never deleted or closed. Governs all task-file lifecycle operations.
work-with-me (contrib/skills/work-with-me/)	an MCP plugin that watches the human's file changes (an inotify watcher, .gitignore-aware, attributing edits to you vs. the agent) and correlates them with your shell history, so you can ask the agent to review your manual edits mid-session.

work-with-me verbs

work-with-me is the third MCP server in .mcp.json. It is off by default (non-intrusive for teammates sharing the config). Typical loop: watch me → work → check me → repeat.

verb / slash	does
watch me / /watch-me	start tracking (fresh checkpoint)
check me / /check-me	review your edits + correlated shell commands, advise, clear checkpoint
fix me / /fix-me	same review surface, but also apply the fixes
compare me / /compare-me	review including the actual git diff of touched files
focus me on X / /focus-me	set the one-line session goal the review uses
list me / /list-me	passive listing of the current buffer (no analysis)
undo me / /undo-me	show diff + git checkout -- revert hints (non-destructive)
ignore me / /ignore-me	discard everything buffered since watch me (aborted attempt)

A PostToolUse hook (hooks/record_agent_edit.sh) records the agent's own edits so check me reviews only your manual changes.

Putting it together

In a consuming workspace you wire .mcp.json once (pointing at the two run_mcp.sh launchers + the work-with-me server), create the workspace .venv, editable-install artheia and rf-theia, and link the skills into .claude/skills/. From there an agent can validate and regenerate .art (artheia MCP), run the test scenarios (rf-theia MCP), and stay oriented (the theia skill) — the same pipeline a human drives via the artheia / theia / tdb CLIs covered in Tutorial and Advanced-Tools.