Metadata-Version: 2.4
Name: mcp-reverse-engineering
Version: 0.1.3
Summary: A sandboxed MCP tool for reverse engineering with multiple tool integrations
Project-URL: Homepage, https://github.com/daedalus/mcp_reverse_engineering
Project-URL: Repository, https://github.com/daedalus/mcp_reverse_engineering
Project-URL: Issues, https://github.com/daedalus/mcp_reverse_engineering/issues
Author-email: Darío Clavijo <clavijodario@gmail.com>
License: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: psutil>=5.9.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.28.0
Provides-Extra: all
Requires-Dist: hatch; extra == 'all'
Requires-Dist: hypothesis; extra == 'all'
Requires-Dist: mypy; extra == 'all'
Requires-Dist: pip-api; extra == 'all'
Requires-Dist: pytest; extra == 'all'
Requires-Dist: pytest-asyncio; extra == 'all'
Requires-Dist: pytest-cov; extra == 'all'
Requires-Dist: pytest-mock; extra == 'all'
Requires-Dist: ruff; extra == 'all'
Provides-Extra: dev
Requires-Dist: hatch; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pip-api; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: lint
Requires-Dist: mypy; extra == 'lint'
Requires-Dist: ruff; extra == 'lint'
Provides-Extra: mcp
Requires-Dist: fastmcp; extra == 'mcp'
Provides-Extra: test
Requires-Dist: hypothesis; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-asyncio; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Requires-Dist: pytest-mock; extra == 'test'
Description-Content-Type: text/markdown

# mcp-reverse-engineering

A sandboxed MCP (Model Context Protocol) tool for reverse engineering that provides a unified interface to various reverse engineering tools with security restrictions.

[![PyPI](https://img.shields.io/pypi/v/mcp-reverse-engineering.svg)](https://pypi.org/project/mcp-reverse-engineering/)
[![Python](https://img.shields.io/pypi/pyversions/mcp-reverse-engineering.svg)](https://pypi.org/project/mcp-reverse-engineering/)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

## Purpose

This project provides a secure, sandboxed environment for executing reverse engineering tools via CLI or MCP protocol. It wraps common reverse engineering utilities (strings, objdump, readelf, binwalk, etc.) with safety features like filesystem isolation, timeouts, and argument validation.

## Install

```bash
pip install mcp-reverse-engineering
```

Or for development:

```bash
pip install -e ".[dev]"
```

### MCP Server Installation

To use as an MCP server with Claude Desktop:

```bash
mcp install src/mcp_reverse_engineering/server.py
```

## Usage

### CLI

```bash
# Extract strings from a binary
mcp-re --tool strings --file /path/to/binary

# Disassemble a binary
mcp-re --tool objdump --args "['-d']" --file /path/to/binary

# Analyze ELF headers
mcp-re --tool readelf --args "['-h', '-s']" --file /path/to/elf

# Run binwalk for firmware analysis
mcp-re --tool binwalk --file /path/to/firmware.bin
```

### Python API

```python
from mcp_reverse_engineering import ReverseEngineeringEngine

# Create engine with default config
engine = ReverseEngineeringEngine(
    workspace="./workspace",
    timeout=30,
)

# List available tools
print(engine.list_available_tools())

# Execute a tool
result = engine.execute_tool("strings", ["-n", "8"], "/path/to/binary")
print(result)
```

### MCP Server

```python
from mcp_reverse_engineering.server import mcp, strings, objdump, readelf, binwalk

# Run the server (stdio transport for Claude Desktop)
if __name__ == "__main__":
    mcp.run()
```

## API

### ReverseEngineeringEngine

Main class for executing reverse engineering tools.

```python
engine = ReverseEngineeringEngine(
    workspace: str = "./workspace",  # Sandbox directory
    timeout: int = 30,               # Tool execution timeout
    config_path: str | Path | None = None,  # YAML config path
)
```

**Methods:**

- `execute_tool(tool_name: str, args: List[str], file_path: Optional[str] = None) -> str` - Execute a tool
- `list_available_tools() -> List[str]` - List enabled tools
- `get_tool_documentation(tool_name: str) -> Dict[str, Any]` - Get tool docs
- `get_mcp_tools() -> List[Dict[str, Any]]` - Get MCP tool schemas

### Available Tools

| Tool | Category | Description |
|------|----------|-------------|
| file | file_tools | Determine file type |
| strings | file_tools | Extract printable strings |
| hexdump | file_tools | Hexadecimal dump |
| xxd | file_tools | Hexadecimal dump |
| objdump | binary_tools | Disassemble binary |
| readelf | binary_tools | Read ELF headers |
| binwalk | firmware_tools | Firmware analysis |

## Development

```bash
# Clone the repository
git clone https://github.com/daedalus/mcp_reverse_engineering.git
cd mcp_reverse_engineering

# Install dependencies
pip install -e ".[test]"

# Run tests
pytest

# Format code
ruff format src/ tests/

# Lint
ruff check src/ tests/

# Type check
mypy src/

# Install pre-commit hooks
pip install pre-commit
pre-commit install
```

## MCP Server Configuration

mcp-name: io.github.daedalus/mcp-reverse-engineering

## Requirements

- Python 3.11+
- External tools: binwalk, radare2, ghidra, etc. (must be installed separately)

## License

MIT
