Crusader_Decomp/ghidra_mcp_wishlist.md

# Ghidra MCP Wishlist

This file records concrete MCP gaps hit during Crusader workflow passes.

Rules for keeping it useful:
- Put only unresolved work in `Remaining TODOs`.
- Move implemented or source-fixed items to `Done / Implemented`.
- Keep each remaining item short: missing capability, fallback, why it matters, proposed behavior, latest status.

## Remaining TODOs

### Raw Patch Extraction From Live Ghidra Edits

- Missing capability: export a machine-friendly raw patch plan from the current live program after verified byte edits, including NE relocation target changes.
- Current fallback: manually translate selector-space Ghidra edits into raw file offsets, helper-window byte blocks, and relocation-record rewrites before re-encoding them in a PowerShell patcher.
- Why it matters: the Regret hidden-debugger `debug menu 2.0` patch was proven in Ghidra first, but the usable deliverable had to become a raw `REGRET.EXE` patch because the available export processor path returned the original executable bytes instead of the modified image.
- Proposed MCP behavior: add an endpoint that emits a structured patch plan for the selected program, including file offsets, original bytes, new bytes, relocation-record deltas, and selector-to-segment metadata for NE executables. A direct `export_patched_binary(...)` helper would also be useful if it can be proven reliable on the target processor path.
- Latest status (2026-04-10): the full Regret runtime/helper plus `loosecannon` trigger patch had to be converted by hand into raw offsets `0xD2840..0xD28DC`, `0xD2C94`, `0xD2E0C`, `0xD2E14`, `0xD2E1C`, `0x7BB25`, `0x7BB15`, `0x7BB05`, and `0x7BAF5` after the live export path produced an unmodified EXE.

### Explicit Write-Target Enforcement And Reporting

- Missing capability: reliable enforcement and reporting of the exact target program for write-capable MCP operations.
- Current fallback: re-read bytes immediately after each write, compare against the intended file on disk, and assume nothing from the returned `target_program` field when explicit selectors were provided.
- Why it matters: during the Regret debugger patch session, `run_write_script(...)` results still reported `target_program=REGRET.EXE` even when `/Writable/REGRET-PATCHED.EXE` was passed explicitly, which made it harder to tell whether a write actually landed on the writable clone or silently fell back.
- Proposed MCP behavior: when explicit selectors are provided, write-capable endpoints should either bind to that exact program and report the resolved full domain-file path, or fail with a structured target-mismatch error instead of proceeding with ambiguous status text.
- Latest status (2026-04-10): the raw-write fallback only remained trustworthy because the session re-read the patched bytes from the writable target after every operation; the reported target text itself was not sufficient evidence.

### Instruction-Overwrite Patching Without Script Fallbacks

- Missing capability: patch over existing defined instructions on writable copies without dropping to custom write scripts that clear code units first.
- Current fallback: use `run_write_script(...)` to clear the affected code units, write bytes manually, trigger disassembly, and then re-verify the result with readback helpers.
- Why it matters: `patch_bytes_and_reanalyze(...)` refused several valid small Regret debugger edits with `Memory change conflicts with instruction`, even though the intended operation was a normal code-patch workflow on a writable copy.
- Proposed MCP behavior: add an explicit instruction-overwrite mode to `patch_bytes_and_reanalyze(...)` for writable targets so the endpoint can clear the conflicting code units, apply the bytes, re-disassemble the region, and report the final instruction text in one machine-friendly result.
- Latest status (2026-04-10): the active `loosecannon` fix at `1148:3743` only landed after falling back to a write script that manually cleared the code unit and forced redisassembly.

### Apply-Class-Layout Schema Parity

- Missing capability: reliable minimal-payload use of `apply_class_layout(...)` during live class-lift batches.
- Current fallback: create the class namespace and provisional structs directly through live `run_write_script(...)`, then defer any later class-binding or per-method typing work.
- Why it matters: the first `EntityDispatchEntry` pilot batch reached the point where the class shell and provisional datatypes existed, but the endpoint still rejected the bind attempt with an undocumented required `methods` property even though the local workflow only needed `class_path`, `instance_struct`, and `vtable_struct`.
- Proposed MCP behavior: `apply_class_layout(...)` should accept a true minimal bind payload when no method list is being applied, or else the bridge/schema should expose the `methods` field explicitly and treat an omitted list as empty instead of a validation error.
- Latest status (2026-04-07): live `CRUSADER.EXE` class-lift pass for `Remorse::EntityDispatchEntry` succeeded via `run_write_script(...)`, creating the class shell plus `/Remorse/EntityDispatchEntryBase` and `/Remorse/EntityDispatchEntryVtable`. The only failed step in that batch was the direct `apply_class_layout(...)` call, which rejected the payload before any class work ran.

