mcilspy/docs/API.md

API Documentation

This document provides detailed API documentation for mcilspy.

Overview

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

1. ILSpy-based tools (require ilspycmd): Decompilation, type listing, diagram generation
2. Direct metadata tools (use dnfile): Method/field/property/event search, resource listing
3. Installation tools: Check and install ilspycmd automatically

Recommended Workflow

When analyzing an unknown .NET assembly, follow this typical workflow:

1. get_metadata_summary - Quick reconnaissance with accurate metadata counts
2. list_types - Discover what types exist in the assembly
3. search_types / search_methods - Find specific types or methods by pattern
4. search_strings / search_fields - Find hardcoded strings and constants
5. decompile_assembly - Deep dive into specific types of interest
6. generate_diagrammer - Visualize type relationships
7. list_resources - Check for embedded files

Tools

1. decompile_assembly

Decompiles a .NET assembly to C# source code. This is the primary tool for reverse-engineering .NET binaries.

Parameters:

Parameter	Type	Required	Default	Description
assembly_path	string	✓	-	Path to the .NET assembly file (.dll or .exe)
output_dir	string	✗	null	Output directory for decompiled files
type_name	string	✗	null	Fully qualified name of specific type to decompile
language_version	string	✗	"Latest"	C# language version to use
create_project	boolean	✗	false	Create a compilable project with multiple files
show_il_code	boolean	✗	false	Show IL bytecode instead of C#
remove_dead_code	boolean	✗	false	Remove unreachable code during decompilation
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
• Preview (latest preview features)
• Latest (default, most recent stable)

Example:

{
  "name": "decompile_assembly",
  "arguments": {
    "assembly_path": "/path/to/MyAssembly.dll",
    "type_name": "MyNamespace.MyClass",
    "language_version": "CSharp10_0",
    "remove_dead_code": true
  }
}

Response: Returns decompiled C# source code as text, or information about saved files if output_dir is specified.

2. list_types

Lists types (classes, interfaces, structs, etc.) in a .NET assembly. Typically the first tool to use when analyzing an unknown assembly.

Parameters:

Parameter	Type	Required	Default	Description
assembly_path	string	✓	-	Path to the .NET assembly file (.dll or .exe)
entity_types	array[string]	✗	["class"]	Types of entities to list

Entity Types (accepts full names or single letters):

• class or c - Classes
• interface or i - Interfaces
• struct or s - Structs
• delegate or d - Delegates
• enum or e - Enums

Example:

{
  "name": "list_types",
  "arguments": {
    "assembly_path": "/path/to/MyAssembly.dll",
    "entity_types": ["class", "interface", "struct"]
  }
}

Response: Returns a formatted list of types organized by namespace, including:

• Type name
• Full qualified name
• Type kind (Class, Interface, etc.)
• Namespace

3. search_types

Search for types by name pattern. Essential for finding specific classes in large assemblies.

Parameters:

Parameter	Type	Required	Default	Description
assembly_path	string	✓	-	Path to the .NET assembly file (.dll or .exe)
pattern	string	✓	-	Search pattern to match against type names
namespace_filter	string	✗	null	Only return types in namespaces containing this string
entity_types	array[string]	✗	all	Types to search (class, interface, struct, delegate, enum)
case_sensitive	boolean	✗	false	Whether pattern matching is case-sensitive
use_regex	boolean	✗	false	Treat pattern as regular expression

Common Search Patterns:

• "Service" - Find all service classes
• "Controller" - Find ASP.NET controllers
• "Handler" - Find command/event handlers
• "Exception" - Find custom exception types
• "I.*Service" (with use_regex=true) - Find service interfaces

Example:

{
  "name": "search_types",
  "arguments": {
    "assembly_path": "/path/to/MyAssembly.dll",
    "pattern": "Service",
    "namespace_filter": "MyApp.Services",
    "entity_types": ["class", "interface"]
  }
}

Response: Returns matching types grouped by namespace with full names for use with decompile_assembly.

4. search_strings

Search for string literals in assembly code. Crucial for reverse engineering - finds hardcoded strings.

Parameters:

Parameter	Type	Required	Default	Description
assembly_path	string	✓	-	Path to the .NET assembly file (.dll or .exe)
pattern	string	✓	-	String pattern to search for in decompiled code
case_sensitive	boolean	✗	false	Whether search is case-sensitive
use_regex	boolean	✗	false	Treat pattern as regular expression
max_results	integer	✗	100	Maximum number of matches to return

Use Cases:

• Find hardcoded URLs and API endpoints
• Locate connection strings
• Discover error messages and logging text
• Find configuration keys and magic values
• Security analysis - find hardcoded credentials
• Locate registry keys and file paths

