Skip to main content
Glama
storm-re-mcp

storm-re-mcp

by nuns-re

storm-re

Build-aware resolver, decompile cache and MCP server in front of pyghidra-mcp, for the PC builds of CyberConnect2's Storm-engine fighting games, plus format notes for their data files.

Ghidra knows how to decompile. It does not know that a program is Storm 4 1.09, that its image base is 0x140000000, that 0x7AB468 is ccPlayer::ChangeAction, or that the same function lives at a different RVA in 1.06. storm-re supplies that layer, caches the expensive output, and returns a bounded summary instead of a raw xref/callee dump.

No game files are included. This repository contains tool code and documentation only: no executables, archives, extracted assets, decompiled code or symbol dumps. You need your own legally obtained copy of the games. Not affiliated with or endorsed by CyberConnect2 or the games' publisher.

Contents

Path

What

src/storm_re/

CLI + MCP server (Python 3.11+, stdlib only)

docs/formats/

CPK, xfbin and param-table layouts

docs/reference/

known Storm 4 1.09 addresses, struct offsets, input bits

docs/agent-guide.md

tool selection and workflows for LLM agents

config.example.toml

every setting with its default

Related MCP server: REA

Requirements

  • Python 3.11+

  • A running pyghidra-mcp with the game executables imported (only needed for decomp/xrefs cache misses; everything else is local SQLite).

  • Optional data sources, all produced from your own copies (see Data sources).

Quick start

git clone <this repo> && cd storm-re
cp config.example.toml ~/.config/storm-re/config.toml   # edit mcp_url + [builds]
bin/storm-re init            # discover programs, SHA-256, image bases; ingest names
bin/storm-re bsim ingest     # optional: precomputed BSim edges
bin/storm-re index           # optional: pre-decompile the hot set

bin/storm-re resolve ccPlayer::ChangeAction -b s4
bin/storm-re decomp ccPlayer::ChangeAction -b s4
bin/storm-re xrefs ccPlayer::ChangeAction -b s4 --limit 20
bin/storm-re diff ccPlayer::ChangeAction --from s4 --to s4-debug --map
bin/storm-re map ccPlayer::ChangeAction --from s4
bin/storm-re symbolize ccPlayer::ChangeAction -b s4
bin/storm-re state_surface ccPlayer -b s4 --limit 20
bin/storm-re write_sites ccPlayer --offset 0xCC0 -b s4 --limit 20
bin/storm-re patch_diff --from s4 --to s4-debug --limit 5
bin/storm-re find ChangeAction

pip install -e . also works and installs a storm-re entry point.

Configuration

Precedence: CLI flag > environment variable > config file > default. Config file: $STORM_RE_CONFIG, else $XDG_CONFIG_HOME/storm-re/config.toml (~/.config/storm-re/config.toml).

Key

Env

Default

Meaning

mcp_url

STORM_RE_MCP

http://127.0.0.1:8770/mcp

pyghidra-mcp endpoint

db

STORM_RE_DB

~/.local/share/storm-re/storm-re.db

SQLite cache

host

STORM_RE_HOST

local

label stored with indexed programs

nucc_root

STORM_RE_NUCC

~/nucc-symbols

games/<game>/<sha>/functions.csv name sets

manual_root

STORM_RE_MANUAL

~/ghidra/storm-research

*.manual.csv hand-verified names

trilogy_tsv

STORM_RE_TRILOGY_TSV

~/ghidra/trilogy-dynsym.tsv

Switch dynsym dump

bsim_root

STORM_RE_BSIM

~/ghidra/match/out

*.bsim.tsv exports

hot_json

STORM_RE_HOT

hot.json in the repo

hot-set topics for index

assets_root

STORM_RE_ASSETS

~/storm-cpk-extracted

your extracted CPK tree

assets_win_root

STORM_RE_ASSETS_WIN

(off)

Windows mirror reported as win_path

Ghidra program names carry a per-project hash suffix (/NSUNS4_release.exe-75912b). Point each build alias at your own import:

[builds.s4]
program = "/NSUNS4_release.exe-1a2b3c"

bin/storm-re builds shows what was found. A build whose program is missing is skipped, so you only need the games you have.

Data sources

