The command tables and the page-side reads, screens and dispatch (scripts/lib/mcp-commands.js and
mcp-page.js) become src/agent/, the facade window.TUBES.call(tool, args) in the page's own scope.
A new <!-- @include-dev agent --> line in src/index.html pastes it in after the game, but only in the
development page (npm run dev, the MCP server, i18n-check, tests that ask with load({agent:true})).
The build drops the line whole: _site/ is byte for byte what main builds.
Tests load the page players get by default, the build test fails if anything outside src/agent/ names
the facade's api/API_ names, and the pages test checks the built page carries none of it and still
plays. ADR 0004 records the rule.
6.3 KiB
Series of Tubes as an MCP server
scripts/mcp.js lets an AI client (Claude Code, Claude Desktop, any MCP client) play, inspect and debug the game
through typed tools. It runs on your machine over stdio and loads the game from this checkout's src/, the way the
tests do: one page in jsdom, seeded, with no animation loop. Nothing is hosted and the game page does not change, so
it stays within ADR 0001: it is a local tool, like npm run dev.
Set it up
npm ci
claude mcp add seriesoftubes -- node /path/to/seriesoftubes/scripts/mcp.js
Other clients take the same command (node /path/to/seriesoftubes/scripts/mcp.js) in their MCP server settings.
npm run mcp starts it by hand; clients should use the node command, because npm run prints a line of its own first.
A game is always loaded: a fresh On-call game in Frankfurt until you start or load another. Every game is seeded, so the same seed and the same moves give the same game.
Tools
| Tool | What it does |
|---|---|
new_game |
Start a network in any home city with a preset (soft for Best Effort, freeze, oncall, bgp, sandbox), a seed, your own ASN, and the sandbox's chaos dial |
load_save, export_save |
Load an exported save (a path or JSON text, migrated as the game does) or write one the real game can import |
status |
Date, cash, revenue and costs by kind, level, tier and why it is not Tier 1, the goal, traffic, reach, POPs, incidents |
advance |
Run N days through dayTick(). Stops when a window opens or the network goes bankrupt. Returns the log, new incidents, cash and the time each day took |
network, city, find |
The world: policies and what a network asks for, its PoPs, cone and price; a city's exchanges, transit sellers, cables; search by name, id or ASN |
traceroute |
The looking glass: which exit wins to a network and why, with the AS path |
peering_check |
Would this network peer with you over a PNI or at an exchange, and the game's reason if not |
hot_spots |
The fullest links, transit ports and PNIs, the transit bill by carrier, and the biggest traffic still on transit with the way off it |
schema |
The typed contract: every action with its arguments, their domains and what it does; what is not available and why; a field-by-field reference of state and results |
catalog |
The reference tables the arguments point at (cities, networks, ports, optics, interns…), plus the conference calendar with its keys and the RouteScript recipes with their scripts |
state, results, ui |
The saved game itself (S), the last traffic computation (R) and the view state, as JSON, whole or by path (pops.fra, loanOffers, links.<id>) |
actions, act |
Every action with its arguments, and running one |
screen, panel, click, open_link |
The game's own windows, panels, left drawer, NOC dashboard, bank and puzzle box as text with numbered buttons; press one; open a link's build window |
Acting
act checks the arguments against schema first: a wrong id or value is an error that says what would fit, and
nothing runs. The action then runs as the game runs it, with what a player would type and pick filled in: a rename,
a RouteScript, a custom metric, the route and size of a link, the source and line system of dark fiber, the design
of a cable, the POPs to close. Confirmations are given, so rmLink removes the link in one call. The result says
what happened:
outcome |
Meaning |
|---|---|
applied |
Something changed. charged is what the game's money gate took; cashChange also counts goal rewards |
rejected |
The game said no; toasts has its words |
no_effect |
Nothing changed and nothing was said: usually a wrong id or a precondition |
shown |
A view or a draft: only the screen changed |
decision |
A window asks a question (a De-Kicks quote, a retention offer). Answer with one of decision.options or closeModal; other game commands wait until then |
quote |
With dryRun: {setup, monthly, days, blocked}, priced with the game's own helpers. Nothing happens, and no dice are rolled |
stopped |
The network is bankrupt |
click presses a button as a player's click does, with the button's own arguments, so a confirmation arms first
and windows step on as they do in the game. Lists the game acts on when they change are listed with their options
and clicked with a value. Neither tool reaches files, save slots, settings, the title screen or the game speed: time
moves only with advance. There is no tool that evaluates code in the page.
Looking into a bug report
load_savewith the save attached to the issue.statusandhot_spotsfor the picture,tracerouteandpeering_checkfor one network's traffic,stateandresultsfor the numbers behind them.advancea few days and readtiming.slowestDaysfor lag, or the log for what went wrong.
Code
scripts/mcp.js: the stdio transport (JSON-RPC 2.0, one message per line) and the protocol methods.scripts/lib/mcp-game.js: the session (one game page: the development page, which has the facade) and the tool list with input schemas.src/agent/: the facade (window.TUBES.call(tool, args)), in the page's own scope: every action's class, arguments, domains, price and description (20-commands.js), thestate/resultsfield reference (30-docs.js), the reads, screens, dispatch and time. It is part of the development page only, never of the page players get (ADR 0004).scripts/lib/mcp-headless.js: added to the server's own page to start, load and export games.tests/agent-api.test.js: the facade is inert until called, and the page players get has none of it.tests/mcp.test.js: the protocol, a game played through the tools, determinism, saves, and what stays out of reach.tests/mcp-commands.test.js: every action classified and its arguments real, outcomes, quotes, typed text, multi-step builds, confirmations, the reads and the screens.
The tools read the game's internals (S, R, ACT, NETS…), which are not a stable API: a refactor in src/ can
break a tool, and the tests are there to catch that in CI. A new action in ACT needs an entry in
src/agent/20-commands.js (a class, or API_DENY), or tests/mcp-commands.test.js fails.