Example:

{
  "name": "search_strings",
  "arguments": {
    "assembly_path": "/path/to/MyAssembly.dll",
    "pattern": "api.example.com",
    "max_results": 50
  }
}

Response: Returns matching code lines grouped by type, with context about the containing method.

5. generate_diagrammer

Generates an interactive HTML diagram showing assembly type relationships.

Parameters:

Parameter	Type	Required	Default	Description
assembly_path	string	✓	-	Path to the .NET assembly file (.dll or .exe)
output_dir	string	✗	null	Output directory for the diagrammer
include_pattern	string	✗	null	Regex pattern for types to include
exclude_pattern	string	✗	null	Regex pattern for types to exclude

Example:

{
  "name": "generate_diagrammer",
  "arguments": {
    "assembly_path": "/path/to/MyAssembly.dll",
    "output_dir": "./diagrams",
    "include_pattern": "MyNamespace\\..+",
    "exclude_pattern": ".*Generated.*"
  }
}

Response: Returns success status and output directory path. The HTML file can be opened in a web browser to view the interactive diagram.

6. dump_package

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:

{
  "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:

Parameter	Type	Required	Default	Description
assembly_path	string	✓	-	Path to the .NET assembly file (.dll or .exe)

Example:

{
  "name": "get_assembly_info",
  "arguments": {
    "assembly_path": "/path/to/MyAssembly.dll"
  }
}

Response: Returns assembly metadata including:

• Assembly name
• Version (extracted from AssemblyVersion attribute)
• Full name
• Location
• Target framework (e.g., .NET Framework 4.8, .NET 6.0)
• Runtime version (if available)
• Whether the assembly is signed
• Whether debug information (PDB) is available

Direct Metadata Tools

These tools use dnfile for direct PE/metadata parsing. They do not require ilspycmd to be installed.

8. search_methods

Search for methods in an assembly by name pattern. Uses direct metadata parsing of the MethodDef table.

Parameters:

Parameter	Type	Required	Default	Description
assembly_path	string	✓	-	Path to the .NET assembly file (.dll or .exe)
pattern	string	✓	-	Search pattern to match against method names
type_filter	string	✗	null	Only search methods in types containing this string
namespace_filter	string	✗	null	Only search in namespaces containing this string
public_only	boolean	✗	false	Only return public methods
case_sensitive	boolean	✗	false	Whether pattern matching is case-sensitive
use_regex	boolean	✗	false	Treat pattern as regular expression

Use Cases:

• Find entry points and main methods
• Locate event handlers (OnClick, Handle*)
• Find lifecycle methods (Initialize, Dispose)
• Discover API endpoints

Example:

{
  "name": "search_methods",
  "arguments": {
    "assembly_path": "/path/to/MyAssembly.dll",
    "pattern": "Handle",
    "public_only": true
  }
}

Response: Returns matching methods grouped by declaring type, showing visibility modifiers (public, static, virtual, abstract).

9. search_fields

Search for fields and constants in an assembly. Uses direct metadata parsing of the Field table.

Parameters:

Parameter	Type	Required	Default	Description
assembly_path	string	✓	-	Path to the .NET assembly file (.dll or .exe)
pattern	string	✓	-	Search pattern to match against field names
type_filter	string	✗	null	Only search fields in types containing this string
namespace_filter	string	✗	null	Only search in namespaces containing this string
public_only	boolean	✗	false	Only return public fields
constants_only	boolean	✗	false	Only return constant (literal) fields
case_sensitive	boolean	✗	false	Whether pattern matching is case-sensitive
use_regex	boolean	✗	false	Treat pattern as regular expression

Use Cases:

• Find configuration values and magic numbers
• Locate constant strings (URLs, error messages)
• Discover static fields (singletons, caches)

Example:

{
  "name": "search_fields",
  "arguments": {
    "assembly_path": "/path/to/MyAssembly.dll",
    "pattern": "ConnectionString",
    "constants_only": true
  }
}

10. search_properties

Search for properties in an assembly by name pattern. Uses direct metadata parsing of the Property table.

Parameters:

Parameter	Type	Required	Default	Description
assembly_path	string	✓	-	Path to the .NET assembly file (.dll or .exe)
pattern	string	✓	-	Search pattern to match against property names
type_filter	string	✗	null	Only search properties in types containing this string
namespace_filter	string	✗	null	Only search in namespaces containing this string
case_sensitive	boolean	✗	false	Whether pattern matching is case-sensitive
use_regex	boolean	✗	false	Treat pattern as regular expression

Use Cases:

• Find configuration properties
• Locate data model fields
• Discover API response/request properties

11. list_events

List all events defined in an assembly. Uses direct metadata parsing of the Event table.

Parameters:

Parameter	Type	Required	Default	Description
assembly_path	string	✓	-	Path to the .NET assembly file (.dll or .exe)
type_filter	string	✗	null	Only list events in types containing this string
namespace_filter	string	✗	null	Only list events in namespaces containing this string

Use Cases:

• Understand event-driven architecture
• Discover observer patterns
• Analyze UI event handlers

12. list_resources

List all embedded resources in an assembly. Uses direct metadata parsing of the ManifestResource table.

Parameters:

Parameter	Type	Required	Default	Description
assembly_path	string	✓	-	Path to the .NET assembly file (.dll or .exe)

Use Cases:

• Find embedded files (images, configs, data)
• Discover localization resources
• Locate embedded assemblies

13. get_metadata_summary

Get a comprehensive metadata summary with accurate statistics. Uses dnfile for direct metadata counts.

Parameters:

Parameter	Type	Required	Default	Description
assembly_path	string	✓	-	Path to the .NET assembly file (.dll or .exe)

Response: Returns comprehensive assembly information including:

• Assembly identity (name, version, culture, public key token)
• Target framework (if available)
• Statistics table (type/method/field/property/event/resource counts)
• List of referenced assemblies

Example:

{
  "name": "get_metadata_summary",
  "arguments": {
    "assembly_path": "/path/to/MyAssembly.dll"
  }
}

Installation & Diagnostics Tools

These tools help manage ilspycmd installation and diagnose issues.

14. check_ilspy_installation

Check if ilspycmd and dotnet CLI are installed and working. Use this to diagnose issues with decompilation tools.

Parameters: None

Response: Returns installation status including:

• dotnet CLI availability and version
• ilspycmd availability, version, and path
• Instructions if anything is missing

Example:

{
  "name": "check_ilspy_installation",
  "arguments": {}
}

15. install_ilspy

Install or update ilspycmd, the ILSpy command-line decompiler. Automatically detects your platform and package manager to provide optimal installation instructions.

Parameters:

Parameter	Type	Required	Default	Description
update	boolean	✗	false	Update to latest version even if already installed
install_dotnet_sdk	boolean	✗	false	Attempt to install .NET SDK if missing (may require sudo)

Supported Platforms for Auto-Install:

• Arch Linux/Manjaro: pacman -S dotnet-sdk
• Ubuntu/Debian/Mint: apt install dotnet-sdk-8.0
• Fedora/RHEL/CentOS: dnf install dotnet-sdk-8.0
• openSUSE: zypper install dotnet-sdk-8.0
• macOS: brew install dotnet-sdk (Homebrew)
• Windows: winget install Microsoft.DotNet.SDK.8 or choco install dotnet-sdk

Example - Update ilspycmd:

{
  "name": "install_ilspy",
  "arguments": {
    "update": true
  }
}

Example - Full installation (SDK + ilspycmd):

{
  "name": "install_ilspy",
  "arguments": {
    "install_dotnet_sdk": true
  }
}

Response:

• Success message with version and path on successful installation
• Platform-specific installation instructions if dotnet CLI is missing
• Option to auto-install with install_dotnet_sdk=true
• PATH troubleshooting tips if installation succeeds but tool isn't found

Prompts

1. analyze_assembly

Provides a structured prompt for analyzing a .NET assembly and understanding its structure.

Arguments:

Argument	Type	Required	Description
assembly_path	string	✓	Path to the .NET assembly file
focus_area	string	✗	Specific area to focus on (types, namespaces, dependencies)

Example:

{
  "name": "analyze_assembly",
  "arguments": {
    "assembly_path": "/path/to/MyAssembly.dll",
    "focus_area": "types"
  }
}

2. decompile_and_explain

Provides a structured prompt for decompiling a specific type and explaining its functionality.

Arguments:

Argument	Type	Required	Description
assembly_path	string	✓	Path to the .NET assembly file
type_name	string	✓	Fully qualified name of the type to analyze

Example:

{
  "name": "decompile_and_explain",
  "arguments": {
    "assembly_path": "/path/to/MyAssembly.dll",
    "type_name": "MyNamespace.ImportantClass"
  }
}

Error Handling

The server provides detailed error messages for common issues:

Validation Errors

• Empty or invalid assembly paths
• Non-existent files
• Invalid file extensions (must be .dll or .exe)
• Invalid reference paths

Runtime Errors

• ILSpyCmd not found or not installed
• Permission issues accessing files
• Decompilation failures
• Invalid assembly format

Error Response Format

{
  "content": [
    {
      "type": "text",
      "text": "Validation Error: Assembly file not found: /invalid/path.dll"
    }
  ]
}

Data Models

DecompileRequest

class DecompileRequest(BaseModel):
    assembly_path: str
    output_dir: str | None = None
    type_name: str | None = None
    language_version: LanguageVersion = LanguageVersion.LATEST
    create_project: bool = False
    show_il_code: bool = False
    remove_dead_code: bool = False
    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

class DumpPackageRequest(BaseModel):
    assembly_path: str  # Path to assembly or NuGet package folder
    output_dir: str  # Required: directory to dump assemblies into

DumpPackageResponse

class DumpPackageResponse(BaseModel):
    success: bool
    output_path: str | None = None
    assemblies_dumped: list[str] = []
    error_message: str | None = None

TypeInfo

class TypeInfo(BaseModel):
    name: str
    full_name: str
    kind: str
    namespace: str | None = None

AssemblyInfo

class AssemblyInfo(BaseModel):
    name: str
    version: str
    full_name: str
    location: str
    target_framework: str | None = None
    runtime_version: str | None = None
    is_signed: bool = False
    has_debug_info: bool = False

MethodInfo (metadata_reader)

@dataclass
class MethodInfo:
    name: str
    full_name: str
    declaring_type: str
    namespace: str | None
    return_type: str | None = None
    is_public: bool = False
    is_static: bool = False
    is_virtual: bool = False
    is_abstract: bool = False
    parameters: list[str] = field(default_factory=list)

FieldInfo (metadata_reader)

@dataclass
class FieldInfo:
    name: str
    full_name: str
    declaring_type: str
    namespace: str | None
    field_type: str | None = None
    is_public: bool = False
    is_static: bool = False
    is_literal: bool = False  # Constant
    default_value: str | None = None

AssemblyMetadata (metadata_reader)

@dataclass
class AssemblyMetadata:
    name: str
    version: str
    culture: str | None = None
    public_key_token: str | None = None
    target_framework: str | None = None
    type_count: int = 0
    method_count: int = 0
    field_count: int = 0
    property_count: int = 0
    event_count: int = 0
    resource_count: int = 0
    referenced_assemblies: list[str] = field(default_factory=list)

Usage Examples

Basic Decompilation

# Using the MCP client
result = await session.call_tool(
    "decompile_assembly",
    {"assembly_path": "MyApp.dll"}
)

Filtered Type Listing

# List only classes and interfaces
result = await session.call_tool(
    "list_types",
    {
        "assembly_path": "MyApp.dll",
        "entity_types": ["class", "interface"]
    }
)

Search for Service Classes

# Find all classes with "Service" in their name
result = await session.call_tool(
    "search_types",
    {
        "assembly_path": "MyApp.dll",
        "pattern": "Service",
        "entity_types": ["class", "interface"]
    }
)

Find Hardcoded URLs

# Search for API endpoints
result = await session.call_tool(
    "search_strings",
    {
        "assembly_path": "MyApp.dll",
        "pattern": "https://",
        "use_regex": False
    }
)

Targeted Decompilation

# Decompile specific type with optimizations
result = await session.call_tool(
    "decompile_assembly",
    {
        "assembly_path": "MyApp.dll",
        "type_name": "MyApp.Core.Engine",
        "language_version": "CSharp11_0",
        "remove_dead_code": True
    }
)

Search for Event Handlers (Direct Metadata)

# Find all methods with "Handle" in their name
result = await session.call_tool(
    "search_methods",
    {
        "assembly_path": "MyApp.dll",
        "pattern": "Handle",
        "public_only": True
    }
)

Find Constants

# Search for connection string constants
result = await session.call_tool(
    "search_fields",
    {
        "assembly_path": "MyApp.dll",
        "pattern": "Connection",
        "constants_only": True
    }
)

Get Assembly Statistics

# Get comprehensive metadata summary
result = await session.call_tool(
    "get_metadata_summary",
    {"assembly_path": "MyApp.dll"}
)

List Embedded Resources

# Find what resources are embedded
result = await session.call_tool(
    "list_resources",
    {"assembly_path": "MyApp.dll"}
)

Configuration

Environment Variables

Variable	Description	Default
LOGLEVEL	Logging level (DEBUG, INFO, WARNING, ERROR)	INFO

MCP Client Configuration

For Claude Desktop:

{
  "mcpServers": {
    "ilspy": {
      "command": "mcilspy"
    }
  }
}

For development:

{
  "mcpServers": {
    "ilspy": {
      "command": "python",
      "args": ["-m", "mcilspy.server"],
      "env": {
        "LOGLEVEL": "DEBUG"
      }
    }
  }
}