mcilspy/README.md

# mcilspy

[![PyPI version](https://img.shields.io/pypi/v/mcilspy.svg)](https://pypi.org/project/mcilspy/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io/)

**Decompile, search, and analyze .NET assemblies with AI assistance.**

An MCP server that gives Claude (or any MCP client) the power to reverse-engineer .NET binaries — find hardcoded secrets, understand obfuscated code, recover lost source, and explore assembly internals.

---

## Quick Start (30 seconds)

```bash
# Install
pip install mcilspy

# Add to Claude Code
claude mcp add ilspy -- python -m mcilspy.server

# Or add to Claude Desktop's config.json
```

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

**That's it.** Ask Claude to analyze any `.dll` or `.exe`:

> *"Decompile the LoginService class from this assembly and explain what it does"*

---

## What Can You Do?

### Find Hardcoded Secrets
```
"Search for any URLs, API keys, or connection strings in MyApp.dll"
```
Discovers hardcoded credentials, endpoints, and configuration that shouldn't be in code.

### Reverse Engineer Unknown Binaries
```
"List all the types in this DLL and identify the main entry points"
```
Understand the structure of any .NET assembly without source code.

### Recover Lost Source Code
```
"Decompile the entire assembly to a project I can build"
```
Recreate compilable C# projects from binaries when source is unavailable.

### Analyze Malware Behavior
```
"Find all network-related methods and show me what URLs this malware contacts"
```
Safe static analysis of suspicious .NET executables.

### Understand Third-Party Libraries
```
"Show me how Newtonsoft.Json handles circular references"
```
Learn from decompiled implementations when documentation falls short.

---

## Features at a Glance

| Tool | What It Does | Requires ilspycmd? |
|------|--------------|:------------------:|
| `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) | No |
| `search_methods` | Find methods by name | No |
| `search_fields` | Find fields and constants | No |
| `search_properties` | Find properties by name | No |
| `list_events` | List all events | No |
| `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 |

**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.

---

## Installation Options

### Option 1: Just the MCP Server (metadata tools only)
```bash
pip install mcilspy
```
Gives you search and metadata tools immediately.

### Option 2: Full Decompilation Power
```bash
# Install the MCP server
pip install mcilspy

# Let the server install ilspycmd for you (detects your OS automatically)
# Just ask Claude: "Install ilspycmd" or call install_ilspy with install_dotnet_sdk=true
```

**Supported platforms for auto-install:**
- Arch Linux (`pacman`)
- Ubuntu/Debian (`apt`)
- Fedora/RHEL (`dnf`)
- macOS (`homebrew`)
- Windows (`winget` / `chocolatey`)

### Option 3: Manual ilspycmd Setup
```bash
# Install .NET SDK from https://dotnet.microsoft.com/download
# Then:
dotnet tool install --global ilspycmd
```

---

## Table of Contents

- [Quick Start](#quick-start-30-seconds)
- [What Can You Do?](#what-can-you-do)
- [Features at a Glance](#features-at-a-glance)
- [Installation Options](#installation-options)
- [Tool Reference](#tool-reference)
  - [Decompilation Tools](#decompilation-tools-requires-ilspycmd)
  - [Metadata Tools](#metadata-tools-no-ilspycmd-required)
  - [Installation Tools](#installation--diagnostics)
- [Configuration](#configuration)
- [Troubleshooting](#troubleshooting)
- [License & Acknowledgments](#license)

---

## Tool Reference

### Decompilation Tools (requires ilspycmd)

<details>
<summary><strong>decompile_assembly</strong> — Convert binaries back to C# source</summary>

The primary reverse-engineering tool. Decompiles .NET assemblies to readable C#.

| Parameter | Required | Description |
|-----------|:--------:|-------------|
| `assembly_path` | Yes | Path to .dll or .exe |
| `type_name` | No | Specific type to decompile (e.g., `MyNamespace.MyClass`) |
| `output_dir` | No | Save decompiled files to directory |
| `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",
  "use_pdb_variable_names": true
}
```
</details>

<details>
<summary><strong>list_types</strong> — Enumerate types in an assembly</summary>

Your starting point for exploring unknown assemblies.

| Parameter | Required | Description |
|-----------|:--------:|-------------|
| `assembly_path` | Yes | Path to .dll or .exe |
| `entity_types` | No | Filter: `class`, `interface`, `struct`, `delegate`, `enum` |

```json
{
  "assembly_path": "/path/to/MyApp.dll",
  "entity_types": ["class", "interface"]
}
```
</details>

<details>
<summary><strong>search_types</strong> — Find types by name pattern</summary>

| Parameter | Required | Description |
|-----------|:--------:|-------------|
| `assembly_path` | Yes | Path to .dll or .exe |
| `pattern` | Yes | Search pattern |
| `namespace_filter` | No | Limit to specific namespace |
| `use_regex` | No | Enable regex matching |
| `case_sensitive` | No | Case-sensitive search |

```json
{
  "assembly_path": "/path/to/MyApp.dll",
  "pattern": "Controller",
  "namespace_filter": "MyApp.Web"
}
```
</details>

<details>
<summary><strong>search_strings</strong> — Find hardcoded strings (secrets, URLs, config)</summary>

Essential for security analysis. Finds strings embedded in IL code.

| Parameter | Required | Description |
|-----------|:--------:|-------------|
| `assembly_path` | Yes | Path to .dll or .exe |
| `pattern` | Yes | String to search for |
| `use_regex` | No | Enable regex matching |
| `max_results` | No | Limit results (default: 100) |

```json
{
  "assembly_path": "/path/to/MyApp.dll",
  "pattern": "api\\..*\\.com"
  "use_regex": true
}
```
</details>

<details>
<summary><strong>generate_diagrammer</strong> — Create interactive type relationship diagrams</summary>

Generates an HTML visualization of type hierarchies and relationships.

| Parameter | Required | Description |
|-----------|:--------:|-------------|
| `assembly_path` | Yes | Path to .dll or .exe |
| `output_dir` | No | Where to save the HTML |
| `include_pattern` | No | Regex for types to include |
| `exclude_pattern` | No | Regex for types to exclude |

</details>

<details>
<summary><strong>dump_package</strong> — Extract assemblies from NuGet packages</summary>

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.
</details>

<details>
<summary><strong>get_assembly_info</strong> — Get assembly metadata</summary>

Returns version, target framework, strong name signing status, and debug info.

| Parameter | Required | Description |
|-----------|:--------:|-------------|
| `assembly_path` | Yes | Path to .dll or .exe |

</details>

### Metadata Tools (no ilspycmd required)

These tools use direct PE/metadata parsing via [dnfile](https://github.com/malwarefrank/dnfile) and work without any .NET installation.

<details>
<summary><strong>search_methods</strong> — Find methods by name pattern</summary>

| Parameter | Required | Description |
|-----------|:--------:|-------------|
| `assembly_path` | Yes | Path to .dll or .exe |
| `pattern` | Yes | Method name pattern |
| `type_filter` | No | Limit to types containing this string |
| `namespace_filter` | No | Limit to specific namespace |
| `public_only` | No | Only public methods |
| `use_regex` | No | Enable regex matching |

```json
{
  "assembly_path": "/path/to/MyApp.dll",
  "pattern": "Handle",
  "public_only": true
}
```
</details>

<details>
<summary><strong>search_fields</strong> — Find fields and constants</summary>

Great for finding magic numbers, configuration values, and API keys stored as constants.

| Parameter | Required | Description |
|-----------|:--------:|-------------|
| `assembly_path` | Yes | Path to .dll or .exe |
| `pattern` | Yes | Field name pattern |
| `constants_only` | No | Only literal/const fields |
| `public_only` | No | Only public fields |

```json
{
  "assembly_path": "/path/to/MyApp.dll",
  "pattern": "Key|Secret|Password",
  "use_regex": true,
  "constants_only": true
}
```
</details>

<details>
<summary><strong>search_properties</strong> — Find properties by name</summary>

| Parameter | Required | Description |
|-----------|:--------:|-------------|
| `assembly_path` | Yes | Path to .dll or .exe |
| `pattern` | Yes | Property name pattern |
| `type_filter` | No | Limit to types containing this string |
| `namespace_filter` | No | Limit to specific namespace |

</details>

<details>
<summary><strong>list_events</strong> — List all events in an assembly</summary>

Useful for understanding event-driven architectures and observer patterns.

| Parameter | Required | Description |
|-----------|:--------:|-------------|
| `assembly_path` | Yes | Path to .dll or .exe |
| `type_filter` | No | Limit to types containing this string |
| `namespace_filter` | No | Limit to specific namespace |

</details>

<details>
<summary><strong>list_resources</strong> — Find embedded resources</summary>

Discovers embedded files, images, localization data, and other resources.

| Parameter | Required | Description |
|-----------|:--------:|-------------|
| `assembly_path` | Yes | Path to .dll or .exe |

</details>

<details>
<summary><strong>get_metadata_summary</strong> — Comprehensive assembly statistics</summary>

Returns type/method/field/property/event counts and referenced assemblies.

| Parameter | Required | Description |
|-----------|:--------:|-------------|
| `assembly_path` | Yes | Path to .dll or .exe |

</details>

### Installation & Diagnostics

<details>
<summary><strong>check_ilspy_installation</strong> — Diagnose your setup</summary>

Shows whether dotnet CLI and ilspycmd are installed, with version info and troubleshooting tips.

No parameters required.
</details>

<details>
<summary><strong>install_ilspy</strong> — Auto-install everything you need</summary>

Detects your platform and installs the .NET SDK and ilspycmd automatically.

| Parameter | Required | Description |
|-----------|:--------:|-------------|
| `update` | No | Update ilspycmd to latest version |
| `install_dotnet_sdk` | No | Also install .NET SDK if missing |

```json
{
  "install_dotnet_sdk": true
}
```

**Auto-detected package managers:** pacman, apt, dnf, zypper, homebrew, winget, chocolatey
</details>

---

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `LOGLEVEL` | `INFO` | Logging verbosity: `DEBUG`, `INFO`, `WARNING`, `ERROR` |

### Debug Mode

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

---

## Troubleshooting

### "ilspycmd not found"

Ask Claude to run the installation tool:
> *"Install ilspycmd for me"*

Or manually:
```bash
dotnet tool install --global ilspycmd
export PATH="$PATH:$HOME/.dotnet/tools"  # Add to your shell profile
```

### "dotnet not installed"

The `install_ilspy` tool can install it automatically:
```json
{"install_dotnet_sdk": true}
```

Or install manually from [dotnet.microsoft.com/download](https://dotnet.microsoft.com/download)

### Assembly parsing errors

Some obfuscated or corrupted assemblies may fail to parse. The dnfile-based tools (search_methods, search_fields, etc.) are more tolerant than full decompilation.

---

## Supported Formats

- .NET Framework assemblies (2.0 - 4.8)
- .NET Core / .NET 5-9+ assemblies
- Any PE file with .NET metadata

**C# Language Versions:** CSharp1 through CSharp12, Preview, Latest

---

## License

MIT License — see [LICENSE](LICENSE) for details.

## Acknowledgments

- **Original project by [Borealin](https://github.com/Borealin/ilspy-mcp-server)** — foundation for this MCP server
- **[ILSpy](https://github.com/icsharpcode/ILSpy)** — the excellent open-source .NET decompiler
- **[dnfile](https://github.com/malwarefrank/dnfile)** — Python library for .NET metadata parsing
- **[Model Context Protocol](https://modelcontextprotocol.io/)** — the integration standard

---

<p align="center">
  <i>Built for security researchers, reverse engineers, and curious developers.</i>
</p>