windows-exe-decompiler-mcp-server 0.1.1 → 0.1.4

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on Keep a Changelog, and this project follows Semantic
+Versioning where practical.
+
+## [Unreleased]
+
+## [0.1.4] - 2026-03-14
+
+- Added safer Ghidra defaults for `GHIDRA_PROJECT_ROOT` / `GHIDRA_LOG_ROOT`, automatic project-parent creation, and safer Windows defaults that avoid unstable per-repo relative paths
+- Fixed bundled `ghidra_scripts` resolution so helper scripts are loaded from the installed package or repository root instead of the current working directory
+- Added richer Ghidra diagnostics: persisted command/runtime logs, parsed Java exception summaries, normalized remediation hints, and stage progress callbacks for queued analysis
+- Surfaced structured `ghidra_execution` summaries through `workflow.reconstruct`, `workflow.semantic_name_review`, `workflow.function_explanation_review`, `workflow.module_reconstruction_review`, `report.summarize`, and `report.generate`
+- Added Java runtime detection and Java 21+ setup guidance across `ghidra.health`, `system.health`, `system.setup.guide`, and high-level workflows
+- Extended module reconstruction review refresh so all three high-level semantic review workflows now expose the same Ghidra project/log/progress context after export refresh
+- Stabilized unit coverage for Ghidra analysis failure handling, timeout reporting, Java fallback extraction, and degraded function-index recovery
+
+## [0.1.3] - 2026-03-14
+
+- Added DLL- and COM-oriented profiling with `dll.export.profile` and `com.role.profile`
+- Added module-level LLM review primitives: `code.module.review.prepare`, `code.module.review`, `code.module.review.apply`, prompt `reverse.module_reconstruction_review`, and `workflow.module_reconstruction_review`
+- Extended `workflow.reconstruct` with role-aware export strategy so DLL/COM/Rust preflight can influence module grouping and reconstruction priority
+- Improved runtime memory ingestion with segment/module hints, region ownership, and richer runtime provenance
+- Added structured setup guidance with `system.setup.guide` and surfaced install/input requirements from health checks and high-level workflows
+- Refined README, installation docs, and release packaging for the `0.1.3` npm/GitHub release
+
+## [0.1.2] - 2026-03-12
+
+- Upgraded `workflow.reconstruct` with universal preflight orchestration, including binary role profiling, Rust-specific profiling, and optional automatic function-index recovery before export
+- Aligned `workflow.semantic_name_review` and `workflow.function_explanation_review` with reconstruct refresh preflight, provenance, and selection diff semantics
+- Added `.pdata`-driven PE recovery tooling: `pe.pdata.extract`, `code.functions.smart_recover`, `pe.symbols.recover`, and `code.functions.define`
+- Added `workflow.function_index_recover` and `rust_binary.analyze` to make Rust and hard-to-index native samples recoverable even when Ghidra function extraction fails
+- Hardened sample/original and Ghidra project fallback handling so analysis can continue when older workspaces are incomplete
+- Stabilized runtime state defaults by moving workspace, database, cache, and audit paths to persistent user-level configuration roots
+
+## [0.1.1] - 2026-03-11
+
+- Added `binary.role.profile` for universal EXE/DLL/.NET/driver role profiling, export surface triage, and COM/service/plugin indicators
+- Added quality scaffolding with benchmark corpus example and evaluation guidance for future regression baselines
+- Added async job mode for `workflow.reconstruct`, `workflow.semantic_name_review`, and `workflow.function_explanation_review`
+- Wired queued workflow execution into the background analysis task runner
+- Integrated binary role profile output into `report.summarize` and `report.generate`
+- Added report coverage for runtime/semantic provenance plus binary role context in generated markdown and JSON output
+- Continued repository and packaging cleanup for public GitHub/npm release
+
+## [0.1.0] - 2026-03-11
+
+- Initial public packaging baseline
+- MCP server with static PE analysis, Ghidra integration hooks, runtime evidence tools, and reconstruction workflows

package/CLAUDE_INSTALLATION.md

@@ -0,0 +1,143 @@
+# Claude Installation
+
+This repository can be installed into Claude Code as an MCP server in three
+scopes:
+
+- `local`: machine-local config for the current project, stored in
+  `~/.claude.json`
+- `user`: machine-wide config for your user, stored in `~/.claude.json`
+- `project`: project-scoped config written to `.mcp.json` in the repo root
+
+On this Windows setup, writing the config file directly is more reliable than
+shelling out to `claude mcp add`, so the install script uses the config-file
+path directly and then verifies the result with `claude mcp get`.
+
+## Prerequisites
+
+- Claude Code CLI installed and available as `claude`
+- Node.js available as `node`
+- Project already built with `npm run build`
+
+## Recommended Install
+
+From the repository root:
+
+```powershell
+.\install-to-claude.ps1
+```
+
+The default scope is `user`, so this installs the server once for your account
+and makes it available in all Claude Code projects on this machine.
+
+The script also writes a stable `WORKSPACE_ROOT` by default:
+
+- `%USERPROFILE%/.windows-exe-decompiler-mcp-server/workspaces`
+
+It also pins:
+
+- `DB_PATH`
+- `CACHE_ROOT`
+- `AUDIT_LOG_PATH`
+- `GHIDRA_PROJECT_ROOT`
+- `GHIDRA_LOG_ROOT`
+
+The server's bundled `ghidra_scripts/` directory is resolved from the installed
+package or repository root, not from the shell's current working directory. You
+do not need to manually point Claude at `ExtractFunctions.py`.
+
+For Ghidra 12.0.4, keep Java 21+ available. If Java is installed outside the
+system default location, also set `JAVA_HOME`.
+
+## Pass Ghidra Explicitly
+
+```powershell
+.\install-to-claude.ps1 -GhidraPath "C:\path\to\ghidra"
+```
+
+The script writes both `GHIDRA_PATH` and `GHIDRA_INSTALL_DIR`.
+
+If you want to pin Ghidra project/log roots explicitly, set:
+
+- `GHIDRA_PROJECT_ROOT`
+- `GHIDRA_LOG_ROOT`
+
+If you want a different persistent workspace root:
+
+```powershell
+.\install-to-claude.ps1 -WorkspaceRoot "D:\reverse-data\workspaces"
+```
+
+## Change Scope
+
+Examples:
+
+```powershell
+.\install-to-claude.ps1 -Scope local
+.\install-to-claude.ps1 -Scope user
+.\install-to-claude.ps1 -Scope project
+```
+
+If you choose `project`, the script writes `.mcp.json` into the repository
+root. If you choose `local` or `user`, the script updates `~/.claude.json`.
+Use `local` only when you want this repo to override the global `user`
+registration.
+
+If both `user` and `local` registrations exist, Claude will show the `local`
+scope while you are inside that repository, and the `user` scope everywhere
+else.
+
+## Manual Config Format
+
+Claude Code recognizes the standard MCP config shape:
+
+```json
+{
+  "mcpServers": {
+    "windows-exe-decompiler": {
+      "command": "node",
+      "args": ["E:/Playground/Reverse/dist/index.js"],
+      "cwd": "E:/Playground/Reverse",
+      "env": {
+        "WORKSPACE_ROOT": "C:/Users/<you>/.windows-exe-decompiler-mcp-server/workspaces",
+        "GHIDRA_PATH": "C:/path/to/ghidra",
+        "GHIDRA_INSTALL_DIR": "C:/path/to/ghidra"
+      }
+    }
+  }
+}
+```
+
+That same server object works in:
+
+- repo-local `.mcp.json` for `project` scope
+- top-level `mcpServers` in `~/.claude.json` for `user` scope
+- `projects["E:/path/to/repo"].mcpServers` in `~/.claude.json` for `local`
+  scope
+
+## Verify
+
+```powershell
+claude mcp list
+claude mcp get windows-exe-decompiler
+```
+
+If you used `project` scope, `claude mcp get` should report `Scope: Project
+config (shared via .mcp.json)`. If you used `local` or `user`, it should report
+the corresponding Claude config scope from `~/.claude.json`.
+
+## First-run setup guidance
+
+If Claude can connect to the MCP server but reports missing Python packages,
+dynamic-analysis extras, or Ghidra configuration, ask it to call:
+
+- `system.setup.guide`
+- `system.health`
+- `ghidra.health`
+
+These tools return structured `setup_actions` and `required_user_inputs`
+instead of only failing with a generic error.
+
+## References
+
+- Claude Code MCP overview: https://docs.anthropic.com/en/docs/claude-code/mcp
+- Claude Code MCP management and CLI behavior: https://docs.anthropic.com/en/docs/claude-code/mcp#manage-mcp-servers

package/CODEX_INSTALLATION.md

@@ -14,6 +14,25 @@ Then run the helper script from the repository root:
 .\install-to-codex.ps1
 ```
 
+By default, the script writes a stable `WORKSPACE_ROOT` under your user profile:
+
+- `%USERPROFILE%/.windows-exe-decompiler-mcp-server/workspaces`
+
+It also pins:
+
+- `DB_PATH`
+- `CACHE_ROOT`
+- `AUDIT_LOG_PATH`
+- `GHIDRA_PROJECT_ROOT`
+- `GHIDRA_LOG_ROOT`
+
+The server's bundled `ghidra_scripts/` directory is resolved from the installed
+package or repository root, not from the shell's current working directory. You
+do not need to manually configure a script path for `ExtractFunctions.py`.
+
+For Ghidra 12.0.4, keep Java 21+ available. If Java is installed in a custom
+location, set `JAVA_HOME` before starting Codex.
+
 If Ghidra is not already configured through `GHIDRA_PATH` or
 `GHIDRA_INSTALL_DIR`, pass it explicitly:
 
@@ -21,12 +40,21 @@ If Ghidra is not already configured through `GHIDRA_PATH` or
 .\install-to-codex.ps1 -GhidraPath "C:\tools\ghidra"
 ```
 
