windows-exe-decompiler-mcp-server 0.1.0

package/CODEX_INSTALLATION.md

@@ -0,0 +1,69 @@
+# Install in Codex
+
+## Quick start
+
+Build the project first:
+
+```powershell
+npm run build
+```
+
+Then run the helper script from the repository root:
+
+```powershell
+.\install-to-codex.ps1
+```
+
+If Ghidra is not already configured through `GHIDRA_PATH` or
+`GHIDRA_INSTALL_DIR`, pass it explicitly:
+
+```powershell
+.\install-to-codex.ps1 -GhidraPath "C:\tools\ghidra"
+```
+
+## What the script does
+
+- validates that `dist/index.js` exists
+- registers the MCP server with Codex
+- updates `~/.codex/config.toml`
+- writes `GHIDRA_PATH` and `GHIDRA_INSTALL_DIR` when a Ghidra path is provided
+
+## Manual configuration example
+
+If you prefer to edit the config by hand, add a block like this to
+`C:\Users\<you>\.codex\config.toml`:
+
+```toml
+[mcp_servers.windows-exe-decompiler]
+command = "node"
+args = ["E:/path/to/repo/dist/index.js"]
+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" }
+```
+
+## Verify
+
+Run:
+
+```powershell
+codex mcp list
+```
+
+Then ask Codex to call one of these tools:
+
+- `tool.help`
+- `sample.ingest`
+- `workflow.triage`
+
+## Troubleshooting
+
+- `dist/index.js was not found`
+  Run `npm run build` first.
+- `node` was not found
+  Install Node.js or pass `-NodePath`.
+- native analysis is unavailable
+  Set `GHIDRA_PATH` or `GHIDRA_INSTALL_DIR`, or rerun the script with
+  `-GhidraPath`.

package/COPILOT_INSTALLATION.md