### Class-Lift Typing Live Parity

- Missing capability: end-to-end live-session parity for storage-aware `this` typing on 16-bit NE methods whose current storage does not match the default pointer storage the binder would choose.
- Current fallback: use local PyGhidra with `DYNAMIC_STORAGE_ALL_PARAMS`, or move methods with `set_function_class(...)` and defer final `this` typing/manual prototype cleanup.
- Why it matters: `EntityVmContext` lifecycle methods and `EntityVmRuntime::Create` still need the live MCP path to behave like the verified local PyGhidra repair flow.
- Proposed MCP behavior: `set_function_this_type(...)` and `apply_class_layout(...)` should reliably fall back to dynamic storage in-session for these 16-bit cases, while preserving structured per-method warnings instead of aborting the batch.
- Latest status (2026-04-06): local PyGhidra confirmed that `1420:0eec`, `1420:10b6`, `1420:10da`, `1420:1162`, `1420:118f`, and `1420:1278` accept `EntityVmContext * this` cleanly via `DYNAMIC_STORAGE_ALL_PARAMS`. The live storage-aware path now also accepts explicit `/Remorse/EntityVmRuntime *32`, `/Remorse/EntityVmOwnerResource *32`, `/Remorse/EntityVmContext *32`, and `/Remorse/EntityVmSlotEntry *32` signatures in-session once the exact `*32` datatype has first been resolved into the program data-type manager. The remaining live gap is now mostly about deeper mixed-width parameter packs like `1420:0eec CreateFromSlotIndex`, not the previously blocked 4-byte object-pointer cases themselves.

### Storage-Aware Prototype Live Verification

- Missing capability: confirmed live-session parity for the newest storage-aware prototype fixes on 16-bit NE repair cases.
- Current fallback: if the active GUI session is on an older plugin build, reload the plugin; if parity still fails, use local PyGhidra or manually compensate when testing stack offsets / calling conventions.
- Why it matters: `1000:42e2` and `1420:1499` are the known proof cases for explicit return storage, stack-word parameter modeling, and 16-bit far calling conventions.
- Proposed MCP behavior: `set_function_prototype_storage(...)` should accept bare `stack:` offsets in the same hex-style form used in current workflow notes and should preserve exact calling-convention tokens such as `__cdecl16far` before falling back to lossy legacy normalization.
- Latest status (2026-04-06): the reloaded live plugin now reaches the real storage-aware implementation in-session on both proof cases, and explicit `AX:DX` return storage survives correctly on `1000:42e2` and `1420:1499`. The remaining live parity issue is now narrower: `calling_convention='__cdecl16far'` still normalizes those proof-case applies to plain `__cdecl`, but direct live `run_write_script(...)` calls can immediately restore `__cdecl16far`, which proves the live database accepts the exact convention token and leaves the endpoint-side normalization/deployment path as the remaining gap.

### Live Metadata / Read-Target Verification

- Missing capability: fully verified live-session parity for selector-aware reads and metadata helpers in mixed-build or partially refreshed GUI sessions.
- Current fallback: bridge alias retries, explicit-target normalization, and manual project-note cross-checks when a live session still behaves like an older plugin build.
- Why it matters: Crusader work routinely needs side-by-side reads across `/CRUSADER.EXE`, `/es/CRUSADER.EXE`, `/Writable/...`, and other project entries without changing the active Ghidra tab.
- Proposed MCP behavior: `list_project_programs(...)`, `get_runtime_capabilities(...)`, `get_callers(...)`, and other selector-aware read helpers should bind reliably to the requested or active target and return structured unsupported-state output instead of raw context failures.
- Latest status (2026-04-06): the local fork already includes alias fallbacks and Windows path/folder normalization for explicit-target matching. Remaining work is live-session verification after plugin refresh, not additional local source coverage.

