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

package/CLAUDE_INSTALLATION.md

@@ -0,0 +1,129 @@
+# 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`
+
+## 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 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,16 @@ 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`
+
 If Ghidra is not already configured through `GHIDRA_PATH` or
 `GHIDRA_INSTALL_DIR`, pass it explicitly:
 
@@ -21,11 +31,18 @@ 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
 
 ## Manual configuration example
@@ -41,7 +58,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 +75,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,16 @@ 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`
+
 Build the project first:
 
 ```powershell
@@ -18,6 +28,12 @@ If Ghidra is not already configured in the environment, pass it explicitly:
 .\install-to-copilot.ps1 -GhidraPath "C:\tools\ghidra"
 ```
 
+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 +76,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 +102,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.