Enfusion MCP

A Python Model Context Protocol server for Arma Reforger Enfusion Workbench. Inspect the editor, read world context, and prepare deterministic vegetation placements through an MCP client.

The target addon and world are configured explicitly. No particular map, project name, or author-specific filesystem layout is required.

Status: alpha (0.1.0a0). The Python server, planner, coordination layer, and staged Enforce bridge are implemented. The production vegetation catalog is empty and a separate bridge mutation gate is disabled. Live vegetation planning and creation therefore remain unavailable until the catalog and bridge have been validated in Workbench. See current limitations.

What it provides

The server exposes these five tools over STDIO. It does not require an LLM API key: the MCP client supplies the assistant and manages its own credentials.

MCP client
    │ STDIO
    ▼
Python server on Linux ── SQLite ledger + process lock
    │ loopback NET API
    ▼
Enfusion Workbench through Proton
    └── EnfusionMCP bridge in your addon

Related MCP server: Enfusion Workbench MCP

Requirements

• Linux and Python 3.11 or newer.

• uv for the locked development environment.

• Arma Reforger Tools / Enfusion Workbench, launched manually through Steam/Proton, for editor integration.

• An MCP client that can launch a local STDIO process.

The supported runtime profile is native-linux-proton. Windows-native and remote Workbench connections are not implemented. Workbench is not needed to run the Python tests.

Getting started

1. Install from a source checkout

git clone https://github.com/jecacs/enfusion-mcp.git
cd enfusion-mcp
uv sync --frozen

This installs the enfusion-mcp executable in .venv/bin/ and the development tools in the same virtual environment.

2. Configure your addon and world

All ten variables below are required. The server reads the process environment; it does not load .env files or infer the target from the currently open map.

Example environment, with placeholders to replace with your own paths and world resource:

export ENFUSION_PLATFORM_MODE='native-linux-proton'
export ENFUSION_STEAM_TOOLS_APP_ID='1874910'
export ENFUSION_PROTON_PREFIX='/path/to/proton-prefix'
export ENFUSION_WORKBENCH_HOST='127.0.0.1'
export ENFUSION_WORKBENCH_PORT='5775'
export ENFUSION_PROJECT_HOST_PATH='/path/to/proton-prefix/drive_c/path/to/addon'
export ENFUSION_PROJECT_ENGINE_PATH='C:\path\to\addon'
export ENFUSION_ALLOWED_WORLD='$myaddon:world.ent'
export ENFUSION_SAFE_MODE='1'
export ENFUSION_STATE_DIR='/path/to/enfusion-mcp/.state'

The example path pair assumes dosdevices/c: points to the prefix's drive_c. Use the real mapping for your installation. Quote world resource names in the shell so $ is preserved. Resource identifiers are compared exactly; an alias and a GUID representation are not treated as interchangeable.

Each server process targets one configured world. To use another map, change the project paths and world resource as needed, then restart the process. Processes targeting the same Workbench endpoint must share the same state directory, even when their configured maps differ.

See Linux/Proton paths for mapping details and coordination for shared state requirements.

3. Prepare the Workbench bridge

World context, terrain sampling, and vegetation operations use the three handlers in bridge/Scripts/WorkbenchGame/EnfusionMCP/. The Python installer does not copy them into an addon or start Workbench.

Follow the bridge installation and validation procedure for your chosen addon. Start Workbench manually, open the configured world, and validate the handlers before using the editor integration. Installing the staged bridge does not enable vegetation creation.

4. Connect an MCP client

Configure your client to launch the absolute path to /path/to/enfusion-mcp/.venv/bin/enfusion-mcp with the environment above. Use the complete generic STDIO configuration, or the examples for Codex, Claude Code, and other local hosts.

Start with workbench_status, then world_context and vegetation_catalog. The shipped catalog reports production_ready: false; this is expected.

Vegetation workflow

Once a verified catalog and a validated bridge revision are available:

1. Open the configured world and manually create or select MCP_Preview or MCP_Vegetation as the target layer.

2. Select one closed, polygon-compatible shape outlining the placement area.

3. Inspect world_context and choose prefabs from vegetation_catalog.

4. Call vegetation_plan with a seed, count, spacing, slope, scale range, and weighted palette. Review the resulting placements and rejection statistics.

5. Call vegetation_apply with the returned plan_id and a UUID idempotency key. Keep that same key when checking an uncertain result.

6. Inspect the result in Workbench and save manually if desired.

Plans expire after 30 minutes. The intended editor operation is one undoable batch; a single Ctrl+Z still requires live acceptance testing. Detailed inputs, determinism guarantees, and retry behavior are documented in the vegetation workflow.

Safety and current limitations

The server validates the configured world, project path mapping, catalog, stored plan, and bridge identity. The bridge also checks that the requested world and subscene match the editor before inspecting or creating a batch. Selecting a different map cannot silently retarget an existing plan.

• Connections are restricted to literal 127.0.0.1:5775.

• The server never launches Steam, Proton, Workbench, a shell, or a model API.

• Mutations are serialized across processes using a shared SQLite ledger and Linux file lock. Uncertain outcomes are reconciled before further creation.

• Tools expose no arbitrary script execution, endpoint forwarding, prefab spawning, automatic layer creation, or world saving.

• STDIO protocol output goes to stdout; diagnostics go to stderr.

The production catalog is deliberately empty, and MUTATION_IMPLEMENTATION_VALIDATED remains false. Enforce source contracts are checked by Python tests, but handler compilation, engine decoding, transforms, rollback, and Undo still need live Workbench validation. Map configuration support does not imply every addon or prefab has been tested.

For the detailed boundaries, see safe mode, threat model, and bridge evidence.

Development

uv sync --frozen
uv run ruff format --check .
uv run ruff check .
uv run mypy
uv run pytest
uv build --no-build-isolation
uv run twine check dist/*

Tests cover configuration, Proton path containment, NET API framing, STDIO contracts, deterministic geometry, persistent coordination, and static bridge contracts. They use temporary projects and fake Workbench endpoints.

The wheel contains the Python runtime and license notices. Bridge sources and the full documentation are included in the source distribution. See architecture and NET API protocol for implementation details. Earlier development evidence is retained in the implementation history.

When upgrading an earlier installation, resolve outstanding operations first, run uv sync --frozen, and update the client executable and all bridge handlers to the matching revision. Package, handler, and protocol identifiers have been generalized; old plans and entity names are not migrated. Keep the operation ledger if any result is unresolved.

License

MIT. Upstream attribution and adapted integration patterns are documented in NOTICE.md.