## Done / Implemented In Local Fork

### Transport And Runtime

- POST endpoints now accept both `application/json` and `application/x-www-form-urlencoded` request bodies. Unsupported POST payloads fail early with `unsupported-content-type` instead of degrading into missing-parameter errors.
- `get_runtime_capabilities()` reports readonly/write-script capability state and `run_readonly_script(...)` returns structured unsupported-state output when Python support is unavailable.
- `run_write_script(...)` and alias `run_transaction_script(...)` are implemented with dry-run support, explicit target selectors, a write-policy denylist, and machine-friendly transaction results.
- Bridge runtime helpers retry compatible aliases on `404` / `No context found for request` for mixed-build live sessions.

### Explicit Targeting And Project Access

- Explicit write targeting is implemented for edit flows such as `apply_program_edit_plan(...)` and `patch_bytes_and_reanalyze(...)` with deterministic save behavior.
- Selector-aware read/query endpoints now accept `project_dir`, `project_name`, `folder_path`, and `program_name` and reuse the same target-resolution layer as write flows.
- Target matching now normalizes Windows path casing and slash style and can infer missing project selectors from the active domain file when appropriate.
- `list_project_programs(...)` plus alias `project_programs` is implemented and returns machine-friendly folder/program inventory.

### Analysis, Inspection, And Xrefs

- Function boundary repair helpers are implemented: `create_function_by_address(...)`, `delete_function_by_address(...)`, and `get_function_containing(...)`.
- Arbitrary memory/code inspection helpers are implemented: `read_region(...)`, `disassemble_region(...)`, `get_instruction_window(...)`, `search_instructions(...)`, and `get_data_uses(...)`.
- `search_bytes(...)` is implemented with `??` wildcards and machine-friendly hit output.
- Caller/xref recovery is improved via `get_callers(...)`, and `get_xrefs_to(...)` / `get_xrefs_from(...)` return typed reference kinds plus containing-function metadata.
- `get_symbol_at(address)` now uses direct routes when present and bridge-side legacy fallbacks when the live process is older.

### Batch Edits And Comparison Tools

- Batch helpers are implemented: `set_comments(...)`, `set_decompiler_comments(...)`, `rename_functions_by_address(...)`, and `apply_program_edit_plan(...)` with dry-run support.
- Reanalysis helpers are implemented: `reanalyze_region(...)`, `patch_bytes_and_reanalyze(...)`, and `analyze_function_boundaries(...)`.
- Cross-program comparison helpers are implemented: `compare_regions(...)`, `compare_strings(...)`, and `compare_functions(...)`.
- `port_symbols(...)` now ports verified names/comments between programs with provenance text and explicit source/target selectors.

### Class / Namespace / OO Recovery

- Namespace and class authoring helpers are implemented: `create_namespace(...)`, `create_class(...)`, `list_namespace_members(...)`, `move_symbol_to_namespace(...)`, and `set_function_class(...)`.
- Vtable and struct helpers are implemented: `analyze_vtable(...)`, `create_or_update_struct(...)`, `create_or_update_vtable(...)`, and alias coverage such as `build_vtable` / `set_this_type`.
- `set_function_this_type(...)` supports storage-strategy hints and `apply_class_layout(...)` now soft-fails per-method typing with structured warnings instead of aborting the whole batch.

### Prototype And Storage Modeling

- The storage-aware prototype endpoint is implemented as `set_function_prototype_storage(...)` with alias `set_storage_aware_prototype(...)`.
- The endpoint accepts declarative `return_type`, `return_storage`, ordered parameter lines (`name|type|storage`), explicit target selectors, varargs, and machine-friendly warnings when hidden `__return_storage_ptr__` state is still present.
- Source-level fixes landed on 2026-04-06 for the two known live correctness bugs:
  - `stack:` storage is now parsed before generic Ghidra deserialization so workflow-style bare stack offsets are interpreted consistently.
  - exact calling-convention tokens are tried before legacy normalization so 16-bit far conventions such as `__cdecl16far` are not needlessly collapsed to plain `__cdecl` when the exact token is accepted.

### Historical Notes

- If a future pass hits a new MCP gap, add it under `Remaining TODOs` and move it to `Done / Implemented In Local Fork` once the local source and bridge support are both in place.