mcilspy/docs/API.md

API Documentation

This document provides detailed API documentation for the ILSpy MCP Server.

Overview

The ILSpy MCP Server provides a Model Context Protocol (MCP) interface to the ILSpy .NET decompiler. It exposes four main tools and two prompts for interacting with .NET assemblies.

Tools

1. decompile_assembly

Decompiles a .NET assembly to C# source code.

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 code instead of C#
remove_dead_code	boolean	✗	false	Remove dead code during decompilation
nested_directories	boolean	✗	false	Use nested directories for namespaces

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.

Parameters:

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

Entity Types:

• c - Classes
• i - Interfaces
• s - Structs
• d - Delegates
• e - Enums

Example:

{
  "name": "list_types",
  "arguments": {
    "assembly_path": "/path/to/MyAssembly.dll",
    "entity_types": ["c", "i", "s"]
  }
}

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

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

3. generate_diagrammer

Generates an interactive HTML diagrammer for visualizing assembly structure.

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\\..+"
  }
}

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

4. get_assembly_info

Gets basic information about a .NET assembly.

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
• Full name
• Location
• Target framework (if available)
• Runtime version (if available)
• Whether the assembly is signed
• Whether debug information is available

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: Optional[str] = None
    type_name: Optional[str] = None
    language_version: LanguageVersion = LanguageVersion.LATEST
    create_project: bool = False
    show_il_code: bool = False
    remove_dead_code: bool = False
    nested_directories: bool = False
    # ... additional fields

TypeInfo

class TypeInfo(BaseModel):
    name: str
    full_name: str
    kind: str
    namespace: Optional[str] = None

AssemblyInfo

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

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": ["c", "i"]
    }
)

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
    }
)

Configuration

Environment Variables

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

MCP Client Configuration

For Claude Desktop:

{
  "mcpServers": {
    "ilspy": {
      "command": "ilspy-mcp-server"
    }
  }
}

For development:

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