<p align="center"> <img src="assets/banner.svg" alt="Arma Reforger MCP Server for Enfusion and Enforce Script modding" width="100%"> </p>

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

[!IMPORTANT] Static analysis is intentionally conservative and heuristic. Enfusion Workbench remains the final compiler, importer, resource database, and runtime validator.

[!WARNING] Windows/Workbench support is currently Beta and available for public testing. The Windows CI matrix and a real Workbench compatibility preflight pass, while native-Windows hardware acceptance remains pending. If something fails, please open a Windows/Workbench bug report so the maintainer can reproduce and fix it.

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

MCP capabilities

Tool	Purpose	Side effects
doctor	Diagnose runtime, paths, Workbench, limits, and cache	None
server_status	Show configuration, path availability, and safety gates	None
list_projects	Discover and parse .gproj addons	None
get_mod_development_standard	Return the versioned mod structure and engineering rules	None
inspect_project	Inventory assets, dependencies, and structure compliance	None
audit_mod_structure	Audit official or enterprise addon-structure rules	None
read_project_file	Read bounded text ranges with SHA-256	None
search_workspace	Literal search across scripts and Enfusion text resources	None
validate_resources	Check .meta, duplicate GUIDs, paths, and local references	None
analyze_enforce_script	Run documented convention/performance heuristics	None
generate_script_template	Generate tagged, bilingual Enforce Script skeletons	None
inspect_logs	Group actionable Workbench/game errors	None
search_official_docs	Search a curated primary-source catalog	None
search_local_api	Search installed Arma Reforger and Enfusion Doxygen HTML	None
write_project_file	Dry-run or atomically write approved text resources	Opt-in
inspect_layout	Inspect widget declarations and local resource references	None
export_layout_bundle	Export a layout, metadata, and local source dependencies	Opt-in
inspect_source_archive	Inventory a source ZIP and reject traversal/ZIP-bomb risks	None
extract_source_archive	Extract an authorized source ZIP below a configured root	Opt-in
export_project_archive	Export editable addon source with a JSON manifest	Opt-in
install_workbench_bridge	Install the bundled read-only NET API bridge source	Opt-in
workbench_status	Query live Workbench, compiler, and World Editor state	None
workbench_validate_scripts	Compile a script configuration in live Workbench	None
workbench_open_resource	Open a mounted resource in Workbench	Opt-in
workbench_focus_module	Focus an allowlisted Workbench editor module	Opt-in
workbench_bridge_call	Query bridge info, mounted resources, or World Editor state	Opt-in
workbench_custom_call	Call a verified custom NetApiHandler contract	Opt-in
workbench_command	Prepare or launch an allowlisted Workbench command	Opt-in

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.

Variable	Default	Description
ARMA_REFORGER_PROJECT_ROOTS	Workbench addon folder on Windows	Semicolon-separated allowed project roots
ARMA_REFORGER_LOG_DIRS	Workbench and game log folders on Windows	Semicolon-separated read-only log roots
ARMA_REFORGER_DOCS_DIR	None	Semicolon-separated local Workbench Doxygen roots
ARMA_REFORGER_ARCHIVE_ROOTS	Project roots	Allowed ordinary source-ZIP roots
ARMA_REFORGER_EXPORT_DIR	None	Existing directory for generated source ZIPs
ARMA_REFORGER_WORKBENCH_PATH	None	Absolute Workbench executable
ARMA_REFORGER_WORKBENCH_ADDON_DIRS	Matching Steam-library game data	Semicolon-separated dependency addon roots
ARMA_REFORGER_ALLOW_WRITES	false	Enable non-dry-run project writes
ARMA_REFORGER_ALLOW_PROCESS_EXECUTION	false	Enable Workbench launch
ARMA_REFORGER_ALLOW_ARCHIVE_OPERATIONS	false	Enable source ZIP extraction/export
ARMA_REFORGER_ALLOW_WORKBENCH_ACTIONS	false	Enable UI/custom NET API actions
ARMA_REFORGER_NET_API_HOST	127.0.0.1	Loopback host only
ARMA_REFORGER_NET_API_PORTS	5775,5700	Ordered ports to probe
ARMA_REFORGER_NET_API_TIMEOUT_MS	5000	Timeout per NET API attempt
ARMA_REFORGER_MAX_FILE_BYTES	2097152	Per-file read/write safety limit
ARMA_REFORGER_MAX_SEARCH_RESULTS	100	Default search result limit
ARMA_REFORGER_MAX_TRAVERSAL_DEPTH	12	Maximum recursive directory depth
ARMA_REFORGER_MAX_ARCHIVE_ENTRIES	10000	Maximum files accepted in a source ZIP
ARMA_REFORGER_MAX_ARCHIVE_EXPANDED_BYTES	1073741824	Maximum declared expanded ZIP size
ARMA_REFORGER_MAX_INDEXED_FILES	50000	Maximum files traversed by one project operation
ARMA_REFORGER_OPERATION_TIMEOUT_MS	60000	Maximum duration of one MCP tool request
ARMA_REFORGER_PROJECT_CACHE_TTL_MS	5000	Project-discovery cache lifetime
ARMA_REFORGER_OBSERVABILITY_LEVEL	info	Structured stderr logs: silent/error/info/debug

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.

[!WARNING] Published Workshop data is compressed, indexed, and protected and cannot be reconstructed into editable source. Archive tools support only ordinary source ZIPs that you own or may modify.

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.