@@ -0,0 +1,77 @@
+# Install in GitHub Copilot
+
+This repository includes a helper script for local GitHub Copilot clients:
+
+```powershell
+.\install-to-copilot.ps1
+```
+
+Build the project first:
+
+```powershell
+npm run build
+```
+
+If Ghidra is not already configured in the environment, pass it explicitly:
+
+```powershell
+.\install-to-copilot.ps1 -GhidraPath "C:\tools\ghidra"
+```
+
+## What the script updates
+
+- workspace config: `.vscode/mcp.json`
+- Copilot CLI config: `~/.copilot/mcp-config.json`
+
+You can target only one config:
+
+```powershell
+.\install-to-copilot.ps1 -SkipCopilotCliConfig
+.\install-to-copilot.ps1 -SkipWorkspaceConfig
+```
+
+If the `code` command is available and you also want to try the VS Code
+user-level profile route:
+
+```powershell
+.\install-to-copilot.ps1 -InstallVsCodeUserProfile
+```
+
+## Verify
+
+### VS Code / GitHub Copilot
+
+1. Open the repository in VS Code.
+2. Confirm that `.vscode/mcp.json` contains `windows-exe-decompiler`.
+3. Trust the MCP server when VS Code prompts you.
+4. Ask Copilot to call `tool.help` or `workflow.triage`.
+
+### Copilot CLI
+
+Run:
+
+```text
+/mcp list
+```
+
+or:
+
+```text
+/mcp show windows-exe-decompiler
+```
+
+## 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
+
+## Scope
+
+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.

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -0,0 +1,314 @@
+# Windows EXE Decompiler MCP Server
+
+中文说明见 [`README_zh.md`](./README_zh.md).
+
+An MCP server for Windows binary reverse engineering.
+
+It exposes PE triage, native and .NET analysis, Ghidra-backed function
+inspection, runtime evidence import, reconstruction workflows, and report
+generation as MCP tools that any tool-calling LLM can consume.
+
+## What this project is for
+
+This server is designed to provide a reusable reverse-engineering tool surface
+over MCP instead of one-off local scripts.
+
+Primary use cases:
+
+- Windows PE triage
+- import / export / string / YARA analysis
+- Ghidra-assisted decompile, CFG, and function search
+- .NET metadata inspection
+- runtime trace and memory snapshot import
+- function naming and explanation review workflows
+- source-like reconstruction export with validation harnesses
+
+## Current capability areas
+
+### Static analysis
+
+- `sample.ingest`
+- `sample.profile.get`
+- `pe.fingerprint`
+- `pe.imports.extract`
+- `pe.exports.extract`
+- `strings.extract`
+- `strings.floss.decode`
+- `yara.scan`
+- `runtime.detect`
+- `packer.detect`
+
+### Ghidra and code analysis
+
+- `ghidra.health`
+- `ghidra.analyze`
+- `code.functions.list`
+- `code.functions.rank`
+- `code.functions.search`
+- `code.function.decompile`
+- `code.function.disassemble`
+- `code.function.cfg`
+- `code.functions.reconstruct`
+
+### Reconstruction and review workflows
+
+- `code.reconstruct.plan`
+- `code.reconstruct.export`
+- `dotnet.metadata.extract`
+- `dotnet.types.list`
+- `dotnet.reconstruct.export`
+- `workflow.triage`
+- `workflow.deep_static`
+- `workflow.reconstruct`
+- `workflow.semantic_name_review`
+- `workflow.function_explanation_review`
+
+### Runtime evidence and reporting
+
+- `dynamic.dependencies`
+- `sandbox.execute`
+- `dynamic.trace.import`
+- `dynamic.memory.import`
+- `attack.map`
+- `ioc.export`
+- `report.summarize`
+- `report.generate`
+- `artifacts.list`
+- `artifact.read`
+- `artifacts.diff`
+- `tool.help`
+
+## Project layout
+
+```text
+bin/                         npm CLI entrypoint
+dist/                        compiled TypeScript output
+ghidra_scripts/              Ghidra helper scripts used by the server
+helpers/DotNetMetadataProbe/ .NET metadata helper project
+src/                         TypeScript MCP server source
+tests/                       unit and integration tests
+workers/                     Python worker, YARA rules, dynamic helpers
+install-to-codex.ps1         local Codex MCP install helper
+install-to-copilot.ps1       local GitHub Copilot MCP install helper
+```
+
+## Prerequisites
+
+Required:
+
+- Node.js 18+
+- npm 9+
+- Python 3.9+
+
+Optional but strongly recommended:
+
+- Ghidra for native decompile and CFG features
+- .NET SDK for `dotnet.metadata.extract`
+- Clang for reconstruct export validation
+- Python packages from [`requirements.txt`](./requirements.txt)
+- Python worker packages from [`workers/requirements.txt`](./workers/requirements.txt)
+
+## Local development setup
+
+Install JavaScript dependencies:
+
+```bash
+npm install
+```
+
+Install Python worker dependencies:
+
+```bash
+python -m pip install -r requirements.txt
+python -m pip install -r workers/requirements.txt
+python -m pip install -r workers/requirements-dynamic.txt
+```
+
+Build the server:
+
+```bash
+npm run build
+```
+
+Run tests:
+
+```bash
+npm test
+```
+
+Start the server locally:
+
+```bash
+npm start
+```
+
+## MCP client configuration
+
+### Generic stdio config
+
+Most MCP clients can start this server with:
+
+```json
+{
+  "mcpServers": {
+    "windows-exe-decompiler": {
+      "command": "node",
+      "args": ["/absolute/path/to/repo/dist/index.js"],
+      "cwd": "/absolute/path/to/repo",
+      "env": {
+        "GHIDRA_PATH": "C:/path/to/ghidra",
+        "GHIDRA_INSTALL_DIR": "C:/path/to/ghidra"
+      }
+    }
+  }
+}
+```
+
+### Local install helpers
+
+This repository already includes local install scripts:
+
+- Codex: [`install-to-codex.ps1`](./install-to-codex.ps1)
+- GitHub Copilot: [`install-to-copilot.ps1`](./install-to-copilot.ps1)
+
+Related docs:
+
+- [`CODEX_INSTALLATION.md`](./CODEX_INSTALLATION.md)
+- [`COPILOT_INSTALLATION.md`](./COPILOT_INSTALLATION.md)
+
+## Sample ingest note
+
+For local IDE clients such as VS Code or Copilot, prefer:
+
+```json
+{
+  "tool": "sample.ingest",
+  "arguments": {
+    "path": "E:/absolute/path/to/sample.exe"
+  }
+}
+```
+
+Use `bytes_b64` only when the MCP client cannot access the same filesystem as
+the MCP server.
+
+## Publishing to npm
+
+### What is included in the npm package
+
+The published package includes:
+
+- compiled `dist/`
+- a CLI entrypoint in `bin/`
+- Python workers and YARA rules
+- Ghidra helper scripts
+- the .NET metadata helper source
+- MCP client install scripts
+
+It intentionally excludes:
+
+- tests
+- local workspaces
+- caches
+- generated reports
+- scratch documents and internal progress notes
+
+### Pre-publish checklist
+
+1. Pick a package name that is available on npm.
+2. Update the version in [`package.json`](./package.json).
+3. Run:
+
+```bash
+npm run release:check
+```
+
+4. Inspect the dry-run pack list:
+
+```bash
+npm run pack:dry-run
+```
+
+5. Log in to npm:
+
+```bash
+npm login
+```
+
+6. Publish:
+
+```bash
+npm publish
+```
+
+### GitHub Actions
+
+This repository now includes:
+
+- [`ci.yml`](./.github/workflows/ci.yml): build, Python syntax check, key unit tests, and `npm pack --dry-run`
+- [`publish-npm.yml`](./.github/workflows/publish-npm.yml): publish on `v*` tags or manual dispatch, then create a GitHub Release with the npm tarball attached
+- [`dependabot.yml`](./.github/dependabot.yml): weekly npm and GitHub Actions dependency updates
+
+Before npm publishing from GitHub Actions, add this repository secret:
+
+- `NPM_TOKEN`
+
+Recommended release flow:
+
+```bash
+npm version patch
+git push origin main --follow-tags
+```
+
+That tag push will trigger the publish workflow.
+
+## Contributing
+
+See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for local
+setup, validation, and release steps.
+
+## Security
+
+See [`SECURITY.md`](./SECURITY.md) for disclosure guidance
+and operational boundaries.
+
+### Using the published package
+
+Once published, an MCP client can use `npx`:
+
+```json
+{
+  "mcpServers": {
+    "windows-exe-decompiler": {
+      "command": "npx",
+      "args": ["-y", "windows-exe-decompiler-mcp-server"],
+      "env": {
+        "GHIDRA_PATH": "C:/path/to/ghidra",
+        "GHIDRA_INSTALL_DIR": "C:/path/to/ghidra"
+      }
+    }
+  }
+}
+```
+
+## Security boundaries
+
+This project is designed for analysis workflows, not for live malware
+operations. Current practical strengths are:
+
+- triage and classification support
+- reverse-engineering evidence extraction
+- IOC and ATT&CK export
+- runtime evidence import and correlation
+- source-like reconstruction and review
+
+Current non-goals:
+
+- original source recovery for complex native binaries
+- guaranteed malware family attribution from static evidence alone
+- full automatic unpacking for all packers
+- high-confidence semantic recovery of every function in heavily optimized code
+
+## License
+
+This project is released under the MIT license. See [`LICENSE`](./LICENSE).

