Arma Reforger MCP Server — Enfusion & Enforce Script Modding

Arma Reforger MCP is a local, security-focused Model Context Protocol server and native Claude Code + Codex plugin for Arma Reforger modding, Enfusion Workbench automation, Enforce Script, UI layouts, and editable source bundles. It combines offline project intelligence with the official loopback Workbench NET API and a bundled, auditable NetApiHandler bridge.

English | Deutsch | Changelog

Why this MCP exists

Generic filesystem tools do not understand Enfusion projects. This server models the parts that matter when an Arma Reforger addon fails:

• .gproj IDs, GUIDs, configurations, and dependency GUIDs

• valid Enforce Script modules below Scripts/

• creator-tag and Enfusion style conventions

• .meta ownership, duplicate GUIDs, and {GUID}path references

• Workbench/game log categories and likely remediation

• the local Doxygen API shipped with Arma Reforger Tools

• safe Workbench command construction without shell execution

The repository also packages three reusable Claude/Codex skills:

• $develop-arma-reforger-mod — inspect, research, implement, review, and verify addon changes

• $diagnose-arma-reforger-mod — trace project, dependency, script, resource, replication, and runtime failures

• $control-arma-reforger-workbench — safely orchestrate live Workbench, layout, bridge, and source-bundle operations

Related MCP server: enfusion-mcp

MCP capabilities

Resources are available at reforger://contracts/v1, reforger://server/status, reforger://projects, reforger://standards/mod-development, reforger://docs/official, and reforger://workbench/capabilities. The versioned contract resource fixes the advertised tool, resource, prompt, result-metadata, and error-envelope shapes for compatibility review. Prompts cover script review, failure diagnosis, standards-aware feature planning, and safe Workbench control.

Professional mod structure and rules

get_mod_development_standard exposes the complete bilingual, versioned standard. It distinguishes hard engine requirements, official Bohemia guidelines, and this MCP's enterprise engineering policy so advisory preferences are never mislabeled as compiler facts. audit_mod_structure accepts official and enterprise profiles; inspect_project includes the enterprise audit by default.

The addon layout is content-driven. Only the project descriptor is universal; create conditional areas only when the addon owns that concern:

<AddonName>/
|-- <AddonName>.gproj
|-- Scripts/Game/<TAG>/<Feature>/
|-- Scripts/WorkbenchGame/<TAG>/<Editor>/
|-- Configs/<TAG>/<Feature>/
|-- Prefabs/<TAG>/<Feature>/
|-- UI/<TAG>/<Feature>/{Layouts,Imagesets,Textures}/
|-- Assets/<Domain>/<TAG>/<Feature>/
|-- Worlds/<TAG>/<World>/
\-- Sounds/<TAG>/<Feature>/

For larger teams, keep CI, repository-side tests, architecture/runbook documentation, tooling, contribution/security policy, changelog, and license in a repository wrapper outside the publishable addon tree when practical. The standard also defines reviewable gates for architecture, verified APIs, GUID integrity, multiplayer authority/JIP, security boundaries, measured performance, regression evidence, CI, release/rollback, provenance, and ownership.

Quick start

Requirements

• Node.js 20.19 or newer

• npm 10 or newer

• Arma Reforger Tools for Workbench execution and local Doxygen API search

• A local Arma Reforger addon source directory containing a .gproj

Clean end-user download

For normal use, download the *-standalone.zip asset from GitHub Releases. It contains the single bundled MCP runtime, plugin manifests, skills, essential documentation, and the Workbench bridge. Extract it and run node dist/cli.js --version; no dependency, build, or test installation is required.

Release automation rejects tests, fixtures, source files, E2E tools, source maps, coverage, logs, local configuration, generated databases, and temporary files in the published package. Developer clones intentionally retain tests and CI as quality evidence, while generated Git archives exclude test/E2E directories. Each release also publishes a CycloneDX SBOM and SHA256SUMS; GitHub stores keyless Sigstore attestations for SLSA build provenance and the SBOM. Verify downloads with sha256sum --check SHA256SUMS and gh attestation verify <artifact> -R maxionice/arma-reforger-mcp.

