MCP server: typed, checked actions with outcomes and dry-run prices; schema, catalog, state, results and ui tools
This commit is contained in:
parent
da1a4e2f3c
commit
a72cb7d760
9 changed files with 1542 additions and 85 deletions
|
|
@ -66,7 +66,7 @@ Development runs on `npm run dev` (assembles on every request, reloads on save);
|
|||
| `scripts/test.js` | `npm test`: runs every `tests/*.test.js` |
|
||||
| `scripts/release-notes.js` | Extracts a version's CHANGELOG bullets |
|
||||
| `scripts/perf-bench.js`, `perf-browser.js`, `perf-stats.js`, `perf-fixture.js` | Big-network benchmark, base vs head, headless and in Chromium as a desktop and a throttled phone, with a significance test per row (posted on every PR by `perf.yml` + `perf-comment.yml`), and the generator of its save, `tests/fixtures/big-network.json` |
|
||||
| `scripts/mcp.js`, `scripts/lib/mcp-game.js`, `scripts/lib/mcp-page.js` | The game as a local MCP server: typed tools to play, inspect and debug it from an AI client ([MCP.md](MCP.md)) |
|
||||
| `scripts/mcp.js`, `scripts/lib/mcp-game.js`, `scripts/lib/mcp-commands.js`, `scripts/lib/mcp-page.js` | The game as a local MCP server: typed tools to play, inspect and debug it from an AI client ([MCP.md](MCP.md)) |
|
||||
| `scripts/i18n-check.js`, `scripts/i18n-add.js`, `scripts/lib/dict.js` | Translation coverage and dictionary order; adding, renaming and removing entries |
|
||||
| `scripts/legacy/` | The splitter that made `src/` from the old `site/index.html` (and gave its text labels), and `port-branch.js`, which carries older branches over |
|
||||
| `tests/harness.js` | Loads the assembled page in jsdom with a seeded `Math.random` and a fake canvas |
|
||||
|
|
|
|||
46
docs/MCP.md
46
docs/MCP.md
|
|
@ -22,33 +22,61 @@ the same seed and the same moves give the same game.
|
|||
|
||||
| Tool | What it does |
|
||||
|---|---|
|
||||
| `new_game` | Start a network in any home city with a preset (`freeze`, `oncall`, `bgp`, `sandbox`) and a seed |
|
||||
| `new_game` | Start a network in any home city with a preset (`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 needs an answer or the network goes bankrupt. Returns the log, new incidents, cash and the time each day took |
|
||||
| `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 |
|
||||
| `actions`, `act` | Every game action with its arguments, and running one as a button would |
|
||||
| `screen`, `panel`, `click`, `open_link` | The game's own windows and panels as text with numbered buttons; press one; open a link's build window |
|
||||
| `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 |
|
||||
|
||||
`act` and `click` run the same `ACT` actions the buttons dispatch, so the game's rules, prices and messages apply.
|
||||
They never reach 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.
|
||||
## 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.
|
||||
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 `tests/mcp.test.js` is there to catch that in CI.
|
||||
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.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue