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

package/dist/tools/system-setup-guide.js

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+import { RequiredUserInputSchema, SetupActionSchema, buildAllSetupActions, buildBaselinePythonSetupActions, buildDynamicDependencySetupActions, buildGhidraRequiredUserInputs, buildGhidraSetupActions, buildPyGhidraSetupActions, mergeRequiredUserInputs, mergeSetupActions, } from '../setup-guidance.js';
+const TOOL_NAME = 'system.setup.guide';
+export const systemSetupGuideInputSchema = z.object({
+    focus: z
+        .enum(['all', 'python', 'dynamic', 'ghidra'])
+        .default('all')
+        .describe('Which setup area to describe. Use all for a first-run bootstrap guide.'),
+    include_optional: z
+        .boolean()
+        .default(true)
+        .describe('Include optional setup actions such as PyGhidra and dynamic-analysis extras.'),
+});
+export const systemSetupGuideOutputSchema = z.object({
+    ok: z.boolean(),
+    data: z.object({
+        focus: z.enum(['all', 'python', 'dynamic', 'ghidra']),
+        setup_actions: z.array(SetupActionSchema),
+        required_user_inputs: z.array(RequiredUserInputSchema),
+        notes: z.array(z.string()),
+    }),
+    errors: z.array(z.string()).optional(),
+});
+export const systemSetupGuideToolDefinition = {
+    name: TOOL_NAME,
+    description: 'Explain required bootstrap steps, including pip install commands and user-supplied paths such as GHIDRA_PATH.',
+    inputSchema: systemSetupGuideInputSchema,
+    outputSchema: systemSetupGuideOutputSchema,
+};
+export function createSystemSetupGuideHandler() {
+    return async (args) => {
+        const input = systemSetupGuideInputSchema.parse(args);
+        let setupActions = buildAllSetupActions(input.include_optional);
+        let requiredUserInputs = buildGhidraRequiredUserInputs();
+        const notes = [
+            'Prefer absolute paths when providing tool locations such as the Ghidra installation directory.',
+            'If your MCP client can read the local filesystem, prefer sample.ingest(path=...) over bytes_b64.',
+        ];
+        if (input.focus === 'python') {
+            setupActions = mergeSetupActions(buildBaselinePythonSetupActions());
+            requiredUserInputs = [];
+        }
+        else if (input.focus === 'dynamic') {
+            setupActions = mergeSetupActions(buildBaselinePythonSetupActions(), input.include_optional ? buildDynamicDependencySetupActions() : []);
+            requiredUserInputs = [];
+        }
+        else if (input.focus === 'ghidra') {
+            setupActions = mergeSetupActions(buildGhidraSetupActions(), input.include_optional ? buildPyGhidraSetupActions() : []);
+            requiredUserInputs = mergeRequiredUserInputs(buildGhidraRequiredUserInputs());
+        }
+        return {
+            ok: true,
+            data: {
+                focus: input.focus,
+                setup_actions: setupActions,
+                required_user_inputs: requiredUserInputs,
+                notes,
+            },
+        };
+    };
+}
+//# sourceMappingURL=system-setup-guide.js.map

package/dist/tools/tool-help.d.ts

