Arma Reforger MCP Server — Enfusion & Enforce Script Modding

Arma Reforger MCP is a local, security-focused Model Context Protocol server and Codex plugin for Arma Reforger modding, Enfusion Workbench, and Enforce Script development. It gives AI coding assistants project-aware tools for .gproj discovery, script analysis, resource GUID validation, log diagnosis, local API documentation search, guarded file editing, and Workbench automation.

English | Deutsch

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 two reusable 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

Related MCP server: enfusion-mcp

MCP capabilities

Resources are available at reforger://server/status, reforger://projects, and reforger://docs/official. The server also provides prompts for script review, failure diagnosis, and feature planning.

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

Install 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

Configure Codex as a plugin

The repository root is already a Codex plugin. Its .codex-plugin/plugin.json bundles the MCP server and both skills; .mcp.json launches the compiled server from dist/cli.js.

After cloning and building, add this repository to a local Codex marketplace or use it as a plugin source. Start a new Codex session after installing so the tools and skills are loaded.

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_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 flags --root, --log-dir, --docs-dir, and --workbench override their environment counterparts. Repeat flags to configure multiple roots.

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.

• 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 server_status and list_projects.

2. Inspect the target with inspect_project.

3. Search and read existing implementation patterns.

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

5. Analyze scripts and validate resources.

6. Preview writes with dryRun: true and expectedSha256.

7. Prepare a Workbench verification command with execute: false.

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

Development

npm ci
npm run check
npm run build
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.

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
skills/           # Bundled development and diagnosis workflows
tests/            # Unit, fixture, and MCP integration tests
docs/             # Architecture and research decisions

Read Architecture, Research, and Contributing before substantial changes.

Research basis

The implementation is derived from primary sources: the Bohemia Interactive Community Wiki, 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.