Every source is optional; missing ones are skipped by init.

  • Ghidra names come with your own analysis.

  • Name CSVs (nucc_root): games/<game>/<sha256>/functions.csv with columns rva,name[,short_name,namespace,confidence,size,evidence]. Matched to builds by the exe SHA-256. A community name set in this layout is published at exavadw/naruto-storm-symbols.

  • Manual CSVs (manual_root): same columns; file → build mapping in config.MANUAL_SOURCES. Highest precedence.

  • Switch dynsym TSV (trilogy_tsv): tab-separated, RVA (hex) first, mangled or demangled name last, ≥5 columns. Dump it from your own Switch build.

  • BSim exports (bsim_root): *.bsim.tsv, 7 tab-separated columns query_rva(hex) query_name target_exe target_addr(hex) target_name similarity significance. Target exe names map to aliases via config.TARGET_EXE_PATTERNS.

  • Extracted CPKs (assets_root): <root>/<game>/<cpk dir>/<cpk name>/<entry> plus <root>/CPKS.tsv (game<TAB>cpk rows). See docs/formats/cpk.md.

Commands

command

purpose

init

discover programs, SHA-256 and image base; ingest nucc/manual/trilogy symbols

builds

alias → program, sha, base, symbol/cache counts

resolve <va|rva|name>

one build-verified symbol

decomp <target>

bounded decompile summary; cached

xrefs <target>

callers, callees, data refs; deduplicated

diff <target> --from A --to B [--map]

signature, similarity, symbolic callee delta

bsim ingest

load precomputed BSim TSVs (no Ghidra)

map <name> [--from A] [--to B]

cross-build RVA with method/score/confidence

index [--topic T]

pre-decompile the hot set into SQLite

show <topic|name> [--symbolized]

read indexed entries / readable code with no backend call

symbolize <target>

rewrite FUN_/SUB_/DAT_ to known names

state_surface <root>

static rollback field manifest (offsets, r/w, confidence)

write_sites <target> --offset O

who writes a root+offset (or address xrefs)

input_path

pad poll → CtrlInputPad → gates → ChangeAction

frame_tick

timer idioms and per-frame constants

net_session

Steam/net-session send/recv/tick surface

scene_dispatch

scene/message dispatch

patch_diff --from A --to B

batch function diff between builds (byte mode when both files exist)

export <topic> --out FILE

markdown report from indexed facts

find <query>

symbol index, strings, or code search

asset_index / asset_find / asset_info

index and inspect your extracted CPK tree; parses xfbin chunk tables

stat

cache hit/size/savings

Global: --db, --mcp, --json, --quiet, --timeout, --no-cache. Exit codes: 0 ok, 1 usage, 2 not found/ambiguous, 3 backend, 4 diff target missing, 5 database.

MCP server

bin/storm-re-mcp --db ~/.local/share/storm-re/storm-re.db

Stdio by default, no third-party packages. 22 tools: the resolver/cache/index surface plus storm_explain (one-call function explanation), storm_batch (several read-only calls in one request) and storm_asset_find/storm_asset_info. Every tool runs the CLI with --json, so MCP and CLI cannot drift.

  • Negotiates MCP 2024-11-05 / 2025-03-26 / 2025-06-18; tool annotations and structuredContent.

  • Resources: storm-re://builds, storm-re://stats, storm-re://assets, storm-re://topic/{topic}, storm-re://function/{build}/{rva}.

  • Prompts: rollback_audit, story_port, clean_vs_mod, function_explain.

  • Stdio progress notifications and cancellation; long calls run in a worker.

  • Optional HTTP JSON endpoint: bin/storm-re-mcp --http 127.0.0.1:8788. Bearer token via --token/STORM_RE_MCP_TOKEN; a non-loopback bind requires a token.

  • Tool responses are capped at 48 KB; use resources for full reports/code.

Client config:

"storm-re": {
  "type": "stdio",
  "command": "/path/to/storm-re/bin/storm-re-mcp",
  "args": ["--db", "/path/to/storm-re.db"]
}

resolve, show, stat and symbol find work with Ghidra down; decomp and xrefs need it only on a cache miss. See docs/agent-guide.md for agent workflows.

Builds

