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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```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:**

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

**Example:**
```json
{
  "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](https://github.com/malwarefrank/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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "name": "install_ilspy",
  "arguments": {
    "update": true
  }
}
```

**Example - Full installation (SDK + ilspycmd):**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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
```json
{
  "content": [
    {
      "type": "text",
      "text": "Validation Error: Assembly file not found: /invalid/path.dll"
    }
  ]
}
```

## Data Models

### DecompileRequest
```python
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
```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
```python
class TypeInfo(BaseModel):
    name: str
    full_name: str
    kind: str
    namespace: str | None = None
```

### AssemblyInfo
```python
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)
```python
@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)
```python
@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)
```python
@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
```python
# Using the MCP client
result = await session.call_tool(
    "decompile_assembly",
    {"assembly_path": "MyApp.dll"}
)
```

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

### Search for Service Classes
```python
# 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
```python
# Search for API endpoints
result = await session.call_tool(
    "search_strings",
    {
        "assembly_path": "MyApp.dll",
        "pattern": "https://",
        "use_regex": False
    }
)
```

### Targeted Decompilation
```python
# 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)
```python
# 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
```python
# Search for connection string constants
result = await session.call_tool(
    "search_fields",
    {
        "assembly_path": "MyApp.dll",
        "pattern": "Connection",
        "constants_only": True
    }
)
```

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

### List Embedded Resources
```python
# 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:
```json
{
  "mcpServers": {
    "ilspy": {
      "command": "mcilspy"
    }
  }
}
```

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