# ILSpy MCP Server

A production-grade MCP server that exposes all major ILSpy CLI features as separate tools for decompiling .NET assemblies.

## Features

- **10 MCP Tools**: Decompile, export projects, extract IL, list types/methods, resolve references, and more
- **Workflow Orchestration**: Automated end-to-end processing of .NET assemblies
- **Structured Output**: JSON reports with metadata, types, methods, and logs
- **Forward Compatible**: Raw ilspycmd tool for unsupported features
- **Cross-Platform**: Works on Windows, Linux, and macOS

## Prerequisites

- Python 3.10+
- ILSpy CLI (ilspycmd) installed and available in PATH
  - Download from: https://github.com/icsharpcode/ILSpy/releases
  - Or install via: `dotnet tool install -g ilspycmd`

## Installation

```bash
pip install -r requirements.txt
```

## Usage

### Option 1: MCP Server Mode

Start the MCP server and use it with any MCP-compatible client:

```bash
python server.py
```

The server communicates via stdio using JSON-RPC. Configure it in your MCP client using `config.json`.

### Option 2: Direct Orchestrator Usage

Process assemblies directly using the orchestrator:

```bash
# Single assembly
python orchestrator.py assembly.dll

# Multiple assemblies
python orchestrator.py assembly1.dll assembly2.dll assembly3.exe

# With options
python orchestrator.py assembly.dll --langver:11 --nullable --no-records
```

### Option 3: Python API

Use the orchestrator programmatically:

```python
from orchestrator import process_assemblies, save_report
from pathlib import Path

report = process_assemblies(
    ["assembly.dll"],
    language_version="11",
    nullable_enabled=True,
    handle_records=True,
)

save_report(report, Path("work/report.json"))
```

## Tools

1. **decompile_file** - Decompile assembly to C# files
   - Supports: `--langver`, `--nullable`, `--with-records`, etc.

2. **export_project** - Export compilable C# project
   - Includes: References, metadata, project files

3. **get_il** - Extract IL code
   - View intermediate language instead of decompiled C#

4. **list_types** - List all types in assembly
   - Returns: Namespace-qualified type names

5. **list_methods** - List methods for a type
   - Input: Full type name (e.g., `Namespace.ClassName`)

6. **resolve_references** - Analyze external references
   - Extracts: Package references, assembly references

7. **set_language_version** - Control C# language version
   - Versions: 9, 10, 11, 12, etc.

8. **enable_nullable_context** - Enable/disable nullable reference types
   - Options: `true` or `false`

9. **handle_records_init_only** - Handle record types properly
   - Ensures: Records and init-only setters decompile correctly

10. **raw_ilspycmd** - Run arbitrary ilspycmd commands
    - Forward-compatible with all future ILSpy features

## Output Structure

```
work/
  input/              # Input assemblies (optional)
  output/
    decompile/        # Decompiled C# files
      <assembly>/
        *.cs files
    project/          # Exported projects
      <assembly>/
        *.csproj
        *.cs files
    il/               # IL code output
      <assembly>/
        *.il files
  report.json         # Final structured JSON report
```

## JSON Report Format

The orchestrator generates a structured JSON report:

```json
{
  "assemblies": [
    {
      "assembly": "example.dll",
      "status": "success",
      "paths": {
        "decompiled": "work/output/decompile/example/",
        "project": "work/output/project/example/",
        "il": "work/output/il/example/"
      },
      "types": [
        {
          "name": "Namespace.MyClass",
          "methods": ["Main", "DoSomething"],
          "il_size": {"Main": 123, "DoSomething": 42}
        }
      ],
      "references": ["System", "System.Linq"],
      "flags_used": ["--langver:11", "--nullable"],
      "logs": {
        "stdout": "...",
        "stderr": "..."
      }
    }
  ]
}
```

## Workflow

The orchestrator follows this workflow for each assembly:

1. **Decompile** → Generate C# source files
2. **Export Project** → Create compilable project with references
3. **Extract IL** → Get intermediate language code
4. **List Types** → Discover all types in assembly
5. **List Methods** → For each type, extract methods
6. **Resolve References** → Analyze dependencies
7. **Apply Settings** → Language version, nullable context, records
8. **Generate Report** → Collect all metadata into JSON

## Error Handling

- All tools return structured JSON with `returncode`, `stdout`, and `stderr`
- Failed operations are marked with `status: "error"` in the report
- Full error logs are included in the report for debugging
- Tools are idempotent - safe to run multiple times

## Examples

See `example_usage.py` for complete examples of:
- Processing single assemblies
- Processing multiple assemblies
- Using different language versions
- Enabling/disabling nullable context
- Custom flags and options

## License

This project wraps ILSpy CLI. Please refer to ILSpy's license for usage terms.