MCP server on the official SDK, over stdio or HTTP

scripts/mcp.js registers the same tools on @modelcontextprotocol/server (2.4.0, with
@modelcontextprotocol/node 2.1.2 for node:http; dev dependencies, pinned) instead of its own JSON-RPC
loop. stdio works as before; --http [HOST:]PORT serves Streamable HTTP at /mcp, on loopback unless
told otherwise.

Over HTTP every request's Host must be an address of this machine (or --allow-host), an Origin other
than localhost is refused, and a bearer token (SOT_MCP_TOKEN or --token-file) is optional; bound
beyond loopback without one, the server warns. load_save and export_save take JSON only there, or files
under --save-dir and nowhere else. Calls from every client run one at a time, in order.
This commit is contained in:
Wolfgang Nagele 2026-11-03 15:00:08 -05:00
parent 5b76685e5c
commit 2526dd458d
11 changed files with 467 additions and 63 deletions

View file

@ -31,6 +31,10 @@ one, redesign the feature.
- **Limits:** about 1 GB for the whole site, 100 MB per file.
- **Paths:** the site lives at the domain root (`site/CNAME`), so `/` paths are fine; unknown paths get
`404.html`.
- **Local tools are not hosting.** `npm run dev` and the MCP server (`npm run mcp`, also over `--http`)
run on a developer's own machine against a checkout; nothing they serve is deployed, and the game
never depends on them. Their code stays out of `_site/` (`src/agent/` is development-only, see
`docs/adr/0004-dev-only-code.md`).
## How it deploys

View file

@ -29,7 +29,7 @@ npm run build # builds _site/ for GitHub Pages (assembles src/, s
npm run serve # build and serve the production site locally
npm run perf -- --base-ref origin/main # big-network benchmark vs main (see `performance`)
npm run perf -- --base-ref origin/main --browser # the same, also in real Chromium (desktop and phone)
npm run mcp # the game as a local MCP server for AI clients (docs/MCP.md)
npm run mcp # the game as a local MCP server for AI clients, stdio or --http (docs/MCP.md)
```
## Hard rules

View file

@ -56,7 +56,7 @@ npm run dev # development server: assembles src/ on every request, reloads on
npm test # headless tests: boot, geography, a year of play, every incident, every panel
npm run build # writes the site for GitHub Pages to _site/, with version and date stamped in
npm run i18n:check # lists text missing from (or stale in) the translations
npm run mcp # the game as an MCP server, so an AI client can play and debug it (docs/MCP.md)
npm run mcp # the game as an MCP server, so an AI client can play and debug it (docs/MCP.md; --http for HTTP)
```
## Community

View file