+If you want a different persistent workspace root:
+
+```powershell
+.\install-to-codex.ps1 -WorkspaceRoot "D:\reverse-data\workspaces"
+```
+
 ## What the script does
 
 - validates that `dist/index.js` exists
 - registers the MCP server with Codex
 - updates `~/.codex/config.toml`
+- writes `WORKSPACE_ROOT` so workspaces do not depend on the current repo path
 - writes `GHIDRA_PATH` and `GHIDRA_INSTALL_DIR` when a Ghidra path is provided
+- honors `GHIDRA_PROJECT_ROOT` and `GHIDRA_LOG_ROOT` when you want Ghidra
+  projects and runtime logs under a fixed location
 
 ## Manual configuration example
 
@@ -41,7 +69,7 @@ cwd = "E:/path/to/repo"
 startup_timeout_sec = 30
 tool_timeout_sec = 300
 enabled = true
-env = { GHIDRA_PATH = "C:/tools/ghidra", GHIDRA_INSTALL_DIR = "C:/tools/ghidra" }
+env = { WORKSPACE_ROOT = "C:/Users/<you>/.windows-exe-decompiler-mcp-server/workspaces", GHIDRA_PATH = "C:/tools/ghidra", GHIDRA_INSTALL_DIR = "C:/tools/ghidra" }
 ```
 
 ## Verify
@@ -58,6 +86,13 @@ Then ask Codex to call one of these tools:
 - `sample.ingest`
 - `workflow.triage`
 
+If Codex reports missing Python packages, dynamic-analysis extras, or Ghidra
+configuration, ask it to call:
+
+- `system.setup.guide`
+- `system.health`
+- `ghidra.health`
+
 ## Troubleshooting
 
 - `dist/index.js was not found`

package/COPILOT_INSTALLATION.md

@@ -6,6 +6,25 @@ This repository includes a helper script for local GitHub Copilot clients:
 .\install-to-copilot.ps1
 ```
 
+By default, the script writes a stable `WORKSPACE_ROOT` under your user profile:
+
+- `%USERPROFILE%/.windows-exe-decompiler-mcp-server/workspaces`
+
+It also pins:
+
+- `DB_PATH`
+- `CACHE_ROOT`
+- `AUDIT_LOG_PATH`
+- `GHIDRA_PROJECT_ROOT`
+- `GHIDRA_LOG_ROOT`
+
+The server's bundled `ghidra_scripts/` directory is resolved from the installed
+package or repository root, not from the shell's current working directory. You
+do not need to separately point Copilot at `ExtractFunctions.py`.
+
+For Ghidra 12.0.4, keep Java 21+ available. If Java is installed outside the
+default system location, set `JAVA_HOME` before launching Copilot clients.
+
 Build the project first:
 
 ```powershell
@@ -18,6 +37,17 @@ If Ghidra is not already configured in the environment, pass it explicitly:
 .\install-to-copilot.ps1 -GhidraPath "C:\tools\ghidra"
 ```
 
+If you want to pin Ghidra projects and logs under a fixed location, set:
+
+- `GHIDRA_PROJECT_ROOT`
+- `GHIDRA_LOG_ROOT`
+
+If you want a different persistent workspace root:
+
+```powershell
+.\install-to-copilot.ps1 -WorkspaceRoot "D:\reverse-data\workspaces"
+```
+
 ## What the script updates
 
 - workspace config: `.vscode/mcp.json`
@@ -60,12 +90,24 @@ or:
 /mcp show windows-exe-decompiler
 ```
 
+## First-run setup guidance
+
+If Copilot can reach the MCP server but the server reports missing Python
+packages, dynamic-analysis extras, or Ghidra configuration, ask Copilot to call:
+
+- `system.setup.guide`
+- `system.health`
+- `ghidra.health`
+
+These tools return structured setup actions and missing user inputs.
+
 ## References
 
 - https://code.visualstudio.com/docs/copilot/customization/mcp-servers
 - https://code.visualstudio.com/docs/copilot/reference/mcp-configuration
 - https://docs.github.com/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers
 - https://docs.github.com/en/enterprise-cloud@latest/copilot/reference/cli-command-reference
+- https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/extend-coding-agent-with-mcp
 
 ## Scope
 
@@ -74,4 +116,4 @@ These instructions are for local Copilot clients such as:
 - VS Code with GitHub Copilot
 - GitHub Copilot CLI
 
-They do not configure GitHub.com hosted coding agents.
+They do not configure GitHub.com hosted coding agents. For hosted coding-agent MCP setup, use the GitHub MCP coding-agent documentation linked above.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.