Skip to main content
Glama
@wrathbench/mcp

@wrathbench/mcp

by Shard

wrath-mcp

A client-equivalent agent surface over a stock AzerothCore (World of Warcraft 3.3.5a): packets, not pixels. It gives an agent a game client's eyes and hands on a live character, and nothing a client would not have. Every action goes in as the client opcode a real client would send, through the same server handler, and every observation is a packet the server would send that client.

Four pieces:

Path

What it is

module/

mod-wrathbench, the C++ AzerothCore module. A thin packet bridge and event tap over HTTP and WebSocket inside the worldserver. Its wire is module/PROTOCOL.md.

sdk/

@wrathbench/sdk, the typed Bun/TypeScript client over that wire: the event stream, the state cache, the helpers and their per-call hints. sdk/API.md is the generated per-method reference an agent reads.

mcp/

@wrathbench/mcp, the agent surface over the SDK: a confined, persistent snippet sandbox holding one client, an MCP server, the core tools run_snippet, recent_events, state_summary, write_scratchpad and edit_scratchpad, and the session record every session leaves.

inspector/

@wrathbench/inspector, wrath-inspector: a read-only server and SolidJS views over a session store (the live map, each session, its character, party and events), and the wrath-inspector bin that serves them. It reads records and nothing else.

What an agent may observe and do is docs/CONTRACTS.md; with module/PROTOCOL.md it is the stack's specification. The stack records what its own sessions did (docs/SESSION-FORMAT.md) and knows nothing of what drove them: episodes, scores and model trajectories are a harness's, plugged in through the hooks mcp/ exposes. docs/ARCHITECTURE.md is how the pieces fit and what those hooks are. WrathBench, an LLM evaluation harness, is one such harness and the stack's first consumer.

flowchart TB
    agent["Agent<br/>(any MCP client)"]
    harness["Harness, optional<br/>(e.g. WrathBench)"]
    reader["Readers<br/>(wrath-inspector, a harness's<br/>viewer, scorer, collector)"]

    subgraph mcp["mcp/"]
        server["MCP server + core tools<br/>holds the port secret"]
        host["Sandbox host"]
        child["Confined sandbox child<br/>(Landlock) runs snippets"]
        recorder["Session recorder<br/>in the child"]
        writer["Session writer<br/>write gate"]
    end

    store[("Session record<br/>wrath-session/1<br/>trace, events, calls, nearby")]

    subgraph sdk["sdk/"]
        client["WrathClient<br/>actions, events, state cache"]
    end

    subgraph ws["AzerothCore worldserver"]
        subgraph module["module/"]
            http["HTTP/WS bridge<br/>bearer: port or lease secret"]
            sessions["Sessions and leases"]
            pbridge["Packet bridge"]
            tap["Event tap<br/>whitelist"]
            audit[("Audit log")]
        end
        session["WorldSession<br/>stock opcode handlers"]
        world(("Game world"))
    end

    agent <-->|"MCP over stdio"| server
    harness -. "hooks: tools, rendering,<br/>child extension, records" .-> mcp
    server --> host
    host <-->|"IPC"| child
    server -->|"POST /lease"| http
    child -->|"in-process"| client
    client -->|"POST /action<br/>lease secret only"| http
    http --> sessions
    http --> pbridge
    sessions -->|"login, logout"| session
    pbridge -->|"client opcodes CMSG_*"| session
    session <--> world
    session ==>|"outbound SMSG_*"| tap
    tap ==>|"whitelisted events<br/>WS /events"| client
    pbridge -.-> audit
    tap -.-> audit
    client ==>|"state cache"| recorder
    recorder ==>|"drained on the host's tick"| writer
    server -->|"tool calls and results"| writer
    host -->|"action log"| writer
    writer ==>|"append-only segments"| store
    store ==> reader

Thin arrows carry calls and actions, thick arrows carry observations. An action reaches the world only as the opcode a real client would send, through the same stock handler; what comes back is the session's outbound packets, cut down to what a client would see (docs/CONTRACTS.md). The port secret stays in the MCP process, which leases a per-session secret for the sandbox child, so a snippet can drive its own character and nothing else.

Every session leaves a record: a recorder beside the client reads its state cache, and the host writes that, the tool calls and the action log to one directory of append-only JSONL segments, the format docs/SESSION-FORMAT.md specifies. A player who is not one of the deployment's own sessions is never written. wrath-inspector reads a store back (inspector/README.md): bun inspector/src/bin.ts --store <dir> serves its API and page.

Tested against AzerothCore 3cafaf4a588fd1f287678fdb37438fdedd1ed85c.

