wowdump

wowdump is a build-aware World of Warcraft runtime analysis MCP server. It exposes Frida process control, focused Lua/C++ tracing, bounded data watches, build profile validation, and verified data readers over the MCP 2026-07-28 protocol.

The package supports multiple WoW flavors and builds. retail is a flavor in a build key such as [email protected]; it is not part of the product name.

Install

Run directly from an MCP client:

{
  "mcpServers": {
    "wowdump": {
      "command": "npx",
      "args": [
        "-y",
        "wowdump",
        "--game-root",
        "D:\\Game\\World of Warcraft"
      ]
    }
  }
}

Or install it globally:

npm install --global wowdump
wowdump --game-root "D:\Game\World of Warcraft"

The wowdump executable only starts the stdio MCP server. It is not a separate interactive CLI.

Game Directories

Game directories are resolved once when the MCP server starts. The first non-empty source wins:

1. Repeatable --game-root <path> arguments.
2. WOWDUMP_GAME_ROOTS as a semicolon-separated list on Windows.
3. game_roots in the TOML file selected by --config <path>.
4. %LOCALAPPDATA%\wowdump\config.toml.
5. Automatic detection from verified Battle.net Agent installation metadata, followed by common Windows installation locations.

Example persistent configuration:

game_roots = [
  "D:/Game/World of Warcraft",
  "E:/World of Warcraft"
]

broker_idle_ms = 1200000

WOW_ROOT remains a deprecated compatibility fallback. Invalid selected paths are reported on stderr and are not silently replaced by a lower-priority source.

PID, build, module base, Frida sessions, Hook IDs, and runtime addresses are never persisted in TOML. They are discovered and validated for the current process.

Selecting A Target

Use these read-only tools before starting a dynamic session:

• wow_install_list: installed game directories and flavors.
• wow_build_list: detected build keys and versions.
• wow_target_list: running Wow.exe PIDs matched to an installation and build.

Focused and trace operations accept an explicit pid and buildKey. The server rejects PID/build mismatches and does not reuse a historical PID or module base.

MCP Tools

The primary tool groups are:

• frida_command: generic Frida read, write, script, Hook, process, and session operations.
• wow_lua_trace_* and wow_cpp_trace_*: build-aware bounded trace sessions.
• wow_focus_*, wow_watch_*, and wow_session_checkpoint: explicit before/during/after analysis windows.
• wow_data_source_*, wow_data_read, and wow_build_profile_validate: verified build data and readers.
• wow_broker_*: Broker status, start, reconnect, and stop.
• wow_analysis_coverage and wow_analysis_checkpoint: static profile coverage and checkpoints.

The server rejects legacy MCP handshakes. Protocol output is written only to stdout; diagnostics are written to stderr.

Runtime Layout

Production uses three distinct directory roles:

• Package resources/builds: read-only, build-specific profiles and signatures.
• %LOCALAPPDATA%\wowdump: writable Broker ledgers, focused sessions, logs, and cache.
• Repository analyze/vm: offline analysis inputs and intermediate evidence; it is not required by the installed package.

Stable overrides can be placed in TOML:

profile_root = "D:/wowdump-profiles"
runtime_root = "C:/Users/ACCOUNT/AppData/Local/wowdump"
log_level = "info"
broker_idle_ms = 1200000

The MCP process does not own Frida sessions. A single per-user wowdump-broker process owns attach/detach, scripts, Hooks, Interceptors, request forwarding, and cleanup. Requests refresh its idle timer; the default idle timeout is 20 minutes.

Packaged Builds

This release includes a verified profile for:

• [email protected]

Every build has its own RVA profile, entry signatures, data sources, and manifest hashes. A new build must be relocated and validated; old RVAs are not automatically reused.

Development

npm install
npm run typecheck
npm test
npm run build
npm run bundle:verify
npm run package:verify

To regenerate the packaged bundle from the repository-only analysis workspace:

npm run bundle:build

npm run package:verify enforces the npm file whitelist, creates a real tarball, installs it in a temporary directory, starts the installed wowdump bin, and performs an MCP 2026-07-28 handshake.

License

MIT