@ -73,7 +73,7 @@ Development runs on `npm run dev` (assembles the development page on every reque
| `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-headless.js`, `src/agent/` | 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-headless.js`, `src/agent/` | The game as a local MCP server, on the official SDK over stdio or HTTP: 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: the players' page, or the development page with `{agent: true}` |

View file

@ -1,9 +1,10 @@
# 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`.
through typed tools. It runs on your machine, over stdio or over HTTP, 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`,
not a server for the game. The protocol is the official SDK's (`@modelcontextprotocol/server`, a dev dependency).
## Set it up
@ -15,6 +16,30 @@ 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.
### Over HTTP
For a client that connects to a running server instead of starting one (another process, a container, another
machine), serve Streamable HTTP:
```sh
node scripts/mcp.js --http 7777 # http://127.0.0.1:7777/mcp, this machine only
claude mcp add --transport http seriesoftubes http://127.0.0.1:7777/mcp
```
- **Where it listens is your choice.** `--http 7777` binds loopback. `--http 0.0.0.0:7777` (or one address) lets
other machines in, and then anyone who can reach it can play; the server says so when it starts.
- **Token (optional).** With `SOT_MCP_TOKEN=…` or `--token-file FILE`, every request needs
`Authorization: Bearer <token>` (`claude mcp add … --header "Authorization: Bearer …"`). Without a token, a server
bound beyond loopback warns. There is no TLS: beyond a network you trust, use `ssh -L 7777:127.0.0.1:7777` or a
TLS proxy in front.
- **Always checked, wherever it listens:** the `Host` must be an address of this machine (or a name given with
`--allow-host`), which stops DNS rebinding, and a request from a web page (an `Origin` other than localhost) is
refused, so no website can drive the game through your browser.
- **Files:** over HTTP, `load_save` and `export_save` take and give JSON only. `--save-dir DIR` lets them read and
write files under `DIR` and nowhere else (symbolic links that lead out are refused).
- **One game for every client.** Calls run one at a time, in the order they arrive; `new_game` or `load_save` from
any client replaces the game for all of them.
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.
@ -68,7 +93,9 @@ moves only with `advance`. There is no tool that evaluates code in the page.
## Code
- `scripts/mcp.js`: the stdio transport (JSON-RPC 2.0, one message per line) and the protocol methods.
- `scripts/mcp.js`: the server on the SDK: the tools registered from `TOOLS`, stdio or Streamable HTTP, the Host,
Origin and token checks, the one-at-a-time queue.
- `tests/mcp-http.test.js`: the HTTP transport, its checks, the token and the save directory.
- `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,

79
package-lock.json generated
View file

@ -9,6 +9,8 @@
"version": "2.7.0",
"license": "MIT",
"devDependencies": {
"@modelcontextprotocol/node": "2.1.2",
"@modelcontextprotocol/server": "2.4.0",
"jsdom": "24.1.3",
"playwright-core": "1.56.0"
},
@ -145,6 +147,63 @@
"node": ">=18"
}
},
"node_modules/@hono/node-server": {
"version": "2.1.6",
"resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-2.1.6.tgz",
"integrity": "sha512-p/KH9MnfNcsm3sR6x4lNgm5j+QN4Et8srKredl9DZfXiyZ1UQ3aQ2YVpFLbqktYN5JI+DB+VZFKM2PqE5hLKjQ==",
"dev": true,
"license": "MIT",
"engines": {
"node": ">=20"
},
"peerDependencies": {
"hono": "^4 || ^5.0.0-0"
}
},
"node_modules/@modelcontextprotocol/core": {
"version": "2.4.0",
"resolved": "https://registry.npmjs.org/@modelcontextprotocol/core/-/core-2.4.0.tgz",
"integrity": "sha512-z8QBKqdfXLPzkLQuG4xp8hrVEMm1PZ1IgxMN2sMbJiFiAKOWXnAzogXn2W4aqIBlP1ea6U5yiqVquvUNM1Cj6Q==",
"dev": true,
"license": "Apache-2.0",
"dependencies": {
"zod": "^4.2.0"
},
"engines": {
"node": ">=20"
}
},
"node_modules/@modelcontextprotocol/node": {
"version": "2.1.2",
"resolved": "https://registry.npmjs.org/@modelcontextprotocol/node/-/node-2.1.2.tgz",
"integrity": "sha512-IIcIqBpr6NCQQs5DgJTgvbSOAw+3iaR/uquqg+e0nXCdudfjPg/80x0TseUnQx14AUAtE4fsJCEpJKPyb6WPVA==",
"dev": true,
"license": "Apache-2.0",
"dependencies": {
"@hono/node-server": "^1.19.9 || ^2.1.3",
"hono": "^4.11.4"
},
"engines": {
"node": ">=20"
},
"peerDependencies": {
"@modelcontextprotocol/server": "^2.4.0"
}
},
"node_modules/@modelcontextprotocol/server": {
"version": "2.4.0",
"resolved": "https://registry.npmjs.org/@modelcontextprotocol/server/-/server-2.4.0.tgz",
"integrity": "sha512-rgR9yxSaAJ+bcsi/XroT/S2AfPiIWloXAnrdfYSCms9ivVju0ishu/wW0J21Ho6+ZOR1r7RyeRbjiRuF87ix5Q==",
"dev": true,
"license": "Apache-2.0",
"dependencies": {
"@modelcontextprotocol/core": "2.4.0",
"zod": "^4.2.0"
},
"engines": {
"node": ">=20"
}
},
"node_modules/agent-base": {
"version": "7.1.4",
"resolved": "https://registry.npmjs.org/agent-base/-/agent-base-7.1.4.tgz",
@ -457,6 +516,16 @@
"node": ">= 0.4"
}
},
"node_modules/hono": {
"version": "4.13.16",
"resolved": "https://registry.npmjs.org/hono/-/hono-4.13.16.tgz",
"integrity": "sha512-AOLOEhvrV+iH92xXCnFr/5+3KjPKcI3xP63XJtX5spAnkznPdHijlIsUTpi7/9EhWqrTCekw5c5zh1K+YsVw7A==",
"dev": true,
"license": "MIT",
"engines": {
"node": ">=16.9.0"
}
},
"node_modules/html-encoding-sniffer": {
"version": "4.0.0",
"resolved": "https://registry.npmjs.org/html-encoding-sniffer/-/html-encoding-sniffer-4.0.0.tgz",
@ -859,6 +928,16 @@
"integrity": "sha512-JZnDKK8B0RCDw84FNdDAIpZK+JuJw+s7Lz8nksI7SIuU3UXJJslUthsi+uWBUYOwPFwW7W7PRLRfUKpxjtjFCw==",
"dev": true,
"license": "MIT"
},
"node_modules/zod": {
"version": "4.6.7",
"resolved": "https://registry.npmjs.org/zod/-/zod-4.6.7.tgz",
"integrity": "sha512-g8W2D2kU6a8untc053fX1uVBKzM7yqAxW/3zwk83+6RyF2+SKOuV+c0wBDhUwzV1PaGapmZH+rmcUzPf+3CGwg==",
"dev": true,
"license": "MIT",
"funding": {
"url": "https://github.com/sponsors/colinhacks"
}
}
}
}

