# 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](adr/0001-github-pages-only.md): it is a local tool, like `npm run dev`. ## Set it up ```sh 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.`) | | `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 1. `load_save` with the save attached to the issue. 2. `status` and `hot_spots` for the picture, `traceroute` and `peering_check` for one network's traffic, `state` and `results` for the numbers behind them. 3. `advance` a few days and read `timing.slowestDays` for 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) and the tool list with input schemas. - `scripts/lib/mcp-commands.js`: runs inside the page: every action's class, arguments, domains, price and description, and the `state`/`results` field reference. - `scripts/lib/mcp-page.js`: runs inside the page and reads or drives the game through its own globals. - `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 `scripts/lib/mcp-commands.js` or the server's `DENY` list, or `tests/mcp-commands.test.js` fails.