mcilspy/README.md

# mcilspy

A Model Context Protocol (MCP) server that provides .NET assembly decompilation capabilities using ILSpy.

## Features

### ILSpy-based Tools (requires ilspycmd)
- **Decompile Assemblies**: Convert .NET assemblies back to readable C# source code
- **List Types**: Enumerate classes, interfaces, structs, delegates, and enums in assemblies
- **Search Types**: Find types by name pattern with regex support
- **Search Strings**: Find hardcoded strings in assembly code (URLs, credentials, etc.)
- **Generate Diagrammer**: Create interactive HTML visualizations of assembly structure
- **Assembly Information**: Get metadata about .NET assemblies (version, target framework, etc.)

### Direct Metadata Tools (no ilspycmd required)
- **Search Methods**: Find methods by name pattern directly from metadata tables
- **Search Fields**: Find fields and constants in assemblies
- **Search Properties**: Find properties by name pattern
- **List Events**: Enumerate all events defined in an assembly
- **List Resources**: List embedded resources (files, images, etc.)
- **Metadata Summary**: Get comprehensive assembly metadata with statistics

### Installation & Diagnostics
- **Check Installation**: Verify ilspycmd and dotnet CLI status
- **Install ILSpy**: Automatically install or update ilspycmd

## Prerequisites

1. **ILSpy Command Line Tool**: Install the global dotnet tool:
   ```bash
   dotnet tool install --global ilspycmd
   ```

2. **Python 3.10+**: Required for running the MCP server

## Installation

Install from PyPI:

```bash
pip install mcilspy
```

Or for development:

```bash
git clone https://github.com/Borealin/mcilspy.git
cd mcilspy
pip install -e .
```

## Usage

### MCP Client Configuration

Configure your MCP client (e.g., Claude Desktop) to use the server:

```json
{
  "mcpServers": {
    "ilspy": {
      "command": "python",
      "args": ["-m", "mcilspy.server"]
    }
  }
}
```

### Available Tools

#### 1. `decompile_assembly`
Decompile a .NET assembly to C# source code. This is the primary tool for reverse-engineering .NET binaries.

**Parameters:**
- `assembly_path` (required): Path to the .NET assembly file
- `output_dir` (optional): Output directory for decompiled files
- `type_name` (optional): Fully qualified type name to decompile (e.g., "MyNamespace.MyClass")
- `language_version` (optional): C# language version (default: "Latest")
- `create_project` (optional): Create a compilable project structure
- `show_il_code` (optional): Show IL bytecode instead of C#
- `remove_dead_code` (optional): Remove unreachable code during decompilation
- `remove_dead_stores` (optional): Remove unused variable assignments
- `show_il_sequence_points` (optional): Include debugging sequence points in IL output
- `nested_directories` (optional): Use nested directories for namespaces

**Example:**
```json
{
  "name": "decompile_assembly",
  "arguments": {
    "assembly_path": "/path/to/MyAssembly.dll",
    "type_name": "MyNamespace.MyClass",
    "language_version": "CSharp10_0"
  }
}
```

#### 2. `list_types`
List types in a .NET assembly. Typically the **first tool to use** when analyzing an unknown assembly.

**Parameters:**
- `assembly_path` (required): Path to the .NET assembly file
- `entity_types` (optional): Types to include (accepts full names or single letters):
  - `"class"` or `"c"` (default)
  - `"interface"` or `"i"`
  - `"struct"` or `"s"`
  - `"delegate"` or `"d"`
  - `"enum"` or `"e"`

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

#### 3. `search_types`
Search for types by name pattern. Essential for finding specific classes in large assemblies.

**Parameters:**
- `assembly_path` (required): Path to the .NET assembly file
- `pattern` (required): Search pattern to match against type names
- `namespace_filter` (optional): Only search in namespaces containing this string
- `entity_types` (optional): Types to search (default: all types)
- `case_sensitive` (optional): Case-sensitive matching (default: false)
- `use_regex` (optional): Treat pattern as regular expression (default: false)

**Example:**
```json
{
  "name": "search_types",
  "arguments": {
    "assembly_path": "/path/to/MyAssembly.dll",
    "pattern": "Service",
    "namespace_filter": "MyApp.Services"
  }
}
```

#### 4. `search_strings`
Search for string literals in assembly code. Crucial for reverse engineering - finds hardcoded URLs, credentials, configuration, etc.

**Parameters:**
- `assembly_path` (required): Path to the .NET assembly file
- `pattern` (required): String pattern to search for
- `case_sensitive` (optional): Case-sensitive matching (default: false)
- `use_regex` (optional): Treat pattern as regular expression (default: false)
- `max_results` (optional): Maximum matches to return (default: 100)

**Example:**
```json
{
  "name": "search_strings",
  "arguments": {
    "assembly_path": "/path/to/MyAssembly.dll",
    "pattern": "api.example.com"
  }
}
```

#### 5. `generate_diagrammer`
Generate an interactive HTML diagram showing assembly type relationships.

**Parameters:**
- `assembly_path` (required): Path to the .NET assembly file
- `output_dir` (optional): Output directory for the diagrammer
- `include_pattern` (optional): Regex pattern for types to include
- `exclude_pattern` (optional): Regex pattern for types to exclude

#### 6. `get_assembly_info`
Get metadata and version information about an assembly.

**Parameters:**
- `assembly_path` (required): Path to the .NET assembly file

Returns: Assembly name, version, target framework, signing status, and debug info availability.

### Direct Metadata Tools