View file

@ -25,6 +25,8 @@
"node": ">=20"
},
"devDependencies": {
"@modelcontextprotocol/node": "2.1.2",
"@modelcontextprotocol/server": "2.4.0",
"jsdom": "24.1.3",
"playwright-core": "1.56.0"
}

View file

@ -33,7 +33,21 @@ function pageCall(g, tool, args = {}) {
return JSON.parse(g.ev('JSON.stringify(TUBES.call(__mcpTool,__mcpArgs))') || 'null');
}
// Where load_save and export_save may touch files. stdio (saveDir undefined): anywhere, as the operator's own client
// asks. Over HTTP the client may be another machine: nowhere (null), or only under one directory, symlinks included.
function savePath(s, p, write) {
if (s.saveDir === undefined) return path.resolve(p);
if (s.saveDir === null) throw new Error('This server takes saves as JSON only: give json instead of path (the server can allow a directory with --save-dir).');
const root = s.saveDir, full = path.resolve(root, String(p));
let real;
try { real = write ? path.join(fs.realpathSync(path.dirname(full)), path.basename(full)) : fs.realpathSync(full); } catch (e) { throw new Error(`${p}: no such file or directory under the save directory`); }
if (!real.startsWith(root + path.sep)) throw new Error(`${p} is outside the save directory.`);
if (write && fs.existsSync(real) && fs.lstatSync(real).isSymbolicLink()) throw new Error(`${p} is a symbolic link: write to a plain file.`);
return real;
}
// opts.seed, opts.file as tests/harness.js takes them (a file must be a development page: it carries the facade).
// opts.saveDir: see savePath.
function createSession(opts = {}) {
let game = null;
const boot = () => {
@ -44,6 +58,7 @@ function createSession(opts = {}) {
return g;
};
const session = {
saveDir: opts.saveDir,
get game() { return game || (game = boot()); },
// The page's own tools (TUBES.call).
call(name, args) { return pageCall(session.game, name, args); },
@ -79,7 +94,7 @@ const TOOLS = [
inputSchema: obj({ path: str('Path to a .json save file.'), json: str('The save itself, as JSON text.') }),
run: (s, a) => {
if (!a.path === !a.json) throw new Error('Give either path or json.');
const txt = a.path ? fs.readFileSync(path.resolve(a.path), 'utf8') : a.json;
const txt = a.path ? fs.readFileSync(savePath(s, a.path, false), 'utf8') : a.json;
return s.loadSave(txt);
},
},
@ -89,7 +104,7 @@ const TOOLS = [
inputSchema: obj({ path: str('Where to write the .json file.') }),
run: (s, a) => {
const txt = s.headless('exportSave', require('../../package.json').version);
if (a.path) { fs.writeFileSync(path.resolve(a.path), txt); return { wrote: path.resolve(a.path), bytes: Buffer.byteLength(txt) }; }
if (a.path) { const f = savePath(s, a.path, true); fs.writeFileSync(f, txt); return { wrote: f, bytes: Buffer.byteLength(txt) }; }
if (txt.length > MAX_INLINE_SAVE) throw new Error(`The save is ${txt.length} characters; give a path to write it to.`);
return JSON.parse(txt);
},
@ -215,4 +230,4 @@ const TOOLS = [
},
];
module.exports = { createSession, TOOLS, actArgs };
module.exports = { createSession, TOOLS, actArgs, savePath };

View file

@ -1,70 +1,180 @@
#!/usr/bin/env node
// Series of Tubes as an MCP server: an AI client can play, inspect and debug the game through typed tools.
// It runs locally over stdio and loads the game from this checkout's src/ (scripts/lib/mcp-game.js); nothing is
// hosted, and the game page itself does not change. Register it with a client, for example:
// It loads the game from this checkout's src/ (scripts/lib/mcp-game.js) and speaks MCP through the official SDK
// (@modelcontextprotocol/server), over stdio or over HTTP. Nothing is hosted: this is a local tool, like npm run dev,
// and the game page players get does not change.
//
// node scripts/mcp.js # stdio, for a client that starts the server itself
// node scripts/mcp.js --http 7777 # Streamable HTTP on http://127.0.0.1:7777/mcp
// node scripts/mcp.js --http 0.0.0.0:7777 # the same on every interface: anyone who can reach it can play
//
// claude mcp add seriesoftubes -- node /path/to/seriesoftubes/scripts/mcp.js
// claude mcp add --transport http seriesoftubes http://127.0.0.1:7777/mcp
//
// Protocol: JSON-RPC 2.0, one message per line on stdin and stdout (MCP stdio transport). stdout carries only
// protocol messages; anything else goes to stderr.
const readline = require('node:readline');
// stdout carries only protocol messages in stdio mode; anything else goes to stderr.
const crypto = require('node:crypto');
const fs = require('node:fs');
const http = require('node:http');
const os = require('node:os');
const path = require('node:path');
const { McpServer, fromJsonSchema, createMcpHandler, validateHostHeader, validateOriginHeader, localhostAllowedHostnames, localhostAllowedOrigins } = require('@modelcontextprotocol/server');
const { createSession, TOOLS } = require('./lib/mcp-game');
const { version } = require('../package.json');
const VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
const INSTRUCTIONS = `Series of Tubes is a cartoon game about building an internet backbone: POPs in cities, links between them, transit, exchanges, PNIs, customers. A game is always loaded (a fresh On-call game in Frankfurt until you start or load another).
Read with status, network, city, find, traceroute, peering_check and hot_spots, or raw with state, results and catalog; schema is the typed contract of every action. Change things with act (arguments are checked, outcome says what happened, dryRun prices a move first), or with screen, panel and click, which show the game's own panels and windows as text with numbered buttons. Time moves only with advance. Games are seeded: the same seed and moves give the same game.
To look into a bug report: load_save with the attached save, then status, hot_spots, and advance with timings.`;
const MCP_PATH = '/mcp';
const session = createSession();
const send = (msg) => process.stdout.write(JSON.stringify(msg) + '\n');
const reply = (id, result) => send({ jsonrpc: '2.0', id, result });
const error = (id, code, message) => send({ jsonrpc: '2.0', id, error: { code, message } });
const usage = () => `Usage: node scripts/mcp.js [options]
function handle(msg) {
const { id, method, params = {} } = msg;
const isRequest = id !== undefined && id !== null;
switch (method) {
case 'initialize':
return reply(id, {
protocolVersion: VERSIONS.includes(params.protocolVersion) ? params.protocolVersion : VERSIONS[0],
capabilities: { tools: { listChanged: false } },
serverInfo: { name: 'seriesoftubes', title: 'Series of Tubes', version },
instructions: INSTRUCTIONS,
});
case 'ping':
return reply(id, {});
case 'tools/list':
return reply(id, { tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })) });
case 'tools/call': {
const tool = TOOLS.find((t) => t.name === params.name);
if (!tool) return error(id, -32602, `Unknown tool: ${params.name}`);
(no options) stdio: the client starts this process and talks over stdin and stdout
--http [HOST:]PORT Streamable HTTP at http://HOST:PORT${MCP_PATH} instead (HOST defaults to 127.0.0.1)
--token-file FILE HTTP: require "Authorization: Bearer <the file's contents>" (or set SOT_MCP_TOKEN)
--allow-host NAME HTTP: also accept this Host name (repeatable), e.g. for a tunnel or a LAN name
--save-dir DIR HTTP: load_save and export_save may read and write files under DIR (otherwise no files)
--help`;
// Valueless flags are true; repeated ones collect; --kebab-case becomes camelCase.
function parseArgs(argv) {
const out = {};
for (let i = 0; i < argv.length; i++) {
const a = argv[i];
if (!a.startsWith('--')) continue;
const k = a.slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase()), v = argv[i + 1];
const val = v === undefined || v.startsWith('--') ? true : (i++, v);
out[k] = k in out ? [].concat(out[k], val) : val;
}
return out;
}
// Tool calls run one at a time, in the order they arrived, from every client: one game, one move at a time.
function serial() {
let chain = Promise.resolve();
return (f) => { const p = chain.then(f); chain = p.catch(() => {}); return p; };
}
// One MCP server definition over the game session: the SDK asks for a fresh one per connection (stdio) or per request
// (HTTP); they all share the session and its queue.
function serverFactory(session) {
const queue = serial();
const schemas = new Map(TOOLS.map((t) => [t.name, fromJsonSchema(t.inputSchema)]));
return () => {
const server = new McpServer({ name: 'seriesoftubes', title: 'Series of Tubes', version }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
for (const tool of TOOLS) {
server.registerTool(tool.name, { description: tool.description, inputSchema: schemas.get(tool.name) }, (args) => queue(async () => {
try {
const out = tool.run(session, params.arguments || {});
const out = await tool.run(session, args || {});
const errs = session.errors();
return reply(id, { content: [{ type: 'text', text: JSON.stringify(out, null, 1) }], ...(errs.length ? { _meta: { pageErrors: errs.slice(-5) } } : {}) });
return { content: [{ type: 'text', text: JSON.stringify(out, null, 1) }], ...(errs.length ? { _meta: { pageErrors: errs.slice(-5) } } : {}) };
} catch (e) {
return reply(id, { content: [{ type: 'text', text: String(e && e.message || e) }], isError: true });
return { content: [{ type: 'text', text: String(e && e.message || e) }], isError: true };
}
}));
}
default:
if (method && method.startsWith('notifications/')) return undefined;
if (isRequest) return error(id, -32601, `Method not found: ${method}`);
return undefined;
}
return server;
};
}
if (require.main === module) {
// The game page logs nothing to stdout, but a stray console.log anywhere must not break the protocol.
console.log = console.info = (...a) => console.error(...a);
const rl = readline.createInterface({ input: process.stdin });
rl.on('line', (line) => {
if (!line.trim()) return;
let msg;
try { msg = JSON.parse(line); } catch (e) { return error(null, -32700, 'Parse error'); }
if (Array.isArray(msg)) { for (const m of msg) handle(m); return; }
handle(msg);
// --http [HOST:]PORT, with IPv6 hosts in brackets ([::1]:7777).
function parseListen(v) {
const s = String(v === true ? '' : v);
const m = /^(?:\[([^\]]+)\]|([^:]+)):(\d+)$/.exec(s) || /^()()(\d+)$/.exec(s);
// Port 0 picks a free one (the banner says which).
if (!m || +m[3] > 65535) throw new Error(`--http takes [HOST:]PORT, e.g. 7777 or 0.0.0.0:7777, not "${s}"`);
return { host: m[1] || m[2] || '127.0.0.1', port: +m[3] };
}
const isLoopback = (h) => h === 'localhost' || h === '::1' || /^127\.\d+\.\d+\.\d+$/.test(h);
const isWildcard = (h) => h === '0.0.0.0' || h === '::';
const bracket = (h) => (h.includes(':') && !h.startsWith('[') ? `[${h}]` : h);
// The names a request's Host may carry: this machine by loopback, the address the server is bound to (every local
// address when bound to all of them), and names the operator allowed. Anything else is a name someone else's DNS
// points here (DNS rebinding) and is refused.
function allowedHosts(host, extra = []) {
const out = new Set([...localhostAllowedHostnames(), ...extra.map(String)]);
if (isWildcard(host)) for (const list of Object.values(os.networkInterfaces())) for (const a of list || []) out.add(bracket(a.address.split('%')[0]));
else out.add(bracket(host));
return [...out];
}
// Constant-time token check (hashing first makes the lengths equal, so the length does not leak either).
const sameToken = (a, b) => crypto.timingSafeEqual(crypto.createHash('sha256').update(String(a)).digest(), crypto.createHash('sha256').update(String(b)).digest());
// The HTTP side: Host and Origin checked on every request (browsers cannot be talked into driving the game from a
// website), the token when there is one, then the SDK's Streamable HTTP handler.
function createHttpServer(factory, { host, allow = [], token = null } = {}) {
const { toNodeHandler } = require('@modelcontextprotocol/node');
const handle = toNodeHandler(createMcpHandler(factory));
const hosts = allowedHosts(host, allow), origins = localhostAllowedOrigins();
const deny = (res, code, message, headers = {}) => {
res.writeHead(code, { 'content-type': 'application/json', ...headers });
res.end(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32000, message } }));
};
const server = http.createServer((req, res) => {
const url = new URL(req.url, 'http://localhost');
if (url.pathname !== MCP_PATH) return deny(res, 404, `The MCP endpoint is ${MCP_PATH}.`);
const h = validateHostHeader(req.headers.host, hosts);
if (!h.ok) return deny(res, 403, `Host not allowed: ${h.message}. Use an address of this machine, or start the server with --allow-host.`);
const o = validateOriginHeader(req.headers.origin, origins);
if (!o.ok) return deny(res, 403, 'Origin not allowed: a web page may not drive this server.');
if (token) {
const m = /^Bearer\s+(.+)$/i.exec(req.headers.authorization || '');
if (!m || !sameToken(m[1].trim(), token)) return deny(res, 401, 'A bearer token is required.', { 'www-authenticate': 'Bearer realm="seriesoftubes"' });
}
handle(req, res);
});
// advance over thousands of days on a big network takes minutes; Node's default would cut it off at five.
server.requestTimeout = 30 * 60 * 1000;
return server;
}
module.exports = { handle, TOOLS };
function readToken(args) {
if (args.tokenFile) {
const t = fs.readFileSync(path.resolve(String(args.tokenFile)), 'utf8').trim();
if (!t) throw new Error(`${args.tokenFile} is empty`);
return t;
}
return process.env.SOT_MCP_TOKEN ? String(process.env.SOT_MCP_TOKEN).trim() || null : null;
}
async function main() {
const args = parseArgs(process.argv.slice(2));
if (args.help) { console.error(usage()); process.exit(0); }
const say = (m) => console.error(`[series-of-tubes] ${m}`);
const die = (m) => { console.error(`error: ${m}`); process.exit(1); };
// The game page logs nothing to stdout, but a stray console.log anywhere must not break the stdio protocol.
console.log = console.info = (...a) => console.error(...a);
if (!args.http) {
for (const k of ['tokenFile', 'allowHost', 'saveDir']) if (args[k] !== undefined) die(`--${k.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase())} is an --http option`);
const { serveStdio } = require('@modelcontextprotocol/server/stdio');
const session = createSession();
serveStdio(serverFactory(session));
return;
}
let listen, token;
try { listen = parseListen(args.http); token = readToken(args); } catch (e) { die(e.message); }
// Over HTTP the client may be another machine: files only under --save-dir, never anywhere on this one.
let saveDir = null;
if (args.saveDir !== undefined) {
try { saveDir = fs.realpathSync(path.resolve(String(args.saveDir))); } catch (e) { die(`--save-dir ${args.saveDir}: ${e.message}`); }
if (!fs.statSync(saveDir).isDirectory()) die(`--save-dir ${args.saveDir} is not a directory`);
}
const session = createSession({ saveDir });
const server = createHttpServer(serverFactory(session), { host: listen.host, allow: [].concat(args.allowHost || []), token });
server.on('error', (e) => die(`could not listen on ${bracket(listen.host)}:${listen.port}: ${e.message}`));
server.listen(listen.port, listen.host, () => {
const ad = server.address(), at = `${bracket(ad.address)}:${ad.port}`;
say(`MCP server ${version} on http://${at}${MCP_PATH} (one game, shared by every client; calls run one at a time)`);
say(token ? 'a bearer token is required' : 'no token: anything that can reach this address may play');
if (!isLoopback(listen.host) && !token) say(`WARNING: bound to ${listen.host}, beyond this machine, without a token. Set SOT_MCP_TOKEN or --token-file to require one.`);
say(saveDir ? `load_save and export_save files: under ${saveDir}` : 'load_save and export_save take JSON only (no files: --save-dir DIR allows some)');
});
const shutdown = () => server.close(() => process.exit(0));
process.on('SIGINT', shutdown);
process.on('SIGTERM', shutdown);
}
if (require.main === module) main();
module.exports = { serverFactory, createHttpServer, serial, parseArgs, parseListen, allowedHosts, INSTRUCTIONS, MCP_PATH };

166
tests/mcp-http.test.js Normal file
View file

@ -0,0 +1,166 @@
// The MCP server over HTTP (scripts/mcp.js --http): the same tools as stdio through the SDK's Streamable HTTP
// handler, with the Host and Origin checked on every request, an optional bearer token, and files confined.
const test = require('node:test');
const assert = require('node:assert/strict');
const fs = require('node:fs');
const http = require('node:http');
const os = require('node:os');
const path = require('node:path');
const { spawn } = require('node:child_process');
const { createSession } = require('../scripts/lib/mcp-game');
const { serverFactory, createHttpServer, serial, parseListen, allowedHosts, MCP_PATH } = require('../scripts/mcp');
const INIT = { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'test', version: '1' } };
// One server on a free loopback port for the length of fn.
async function withServer(opts, fn) {
const session = createSession({ saveDir: opts.saveDir === undefined ? null : opts.saveDir });
const server = createHttpServer(serverFactory(session), { host: '127.0.0.1', allow: opts.allow, token: opts.token });
await new Promise((r) => server.listen(0, '127.0.0.1', r));
const base = `http://127.0.0.1:${server.address().port}`;
try { await fn(base); } finally { await new Promise((r) => server.close(r)); }
}
// A JSON-RPC message as an MCP client posts it; the answer may come as JSON or as one SSE event. node:http, not fetch,
// because fetch will not send a Host header of the caller's choosing.
let seq = 0;
function post(base, pathname, payload, headers = {}) {
const u = new URL(base), data = payload === undefined ? '' : JSON.stringify(payload);
return new Promise((resolve, reject) => {
const req = http.request({ host: u.hostname, port: u.port, path: pathname, method: 'POST',
headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream', 'mcp-protocol-version': '2025-06-18', 'content-length': Buffer.byteLength(data), ...headers } }, (res) => {
let text = '';
res.setEncoding('utf8');
res.on('data', (d) => { text += d; });
res.on('end', () => resolve({ status: res.statusCode, headers: res.headers, text }));
});
req.on('error', reject);
req.end(data);
});
}
async function rpc(base, method, params, headers = {}) {
const res = await post(base, MCP_PATH, { jsonrpc: '2.0', id: ++seq, method, params }, headers);
let body = null;
if (/event-stream/.test(res.headers['content-type'] || '')) {
const data = res.text.split('\n').filter((l) => l.startsWith('data: ')).map((l) => JSON.parse(l.slice(6)));
body = data.find((d) => d.id !== undefined) || null;
} else if (res.text) body = JSON.parse(res.text);
return { status: res.status, headers: res.headers, body };
}
const call = async (base, name, args = {}, headers) => {
const r = await rpc(base, 'tools/call', { name, arguments: args }, headers);
const c = r.body && r.body.result;
return { ...r, isError: !!(c && c.isError), text: c ? c.content[0].text : null, json: c && !c.isError ? JSON.parse(c.content[0].text) : null };
};
test('HTTP: initialize, list the tools and play, as over stdio', () => withServer({}, async (base) => {
const init = await rpc(base, 'initialize', INIT);
assert.equal(init.status, 200);
assert.equal(init.body.result.protocolVersion, '2025-06-18');
assert.equal(init.body.result.serverInfo.name, 'seriesoftubes');
assert.match(init.body.result.instructions, /Time moves only with advance/);
const list = await rpc(base, 'tools/list', {});
assert.ok(list.body.result.tools.length >= 22);
assert.deepEqual(list.body.result.tools.find((t) => t.name === 'network').inputSchema.required, ['network'], 'the schemas as written');
const st = await call(base, 'status');
assert.equal(st.json.home, 'Frankfurt');
await call(base, 'act', { action: 'launchBB', args: { city: 'fra' } });
const a = await call(base, 'advance', { days: 3 });
assert.equal(a.json.daysRun, 3);
assert.equal((await call(base, 'status')).json.day, 3, 'one game, kept between requests');
// Arguments are checked against the tool's schema before the game sees them; the game's own errors stay its own.
const extra = await call(base, 'status', { nope: 1 });
assert.ok(extra.isError && /additional properties/.test(extra.text));
const bad = await call(base, 'network', { network: 'no such thing at all' });
assert.ok(bad.isError && /No network matches/.test(bad.text));
assert.equal((await rpc(base, 'tools/call', { name: 'nope', arguments: {} })).body.error.code, -32602);
assert.equal((await post(base, '/elsewhere', {})).status, 404);
}));
test('HTTP: a Host this machine does not answer to, or a web page\'s Origin, is refused', () => withServer({ allow: ['tubes.lan'] }, async (base) => {
const port = new URL(base).port;
// DNS rebinding: a name someone else's DNS points at 127.0.0.1.
assert.equal((await rpc(base, 'tools/list', {}, { host: `evil.example:${port}` })).status, 403);
assert.equal((await rpc(base, 'tools/list', {}, { host: `tubes.lan:${port}` })).status, 200, 'unless the operator allowed it');
assert.equal((await rpc(base, 'tools/list', {}, { host: `localhost:${port}` })).status, 200);
// A website open in a browser on this machine.
assert.equal((await rpc(base, 'tools/list', {}, { origin: 'https://evil.example' })).status, 403);
assert.equal((await rpc(base, 'tools/list', {}, { origin: 'null' })).status, 403);
assert.equal((await rpc(base, 'tools/list', {}, { origin: 'http://localhost:6274' })).status, 200, 'a local browser-based client may');
}));
test('HTTP: with a token, every request must carry it', () => withServer({ token: 's3cret-token' }, async (base) => {
const none = await rpc(base, 'tools/list', {});
assert.equal(none.status, 401);
assert.match(none.headers['www-authenticate'], /^Bearer/);
assert.equal((await rpc(base, 'tools/list', {}, { authorization: 'Bearer wrong' })).status, 401);
assert.equal((await rpc(base, 'tools/list', {}, { authorization: 'Basic czNjcmV0LXRva2Vu' })).status, 401);
assert.equal((await rpc(base, 'tools/list', {}, { authorization: 'Bearer s3cret-token' })).status, 200);
}));
test('HTTP: saves as JSON only, unless --save-dir, and then nowhere outside it', async () => {
await withServer({}, async (base) => {
for (const [tool, args] of [['load_save', { path: '/etc/hosts' }], ['export_save', { path: path.join(os.tmpdir(), 'x.json') }]]) {
const r = await call(base, tool, args);
assert.ok(r.isError && /JSON only/.test(r.text), `${tool} refuses a path`);
}
const out = await call(base, 'export_save');
assert.equal(out.json.app, 'series-of-tubes');
const back = await call(base, 'load_save', { json: JSON.stringify(out.json) });
assert.equal(back.json.home, 'Frankfurt');
});
const root = fs.mkdtempSync(path.join(os.tmpdir(), 'tubes-saves-')), dir = fs.realpathSync(root);
const outside = fs.mkdtempSync(path.join(os.tmpdir(), 'tubes-outside-'));
try {
fs.writeFileSync(path.join(outside, 'secret.json'), '{"secret":1}');
fs.symlinkSync(path.join(outside, 'secret.json'), path.join(dir, 'link.json'));
fs.symlinkSync(outside, path.join(dir, 'out'));
await withServer({ saveDir: dir }, async (base) => {
const w = await call(base, 'export_save', { path: 'mine.json' });
assert.equal(w.json.wrote, path.join(dir, 'mine.json'));
assert.equal((await call(base, 'load_save', { path: 'mine.json' })).json.home, 'Frankfurt');
for (const [tool, p, why] of [['load_save', '../' + path.basename(outside) + '/secret.json', /outside/], ['load_save', '/etc/hosts', /outside|no such file/],
['load_save', 'link.json', /outside/], ['load_save', 'out/secret.json', /outside/], ['export_save', 'out/x.json', /outside/],
['export_save', 'link.json', /symbolic link|outside/], ['export_save', '../escape.json', /outside/]]) {
const r = await call(base, tool, { path: p });
assert.ok(r.isError && why.test(r.text), `${tool} ${p}: ${r.text}`);
}
assert.equal(fs.readFileSync(path.join(outside, 'secret.json'), 'utf8'), '{"secret":1}', 'nothing outside was touched');
assert.ok(!fs.existsSync(path.join(os.tmpdir(), 'escape.json')));
});
} finally { fs.rmSync(root, { recursive: true, force: true }); fs.rmSync(outside, { recursive: true, force: true }); }
});
test('calls run one at a time, in the order they came', async () => {
const q = serial(), log = [];
const slow = (n, ms) => q(async () => { log.push(`start ${n}`); await new Promise((r) => setTimeout(r, ms)); log.push(`end ${n}`); return n; });
const failing = q(async () => { log.push('start bad'); throw new Error('bad'); });
const r = await Promise.allSettled([slow(1, 30), failing, slow(2, 1)]);
assert.deepEqual(log, ['start bad', 'start 1', 'end 1', 'start 2', 'end 2']);
assert.deepEqual(r.map((x) => x.status), ['fulfilled', 'rejected', 'fulfilled'], 'a failed call does not stop the queue');
});
test('--http: where it listens, which Host names it answers to, and what it says about it', async () => {
assert.deepEqual(parseListen('7777'), { host: '127.0.0.1', port: 7777 });
assert.deepEqual(parseListen('0.0.0.0:7777'), { host: '0.0.0.0', port: 7777 });
assert.deepEqual(parseListen('[::1]:7777'), { host: '::1', port: 7777 });
assert.throws(() => parseListen(true), /HOST:\]PORT/);
assert.throws(() => parseListen('localhost'), /HOST:\]PORT/);
const loop = allowedHosts('127.0.0.1');
assert.ok(loop.includes('localhost') && loop.includes('127.0.0.1') && !loop.includes('0.0.0.0'));
const all = allowedHosts('0.0.0.0');
assert.ok(all.includes('127.0.0.1'), 'bound to every address: every address of this machine');
// The server itself, bound beyond loopback without a token: it runs, and says so loudly.
const child = spawn(process.execPath, [path.join(__dirname, '..', 'scripts', 'mcp.js'), '--http', '0.0.0.0:0'], { stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, SOT_MCP_TOKEN: '' } });
try {
let err = '';
await new Promise((res, rej) => { child.stderr.on('data', (d) => { err += d; if (/WARNING/.test(err) && /JSON only|--save-dir/.test(err)) res(); }); child.on('exit', () => rej(new Error(err))); });
assert.match(err, /MCP server .* on http:\/\/.*:\d+\/mcp/);
assert.match(err, /WARNING: bound to 0\.0\.0\.0, beyond this machine, without a token/);
} finally { child.kill(); }
const bad = spawn(process.execPath, [path.join(__dirname, '..', 'scripts', 'mcp.js'), '--save-dir', os.tmpdir()], { stdio: ['ignore', 'pipe', 'pipe'] });
let msg = '';
bad.stderr.on('data', (d) => { msg += d; });
assert.equal(await new Promise((r) => bad.on('exit', r)), 1);
assert.match(msg, /--save-dir is an --http option/);
});

