docs: revamp README with compelling structure and modern formatting
- Add badges (PyPI, Python version, License, MCP) - Hero section with clear value proposition - Quick Start in 30 seconds at the top - "What Can You Do?" section with real-world use cases - Features at a Glance table showing tool/dependency matrix - Collapsible <details> sections for tool reference (cleaner UX) - Table of contents for navigation - Streamlined troubleshooting section - Centered footer tagline for security researchers
This commit is contained in:
parent
4354408588
commit
80a0a15cfc
686
README.md
686
README.md
@ -1,426 +1,464 @@
|
|||||||
# mcilspy
|
# mcilspy
|
||||||
|
|
||||||
A Model Context Protocol (MCP) server that provides .NET assembly decompilation capabilities using ILSpy.
|
[](https://pypi.org/project/mcilspy/)
|
||||||
|
[](https://www.python.org/downloads/)
|
||||||
|
[](https://opensource.org/licenses/MIT)
|
||||||
|
[](https://modelcontextprotocol.io/)
|
||||||
|
|
||||||
## Features
|
**Decompile, search, and analyze .NET assemblies with AI assistance.**
|
||||||
|
|
||||||
### ILSpy-based Tools (requires ilspycmd)
|
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.
|
||||||
- **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
|
## Quick Start (30 seconds)
|
||||||
- **Check Installation**: Verify ilspycmd and dotnet CLI status
|
|
||||||
- **Install ILSpy**: Automatically install or update ilspycmd
|
|
||||||
|
|
||||||
## Prerequisites
|
```bash
|
||||||
|
# Install
|
||||||
|
pip install mcilspy
|
||||||
|
|
||||||
1. **ILSpy Command Line Tool**: Install the global dotnet tool:
|
# Add to Claude Code
|
||||||
```bash
|
claude mcp add ilspy -- python -m mcilspy.server
|
||||||
dotnet tool install --global ilspycmd
|
|
||||||
```
|
|
||||||
|
|
||||||
2. **Python 3.10+**: Required for running the MCP server
|
# Or add to Claude Desktop's config.json
|
||||||
|
```
|
||||||
|
|
||||||
## Installation
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"ilspy": {
|
||||||
|
"command": "python",
|
||||||
|
"args": ["-m", "mcilspy.server"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
Install from PyPI:
|
**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 | 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_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 |
|
||||||
|
| `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.
|
||||||
|
**8 more tools** unlock with `ilspycmd` for full decompilation power.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Installation Options
|
||||||
|
|
||||||
|
### Option 1: Just the MCP Server (metadata tools only)
|
||||||
```bash
|
```bash
|
||||||
pip install mcilspy
|
pip install mcilspy
|
||||||
```
|
```
|
||||||
|
Gives you search and metadata tools immediately.
|
||||||
|
|
||||||
Or for development:
|
### Option 2: Full Decompilation Power
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
git clone https://github.com/Borealin/mcilspy.git
|
# Install the MCP server
|
||||||
cd mcilspy
|
pip install mcilspy
|
||||||
pip install -e .
|
|
||||||
|
# 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
|
||||||
```
|
```
|
||||||
|
|
||||||
## Usage
|
**Supported platforms for auto-install:**
|
||||||
|
- Arch Linux (`pacman`)
|
||||||
|
- Ubuntu/Debian (`apt`)
|
||||||
|
- Fedora/RHEL (`dnf`)
|
||||||
|
- macOS (`homebrew`)
|
||||||
|
- Windows (`winget` / `chocolatey`)
|
||||||
|
|
||||||
### MCP Client Configuration
|
### Option 3: Manual ilspycmd Setup
|
||||||
|
```bash
|
||||||
|
# Install .NET SDK from https://dotnet.microsoft.com/download
|
||||||
|
# Then:
|
||||||
|
dotnet tool install --global ilspycmd
|
||||||
|
```
|
||||||
|
|
||||||
Configure your MCP client (e.g., Claude Desktop) to use the server:
|
---
|
||||||
|
|
||||||
|
## 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# |
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"mcpServers": {
|
"assembly_path": "/path/to/MyApp.dll",
|
||||||
"ilspy": {
|
"type_name": "MyApp.Services.AuthService"
|
||||||
"command": "python",
|
|
||||||
"args": ["-m", "mcilspy.server"]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
</details>
|
||||||
|
|
||||||
### Available Tools
|
<details>
|
||||||
|
<summary><strong>list_types</strong> — Enumerate types in an assembly</summary>
|
||||||
|
|
||||||
#### 1. `decompile_assembly`
|
Your starting point for exploring unknown assemblies.
|
||||||
Decompile a .NET assembly to C# source code. This is the primary tool for reverse-engineering .NET binaries.
|
|
||||||
|
|
||||||
**Parameters:**
|
| Parameter | Required | Description |
|
||||||
- `assembly_path` (required): Path to the .NET assembly file
|
|-----------|:--------:|-------------|
|
||||||
- `output_dir` (optional): Output directory for decompiled files
|
| `assembly_path` | Yes | Path to .dll or .exe |
|
||||||
- `type_name` (optional): Fully qualified type name to decompile (e.g., "MyNamespace.MyClass")
|
| `entity_types` | No | Filter: `class`, `interface`, `struct`, `delegate`, `enum` |
|
||||||
- `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
|
```json
|
||||||
{
|
{
|
||||||
"name": "decompile_assembly",
|
"assembly_path": "/path/to/MyApp.dll",
|
||||||
"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"]
|
"entity_types": ["class", "interface"]
|
||||||
}
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
</details>
|
||||||
|
|
||||||
#### 3. `search_types`
|
<details>
|
||||||
Search for types by name pattern. Essential for finding specific classes in large assemblies.
|
<summary><strong>search_types</strong> — Find types by name pattern</summary>
|
||||||
|
|
||||||
**Parameters:**
|
| Parameter | Required | Description |
|
||||||
- `assembly_path` (required): Path to the .NET assembly file
|
|-----------|:--------:|-------------|
|
||||||
- `pattern` (required): Search pattern to match against type names
|
| `assembly_path` | Yes | Path to .dll or .exe |
|
||||||
- `namespace_filter` (optional): Only search in namespaces containing this string
|
| `pattern` | Yes | Search pattern |
|
||||||
- `entity_types` (optional): Types to search (default: all types)
|
| `namespace_filter` | No | Limit to specific namespace |
|
||||||
- `case_sensitive` (optional): Case-sensitive matching (default: false)
|
| `use_regex` | No | Enable regex matching |
|
||||||
- `use_regex` (optional): Treat pattern as regular expression (default: false)
|
| `case_sensitive` | No | Case-sensitive search |
|
||||||
|
|
||||||
**Example:**
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"name": "search_types",
|
"assembly_path": "/path/to/MyApp.dll",
|
||||||
"arguments": {
|
"pattern": "Controller",
|
||||||
"assembly_path": "/path/to/MyAssembly.dll",
|
"namespace_filter": "MyApp.Web"
|
||||||
"pattern": "Service",
|
|
||||||
"namespace_filter": "MyApp.Services"
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
</details>
|
||||||
|
|
||||||
#### 4. `search_strings`
|
<details>
|
||||||
Search for string literals in assembly code. Crucial for reverse engineering - finds hardcoded URLs, credentials, configuration, etc.
|
<summary><strong>search_strings</strong> — Find hardcoded strings (secrets, URLs, config)</summary>
|
||||||
|
|
||||||
**Parameters:**
|
Essential for security analysis. Finds strings embedded in IL code.
|
||||||
- `assembly_path` (required): Path to the .NET assembly file
|
|
||||||
- `pattern` (required): String pattern to search for
|
| Parameter | Required | Description |
|
||||||
- `case_sensitive` (optional): Case-sensitive matching (default: false)
|
|-----------|:--------:|-------------|
|
||||||
- `use_regex` (optional): Treat pattern as regular expression (default: false)
|
| `assembly_path` | Yes | Path to .dll or .exe |
|
||||||
- `max_results` (optional): Maximum matches to return (default: 100)
|
| `pattern` | Yes | String to search for |
|
||||||
|
| `use_regex` | No | Enable regex matching |
|
||||||
|
| `max_results` | No | Limit results (default: 100) |
|
||||||
|
|
||||||
**Example:**
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"name": "search_strings",
|
"assembly_path": "/path/to/MyApp.dll",
|
||||||
"arguments": {
|
"pattern": "api\\..*\\.com"
|
||||||
"assembly_path": "/path/to/MyAssembly.dll",
|
"use_regex": true
|
||||||
"pattern": "api.example.com"
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
</details>
|
||||||
|
|
||||||
#### 5. `generate_diagrammer`
|
<details>
|
||||||
Generate an interactive HTML diagram showing assembly type relationships.
|
<summary><strong>generate_diagrammer</strong> — Create interactive type relationship diagrams</summary>
|
||||||
|
|
||||||
**Parameters:**
|
Generates an HTML visualization of type hierarchies and relationships.
|
||||||
- `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`
|
| Parameter | Required | Description |
|
||||||
Get metadata and version information about an assembly.
|
|-----------|:--------:|-------------|
|
||||||
|
| `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 |
|
||||||
|
|
||||||
**Parameters:**
|
</details>
|
||||||
- `assembly_path` (required): Path to the .NET assembly file
|
|
||||||
|
|
||||||
Returns: Assembly name, version, target framework, signing status, and debug info availability.
|
<details>
|
||||||
|
<summary><strong>get_assembly_info</strong> — Get assembly metadata</summary>
|
||||||
|
|
||||||
### Direct Metadata Tools
|
Returns version, target framework, strong name signing status, and debug info.
|
||||||
|
|
||||||
These tools use direct PE/metadata parsing via [dnfile](https://github.com/malwarefrank/dnfile) and don't require ilspycmd to be installed.
|
| Parameter | Required | Description |
|
||||||
|
|-----------|:--------:|-------------|
|
||||||
|
| `assembly_path` | Yes | Path to .dll or .exe |
|
||||||
|
|
||||||
#### 7. `search_methods`
|
</details>
|
||||||
Search for methods in an assembly by name pattern. Useful for finding entry points, event handlers, and API endpoints.
|
|
||||||
|
|
||||||
**Parameters:**
|
### Metadata Tools (no ilspycmd required)
|
||||||
- `assembly_path` (required): Path to the .NET assembly file
|
|
||||||
- `pattern` (required): Search pattern to match against method names
|
These tools use direct PE/metadata parsing via [dnfile](https://github.com/malwarefrank/dnfile) and work without any .NET installation.
|
||||||
- `type_filter` (optional): Only search methods in types containing this string
|
|
||||||
- `namespace_filter` (optional): Only search in namespaces containing this string
|
<details>
|
||||||
- `public_only` (optional): Only return public methods (default: false)
|
<summary><strong>search_methods</strong> — Find methods by name pattern</summary>
|
||||||
- `case_sensitive` (optional): Case-sensitive matching (default: false)
|
|
||||||
- `use_regex` (optional): Treat pattern as regular expression (default: false)
|
| 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 |
|
||||||
|
|
||||||
**Example:**
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"name": "search_methods",
|
"assembly_path": "/path/to/MyApp.dll",
|
||||||
"arguments": {
|
|
||||||
"assembly_path": "/path/to/MyAssembly.dll",
|
|
||||||
"pattern": "Handle",
|
"pattern": "Handle",
|
||||||
"public_only": true
|
"public_only": true
|
||||||
}
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
</details>
|
||||||
|
|
||||||
#### 8. `search_fields`
|
<details>
|
||||||
Search for fields and constants in an assembly. Useful for finding configuration values and magic numbers.
|
<summary><strong>search_fields</strong> — Find fields and constants</summary>
|
||||||
|
|
||||||
**Parameters:**
|
Great for finding magic numbers, configuration values, and API keys stored as constants.
|
||||||
- `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`
|
| Parameter | Required | Description |
|
||||||
Search for properties in an assembly by name pattern. Useful for finding data model fields and configuration properties.
|
|-----------|:--------:|-------------|
|
||||||
|
| `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 |
|
||||||
|
|
||||||
**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
|
```json
|
||||||
{
|
{
|
||||||
"name": "install_ilspy",
|
"assembly_path": "/path/to/MyApp.dll",
|
||||||
"arguments": {
|
"pattern": "Key|Secret|Password",
|
||||||
"update": true
|
"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 |
|
||||||
|
|
||||||
**Example - Full installation (SDK + ilspycmd):**
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"name": "install_ilspy",
|
|
||||||
"arguments": {
|
|
||||||
"install_dotnet_sdk": true
|
"install_dotnet_sdk": true
|
||||||
}
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### Available Prompts
|
**Auto-detected package managers:** pacman, apt, dnf, zypper, homebrew, winget, chocolatey
|
||||||
|
</details>
|
||||||
|
|
||||||
#### 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
|
## Configuration
|
||||||
|
|
||||||
### Environment Variables
|
### Environment Variables
|
||||||
|
|
||||||
- `LOGLEVEL`: Set logging level (DEBUG, INFO, WARNING, ERROR). Default: INFO
|
| Variable | Default | Description |
|
||||||
|
|----------|---------|-------------|
|
||||||
### MCP Client Examples
|
| `LOGLEVEL` | `INFO` | Logging verbosity: `DEBUG`, `INFO`, `WARNING`, `ERROR` |
|
||||||
|
|
||||||
**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
|
### Debug Mode
|
||||||
|
|
||||||
Enable debug logging to see detailed operation info:
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"ilspy": {
|
||||||
|
"command": "python",
|
||||||
|
"args": ["-m", "mcilspy.server"],
|
||||||
"env": {
|
"env": {
|
||||||
"LOGLEVEL": "DEBUG"
|
"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
|
## License
|
||||||
|
|
||||||
This project is licensed under the MIT License - see the LICENSE file for details.
|
MIT License — see [LICENSE](LICENSE) for details.
|
||||||
|
|
||||||
## Acknowledgments
|
## Acknowledgments
|
||||||
|
|
||||||
- **Original project by [Borealin](https://github.com/Borealin/ilspy-mcp-server)** - Thank you for creating the foundation for this MCP server!
|
- **Original project by [Borealin](https://github.com/Borealin/ilspy-mcp-server)** — foundation for this MCP server
|
||||||
- Built on top of the excellent [ILSpy](https://github.com/icsharpcode/ILSpy) decompiler
|
- **[ILSpy](https://github.com/icsharpcode/ILSpy)** — the excellent open-source .NET decompiler
|
||||||
- Uses the [Model Context Protocol](https://modelcontextprotocol.io/) for integration
|
- **[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>
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user