These tools use direct PE/metadata parsing via [dnfile](https://github.com/malwarefrank/dnfile) and don't require ilspycmd to be installed.

#### 7. `search_methods`
Search for methods in an assembly by name pattern. Useful for finding entry points, event handlers, and API endpoints.

**Parameters:**
- `assembly_path` (required): Path to the .NET assembly file
- `pattern` (required): Search pattern to match against method names
- `type_filter` (optional): Only search methods in types containing this string
- `namespace_filter` (optional): Only search in namespaces containing this string
- `public_only` (optional): Only return public methods (default: false)
- `case_sensitive` (optional): Case-sensitive matching (default: false)
- `use_regex` (optional): Treat pattern as regular expression (default: false)

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

#### 8. `search_fields`
Search for fields and constants in an assembly. Useful for finding configuration values and magic numbers.

**Parameters:**
- `assembly_path` (required): Path to the .NET assembly file
- `pattern` (required): Search pattern to match against field names
- `type_filter` (optional): Only search fields in types containing this string
- `namespace_filter` (optional): Only search in namespaces containing this string
- `public_only` (optional): Only return public fields (default: false)
- `constants_only` (optional): Only return constant (literal) fields (default: false)
- `case_sensitive` (optional): Case-sensitive matching (default: false)
- `use_regex` (optional): Treat pattern as regular expression (default: false)

#### 9. `search_properties`
Search for properties in an assembly by name pattern. Useful for finding data model fields and configuration properties.

**Parameters:**
- `assembly_path` (required): Path to the .NET assembly file
- `pattern` (required): Search pattern to match against property names
- `type_filter` (optional): Only search properties in types containing this string
- `namespace_filter` (optional): Only search in namespaces containing this string
- `case_sensitive` (optional): Case-sensitive matching (default: false)
- `use_regex` (optional): Treat pattern as regular expression (default: false)

#### 10. `list_events`
List all events defined in an assembly. Useful for understanding event-driven architecture and observer patterns.

**Parameters:**
- `assembly_path` (required): Path to the .NET assembly file
- `type_filter` (optional): Only list events in types containing this string
- `namespace_filter` (optional): Only list events in namespaces containing this string

#### 11. `list_resources`
List all embedded resources in an assembly. Finds embedded files, images, localization data, etc.

**Parameters:**
- `assembly_path` (required): Path to the .NET assembly file

#### 12. `get_metadata_summary`
Get a comprehensive metadata summary with statistics. More accurate than `get_assembly_info` for metadata counts.

**Parameters:**
- `assembly_path` (required): Path to the .NET assembly file

Returns: Assembly identity, type/method/field/property/event/resource counts, and referenced assemblies.

### Installation & Diagnostics Tools

#### 13. `check_ilspy_installation`
Check if ilspycmd and dotnet CLI are installed and working. Use this to diagnose issues.

**Parameters:** None

Returns: Installation status with version information and troubleshooting tips.

#### 14. `install_ilspy`
Install or update ilspycmd automatically. Detects your platform and package manager for optimal installation experience.

**Parameters:**
- `update` (optional): If true, update to the latest version even if already installed (default: false)
- `install_dotnet_sdk` (optional): If true, attempt to install .NET SDK when missing (default: false). Supports automatic detection for:
  - **Arch Linux**: `pacman`
  - **Ubuntu/Debian**: `apt`
  - **Fedora/RHEL**: `dnf`
  - **openSUSE**: `zypper`
  - **macOS**: `homebrew`
  - **Windows**: `winget` or `chocolatey`

**Example - Update ilspycmd:**
```json
{
  "name": "install_ilspy",
  "arguments": {
    "update": true
  }
}
```

**Example - Full installation (SDK + ilspycmd):**
```json
{
  "name": "install_ilspy",
  "arguments": {
    "install_dotnet_sdk": true
  }
}
```

### Available Prompts

#### 1. `analyze_assembly`
Analyze a .NET assembly and provide insights about its structure.

#### 2. `decompile_and_explain`
Decompile a specific type and provide explanation of its functionality.

## Supported Assembly Types

- .NET Framework assemblies (.dll, .exe)
- .NET Core/.NET 5+ assemblies
- Portable Executable (PE) files with .NET metadata

## Supported C# Language Versions

- CSharp1 through CSharp12_0
- Preview
- Latest (default)

## Quick Start

1. **Install the package**:
   ```bash
   pip install mcilspy
   ```

2. **Configure your MCP client** (Claude Desktop example):
   ```json
   {
     "mcpServers": {
       "ilspy": {
         "command": "python",
         "args": ["-m", "mcilspy.server"]
       }
     }
   }
   ```

3. **Use the tools** in your MCP client:
   - Ask to decompile a .NET assembly
   - List types in an assembly
   - Generate interactive diagrams
   - Get assembly information

## Error Handling

The server provides detailed error messages for common issues:
- Assembly file not found
- Invalid assembly format
- ILSpyCmd not installed or not in PATH
- Permission issues
- Decompilation failures

## Configuration

### Environment Variables

- `LOGLEVEL`: Set logging level (DEBUG, INFO, WARNING, ERROR). Default: INFO

### MCP Client Examples

**Claude Desktop** (`config.json`):
```json
{
  "mcpServers": {
    "ilspy": {
      "command": "python",
      "args": ["-m", "mcilspy.server"],
      "env": {
        "LOGLEVEL": "INFO"
      }
    }
  }
}
```

**Development/Testing**:
```json
{
  "mcpServers": {
    "ilspy": {
      "command": "python",
      "args": ["-m", "mcilspy.server"],
      "env": {
        "LOGLEVEL": "DEBUG"
      }
    }
  }
}
```

## Troubleshooting

### Common Issues

1. **"ILSpyCmd not found"**:
   ```bash
   dotnet tool install --global ilspycmd
   ```

2. **"Assembly file not found"**:
   - Check the file path is correct
   - Ensure the file has .dll or .exe extension

3. **Permission errors**:
   - Ensure read access to assembly files
   - Check output directory permissions

### Debug Mode

Enable debug logging to see detailed operation info:
```json
{
  "env": {
    "LOGLEVEL": "DEBUG"
  }
}
```

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Acknowledgments

- **Original project by [Borealin](https://github.com/Borealin/ilspy-mcp-server)** - Thank you for creating the foundation for this MCP server!
- Built on top of the excellent [ILSpy](https://github.com/icsharpcode/ILSpy) decompiler
- Uses the [Model Context Protocol](https://modelcontextprotocol.io/) for integration