View file

@ -1,4 +1,5 @@
// The MCP server (scripts/mcp.js): an AI client plays, inspects and debugs the game through typed tools.
// The MCP server (scripts/mcp.js): an AI client plays, inspects and debugs the game through typed tools. Over stdio
// here; tests/mcp-http.test.js has the HTTP transport.
const test = require('node:test');
const assert = require('node:assert/strict');
const fs = require('node:fs');
@ -27,7 +28,7 @@ test('speaks MCP over stdio: initialize, list tools, call one, and errors as err
assert.equal(init.result.protocolVersion, '2025-06-18');
assert.equal(init.result.serverInfo.name, 'seriesoftubes');
assert.ok(init.result.capabilities.tools);
assert.equal((await ask({ id: 9, method: 'initialize', params: { protocolVersion: '1999-01-01' } })).result.protocolVersion, '2025-11-25', 'an unknown version gets the newest');
assert.equal((await ask({ id: 9, method: 'initialize', params: { protocolVersion: '1999-01-01', capabilities: {}, clientInfo: { name: 'test', version: '1' } } })).result.protocolVersion, '2025-11-25', 'an unknown version gets the newest');
await ask({ method: 'notifications/initialized' });
const list = await ask({ id: 2, method: 'tools/list' });
const names = list.result.tools.map((t) => t.name);