Developer installation from GitHub

git clone https://github.com/maxionice/arma-reforger-mcp.git
cd arma-reforger-mcp
npm ci
npm run build

Smoke-test the CLI:

node dist/cli.js --help
node dist/cli.js --version

Use as a Codex plugin

The repository root is a Codex plugin. .codex-plugin/plugin.json bundles the MCP server and all skills through Codex's native inline MCP server map.

Use either the extracted standalone release or a locally built clone as the plugin source. Start a new Codex session after installing so the tools and skills are loaded.

Use as a Claude Code plugin

Claude Code reads .claude-plugin/plugin.json, its root .mcp.json, and the same skills/ directory:

claude plugin validate . --strict
claude --plugin-dir .

Restart the development session or run /reload-plugins after replacing/rebuilding the package. Both clients receive identical MCP tools and bilingual workflows; only their native plugin manifest differs.

Configure a standalone MCP client

Use an absolute server path and configure at least one addon root:

{
  "mcpServers": {
    "arma-reforger": {
      "command": "node",
      "args": ["C:/Tools/arma-reforger-mcp/dist/cli.js"],
      "env": {
        "ARMA_REFORGER_PROJECT_ROOTS": "C:/Users/you/Documents/My Games/ArmaReforgerWorkbench/addons",
        "ARMA_REFORGER_ARCHIVE_ROOTS": "C:/Users/you/ArmaSourceArchives",
        "ARMA_REFORGER_EXPORT_DIR": "C:/Users/you/ArmaExports",
        "ARMA_REFORGER_DOCS_DIR": "C:/Program Files (x86)/Steam/steamapps/common/Arma Reforger Tools/Workbench/docs",
        "ARMA_REFORGER_LOG_DIRS": "C:/Users/you/Documents/My Games/ArmaReforgerWorkbench/logs;C:/Users/you/Documents/My Games/ArmaReforger/logs"
      }
    }
  }
}

For Codex config.toml, the equivalent standalone configuration is:

[mcp_servers.arma-reforger]
command = "node"
args = ["C:/Tools/arma-reforger-mcp/dist/cli.js"]

[mcp_servers.arma-reforger.env]
ARMA_REFORGER_PROJECT_ROOTS = "C:/Users/you/Documents/My Games/ArmaReforgerWorkbench/addons"
ARMA_REFORGER_DOCS_DIR = "C:/Program Files (x86)/Steam/steamapps/common/Arma Reforger Tools/Workbench/docs"
ARMA_REFORGER_LOG_DIRS = "C:/Users/you/Documents/My Games/ArmaReforgerWorkbench/logs;C:/Users/you/Documents/My Games/ArmaReforger/logs"

Configuration

Copy .env.example as a reference. The server reads environment variables from its parent MCP client; it does not load .env automatically.

CLI equivalents include --archive-root, --export-dir, --workbench-addon-dir, --net-api-port, --allow-archive-operations, and --allow-workbench-actions. Run node dist/cli.js --help for the complete list.

Live Workbench control

1. In Workbench, check File → Options → General → Net API → Enabled.

2. Configure the local port if your Workbench build differs from the probed defaults.

3. Call workbench_status; then use focused operations such as workbench_validate_scripts or workbench_open_resource.

4. For mounted-resource discovery and World Editor snapshots, preview and install workbench/ARM_MCPWorkbenchBridge.c with install_workbench_bridge, reload scripts, and call workbench_bridge_call.

5. Extend control with your own audited NetApiHandler, then call it through workbench_custom_call. This is deliberately gated because handler side effects are project-defined.

The server controls documented NET API and CLI surfaces; it does not perform brittle mouse/keyboard automation. Complete project-specific automation is achieved by adding typed Workbench handlers or command-line plugins, not by exposing arbitrary shell access.

Safety model

• Every project read/write is confined to canonical configured roots.

