From ad72b013ca1f0e44b2622eff7b8791047883ba0a Mon Sep 17 00:00:00 2001 From: Ryan Malloy Date: Wed, 11 Feb 2026 00:51:51 -0700 Subject: [PATCH] docs: update documentation for v0.4.0 features - Add dump_package tool documentation to README and API.md - Document generate_pdb and use_pdb_variable_names parameters - Update tool count from 14 to 15 in API.md - Add DumpPackageRequest/Response models to API.md - Add v0.4.0 and v0.3.0 entries to CHANGELOG - Renumber API.md tools to accommodate new dump_package tool --- CHANGELOG.md | 23 +++++++++++++++++ README.md | 32 ++++++++++++++++++++--- docs/API.md | 72 ++++++++++++++++++++++++++++++++++++++++++++-------- uv.lock | 2 +- 4 files changed, 113 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5f07841..4d302b4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,29 @@ All notable changes to mcilspy will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Calendar Versioning](https://calver.org/) for major releases. +## [0.4.0] - 2026-02-11 + +### Added +- **PDB Generation** (`generate_pdb` flag) - Generate portable PDB files from decompiled assemblies for IDE debugging +- **PDB Variable Names** (`use_pdb_variable_names` flag) - Use original variable names from existing PDB files for improved readability +- **`dump_package` tool** - Extract all assemblies from NuGet package folder structures for bulk analysis + +### Changed +- `decompile_assembly` now exposes all ilspycmd CLI options - mcilspy has 100% feature coverage +- Updated documentation with new tool and parameter descriptions +- Tool count increased from 14 to 15 + +## [0.3.0] - 2026-02-10 + +### Fixed +- **Type parsing regex** - Fixed `list_types` returning empty results (regex expected "Class:" but ilspycmd outputs "Class ") +- **UserStringHeap data access** - Fixed Python name mangling issue in `search_strings` causing crash +- **Decompile stdout mode** - Added `_decompile_to_stdout()` method for simple decompilation without output directory + +### Changed +- Merged comprehensive code review fixes from parallel taskmaster branches (security, architecture, performance, testing) +- All 165 tests passing + ## [0.2.0] - 2026-02-07 ### Security diff --git a/README.md b/README.md index d7397e8..6df2b7f 100644 --- a/README.md +++ b/README.md @@ -78,10 +78,10 @@ Learn from decompiled implementations when documentation falls short. | Tool | What It Does | Requires ilspycmd? | |------|--------------|:------------------:| -| `decompile_assembly` | Full C# source recovery | Yes | +| `decompile_assembly` | Full C# source recovery (with PDB generation) | Yes | | `list_types` | Enumerate classes, interfaces, enums | Yes | | `search_types` | Find types by name pattern | Yes | -| `search_strings` | Find hardcoded strings (URLs, keys) | Yes | +| `search_strings` | Find hardcoded strings (URLs, keys) | No | | `search_methods` | Find methods by name | No | | `search_fields` | Find fields and constants | No | | `search_properties` | Find properties by name | No | @@ -89,11 +89,12 @@ Learn from decompiled implementations when documentation falls short. | `list_resources` | Find embedded files/images | No | | `get_metadata_summary` | Assembly stats and references | No | | `generate_diagrammer` | Interactive HTML type diagrams | Yes | +| `dump_package` | Extract assemblies from NuGet packages | Yes | | `get_assembly_info` | Version, framework, signing info | Yes | | `check_ilspy_installation` | Diagnose setup issues | No | | `install_ilspy` | Auto-install .NET SDK + ilspycmd | No | -**6 tools work immediately** (via [dnfile](https://github.com/malwarefrank/dnfile)) — no .NET SDK required. +**7 tools work immediately** (via [dnfile](https://github.com/malwarefrank/dnfile)) — no .NET SDK required. **8 more tools** unlock with `ilspycmd` for full decompilation power. --- @@ -164,11 +165,14 @@ The primary reverse-engineering tool. Decompiles .NET assemblies to readable C#. | `create_project` | No | Generate compilable .csproj structure | | `language_version` | No | C# version (default: Latest) | | `show_il_code` | No | Output IL bytecode instead of C# | +| `generate_pdb` | No | Generate portable PDB for debugging (requires `output_dir`) | +| `use_pdb_variable_names` | No | Use original variable names from existing PDB | ```json { "assembly_path": "/path/to/MyApp.dll", - "type_name": "MyApp.Services.AuthService" + "type_name": "MyApp.Services.AuthService", + "use_pdb_variable_names": true } ``` @@ -246,6 +250,26 @@ Generates an HTML visualization of type hierarchies and relationships. +
+dump_package — Extract assemblies from NuGet packages + +Extracts all assemblies from a NuGet package folder structure into a flat directory for bulk analysis. + +| Parameter | Required | Description | +|-----------|:--------:|-------------| +| `assembly_path` | Yes | Path to assembly or NuGet package folder | +| `output_dir` | Yes | Directory to dump assemblies into | + +```json +{ + "assembly_path": "/path/to/packages/Newtonsoft.Json", + "output_dir": "./extracted-assemblies" +} +``` + +Useful for analyzing package dependencies or bulk decompilation of NuGet packages. +
+
get_assembly_info — Get assembly metadata diff --git a/docs/API.md b/docs/API.md index dd88446..c1f3dc4 100644 --- a/docs/API.md +++ b/docs/API.md @@ -4,7 +4,7 @@ This document provides detailed API documentation for mcilspy. ## Overview -mcilspy provides a Model Context Protocol (MCP) interface to the ILSpy .NET decompiler. It exposes **14 tools** and two prompts for interacting with .NET assemblies. +mcilspy provides a Model Context Protocol (MCP) interface to the ILSpy .NET decompiler. It exposes **15 tools** and two prompts for interacting with .NET assemblies. ### Tool Categories @@ -44,6 +44,8 @@ Decompiles a .NET assembly to C# source code. This is the primary tool for rever | `remove_dead_stores` | boolean | ✗ | false | Remove unused variable assignments | | `show_il_sequence_points` | boolean | ✗ | false | Include debugging sequence points in IL output | | `nested_directories` | boolean | ✗ | false | Use nested directories for namespaces | +| `generate_pdb` | boolean | ✗ | false | Generate portable PDB file (requires `output_dir`) | +| `use_pdb_variable_names` | boolean | ✗ | false | Use original variable names from existing PDB | **Language Versions:** - `CSharp1` through `CSharp12_0` @@ -206,9 +208,39 @@ Generates an interactive HTML diagram showing assembly type relationships. **Response:** Returns success status and output directory path. The HTML file can be opened in a web browser to view the interactive diagram. -### 6. get_assembly_info +### 6. dump_package -Gets metadata and version information about a .NET assembly. +Dump package assemblies into a folder. Extracts all assemblies from a NuGet package folder structure into a flat directory for easier analysis. + +**Parameters:** + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|---------|-------------| +| `assembly_path` | string | ✓ | - | Path to the assembly or NuGet package folder to extract from | +| `output_dir` | string | ✓ | - | Directory to dump assemblies into (will be created if needed) | + +**Use Cases:** +- Bulk decompilation of NuGet packages +- Analyzing package dependencies +- Extracting DLLs from complex package structures + +**Example:** +```json +{ + "name": "dump_package", + "arguments": { + "assembly_path": "/path/to/packages/Newtonsoft.Json.13.0.1", + "output_dir": "./extracted-assemblies" + } +} +``` + +**Response:** +Returns a summary including output directory path and list of extracted assemblies. + +### 7. get_assembly_info + +Gets metadata and version information about a .NET assembly. Uses ilspycmd to extract detailed assembly attributes. **Parameters:** @@ -241,7 +273,7 @@ Returns assembly metadata including: These tools use [dnfile](https://github.com/malwarefrank/dnfile) for direct PE/metadata parsing. They do **not require ilspycmd** to be installed. -### 7. search_methods +### 8. search_methods Search for methods in an assembly by name pattern. Uses direct metadata parsing of the MethodDef table. @@ -278,7 +310,7 @@ Search for methods in an assembly by name pattern. Uses direct metadata parsing **Response:** Returns matching methods grouped by declaring type, showing visibility modifiers (public, static, virtual, abstract). -### 8. search_fields +### 9. search_fields Search for fields and constants in an assembly. Uses direct metadata parsing of the Field table. @@ -312,7 +344,7 @@ Search for fields and constants in an assembly. Uses direct metadata parsing of } ``` -### 9. search_properties +### 10. search_properties Search for properties in an assembly by name pattern. Uses direct metadata parsing of the Property table. @@ -332,7 +364,7 @@ Search for properties in an assembly by name pattern. Uses direct metadata parsi - Locate data model fields - Discover API response/request properties -### 10. list_events +### 11. list_events List all events defined in an assembly. Uses direct metadata parsing of the Event table. @@ -349,7 +381,7 @@ List all events defined in an assembly. Uses direct metadata parsing of the Even - Discover observer patterns - Analyze UI event handlers -### 11. list_resources +### 12. list_resources List all embedded resources in an assembly. Uses direct metadata parsing of the ManifestResource table. @@ -364,7 +396,7 @@ List all embedded resources in an assembly. Uses direct metadata parsing of the - Discover localization resources - Locate embedded assemblies -### 12. get_metadata_summary +### 13. get_metadata_summary Get a comprehensive metadata summary with accurate statistics. Uses dnfile for direct metadata counts. @@ -395,7 +427,7 @@ Returns comprehensive assembly information including: These tools help manage ilspycmd installation and diagnose issues. -### 13. check_ilspy_installation +### 14. check_ilspy_installation Check if ilspycmd and dotnet CLI are installed and working. Use this to diagnose issues with decompilation tools. @@ -415,7 +447,7 @@ Returns installation status including: } ``` -### 14. install_ilspy +### 15. install_ilspy Install or update ilspycmd, the ILSpy command-line decompiler. Automatically detects your platform and package manager to provide optimal installation instructions. @@ -549,6 +581,24 @@ class DecompileRequest(BaseModel): remove_dead_stores: bool = False show_il_sequence_points: bool = False nested_directories: bool = False + generate_pdb: bool = False # Generate portable PDB file + use_pdb_variable_names: bool = False # Use variable names from existing PDB +``` + +### DumpPackageRequest +```python +class DumpPackageRequest(BaseModel): + assembly_path: str # Path to assembly or NuGet package folder + output_dir: str # Required: directory to dump assemblies into +``` + +### DumpPackageResponse +```python +class DumpPackageResponse(BaseModel): + success: bool + output_path: str | None = None + assemblies_dumped: list[str] = [] + error_message: str | None = None ``` ### TypeInfo diff --git a/uv.lock b/uv.lock index 57affc4..2de0d31 100644 --- a/uv.lock +++ b/uv.lock @@ -332,7 +332,7 @@ wheels = [ [[package]] name = "mcilspy" -version = "0.3.0" +version = "0.4.0" source = { editable = "." } dependencies = [ { name = "dnfile" },