shapez
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
shapez-ai-bridge
English | 简体中文
An AI-operable interface for shapez.io: a single-file official mod + a zero-dependency local bridge + an MCP server. Observe the factory, place and delete buildings, fast-forward deterministically, move blueprints and savegame snapshots, and let any script or MCP client drive it — all locally, over 127.0.0.1.
┌─ shapez.io (Electron) ───────────────────┐
│ shapez-ai-bridge.js │ the mod is a WebSocket *client*
│ (official single-file mod, no Node) ──┼──▶ ws://127.0.0.1:7777/mod
└─────────────────────────────────────────┘
│
┌─────────────┴────────────────────────────┐
│ bridge.mjs (Node, zero dependencies) │
│ ├─ WS /mod ← game mod │
│ ├─ WS /client ← tools / event stream │
│ └─ HTTP /health /status /rpc ← curl │
└─────────────┬────────────────────────────┘
│ HTTP or stdio
┌─────────────┴──────────┬─────────────────┐
│ mcp/server.mjs │ agent/play.mjs │
│ 8 MCP tools (Claude…) │ reference agent│
└────────────────────────┴─────────────────┘Why a separate bridge process? shapez.io's renderer is sandboxed (nodeIntegration:false, sandbox:true), so an in-game mod has no file or socket APIs — but the browser's native WebSocket client is always available. The mod dials out to a small Node process on your machine; that process owns the HTTP API, the MCP server and the snapshot files.
Prefer a GUI?
A local web interface covers the whole setup without any commands: double-click
gui/start.cmd (Windows), and a wizard walks through environment check, mod
install, configuration, bridge start and verification — with live logs and
explicit fixes when something is missing. No configuration file is ever edited
by hand.
node gui/server.mjs # or double-click gui/start.cmd on WindowsIt opens a chromeless app window on http://127.0.0.1:7801/. Same zero-dependency
rules as the rest of the project: it needs only Node and a browser, both of which
you already have by the time you get here. See gui/README.md
(中文) for the walkthrough.
Everything below is the command-line path — the GUI drives exactly the same scripts, so the two are interchangeable.
Related MCP server: arena-agent
30-second quick start
Prerequisites: Node.js ≥ 20, shapez.io desktop 1.5.6 (Steam build), and a checkout of this repository.
1. Install the mod (one command).
Windows (PowerShell):
powershell -ExecutionPolicy Bypass -File install.ps1macOS / Linux:
bash install.sh2. Start the bridge (one command).
node src/bridge/bridge.mjs3. Start shapez.io, load a savegame, then run:
node scripts/smoke_test.mjsExpected: SMOKE TEST PASSED (5/5). (The test briefly places and deletes one belt near the hub to prove writes work — your world is left unchanged.)
What it can do
Curl examples below assume bash. On Windows PowerShell curl is an alias for Invoke-WebRequest — use curl.exe instead, with double quotes around the JSON (escaping the inner quotes), or use the included scripts.
Observe — ask the game what's in the world as JSON: entities with stable uids, hub stock, current goal, camera, stats.
curl -s http://127.0.0.1:7777/rpc -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"obs","params":{"max_entities":5,"include_hub":true}}'Act — place or delete buildings, lay paths, set game speed, move the camera.
curl -s http://127.0.0.1:7777/rpc -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"act","params":{"op":"place","building":"belt","x":5,"y":5}}'Fast-forward — advance N game ticks synchronously and deterministically (the same loop the game's own puzzle validator uses), optionally collecting an observation.
curl -s http://127.0.0.1:7777/rpc -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"act","params":{"op":"step","ticks":600,"collect":true}}'Blueprints — export any region as a portable
SZBP1.*string and paste it back anywhere (material cost per game rules by default, free withcharge:false).curl -s http://127.0.0.1:7777/rpc -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"act","params":{"op":"export_blueprint","region":[0,0,10,10]}}'Save snapshots — save the game and keep a named copy of the save file on the bridge side, then restore it any time.
curl -s http://127.0.0.1:7777/rpc -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"snapshot_save","params":{"name":"before-big-build"}}'MCP — all of the above exposed as 8 MCP tools (
shapez_status,shapez_observe,shapez_action,shapez_batch,shapez_screenshot,shapez_blueprint,shapez_save,shapez_load) for Claude and other MCP clients.echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node src/mcp/server.mjs
The full protocol contract (methods, error codes, observation schema) lives in docs/PROTOCOL.md.
Build a factory from a target shape
src/ai/ contains a layout compiler: give it a goal shape, and it plans a working production line offline, then hands you a blueprint that pastes and delivers.
node src/ai/compiler/cli.mjs --goal "CuCuCuCu" --seed 43391 --hub -2,-2 --jsonIt runs the whole chain with no game running: recipe solver → offline resource map (the world is a pure function of map.seed) → row layout → belt routing with explicit (rotation, rotationVariant) → ten-check validator → SZBP1 blueprint.
--hub is required. Without it the compiler can only invent a hub location, so the collection belt feeds empty ground. A compile whose hub is not pinned is reported as a failure (class: "hub:unpinned"), not a success. Pass the hub's real top-left corner as observed from the game (obs), not a guessed coordinate.
ok: true means the plan is internally consistent and reaches the real hub when pasted onto empty ground. It does not mean the target area is empty: the compiler is offline and does not read your save, so it cannot see what is already built there. Always dry_run the paste first — that is the check that sees the world.
The end-to-end live run (compile → dry_run → paste → per-cell diff → hub delivery) was verified on an earlier plan shape of this same goal. The current code produces the 9-entity plan shown above; it passes the offline validator, round-trip, and the world-frame hub check (hubPinned: true), but the paste-and-deliver step has not been re-run on this exact blueprint — the game was in its menu at the time of the last attempt and new_game wedges after long uptime. Treat the live delivery as verified for the pipeline, not for this byte-for-byte blueprint.
What it handles today
Goals that build |
|
Not yet |
|
Painted goals are map-permitting, not unconditional. The row layout puts every miner on one row at a fixed pitch, so a painted goal needs the world to offer its ore in exactly that pattern. CrCrCrCr needs Cu with red four cells west; on seed 43391 that pattern occurs twice in a 512×512 window. Other seeds may have none — the compiler says no-resource-in-range rather than producing a line that starves. Treat painted goals as "works where the ore lines up", not "works anywhere".
Safety rules the compiler enforces
Refuses to emit a plan that would land on existing buildings. Only belts and wires are replaceable in shapez; pasting over one silently destroys it, and pasting over a machine half-builds the line while still reporting success.
paste_blueprintgained adry_runthat reportswould_apply/would_delete/blockedbefore anything happens.Refuses corners that would flip. A belt's turn is recomputed from its neighbours, so a corner must be a fixed point of that recomputation; when no original rotation makes it one, the plan fails instead of producing a line that breaks later.
Never pastes into a dirty region. v1 builds on fresh ground only. The builder refuses a world snapshot that contains non-hub entities, on both the pinned and unpinned paths — but it only sees a world if you hand it one, so
dry_runremains the authoritative check.Refuses a plan whose hub is unknown. Without
--hubthe collector belt would terminate at an invented coordinate. Such a compile returnsok: falsewithclass: "hub:unpinned"instead of a blueprint.
See research/ai-plan/BATCH.md for the build ledger and research/ai-player/SYNTHESIS.md for the research behind it.
Compatibility
Generated from compat.json:
Game version | Mod version | Protocol | Status |
1.5.6 (Steam build | 0.1.x | 1 | Supported — development baseline |
any other | any | any | Hard fail (error |
The mod declares minimumGameVersion: 1.5.6, and the bridge re-checks the game version reported at handshake against this table; on mismatch nothing is routed.
Uninstall
Delete shapez-ai-bridge.js from the mods folder (that single file is the entire mod), or run install.ps1 -Uninstall / bash install.sh --uninstall.
Known limitations
An honest list, taken from the phase-0 recon (PHASE0-RECON.md):
Steam achievements are disabled while ANY mod is installed. The game only enables its Steam layer when zero mods are loaded (
if (mods.length === 0) steam.listen()). This is official shapez.io behavior, not a bug of this project.The game clears localStorage on every launch (
clearCache()+clearStorageData()in the main process), so the mod has no cross-session local storage. Anything persistent must go through mod settings files or the savegame.shapez.io 1.5.6 has no native blueprint string format. This project defines its own
SZBP1.*format (built on the game's own LZ-string compression), so blueprints are only exchangeable between the same game version — the embeddedgvfield is checked on paste, and a mismatch fails with error2006.Pasting a blueprint charges "blueprint shape" material (in regular mode,
CbCbCbRb:CwCwCwCw) per the game's own cost formula. Usecharge:falseto paste for free.step/awaitfast-forward runs synchronously on the render thread — large tick counts briefly freeze the screen. A single step is capped at 20,000 ticks.Observations of big factories must be clipped with
regionand/ormax_entities. Over-limit observations reporttruncated: trueand always include fullstats— never a silent cut.Desktop only (Windows / macOS / Linux Electron builds). The mobile and browser versions of shapez.io do not support mods and are not applicable.
new_gameneeds a fresh game process. After a very long uptime the game can wedge in the menu: the save is created but the state machine never enters the world. Restart the game and it works immediately.The layout compiler's output is god-mode. It uses
charge:falseand does not check building unlock levels, so it can place a stacker at level 2. The acceptance target (CuCuCuCu) needs only the level-1 cutter, so it holds under either reading, but any "cleared level N" claim from the compiler is a god-mode claim.The compiler builds on fresh ground only. It refuses to place over existing buildings (v1), so extending a running factory is not supported yet.
Troubleshooting
"I can't connect."
Is the bridge running?
curl -s http://127.0.0.1:7777/healthshould return{"ok":true,...}. "Connection refused" → startnode src/bridge/bridge.mjs.Is the game running?
healthreportsmod_connected:trueonly once the game is open with the mod loaded.mod_connected:falsemeans the game (or the mod) isn't there yet.Is the mod in the right place? The game reads
%APPDATA%\shapez.io\mods(Windows),~/Library/Preferences/shapez.io/mods(macOS),~/.local/share/shapez.io/mods(Linux). It must be a single.jsfile directly in that folder (not a subfolder). On startup the game logsLoaded N mods— N must be ≥ 1. The install scripts pick the right folder automatically;-ModsDir/--mods-diroverride it.Security software: a firewall/proxy that blocks localhost traffic can break both the bridge's listener and the mod's WebSocket. Allow
nodeon127.0.0.1:7777; if a system proxy is forced for all traffic, exclude127.0.0.1.
"Version mismatch (error 1002)." The bridge refused the handshake because the game version isn't in the compatibility table. This is a hard fail by design: building codes and internal APIs are version-specific. Fix by upgrading to a mod/bridge version that lists your game build in compat.json (or switch the game back to a supported build via Steam betas). There is no override flag.
"Observation is empty / errors."
Error
1003 not_in_game→ you're in the main menu or still loading. Load a savegame (or start a new one);statuswill sayin_game:true.Region selection:
region:[x0,y0,x1,y1]is an inclusive bounding box — everything outside it is filtered out. Omitregionto observe the bounding box of all entities.Layer: entities live on
regularorwires; observe the right one (defaultregular).
"My MCP client doesn't list the tools."
The path in the client config must be absolute and point at
src/mcp/server.mjs. In JSON on Windows use forward slashes (C:/...) or escaped backslashes (C:\\...).Restart the MCP client after editing its config.
Test the server standalone:
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node src/mcp/server.mjs— you should get a JSON line listing 8 tools.The server logs to stderr, not stdout; check your client's MCP logs for its stderr output.
MCP configuration
mcp-config.example.json:
{
"mcpServers": {
"shapez": {
"command": "node",
"args": [
"C:/path/to/shapez-ai-bridge/src/mcp/server.mjs"
],
"env": {
"SHAPEZ_BRIDGE_URL": "http://127.0.0.1:7777"
}
}
}
}Replace the path with the absolute path of your checkout. Windows path writing in JSON: either forward slashes (C:/Users/you/shapez-ai-bridge/src/mcp/server.mjs) or escaped backslashes (C:\\Users\\you\\...); single backslashes are invalid JSON. command must resolve to a node ≥ 20. If your bridge runs with a token (bridge.config.json), add "SHAPEZ_BRIDGE_TOKEN": "<token>" to env.
License and provenance
This project's code is MIT — see
LICENSE.Vendored lz-string 1.4.5 (
src/shared/lz-string.cjs): © 2013 Pieroxy, dual-licensed MIT / WTFPL — seesrc/shared/lz-string.LICENSE.txt. It compresses blueprints and mirrors the game's own savegame compression.This repository contains no shapez.io game code. All integration goes through the game's official mod API (single-file mods with
METADATA/Mod,ModInterface, thewindow.shapezmodule exports). shapez.io is © tobspr Games.
Development
Directory layout:
Path | What it is |
| In-game mod — single file, loaded by the official mod loader |
| Zero-dependency Node bridge: WS |
| MCP stdio server (8 tools), forwards to the bridge's HTTP API |
| Reference agent driving the bridge over HTTP |
| Vendored lz-string + the |
| Zero-dependency end-to-end smoke test |
| The frozen protocol contract — the single source of truth |
| Machine-readable compatibility matrix |
| Layer selftests (mod RPC in a Node sandbox, lz-string interop, blueprint round-trips) |
| Phase-0 reverse-engineering artifacts (local research only, excluded from distribution) |
Running the layers and their selftests:
npm run selftest:bridge # bridge layer selftest
npm run selftest:mcp # MCP layer selftest
npm run smoke # end-to-end smoke test (needs game + bridge running)
npm run agent # reference agent
node test/mod_rpc_selftest.mjs # mod RPC logic, exercised in a Node sandbox
node test/lzstring_interop.mjs # lz-string byte-level interop with the game's variant
node test/blueprint_selftest.mjs # SZBP1 codec round-tripsSmoke test details: fully non-interactive by default; exit code 0 = pass, 1 = bridge not running, 2 = game not in a world, 3 = other check failed. SHAPEZ_SMOKE_AUTOPLAY=1 additionally suppresses the notice about the temporary belt it places. Override the bridge address with --url / SHAPEZ_BRIDGE_URL; authenticate with --token / SHAPEZ_BRIDGE_TOKEN.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Official remote MCP server bridge for Muumuu Domain.
Create, inspect, validate, and save editable 3D building scenes with Pascal's MCP server.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceExposes app-registered tools as an MCP server for OpenClaw, forwarding actual tool execution back to the app over a WebSocket bridge.-
- AlicenseNot gradedqualityBmaintenanceLocal automation bridge that is both an MCP server and client: 234 tools across 44 namespaces for shell, filesystem, git, desktop control, browser (CDP), Android (ADB), OCR/ASR and memory, plus the ability to connect external MCP servers. Sandboxed execution with token auth, fail-closed policy and audit log.9MIT
- FlicenseNot gradedqualityCmaintenanceEnables MCP clients to query a live Factorio 2.0 world through bounded read-only operations covering spatial, inventory, resource, and diagnostic data over loopback RCON.1-
- AlicenseNot gradedqualityBmaintenanceEnables any local MCP agent host to observe and operate a real Stardew Valley game through 28 tools covering world snapshots, screenshots, movement, inventory, menus, buying/shipping, containers, crafting, placing, fishing, combat and save loading. Writes run only through normal in-game flows under a single-writer control lease with ledger-based idempotency, epoch invalidation, fail-safe release on disconnect, and human takeover via web console or hotkey.1MIT