s4 (1.09), s4-debug (1.06), s4-107, s3/s3hd, s3fb, s2, s1 (Steam exe, alias s1-clean), s1-modded (community mod, patch_diff only), s1-debug, connections, revolution, trilogy (Switch arm64, name/BSim source only). Defined in src/storm_re/config.py.

Symbol precedence

manual (rank 3) > nucc (rank 2) > trilogy (rank 2) > Ghidra (rank 1).

Cache

Key: (sha256, rva, kind, params, name_version). name_version is a hash of the build's rva:name table, so ingesting names invalidates only the affected entries. Raw JSON is zlib-compressed; stat reports raw vs summary chars. map prefers a same-name symbol, then a direct BSim edge, then a Switch-mediated edge, then an equal RVA.

Tests

# unit, no network, no game files
PYTHONPATH=src:tests python3 -m unittest discover -s tests -p 'test_*.py'

# live (needs your DB + MCP + imported programs)
STORM_RE_LIVE=1 PYTHONPATH=src:tests python3 -m unittest discover -s tests -p 'test_live*.py'

Design notes

  • Read-only against Ghidra: no renames, retypes, comments or saves.

  • Every answer carries build, program, sha256, rva, va, confidence, source. A wrong-build answer is visible, never silent.

  • Address input tries VA and RVA and picks the interpretation that resolves to a symbol; --addr-kind va|rva forces one.

License

Code: MIT. Documentation in docs/: CC BY 4.0. Game names are used only to identify compatible software.

Available Tools

22 tools
storm_asset_findStorm Asset FindA
Read-onlyIdempotent

Search decrypted CPK files of storm1/2/3hd/3fb/rev/4/gen by path substring or glob. Returns game, cpk, entry, size, magic, path, win_path. Empty query = per-game/per-CPK overview.

Inputs: cpk, ext, game, limit, +1 more. Returns: ok

storm_asset_infoStorm Asset InfoC
Read-onlyIdempotent

One extracted CPK file: paths, same entry in other games, and the xfbin chunk list (type, name, path) for NUCC files.

Inputs: game (required), path (required), max_chunks. Returns: ok

storm_batchStorm BatchB
Read-onlyIdempotent

Run several read-only storm-re tools in one call. Excludes export and batch.

Inputs: calls (required), stop_on_error. Returns: ok

storm_buildsStorm BuildsB
Read-onlyIdempotent

List build aliases, programs, SHA-256, base and counts.

Inputs: no named parameters. Returns: ok

storm_decompStorm DecompileB
Read-onlyIdempotent

Bounded decompile summary, cache-first. detail=summary default; sig is cheapest; full can be large.

Inputs: target (required), head, build, detail, +2 more. Returns: ok

storm_diffStorm DiffB
Read-onlyIdempotent

Compare one function across two builds: signature, similarity, callee delta.

Inputs: target (required), to_build (required), from_build (required), use_map. Returns: ok

storm_explainStorm ExplainC
Read-onlyIdempotent

One-call explanation: resolve + decompile + symbolize + xrefs + maps.

Inputs: target (required), build, max_bytes. Returns: ok

storm_exportStorm ExportC
Idempotent

Write a compact markdown report from indexed facts.

Inputs: topic (required), out, build, limit, +1 more. Returns: ok

storm_findStorm FindC
Read-onlyIdempotent

Search symbols (local, cheap), strings, or code.

Inputs: query (required), mode, build, limit. Returns: ok

storm_frame_tickStorm Frame TickC
Read-onlyIdempotent

Timer idioms and per-frame constants; flags 60 FPS risks.

Inputs: build, limit, seeds. Returns: ok

storm_input_pathStorm Input PathD
Read-onlyIdempotent

Pad poll -> ccPlayerPad -> CtrlInputPad -> vfunc gates -> ChangeAction.

Inputs: build, depth, limit. Returns: ok

storm_mapStorm MapC
Read-onlyIdempotent

Map a symbol across builds via direct BSim, Trilogy-mediated, name and RVA.

Inputs: name (required), refresh, to_build, from_build. Returns: ok

storm_net_sessionStorm Net SessionD
Read-onlyIdempotent

Steam/net-session send/recv/tick surface and Steam imports.

