factorio-player-mcp
# factorio-player-mcp
An MCP control layer for one dedicated, connected Factorio player.
The project measures gameplay through a constrained interface; it is not a
general RCON or Lua automation server. The agent-facing API will expose only
typed, legal player actions and bounded local observations. It will not expose
arbitrary Lua/RCON, teleportation, item spawning, direct entity mutation,
forced research, evaluator state, or full-map dumps.
## Current status
The version 1 contract is defined. The repository contains an initial Factorio
mod and stdio MCP bootstrap for bounded actor observation and native crafting.
It is not benchmark-valid yet.
- Public policy: [`docs/CONTRACT.md`](docs/CONTRACT.md)
- Machine-readable capability manifest:
[`contracts/capability-manifest.v1.json`](contracts/capability-manifest.v1.json)
- Response schemas: [`contracts/`](contracts/)
- FactoMCP adaptation boundary:
[`docs/FACTOMCP_ADAPTATION.md`](docs/FACTOMCP_ADAPTATION.md)
## Development checks
The contract checks use only the Python standard library:
python3 -m unittest discover -s tests -v
These tests guard the public allow-list, forbidden capabilities, dedicated
player identity policy, bounded observations, action-result fields, and
versioned response schemas.
## Host MCP bootstrap
The current stdio MCP server exposes only `observe_actor`, `observe_local`,
`craft`, `wait`, `move`, `mine`, `place`, `rotate`, and `interact_inventory`.
requires the Factorio mod to be installed and the game to be running with RCON
enabled. The RCON password belongs only in the host-side MCP process; do not
provide it to an agent.
uv sync
FACTORIO_RCON_HOST=127.0.0.1 \
FACTORIO_RCON_PORT=25575 \
FACTORIO_RCON_PASSWORD=replace-me \
uv run factorio-player-mcp
See [`mcp.json.example`](mcp.json.example) for a client configuration template.
TDQS
Scored across 6 tools
observe_actor and observe_local are the only pair with potential overlap, but their descriptions clearly distinguish full player state from nearby entities. The action tools (craft, wait, move, mine) each target a distinct operation.
Two observation tools use a consistent verb_noun pattern (observe_actor, observe_local), while the remaining four are bare verbs (craft, wait, move, mine). This is a minor deviation from a single convention but remains readable and predictable.
Six tools is a well-scoped minimum for basic player control: observe (global/local), act (move, mine, craft), and wait. Each tool earns its place without redundancy.
Core locomotion, mining, crafting, and observation are covered, but major Factorio player operations are absent: placing/removing buildings, inventory management, attacking, and interacting with entities. These gaps would block common agent workflows beyond simple resource gathering.