• Symlinks are skipped during traversal, and resolved paths are checked again.

• Writes default to dryRun: true, support optimistic SHA-256 concurrency checks, restrict extensions, and use an atomic same-directory rename.

• Writes require ARMA_REFORGER_ALLOW_WRITES=true or --allow-writes.

• Workbench launch requires both a validated executable name and ARMA_REFORGER_ALLOW_PROCESS_EXECUTION=true or --allow-process-execution.

• Live NET API access is loopback-only; UI/custom calls require a separate Workbench-action gate.

• ZIP inspection rejects absolute/traversal paths, backslashes, symlinks, encryption, excessive entry counts, and excessive expanded size.

• Actual extraction/export requires both write and archive gates. Extraction additionally requires an explicit source-rights acknowledgement.

• Workbench is spawned with shell: false; the MCP never exposes arbitrary command execution.

• MCP protocol traffic uses stdout. Diagnostics use stderr so JSON-RPC cannot be corrupted.

See SECURITY.md for the trust boundary and reporting process.

Recommended workflow

1. Run doctor, then server_status and list_projects.

2. Read the relevant get_mod_development_standard sections and run audit_mod_structure.

3. Inspect the target with inspect_project.

4. Search and read existing implementation patterns.

5. Verify unknown APIs against local Doxygen or official documentation.

6. Analyze scripts and validate resources.

7. Preview writes with dryRun: true and expectedSha256.

8. Call workbench_status and workbench_validate_scripts, or prepare a Workbench command with execute: false when offline.

9. Inspect layouts and preview exports/extractions before enabling their gates.

10. Compile/reload and test in the matching stable or experimental Workbench branch.

Development

npm ci
npm run check
npm run build
npm run verify:package
npm pack --dry-run

The test suite covers parsers, Enforce Script heuristics, GUID/resource validation, log classification, path confinement, project discovery, and an end-to-end MCP client/server call.

Real Workbench validation is deliberately separate because it requires licensed native-Windows tooling and a genuine addon. The package includes an original, writable acceptance addon template; prepare it without overwriting existing sources with node dist/e2e/cli.js --prepare-addon <absolute-new-directory>. The E2E CLI reads Steam's libraryfolders.vdf, auto-detects stable or experimental Tools and matching game data across separate libraries, and still accepts explicit paths for non-standard layouts. Native Windows is enforced by default, while --allow-compatibility-layer permits a clearly classified Wine/Proton preflight that never counts as production evidence. Follow the bilingual Windows E2E runbook or dispatch the self-hosted Real Workbench E2E workflow. A redacted evidence report is generated for every completed real run.

src/
├── domain/       # Enfusion-aware parsers and analyzers
├── security/     # Canonical project-root confinement
├── services/     # Files, projects, docs, logs, writes, Workbench
├── shared/       # Bilingual result and utility types
├── server.ts     # MCP tools, resources, and prompts
└── cli.ts        # stdio entry point
workbench/        # Bilingual bridge plus reproducible real E2E addon template
skills/           # Development, diagnosis, and Workbench-control workflows
.codex-plugin/    # Native Codex manifest
.claude-plugin/   # Native Claude Code manifest
.mcp.json         # Claude Code bundled MCP launch definition
tests/            # Unit, fixture, and MCP integration tests
docs/             # Architecture and research decisions

Read Architecture, Research, Windows E2E, and Contributing before substantial changes.

Research basis

The implementation is derived from primary sources: the Bohemia Interactive Community Wiki, the official Workbench NET API, the official Arma Reforger samples, the generated Arma Reforger Script API, and the official MCP TypeScript SDK. The exact findings and design consequences are recorded in docs/RESEARCH.md.

Trademark and affiliation

This is an independent open-source project and is not affiliated with or endorsed by Bohemia Interactive. Arma Reforger, Enfusion, and related marks belong to their respective owners. Do not copy Bohemia Interactive game data or sample assets into this repository; follow the applicable Bohemia Interactive licenses.

License

The MCP implementation is available under the MIT License.