@@ -52,7 +52,6 @@ export declare const toolHelpOutputSchema: z.ZodObject<{
                     enum_values?: string[] | undefined;
                 }>, "many">;
             }, "strip", z.ZodTypeAny, {
-                field_count: number;
                 fields: {
                     path: string;
                     type: string;
@@ -63,8 +62,8 @@ export declare const toolHelpOutputSchema: z.ZodObject<{
                     default_value?: any;
                     enum_values?: string[] | undefined;
                 }[];
-            }, {
                 field_count: number;
+            }, {
                 fields: {
                     path: string;
                     type: string;
@@ -75,6 +74,7 @@ export declare const toolHelpOutputSchema: z.ZodObject<{
                     default_value?: any;
                     enum_values?: string[] | undefined;
                 }[];
+                field_count: number;
             }>>;
             output: z.ZodOptional<z.ZodObject<{
                 field_count: z.ZodNumber;
@@ -107,7 +107,6 @@ export declare const toolHelpOutputSchema: z.ZodObject<{
                     enum_values?: string[] | undefined;
                 }>, "many">;
             }, "strip", z.ZodTypeAny, {
-                field_count: number;
                 fields: {
                     path: string;
                     type: string;
@@ -118,8 +117,8 @@ export declare const toolHelpOutputSchema: z.ZodObject<{
                     default_value?: any;
                     enum_values?: string[] | undefined;
                 }[];
-            }, {
                 field_count: number;
+            }, {
                 fields: {
                     path: string;
                     type: string;
@@ -130,12 +129,12 @@ export declare const toolHelpOutputSchema: z.ZodObject<{
                     default_value?: any;
                     enum_values?: string[] | undefined;
                 }[];
+                field_count: number;
             }>>;
         }, "strip", z.ZodTypeAny, {
             name: string;
             description: string;
             output?: {
-                field_count: number;
                 fields: {
                     path: string;
                     type: string;
@@ -146,9 +145,9 @@ export declare const toolHelpOutputSchema: z.ZodObject<{
                     default_value?: any;
                     enum_values?: string[] | undefined;
                 }[];
+                field_count: number;
             } | undefined;
             input?: {
-                field_count: number;
                 fields: {
                     path: string;
                     type: string;
@@ -159,13 +158,13 @@ export declare const toolHelpOutputSchema: z.ZodObject<{
                     default_value?: any;
                     enum_values?: string[] | undefined;
                 }[];
+                field_count: number;
             } | undefined;
             usage_notes?: string[] | undefined;
         }, {
             name: string;
             description: string;
             output?: {
-                field_count: number;
                 fields: {
                     path: string;
                     type: string;
@@ -176,9 +175,9 @@ export declare const toolHelpOutputSchema: z.ZodObject<{
                     default_value?: any;
                     enum_values?: string[] | undefined;
                 }[];
+                field_count: number;
             } | undefined;
             input?: {
-                field_count: number;
                 fields: {
                     path: string;
                     type: string;
@@ -189,6 +188,7 @@ export declare const toolHelpOutputSchema: z.ZodObject<{
                     default_value?: any;
                     enum_values?: string[] | undefined;
                 }[];
+                field_count: number;
             } | undefined;
             usage_notes?: string[] | undefined;
         }>, "many">;
@@ -198,7 +198,6 @@ export declare const toolHelpOutputSchema: z.ZodObject<{
             name: string;
             description: string;
             output?: {
-                field_count: number;
                 fields: {
                     path: string;
                     type: string;
@@ -209,9 +208,9 @@ export declare const toolHelpOutputSchema: z.ZodObject<{
                     default_value?: any;
                     enum_values?: string[] | undefined;
                 }[];
+                field_count: number;
             } | undefined;
             input?: {
-                field_count: number;
                 fields: {
                     path: string;
                     type: string;
@@ -222,6 +221,7 @@ export declare const toolHelpOutputSchema: z.ZodObject<{
                     default_value?: any;
                     enum_values?: string[] | undefined;
                 }[];
+                field_count: number;
             } | undefined;
             usage_notes?: string[] | undefined;
         }[];
@@ -231,7 +231,6 @@ export declare const toolHelpOutputSchema: z.ZodObject<{
             name: string;
             description: string;
             output?: {
-                field_count: number;
                 fields: {
                     path: string;
                     type: string;
@@ -242,9 +241,9 @@ export declare const toolHelpOutputSchema: z.ZodObject<{
                     default_value?: any;
                     enum_values?: string[] | undefined;
                 }[];
+                field_count: number;
             } | undefined;
             input?: {
-                field_count: number;
                 fields: {
                     path: string;
                     type: string;
@@ -255,6 +254,7 @@ export declare const toolHelpOutputSchema: z.ZodObject<{
                     default_value?: any;
                     enum_values?: string[] | undefined;
                 }[];
+                field_count: number;
             } | undefined;
             usage_notes?: string[] | undefined;
         }[];
@@ -267,7 +267,6 @@ export declare const toolHelpOutputSchema: z.ZodObject<{
             name: string;
             description: string;
             output?: {
-                field_count: number;
                 fields: {
                     path: string;
                     type: string;
@@ -278,9 +277,9 @@ export declare const toolHelpOutputSchema: z.ZodObject<{
                     default_value?: any;
                     enum_values?: string[] | undefined;
                 }[];
+                field_count: number;
             } | undefined;
             input?: {
-                field_count: number;
                 fields: {
                     path: string;
                     type: string;
@@ -291,6 +290,7 @@ export declare const toolHelpOutputSchema: z.ZodObject<{
                     default_value?: any;
                     enum_values?: string[] | undefined;
                 }[];
+                field_count: number;
             } | undefined;
             usage_notes?: string[] | undefined;
         }[];
@@ -304,7 +304,6 @@ export declare const toolHelpOutputSchema: z.ZodObject<{
             name: string;
             description: string;
             output?: {
-                field_count: number;
                 fields: {
                     path: string;
                     type: string;
@@ -315,9 +314,9 @@ export declare const toolHelpOutputSchema: z.ZodObject<{
                     default_value?: any;
                     enum_values?: string[] | undefined;
                 }[];
+                field_count: number;
             } | undefined;
             input?: {
-                field_count: number;
                 fields: {
                     path: string;
                     type: string;
@@ -328,6 +327,7 @@ export declare const toolHelpOutputSchema: z.ZodObject<{
                     default_value?: any;
                     enum_values?: string[] | undefined;
                 }[];
+                field_count: number;
             } | undefined;
             usage_notes?: string[] | undefined;
         }[];

package/dist/tools/tool-help.js

@@ -158,6 +158,124 @@ function buildFieldHelpHint(path, toolName) {
             return 'Optional display/original filename. Useful when ingesting from bytes_b64 because there is no source path-derived filename.';
         }
     }
+    if (toolName === 'binary.role.profile') {
+        if (path === 'max_exports') {
+            return 'Controls how many exports/forwarders are surfaced in the summarized DLL or EXE export map.';
+        }
+        if (path === 'max_strings') {
+            return 'Controls how many strings are inspected for COM/service/plugin heuristics. Increase when profiling installer/plugin-heavy samples.';
+        }
+    }
+    if (toolName === 'dll.export.profile') {
+        if (path === 'sample_id') {
+            return 'Use this when you want a DLL-first view of exports, callback surfaces, DllMain lifecycle hints, and host/plugin style invocation patterns.';
+        }
+        if (path === 'max_exports') {
+            return 'Increase this for DLLs with broad export surfaces, command dispatch tables, or heavy use of forwarded exports.';
+        }
+    }
+    if (toolName === 'com.role.profile') {
+        if (path === 'sample_id') {
+            return 'Use this when a PE sample looks like a COM server or exposes registration/class-factory style exports.';
+        }
+        if (path === 'max_strings') {
+            return 'Increase this when CLSID, ProgID, InprocServer32, or interface strings are sparse and you need stronger COM confidence.';
+        }
+    }
+    if (toolName === 'ghidra.analyze') {
+        if (path === 'options.processor') {
+            return 'Use this when you want analyzeHeadless to force a specific processor/language family. Prefer options.language_id when you already know the exact Ghidra language ID.';
+        }
+        if (path === 'options.language_id') {
+            return 'Useful for Rust/Go/C++ binaries when auto-detection under-identifies functions. Example: x86:LE:64:default.';
+        }
+        if (path === 'options.cspec') {
+            return 'Optional compiler specification override. Use only when the default calling-convention model is clearly wrong.';
+        }
+        if (path === 'options.script_paths') {
+            return 'Appends additional post-script directories to the default Ghidra script path. Useful for custom Rust-aware extraction scripts.';
+        }
+    }
+    if (toolName === 'pe.pdata.extract') {
+        if (path === 'sample_id') {
+            return 'Use this first when a PE32+ / Rust sample has zero Ghidra functions. It reads the exception directory / .pdata directly without requiring Ghidra function discovery.';
+        }
+    }
+    if (toolName === 'code.functions.smart_recover') {
+        if (path === 'sample_id') {
+            return 'Use this when Ghidra function extraction fails or returns zero functions. It recovers candidate boundaries from .pdata, exports, and the entry point.';
+        }
+    }
+    if (toolName === 'pe.symbols.recover') {
+        if (path === 'sample_id') {
+            return 'Use this after pe.pdata.extract or code.functions.smart_recover when you need more descriptive recovered symbol names for Rust/Go/C++ binaries.';
+        }
+        if (path === 'max_string_hints') {
+            return 'Increase this when you want more Rust crate path or runtime string hints to influence recovered names.';
+        }
+    }
+    if (toolName === 'code.functions.define') {
+        if (path === 'definitions') {
+            return 'Accepts manual definitions or outputs adapted from code.functions.smart_recover / pe.symbols.recover. Each entry needs address, va, or rva.';
+        }
+        if (path === 'replace_all') {
+            return 'When true, the current function index for this sample is deleted before the imported definitions are inserted.';
+        }
+        if (path === 'source') {
+            return 'Use pdata, symbols_recover, smart_recover, manual, or external so later reports clearly show where this function index came from.';
+        }
+    }
+    if (toolName === 'rust_binary.analyze') {
+        if (path === 'sample_id') {
+            return 'Use this as a high-level Rust triage entrypoint when a PE sample looks Rust-like or Ghidra returns zero functions.';
+        }
+        if (path === 'max_strings') {
+            return 'Increase this when Rust crate paths, panic strings, or async/runtime markers are sparse and you need stronger crate/runtime evidence.';
+        }
+        if (path === 'max_symbol_preview') {
+            return 'Controls how many recovered symbol names are surfaced from pe.symbols.recover in one response.';
+        }
+    }
+    if (toolName === 'workflow.function_index_recover') {
+        if (path === 'define_from') {
+            return 'auto prefers pe.symbols.recover names when available; smart_recover keeps synthetic/import/export-derived names only.';
+        }
+        if (path === 'max_string_hints') {
+            return 'Forwarded to pe.symbols.recover so recovered names can use more Rust/Go/C++ crate and runtime hints.';
+        }
+        if (path === 'replace_all') {
+            return 'Recommended when you want the recovered index to replace an empty or stale function index from a failed Ghidra run.';
+        }
+    }
+    if (toolName === 'code.module.review.prepare') {
+        if (path === 'sample_id') {
+            return 'Use this when reconstruct already produces grouped modules and you want an external LLM to review module roles, summaries, and rewrite guidance.';
+        }
+        if (path === 'role_target') {
+            return 'Forward a binary-role hint such as dll_library, com_server, or native_rust_executable so module preparation keeps role-aware modules visible.';
+        }
+    }
+    if (toolName === 'code.module.review') {
+        if (path === 'role_focus_areas') {
+            return 'Useful for DLL/COM/plugin samples when you want module review to emphasize export dispatch, class factory, callback surface, or lifecycle modules.';
+        }
+    }
+    if (toolName === 'workflow.module_reconstruction_review') {
+        if (path === 'rerun_export') {
+            return 'When true, the workflow refreshes reconstruct/export after module reviews are applied so rewrite headers and reverse_notes.md reflect the new module guidance.';
+        }
+        if (path === 'export_path') {
+            return 'auto is usually correct. Override to native or dotnet only when you already know the reconstruction path that should be refreshed after module review.';
+        }
+    }
+    if (toolName === 'system.setup.guide') {
+        if (path === 'focus') {
+            return 'Use all for a first-run bootstrap guide, ghidra when you specifically need the install path/environment guidance, and dynamic when you only need runtime-analysis extras.';
+        }
+        if (path === 'include_optional') {
+            return 'When false, only required setup steps are returned. Leave true to include optional extras such as PyGhidra and dynamic-analysis components.';
+        }
+    }
     if (path === 'evidence_scope') {
         return 'Controls runtime evidence selection only. Use session for one runtime import/replay lineage, latest for the newest artifact window, all to aggregate historical runtime evidence.';
     }
@@ -180,6 +298,14 @@ function buildFieldHelpHint(path, toolName) {
 }
 function buildUsageNotes(definition) {
     const notes = [];
+    if (definition.name === 'system.setup.guide') {
+        notes.push('Use this before first-run or after a degraded health probe when the MCP client needs exact pip install commands and required user-supplied paths such as GHIDRA_PATH.');
+    }
+    if (definition.name === 'dynamic.dependencies' ||
+        definition.name === 'system.health' ||
+        definition.name === 'ghidra.health') {
+        notes.push('When the environment is degraded, inspect setup_actions and required_user_inputs before retrying. These fields are intended for MCP clients to present exact pip install commands and missing path inputs.');
+    }
     const inputFields = buildSchemaSummary(definition.inputSchema, definition.name).fields.map((item) => item.path);
     const hasEvidenceScope = inputFields.includes('evidence_scope');
     const hasSemanticScope = inputFields.includes('semantic_scope');
@@ -209,6 +335,52 @@ function buildUsageNotes(definition) {
         notes.push('Prefer path for local files. Use bytes_b64 only when the MCP client cannot access the same local filesystem as the MCP server.');
         notes.push('When both path and bytes_b64 are provided, path wins. Passing an absolute file path is the most reliable option for local VS Code/Copilot clients.');
     }
+    if (definition.name === 'binary.role.profile') {
+        notes.push('Use this tool before deep reconstruct when you need a universal EXE/DLL/driver/COM/plugin role summary and export/import entry map.');
+        notes.push('The returned analysis_priorities are intended to guide later MCP calls such as code.functions.search, ghidra.analyze, workflow.reconstruct, or dynamic.memory.import.');
+    }
+    if (definition.name === 'dll.export.profile') {
+        notes.push('Use this tool when a sample is DLL-like and you want a focused view of exports, forwarders, DllMain-style lifecycle hints, and plugin/host callback behavior.');
+        notes.push('Prefer this before workflow.reconstruct for DLLs, shell extensions, plugins, and command-dispatch libraries so later analysis is role-aware.');
+    }
+    if (definition.name === 'com.role.profile') {
+        notes.push('Use this tool when you suspect COM registration or class-factory behavior. It highlights CLSID, ProgID, registration strings, and DllGetClassObject-style exports.');
+        notes.push('Prefer this before reconstruct or semantic review on COM servers so naming and explanation passes start from activation-flow context instead of generic DLL assumptions.');
+    }
+    if (definition.name === 'pe.pdata.extract') {
+        notes.push('Use this tool when Ghidra post-scripts fail or a Rust x64 sample reports zero functions. It parses PE unwind metadata directly and does not require successful Ghidra function indexing.');
+    }
+    if (definition.name === 'code.functions.smart_recover') {
+        notes.push('Use this tool after pe.pdata.extract or failed ghidra.analyze runs to recover candidate function boundaries for Rust/Go/C++ binaries with degraded Ghidra support.');
+    }
+    if (definition.name === 'pe.symbols.recover') {
+        notes.push('Use this after code.functions.smart_recover when you want more descriptive recovered names derived from exports, entry point, runtime hints, and Rust crate strings.');
+        notes.push('The returned symbols can be fed into code.functions.define to establish a reusable function index with recovered names.');
+    }
+    if (definition.name === 'code.functions.define') {
+        notes.push('Use this to import function boundaries from pe.pdata.extract, code.functions.smart_recover, pe.symbols.recover, or external reverse-engineering tooling.');
+        notes.push('This establishes function-index readiness only. It does not imply Ghidra decompile or CFG readiness.');
+    }
+    if (definition.name === 'rust_binary.analyze') {
+        notes.push('This tool aggregates runtime.detect, strings.extract, code.functions.smart_recover, pe.symbols.recover, and binary.role.profile into one Rust-focused assessment.');
+        notes.push('Use it before manual recovery on Rust/Go/C++ samples when you need crate hints, recovered symbol previews, and concrete next steps for code.functions.define.');
+    }
+    if (definition.name === 'workflow.function_index_recover') {
+        notes.push('This workflow chains code.functions.smart_recover, pe.symbols.recover, and code.functions.define so difficult Rust/Go/C++ samples can materialize a reusable function index without a successful Ghidra decompile pass.');
+        notes.push('Use this after ghidra.analyze returns zero functions or degraded function_index readiness. The output includes imported function previews and an optional ranked preview.');
+    }
+    if (definition.name === 'code.module.review.prepare') {
+        notes.push('Use this when grouped modules already exist and you want an external LLM to review module roles, summaries, and rewrite guidance instead of focusing on individual functions.');
+    }
+    if (definition.name === 'code.module.review') {
+        notes.push('This is the module-level analogue of code.function.explain.review. It uses MCP sampling when available and otherwise returns a prompt contract for any tool-calling LLM client.');
+    }
+    if (definition.name === 'workflow.module_reconstruction_review') {
+        notes.push('Use this high-level workflow when you want module review plus an optional reconstruct/export refresh in one MCP call.');
+    }
+    if (definition.name === 'ghidra.analyze') {
+        notes.push('For Rust or other hard-to-index binaries, combine ghidra.analyze with pe.pdata.extract or code.functions.smart_recover. When auto-detection is weak, set options.language_id, options.cspec, or options.script_paths explicitly.');
+    }
     return notes;
 }
 function buildSchemaSummary(schema, toolName) {

package/dist/tools/yara-scan.d.ts

@@ -406,10 +406,6 @@ export declare const YaraScanOutputSchema: z.ZodObject<{
     }>>;
 }, "strip", z.ZodTypeAny, {
     ok: boolean;
-    metrics?: {
-        elapsed_ms: number;
-        tool: string;
-    } | undefined;
     data?: {
         timed_out: boolean;
         matches: {
@@ -469,15 +465,15 @@ export declare const YaraScanOutputSchema: z.ZodObject<{
         } | undefined;
         quality_notes?: string[] | undefined;
     } | undefined;
+    metrics?: {
+        elapsed_ms: number;
+        tool: string;
+    } | undefined;
     warnings?: string[] | undefined;
     errors?: string[] | undefined;
     artifacts?: any[] | undefined;
 }, {
     ok: boolean;
-    metrics?: {
-        elapsed_ms: number;
-        tool: string;
-    } | undefined;
     data?: {
         timed_out: boolean;
         matches: {
@@ -537,6 +533,10 @@ export declare const YaraScanOutputSchema: z.ZodObject<{
         } | undefined;
         quality_notes?: string[] | undefined;
     } | undefined;
+    metrics?: {
+        elapsed_ms: number;
+        tool: string;
+    } | undefined;
     warnings?: string[] | undefined;
     errors?: string[] | undefined;
     artifacts?: any[] | undefined;

package/dist/types.d.ts

@@ -109,6 +109,8 @@ export interface WorkerResult {
     data?: unknown;
     errors?: string[];
     warnings?: string[];
+    setup_actions?: unknown[];
+    required_user_inputs?: unknown[];
     artifacts?: ArtifactRef[];
     metrics?: Record<string, unknown>;
 }