package/bin/windows-exe-decompiler-mcp-server.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import '../dist/index.js'

package/dist/analysis-provenance.d.ts

@@ -0,0 +1,184 @@
+import { z } from 'zod';
+import type { DynamicEvidenceScope, DynamicTraceSummary } from './dynamic-trace.js';
+import type { SemanticArtifactScope, SemanticFunctionExplanationIndex, SemanticNameSuggestionIndex } from './semantic-name-suggestion-artifacts.js';
+export declare const ArtifactSelectionProvenanceSchema: z.ZodObject<{
+    scope: z.ZodEnum<["all", "latest", "session"]>;
+    session_selector: z.ZodNullable<z.ZodString>;
+    artifact_count: z.ZodNumber;
+    artifact_ids: z.ZodArray<z.ZodString, "many">;
+    session_tags: z.ZodArray<z.ZodString, "many">;
+    earliest_artifact_at: z.ZodNullable<z.ZodString>;
+    latest_artifact_at: z.ZodNullable<z.ZodString>;
+    scope_note: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    artifact_count: number;
+    scope_note: string;
+    artifact_ids: string[];
+    session_selector: string | null;
+    session_tags: string[];
+    scope: "all" | "latest" | "session";
+    earliest_artifact_at: string | null;
+    latest_artifact_at: string | null;
+}, {
+    artifact_count: number;
+    scope_note: string;
+    artifact_ids: string[];
+    session_selector: string | null;
+    session_tags: string[];
+    scope: "all" | "latest" | "session";
+    earliest_artifact_at: string | null;
+    latest_artifact_at: string | null;
+}>;
+export declare const AnalysisProvenanceSchema: z.ZodObject<{
+    runtime: z.ZodObject<{
+        scope: z.ZodEnum<["all", "latest", "session"]>;
+        session_selector: z.ZodNullable<z.ZodString>;
+        artifact_count: z.ZodNumber;
+        artifact_ids: z.ZodArray<z.ZodString, "many">;
+        session_tags: z.ZodArray<z.ZodString, "many">;
+        earliest_artifact_at: z.ZodNullable<z.ZodString>;
+        latest_artifact_at: z.ZodNullable<z.ZodString>;
+        scope_note: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        artifact_count: number;
+        scope_note: string;
+        artifact_ids: string[];
+        session_selector: string | null;
+        session_tags: string[];
+        scope: "all" | "latest" | "session";
+        earliest_artifact_at: string | null;
+        latest_artifact_at: string | null;
+    }, {
+        artifact_count: number;
+        scope_note: string;
+        artifact_ids: string[];
+        session_selector: string | null;
+        session_tags: string[];
+        scope: "all" | "latest" | "session";
+        earliest_artifact_at: string | null;
+        latest_artifact_at: string | null;
+    }>;
+    semantic_names: z.ZodOptional<z.ZodObject<{
+        scope: z.ZodEnum<["all", "latest", "session"]>;
+        session_selector: z.ZodNullable<z.ZodString>;
+        artifact_count: z.ZodNumber;
+        artifact_ids: z.ZodArray<z.ZodString, "many">;
+        session_tags: z.ZodArray<z.ZodString, "many">;
+        earliest_artifact_at: z.ZodNullable<z.ZodString>;
+        latest_artifact_at: z.ZodNullable<z.ZodString>;
+        scope_note: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        artifact_count: number;
+        scope_note: string;
+        artifact_ids: string[];
+        session_selector: string | null;
+        session_tags: string[];
+        scope: "all" | "latest" | "session";
+        earliest_artifact_at: string | null;
+        latest_artifact_at: string | null;
+    }, {
+        artifact_count: number;
+        scope_note: string;
+        artifact_ids: string[];
+        session_selector: string | null;
+        session_tags: string[];
+        scope: "all" | "latest" | "session";
+        earliest_artifact_at: string | null;
+        latest_artifact_at: string | null;
+    }>>;
+    semantic_explanations: z.ZodOptional<z.ZodObject<{
+        scope: z.ZodEnum<["all", "latest", "session"]>;
+        session_selector: z.ZodNullable<z.ZodString>;
+        artifact_count: z.ZodNumber;
+        artifact_ids: z.ZodArray<z.ZodString, "many">;
+        session_tags: z.ZodArray<z.ZodString, "many">;
+        earliest_artifact_at: z.ZodNullable<z.ZodString>;
+        latest_artifact_at: z.ZodNullable<z.ZodString>;
+        scope_note: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        artifact_count: number;
+        scope_note: string;
+        artifact_ids: string[];
+        session_selector: string | null;
+        session_tags: string[];
+        scope: "all" | "latest" | "session";
+        earliest_artifact_at: string | null;
+        latest_artifact_at: string | null;
+    }, {
+        artifact_count: number;
+        scope_note: string;
+        artifact_ids: string[];
+        session_selector: string | null;
+        session_tags: string[];
+        scope: "all" | "latest" | "session";
+        earliest_artifact_at: string | null;
+        latest_artifact_at: string | null;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    runtime: {
+        artifact_count: number;
+        scope_note: string;
+        artifact_ids: string[];
+        session_selector: string | null;
+        session_tags: string[];
+        scope: "all" | "latest" | "session";
+        earliest_artifact_at: string | null;
+        latest_artifact_at: string | null;
+    };
+    semantic_names?: {
+        artifact_count: number;
+        scope_note: string;
+        artifact_ids: string[];
+        session_selector: string | null;
+        session_tags: string[];
+        scope: "all" | "latest" | "session";
+        earliest_artifact_at: string | null;
+        latest_artifact_at: string | null;
+    } | undefined;
+    semantic_explanations?: {
+        artifact_count: number;
+        scope_note: string;
+        artifact_ids: string[];
+        session_selector: string | null;
+        session_tags: string[];
+        scope: "all" | "latest" | "session";
+        earliest_artifact_at: string | null;
+        latest_artifact_at: string | null;
+    } | undefined;
+}, {
+    runtime: {
+        artifact_count: number;
+        scope_note: string;
+        artifact_ids: string[];
+        session_selector: string | null;
+        session_tags: string[];
+        scope: "all" | "latest" | "session";
+        earliest_artifact_at: string | null;
+        latest_artifact_at: string | null;
+    };
+    semantic_names?: {
+        artifact_count: number;
+        scope_note: string;
+        artifact_ids: string[];
+        session_selector: string | null;
+        session_tags: string[];
+        scope: "all" | "latest" | "session";
+        earliest_artifact_at: string | null;
+        latest_artifact_at: string | null;
+    } | undefined;
+    semantic_explanations?: {
+        artifact_count: number;
+        scope_note: string;
+        artifact_ids: string[];
+        session_selector: string | null;
+        session_tags: string[];
+        scope: "all" | "latest" | "session";
+        earliest_artifact_at: string | null;
+        latest_artifact_at: string | null;
+    } | undefined;
+}>;
+type ArtifactSelectionProvenance = z.infer<typeof ArtifactSelectionProvenanceSchema>;
+export declare function buildRuntimeArtifactProvenance(dynamicEvidence: DynamicTraceSummary | null | undefined, scope: DynamicEvidenceScope, sessionTag?: string | null): ArtifactSelectionProvenance;
+export declare function buildSemanticArtifactProvenance(label: 'semantic naming artifacts' | 'semantic explanation artifacts', index: SemanticNameSuggestionIndex | SemanticFunctionExplanationIndex | null | undefined, scope: SemanticArtifactScope, sessionTag?: string | null): ArtifactSelectionProvenance;
+export {};
+//# sourceMappingURL=analysis-provenance.d.ts.map