a3ref MCP server

a3ref MCP server — Arma 3 SQF reference and linter for AI agents

Gives Claude, Cursor, VS Code Copilot and any other MCP client the complete Arma 3 scripting reference — every scripting command, every BIS_fnc_* function and the core concept pages (data types, locality, scheduler, event handlers) — mirrored daily from the Bohemia Interactive Community Wiki by a3ref, plus a static checker that catches the mistakes models make most in SQF.

Tool	What it does
search	Find commands, functions, event handlers and topics by name, partial name, operator symbol (>>, !=) or by what they do ("delete vehicle")
get	Read a page: syntax, typed parameters, return value, locality, examples, community notes. Any spelling works (SETPOS, spawnGroup, bis fnc spawngroup); an event handler's name (AnimStateChanged, Draw3D, onLoad) returns its section; section returns one part of a long topic; very long topics return their outline
list_group	Everything in a command or function group ("Multiplayer", "Object Manipulation", ...)
lint_sqf	Check SQF: made-up commands, commands used without their left operand or argument, unknown BIS_fnc_* functions, deprecated or broken commands, diagnostic-build-only commands, format strings missing values, unknown event handler names
recent_changes	What changed on the wiki recently

Example lint_sqf output:

Checked 3 lines: 2 errors, 1 warnings, 0 notes.

1:8 error: Unknown command setUnitHealth (used as a binary command).
2:1 error: setPos needs a left operand. Syntax: `object setPos pos`.
3:4 warning: ctrlSetEventHandler is deprecated. Use ctrlAddEventHandler instead.

The linter only reports what cannot be valid SQF, so it stays quiet on correct code: run over the 5,500 SQF examples on the wiki it reports 23 errors, nearly all of them config or prose pasted into code blocks. The format and event handler checks follow HEMTT's L-S08 and L-S02.

Install

Requires Node.js 18 or newer. The server is a single file with no dependencies to install. Step-by-step instructions for every client: https://wiki.arma3.io/mcp.html

Claude Code (plugin: MCP server + skill)

/plugin marketplace add a3ref/mcp
/plugin install a3ref@a3ref

The plugin also adds the sqf skill, which tells Claude to check commands and lint SQF before showing it.

Claude Code (server only)

claude mcp add a3ref -- npx -y a3ref-mcp

Codex (plugin: MCP server + skill)

codex plugin marketplace add a3ref/mcp
codex plugin add a3ref@a3ref

Or, after adding the marketplace, install a3ref from the Plugins directory of the ChatGPT desktop app. The CLI, the IDE extension and the app share the plugin. Server only: codex mcp add a3ref -- npx -y a3ref-mcp.

Antigravity (plugin: MCP server + skill)

agy plugin install https://github.com/a3ref/mcp

Plugins installed with the CLI or the Antigravity app are available in the app, the IDE and the CLI.

OpenCode

~/.config/opencode/opencode.json (or opencode.json in a project):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "a3ref": {
      "type": "local",
      "command": ["npx", "-y", "a3ref-mcp"],
      "enabled": true
    }
  }
}

For the skill as well, save skills/sqf/SKILL.md as ~/.config/opencode/skills/sqf/SKILL.md.

Claude Desktop, Cursor, Windsurf and other clients

{
  "mcpServers": {
    "a3ref": {
      "command": "npx",
      "args": ["-y", "a3ref-mcp"]
    }
  }
}

Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; Windsurf: ~/.codeium/windsurf/mcp_config.json.

VS Code (Copilot agent mode)

.vscode/mcp.json:

{
  "servers": {
    "a3ref": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "a3ref-mcp"]
    }
  }
}

How it works

The server downloads what it needs from https://wiki.arma3.io/ (index.json, syntax.json and the pages you ask for) and keeps it in memory for an hour. Nothing is bundled, so answers follow the wiki without updating the server. Set A3REF_BASE_URL to use another copy of the site.

The data comes from a3ref/data; the site and the parser live in a3ref/a3ref.github.io. No MCP client? Every page is also plain Markdown and JSON, see https://wiki.arma3.io/llms.txt.

Development

npm install
npm test          # unit tests, offline
npm run build     # bundles src/ into dist/a3ref-mcp.mjs (committed, so npx and the plugin need no install)
npm run smoke     # starts the bundle and calls every tool against the live site

dist/ must be rebuilt and committed with every change to src/; CI checks that it is up to date. AI agents working on the code: see AGENTS.md (layout, rules, how to verify a change).

Content of the reference belongs to the authors of the BI Community Wiki. The code in this repository is MIT licensed.