# Factorio MCP Bridge

M0 is a working, tested integration checkpoint for **Factorio 2.0.77 on Windows**. A Lua mod answers bounded JSON commands over loopback RCON; one shared TypeScript daemon serves MCP clients over stdio and authenticated Streamable HTTP.

The bounded M1 read-only checkpoint now passes live spatial, inventory, diagnostic, cache, isolation, and reload acceptance tests. Broader specification features remain deferred. See [the M1 checkpoint guide](docs/m1-checkpoint.md). Gameplay mutations, plans, construction, and jobs remain unavailable.

## Reproduce the checkpoint

Use Node **24.19.0** and Python **3.11+**. In PowerShell:

```powershell
npm ci
python -m venv .venv
.venv/Scripts/python.exe -m pip install -r requirements-test.txt
npm run checkpoint:m0
```

The live runner defaults to `C:/Steam/steamapps/common/Factorio/bin/x64/Factorio.exe`. Set `FACTORIO_EXECUTABLE` and optionally `FACTORIO_RUNTIME_API` for another installation. It requires matching 2.0.77 runtime documentation.

Every run creates a **new** `.fmcp/live/<run>/` directory with separate game configuration, mods, and saves. It disables public/LAN discovery, binds game/RCON/daemon sockets to loopback, and stops its processes on completion. It never installs into your normal mod directory or opens an existing user save. Temporary test credentials stay in ignored local files; do not publish `.fmcp/`.

| Command | Purpose |
|---|---|
| `npm run check` | Generate contracts, typecheck, validate specification fixtures, run unit/protocol tests, build |
| `npm run test:live` | Exercise the previously built CLI/mod against an isolated real server |
| `npm.cmd run checkpoint:m1` | Validate the bounded read slice using a copy of the running charted development world |
| `npm run checkpoint:m0` | Run the complete checkpoint and record compatibility/test status |
| `npm.cmd run dev:world` | Build, run the live checkpoint, then leave the disposable world running for manual MCP testing |
| `npm run format:check` | Check source formatting |

`dev:world` prints a ready-to-copy stdio command with an explicit local configuration path. Keep that terminal open; press Ctrl+C to stop the test world and daemon. Do not run two checkpoint processes concurrently because they both update the latest report.

Outputs are `dist/cli.js`, `dist/factorio-mcp-bridge_0.2.1.zip`, and the unpacked mod under `dist/mod/`. The CLI bundles all non-Node runtime dependencies. Mod ZIP entries have fixed ordering and timestamps. Live reports are written to `artifacts/live-latest.json` and the individual run directory.

## Read next

- [Checkpoint guide](docs/checkpoints.md): test layers, manual app scenario, and milestone gates.
- [Compatibility](docs/compatibility.md) and [recorded versions](compatibility.json): exact tested lanes and limits.
- [Limitations](docs/limitations.md): what this checkpoint does and does not implement.
- [Client templates](clients/README.md): the same bundled CLI for each client.
- [Development installation](docs/development-install.md): source-linked MCP and skill setup for Codex.
- [Specification](SPECIFICATION.md): architecture and milestone contract.
- [Progress](PROGRESS.md): completed work, actual commands, and next milestone.

The seven canonical tool definitions remain stable in [the tool schema catalog](schemas/mcp-tools.json). Effective discovery includes the tested integration, recipe, research, and production paths when an operator policy is configured. The bounded spatial, inventory, resource, artifact, and observation operations are now tested and advertised. Deferred tools return `CAPABILITY_UNAVAILABLE`, never simulated factory results.

The [operator skill](skills/factorio-operator/SKILL.md) and [workflow examples](examples/tool-calls.json) describe later operation flows as well; discover effective capabilities before using them. The [original handoff validation](VALIDATION.md) describes static specification fixtures, while [checkpoint test status](docs/test-status.json) records the implemented M0 lane.

Version 0.2.1 adds bounded, scoped event history through `query.events`; see the [event contract](docs/m1-checkpoint.md#event-history-021).