# reforge-mcp

An MCP server that answers questions about **Arma Reforger / Enfusion** from *your*
installation, and can optionally drive the Workbench editor.

MIT licensed. **No Bohemia content is redistributed** — every index is generated locally from
the game you already own, and stamped with the build it came from.

---

## Why this exists

Reforger's shipped API documentation is two engine versions behind, cannot be regenerated on
current Tools builds, and gets some core editor inheritance backwards — at least one class is
documented as inheriting from its own subclass. If you are writing anything non-trivial
against the engine, you are working from a map of a different country.

This server reads the game you actually have: the `.pak` archives, the resource database, the
live editor. When it answers, it tells you which build the answer came from.

It is useful on its own. It knows nothing about any particular mod.

---

## What it can do

**Read the engine** (default, no editor needed):

- `symbol_lookup` — a class or enum's real declaration, inheritance chain, members, methods,
  and what uses it
- `source_read` / `source_grep` — read one symbol or grep **inside the `.pak` archives**,
  where ordinary tools cannot look
- `guid_resolve` / `path_guid` / `resource_refs` — resolve resource GUIDs either way, and find
  who overrides, inherits from, or references a resource
- `config_merge_preview` — preview a same-GUID override *before* it silently replaces vanilla
  content
- `prefab_resolve` — a prefab's merged component set with each component's origin
- `addon_deps`, `version_info`, `capabilities`, `diagnose`

**Drive the editor** (opt-in, needs Workbench running):

- Live reads: editor state, entity list, resolved properties, layers, prefabs, resources
- Writes: create/modify/delete entities, edit components, layers, prefabs, scripts, string
  tables, and control the session
- `wb_inspect` — generic runtime reflection over live objects
- `wb_process` / `wb_dialogs` — start, close and restart the editor, and clear the modal
  dialogs that block its automation bridge

---

## Install

**Requirements:** Node.js 20+, Arma Reforger, Arma Reforger Tools (only for editor features).

```bash
git clone <this repo>
cd reforge-mcp
npm install
npm run build
```

Copy `reforge.config.example.json` to `reforge.config.json` and set your paths:

```json
{
  "profile": "research",
  "gamePath": "C:\\Program Files (x86)\\Steam\\steamapps\\common\\Arma Reforger",
  "toolsPath": "C:\\Program Files (x86)\\Steam\\steamapps\\common\\Arma Reforger Tools",
  "steamAppsPath": "C:\\Program Files (x86)\\Steam\\steamapps",
  "projectPath": "C:\\Users\\<you>\\Documents\\My Games\\ArmaReforgerWorkbench\\addons",
  "roots": []
}
```

Build the indexes (a few seconds — they come from your install, not from us):

```bash
npx reforge index build
```

Register it with your MCP client as a stdio server running `node dist/index.js`.

Check it came up:

```bash
npx reforge diagnose
```

---

## Profiles — read this before enabling writes

The server ships in **`research`** mode. In that mode the write tools **do not exist**: they
are absent from the tool list, not merely disabled. An assistant driving the server cannot
see, name, or attempt a capability it has not been granted.

```json
{ "profile": "research" }    // default — 22 tools, 0 writers, no editor needed
{ "profile": "workbench" }   // opt-in  — 68 tools, 33 writers, drives your editor
```

**Switching to `workbench` is a real decision.** It lets the server modify files in the mod
roots you declare, and change a live editor session. Read `WARNINGS.md` first.

---

## What is not in this repository, and why

**No indexes.** The `data/` directory is absent on purpose. Indexes are derived from *your*
Bohemia installation, so shipping them would be redistributing game content. Run
`npx reforge index build`; it takes seconds.

**One shared addon GUID.** `workbench-addon/addon.gproj` ships a real, collision-checked GUID
(`97A138F130D5D9BA`) so it works out of the box. Enfusion identifies addons by GUID and
collisions are **silent**, so if you fork this and intend to distribute your fork, mint your
own 16-character uppercase hex GUID rather than shipping two different addons claiming the
same identity. Using it unmodified, locally, is fine.

**No knowledge base.** `kb_search` ships, but the distilled `kb/` corpus does not — its
licensing needs review before redistribution. The tool degrades quietly: it warns that the
index is missing and answers nothing, rather than failing.

**No experiment runner.** `exp_run` exists upstream but is tied to one specific framework's
validation plan and its instrumented components. It is not a general Enfusion capability, so
it is not here.

---

## The other half: handlers

The editor features need a small addon installed into Workbench. Workbench ships a network
listener but **no functions** — a handler is a script class that says "when this request
arrives, run this inside the editor and send this back". Without the addon, every `wb_*` tool
fails to connect; everything else still works.

See `HANDLERS.md` for what they are, how to install them, and why they are a separate addon.

---

## Documentation

| File | What is in it |
|---|---|
| `USAGE.md` | Configuration, profiles, roots, worked examples |
| `API.md` | Every tool, by tier, with what it actually guarantees |
| `HANDLERS.md` | The Workbench addon: installing, extending, and how it fails |
| `WARNINGS.md` | **Precautions. Read before enabling the `workbench` profile.** |

---

## Design commitments

These are the things the server will not do, and they are enforced in code rather than
documented as intentions:

- **It never publishes.** There is no Workshop upload tool, no publish tool, and a test that
  fails if one is ever added.
- **It answers with a build stamp.** Every index records which game build it was generated
  from, so a stale answer says so instead of being quietly wrong.
- **Writes are dry-run by default**, return a real diff, and need a single-use plan id to
  apply.
- **Reversibility is claimed per operation, never per tool.** Operations that cannot be undone
  record no inverse and say so — a fabricated undo that looks like a restore is worse than
  none.
- **Allowlists, never blocklists**, for menu actions and for read-only enforcement.

## Licence

MIT. See `LICENSE`.

Arma Reforger and Enfusion are trademarks of Bohemia Interactive. This project is not
affiliated with or endorsed by Bohemia Interactive. It redistributes no game content.