Building the module into a worldserver

  1. Check out AzerothCore at the tested commit.

  2. Copy module/ to modules/mod-wrathbench in that tree. The directory name matters: mod-wrathbench.cmake names modules/mod-wrathbench/src/ when it stamps the build identity.

  3. Build as usual; AzerothCore's CMake discovers the module itself. Pass -DWRATHBENCH_BUILD=<your build id> to name the build on GET /health; without it the module reports unknown.

  4. Copy module/conf/mod_wrathbench.conf.dist beside the worldserver's config and set it:

    • WrathBench.Enable = 1 (or AC_WRATH_BENCH_ENABLE=1). The module is off unless this is set, in the shipped conf and in the code alike, so a worldserver that only has it built in opens no control port.

    • WrathBench.Secret, the port secret, 32 characters or more. It is required; without it the module does not listen. Keep it out of the file itself and pass it as AC_WRATH_BENCH_SECRET in the worldserver's environment.

    • WrathBench.Accounts, the game accounts sessions may use. Each must exist in the auth database (account create <name> <password> on the worldserver console) and be a player account: the module refuses one with a GM security level (gm_account), and chat the server would run as a command (chat_command), unless the caller opts in to GM use (mcp/README.md, "GM accounts").

    • WrathBench.BindAddress and WrathBench.Port (default 127.0.0.1:8086, loopback only). To serve callers on other hosts, set the address and keep the port on a private network: it is plain HTTP with bearer secrets.

    • WrathBench.AuditDir, where the per-session audit logs go. Its default is the AzerothCore Docker image's log path; outside that image, point it at a writable directory.

The worldserver needs the 3.3.5a client data (dbc, maps, vmaps, mmaps) for that core, extracted from a client you own. None of it is in this repository, and none of it may be committed here.

Related MCP server: wow-api-mcp

Quick start

With Bun 1.4.4 (.bun-version) and Linux:

bun install --frozen-lockfile

Check the module end to end with the SDK alone. sdk/examples/live-slice.ts connects, creates or reuses a character, says a line, reads the echo off the event stream and checks the state cache against it:

MODULE_HOST=127.0.0.1 MODULE_PORT=8086 \
WRATHBENCH_MODULE_SECRET=<the port secret> \
  bun sdk/examples/live-slice.ts

It uses the module's default account (WrathBench.Account). live-move.ts does the same for movement.

Then serve the core tools to an MCP-capable agent:

WRATHBENCH_MODULE_URL=http://127.0.0.1:8086 \
WRATHBENCH_MODULE_SECRET=<the port secret> \
  bun mcp/src/main.ts --account <an allowed account>

It speaks MCP over stdio, so the agent launches it as its server command. It leases a session secret with the port secret and hands the sandbox only that, and when it exits cleanly it logs the character out and releases the lease. The session is recorded by default, into a sessions directory beside its state directory (--record-dir, --no-record). The sandbox needs Linux 6.7 or later (Landlock with TCP rules) and refuses to start without it. mcp/README.md has the options; sdk/README.md covers using the SDK directly.

Development

bun test                 # sdk, mcp, the inspector and the boundary check, against an in-process module stub
bun run typecheck        # tsc over sdk, mcp, the inspector and scripts; bun test does not check types
bun run boundary         # the stack imports nothing but itself and declared dependencies
bun run docs:api:check   # sdk/API.md matches the source it is generated from

None of these needs a game stack or any game data. The module compiles only inside an AzerothCore tree; see CONTRIBUTING.md for how a module change is verified.

Versions

The stack follows semantic versioning (CONTRIBUTING.md, "Versioning"): major for a breaking change, minor for a feature or addition, patch for a fix. Before 1.0 any release may break, and CHANGELOG.md says how. It lists what each release changed and what an operator must do about it.

Licence

Everything here is MIT under LICENSE, except module/src/WbNavRecast.cpp, which is derived from Recast Navigation and keeps its zlib licence notice. A worldserver built with the module is a combined work under AzerothCore's licence. Nothing here relicenses AzerothCore, Blizzard's assets or any dependency; see THIRD-PARTY-NOTICES.md.

Nothing Blizzard-derived is in this repository: no client files, no extracted maps or DBCs, no game text. The client data a worldserver needs is the user's own to supply, and the stack runs only against a private AzerothCore server.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      An MCP server that gives AI coding assistants access to the World of Warcraft addon API documentation, FrameXML/AddOn UI source code, and the Warcraft Wiki across all four client flavors.
      9
      510 npm
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables LLMs to control a Minecraft bot and interact with the game through MCP tools, including observing state, moving, mining, crafting, building, farming, managing inventory, enchanting, and chatting in-game.
      1
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to write and debug World of Warcraft: Infinite addons end-to-end: statically checking Lua, .toc and XML against the client's own API manual, hot-loading changes into the running game, then executing Lua or slash commands and reading back errors with stacks, print output, events, frame info and screenshots. Also records events, inspects frames and keeps versioned history with one-click rollback.
      25
      MIT