Inputs: build, limit, seeds, include_imports. Returns: ok

storm_patch_diffStorm Patch DiffC
Read-onlyIdempotent

Batch function diff between builds; byte mode finds call-site patches.

Inputs: to_build (required), from_build (required), limit, seeds, +2 more. Returns: ok

storm_resolveStorm ResolveB
Read-onlyIdempotent

Resolve a VA, RVA or full symbol name in one build. Cheap and local; returns build/program/sha/rva/va/name/confidence/source.

Inputs: target (required), build, addr_kind. Returns: ok

storm_scene_dispatchStorm Scene DispatchD
Read-onlyIdempotent

Story scene/message dispatch, stage strings and boss ids.

Inputs: build, limit, seeds. Returns: ok

storm_showStorm ShowB
Read-onlyIdempotent

Read pre-decompiled hot-set entries from SQLite; no Ghidra call.

Inputs: query (required), build, limit, max_bytes, +1 more. Returns: ok

storm_statStorm StatB
Read-onlyIdempotent

Database, cache, BSim, map and index statistics.

Inputs: no named parameters. Returns: ok

storm_state_surfaceStorm State SurfaceC
Read-onlyIdempotent

Static field-access surface for a root object: offsets, sizes, r/w, functions, confidence. Static inference only.

Inputs: root (required), build, limit, param, +3 more. Returns: ok

storm_symbolizeStorm SymbolizeC
Read-onlyIdempotent

Rewrite FUN_/SUB_/DAT_ placeholders to Storm names with mapping and confidence.

Inputs: target (required), build, addr_kind, max_bytes. Returns: ok

storm_write_sitesStorm Write SitesC
Read-onlyIdempotent

Who writes an address or root+offset, with evidence and confidence.

Inputs: target (required), root, build, limit, +5 more. Returns: ok

storm_xrefsStorm XrefsC
Read-onlyIdempotent

Deduplicated callers, callees and data refs for one function.

Inputs: target (required), build, limit, direction. Returns: ok

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    C2.8/5.0

    Scored across 22 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes (resolve, decompile, xrefs, diff, map, find, etc.). A few pairs overlap—storm_diff vs storm_patch_diff, storm_decomp vs storm_show vs storm_explain, and the meta-tools storm_explain/storm_batch vs their individual components—but descriptions make the boundaries readable.

    Naming Consistency5/5

    Every tool uses the storm_ prefix with snake_case, with no mixing of conventions. Suffix patterns vary between verbs and nouns, but the naming scheme is entirely predictable.

    Tool Count3/5

    22 tools is heavy for a single MCP server. While the reverse-engineering domain is broad, some convenience/meta tools (explain, batch) and specialized analysis tools could potentially be consolidated without losing capability.

    Completeness4/5

    The surface covers core RE workflows: symbol resolution, decompilation, xrefs, cross-build diff/mapping, search, symbolization, state/write-site analysis, asset discovery, and build/stat inspection. Minor gaps exist, such as raw disassembly/CFG extraction or general import/export listing, but agents can work around them.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Enables agents to explore a static RTTI, call, and cross-reference graph of a game executable, querying functions, classes, vtables, strings, globals and memory through search, disassembly, signature and SQL tools. It also supports a provenance-tracked naming lifecycle where labels are proposed with evidence, reviewed, and ported across game patches.
      18
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables agents to reverse-engineer software across native binaries, managed code, Electron apps, websites, and live runtime behavior, returning findings linked to the evidence and limitations behind each conclusion. It also maintains a durable workspace where those behaviors can be inspected, questioned, compared against real execution, and exported as runnable handoffs.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Connects AI agents to reverse-engineering tools that inspect native binaries, JavaScript/Electron apps, .NET assemblies, websites, and runtime behavior without source code. Returns pseudocode, references, and evidence so agents can explain how a feature works or reimplement it.
      377,174 npm
      7
      MIT
    • A
      license
      C
      quality
      B
      maintenance
      Enables AI agents to reverse engineer Nintendo 64 ROMs and PlayStation 2 ELF binaries through MIPS disassembly, binary and metadata inspection, memory and crash analysis, and repository reference tracing with structured, verifiable evidence.
      76
      7
      MIT