storm-re-mcp
Build-aware MCP server for Storm-engine games that resolves symbols, serves cached decompilation/xrefs, maps/diffs across builds, indexes assets, and exposes analysis workflows.
Resolve VA/RVA/symbol names to build-verified Storm symbols with confidence and source.
Get bounded, cached decompilation, xrefs, and symbolized code/functions.
Diff functions and patch batches across builds; map symbols via BSim, Trilogy, name, or RVA.
Search symbols, strings, and code; read pre-indexed hot-set entries; run one-call explanations and batched read-only calls.
Analyze state surfaces, write sites, input paths, frame ticks, net sessions, and scene dispatch.
Export markdown reports and index/inspect extracted CPK assets and xfbin chunks.
List builds and database/cache/BSim/index statistics; supports MCP resources/prompts and optional HTTP JSON endpoint.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@storm-re-mcp decompile ccPlayer::ChangeAction in build s4 and show its xrefs"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| CLI + MCP server (Python 3.11+, stdlib only) |
| CPK, xfbin and param-table layouts |
| known Storm 4 1.09 addresses, struct offsets, input bits |
| tool selection and workflows for LLM agents |
| every setting with its default |
Related MCP server: REA
Requirements
Python 3.11+
A running
pyghidra-mcpwith the game executables imported (only needed fordecomp/xrefscache 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 ChangeActionpip 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 |
|
|
| pyghidra-mcp endpoint |
|
|
| SQLite cache |
|
|
| label stored with indexed programs |
|
|
|
|
|
|
|
|
|
|
| Switch dynsym dump |
|
|
|
|
|
|
| hot-set topics for |
|
|
| your extracted CPK tree |
|
| (off) | Windows mirror reported as |
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.csvwith columnsrva,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 inconfig.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 columnsquery_rva(hex) query_name target_exe target_addr(hex) target_name similarity significance. Target exe names map to aliases viaconfig.TARGET_EXE_PATTERNS.Extracted CPKs (
assets_root):<root>/<game>/<cpk dir>/<cpk name>/<entry>plus<root>/CPKS.tsv(game<TAB>cpkrows). Seedocs/formats/cpk.md.
Commands
command | purpose |
| discover programs, SHA-256 and image base; ingest nucc/manual/trilogy symbols |
| alias → program, sha, base, symbol/cache counts |
| one build-verified symbol |
| bounded decompile summary; cached |
| callers, callees, data refs; deduplicated |
| signature, similarity, symbolic callee delta |
| load precomputed BSim TSVs (no Ghidra) |
| cross-build RVA with method/score/confidence |
| pre-decompile the hot set into SQLite |
| read indexed entries / readable code with no backend call |
| rewrite |
| static rollback field manifest (offsets, r/w, confidence) |
| who writes a root+offset (or address xrefs) |
| pad poll → CtrlInputPad → gates → ChangeAction |
| timer idioms and per-frame constants |
| Steam/net-session send/recv/tick surface |
| scene/message dispatch |
| batch function diff between builds (byte mode when both files exist) |
| markdown report from indexed facts |
| symbol index, strings, or code search |
| index and inspect your extracted CPK tree; parses xfbin chunk tables |
| 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.dbStdio 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 andstructuredContent.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|rvaforces one.
License
Code: MIT. Documentation in docs/: CC BY 4.0.
Game names are used only to identify compatible software.
Available Tools
22 toolsstorm_asset_findStorm Asset FindARead-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 InfoCRead-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 BatchBRead-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 BuildsBRead-onlyIdempotent
List build aliases, programs, SHA-256, base and counts.
Inputs: no named parameters. Returns: ok
storm_decompStorm DecompileBRead-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 DiffBRead-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 ExplainCRead-onlyIdempotent
One-call explanation: resolve + decompile + symbolize + xrefs + maps.
Inputs: target (required), build, max_bytes. Returns: ok
storm_exportStorm ExportCIdempotent
Write a compact markdown report from indexed facts.
Inputs: topic (required), out, build, limit, +1 more. Returns: ok
storm_findStorm FindCRead-onlyIdempotent
Search symbols (local, cheap), strings, or code.
Inputs: query (required), mode, build, limit. Returns: ok
storm_frame_tickStorm Frame TickCRead-onlyIdempotent
Timer idioms and per-frame constants; flags 60 FPS risks.
Inputs: build, limit, seeds. Returns: ok
storm_input_pathStorm Input PathDRead-onlyIdempotent
Pad poll -> ccPlayerPad -> CtrlInputPad -> vfunc gates -> ChangeAction.
Inputs: build, depth, limit. Returns: ok
storm_mapStorm MapCRead-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 SessionDRead-onlyIdempotent
Steam/net-session send/recv/tick surface and Steam imports.
Inputs: build, limit, seeds, include_imports. Returns: ok
storm_patch_diffStorm Patch DiffCRead-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 ResolveBRead-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 DispatchDRead-onlyIdempotent
Story scene/message dispatch, stage strings and boss ids.
Inputs: build, limit, seeds. Returns: ok
storm_showStorm ShowBRead-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 StatBRead-onlyIdempotent
Database, cache, BSim, map and index statistics.
Inputs: no named parameters. Returns: ok
storm_state_surfaceStorm State SurfaceCRead-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 SymbolizeCRead-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 SitesCRead-onlyIdempotent
Who writes an address or root+offset, with evidence and confidence.
Inputs: target (required), root, build, limit, +5 more. Returns: ok
storm_xrefsStorm XrefsCRead-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
Scored across 22 tools
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.
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.
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.
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
Structured knowledge base for AI agent solutions. Search, explore, and retrieve build logs.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Versioned documentation registry and semantic search for AI tools and coding assistants.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Related MCP Servers
- AlicenseBqualityCmaintenanceEnables 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.18MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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
- AlicenseNot gradedqualityBmaintenanceConnects 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 npm7MIT
- AlicenseCqualityBmaintenanceEnables 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.767MIT