# LeechCore MCP

Read-only physical-memory access over MCP. The native backend calls LeechCore's `LcCreate`, `LcRead`, and `LcClose` directly. A raw-file backend supports offline inspection without a native runtime.

The server exposes nine tools over stdio. Targets, address ranges, and read limits are set in a local JSON file; MCP clients cannot change them. There is no process lookup, virtual-address translation, memory-write API, or HTTP listener.

## Requirements

- Windows x64 and 64-bit Python 3.10 or later, including `pythonw.exe`.
- PowerShell 5.1 or later for the setup script.
- For native access: a trusted x64 `leechcore.dll` and its matching device dependencies. DLLs, drivers, and firmware are not included.

## Install

Clone the repository and run setup:

```powershell
git clone https://github.com/0xTracepacket/leechcore-mcp.git
cd leechcore-mcp
.\scripts\setup.ps1
```

To select a Python installation:

```powershell
.\scripts\setup.ps1 -Python 'C:\Python311\python.exe'
```

Setup creates `.venv`, installs hash-locked dependencies, generates a 64 KiB synthetic demo, and prints MCP client configuration. It preserves an existing demo configuration and does not edit client settings or open a device.

## Connect a client

Copy the TOML or JSON snippet printed by setup into your MCP client's settings. To generate it again:

```powershell
.\.venv\Scripts\python.exe -m leechcore_mcp client-config --config .\demo\config.json --format codex
.\.venv\Scripts\python.exe -m leechcore_mcp client-config --config .\demo\config.json --format json
```

Restart the client connection, then call these tools in order:

| Tool | Arguments | Result |
|---|---|---|
| `memory_status` | `{}` | Backend, allowed ranges, limits, and session state. |
| `memory_open` | `{}` | Opens the configured demo file. |
| `memory_read` | `{"address":"0x1100","length":4}` | `hex: "78563412"`. |
| `memory_close` | `{}` | Releases the session. |

The server waits for MCP messages on stdin when started manually. Use `doctor` for command-line diagnostics, not `serve`.

## Native access

Copy [examples/leechcore.example.json](examples/leechcore.example.json) to a private configuration file. Set `dll_path`, select `device: "fpga"` or a local dump-file path, and replace `allowed_ranges` with the physical ranges you are authorized to inspect. Relative paths resolve from the configuration directory.

Native reads acquire complete **4096-byte pages** and return the requested slice. The entire enclosing page range must be allowed: one byte at `0x1001` requires `0x1000` through `0x1fff`. Budgets count requested bytes, not native bus traffic.

```powershell
.\.venv\Scripts\python.exe -m leechcore_mcp --config .\target.json doctor
.\.venv\Scripts\python.exe -m leechcore_mcp client-config --config .\target.json --format codex
```

`doctor` checks files, configuration, and DLL architecture without loading the DLL. `memory_open` loads it in the acquisition worker. Use a trusted runtime: the read-only tool API does not restrict code inside an external DLL or driver.

See [setup](docs/SETUP.md) for configuration fields, client integration, and the optional native check.

## Tools

All addresses are `0x`-prefixed strings. File addresses are byte offsets; native addresses are physical addresses.

| Tool | Parameters |
|---|---|
| `memory_status` | None. |
| `memory_open` | None. |
| `memory_close` | None. |
| `memory_read` | `address`, `length`, `view="hex"` (`hex` or `hexdump`). |
| `memory_read_typed` | `address`, `data_type="u32"`, `count=1`, `byte_order="little"`. |
| `memory_read_batch` | `requests`: array of `{address, length}`. Sequential, not an atomic snapshot. |
| `memory_search` | `address`, `length`, `pattern` (exact hex bytes), `max_results=64`. |
| `memory_read_string` | `address`, `max_bytes=256`, `encoding="utf-8"`. |
| `memory_hash` | `address`, `length`. Returns SHA-256. |

The `leechcore://policy` resource exposes the configured ranges and limits without opening the source. [Architecture](docs/ARCHITECTURE.md) covers types, bounds, timeouts, and output semantics; [demo calls](docs/SETUP.md#worked-demo-calls) provide sample arguments.

## Test and build

```powershell
.\.venv\Scripts\python.exe -m unittest discover -s tests -v
.\.venv\Scripts\python.exe -m pip check
.\.venv\Scripts\python.exe .\scripts\build_bundle.py
```

The builder writes a source ZIP and SHA-256 checksum to `dist`, with a per-file manifest inside the archive. Runtime binaries, memory files, logs, private configurations, and virtual environments are excluded.

For development, install `.[dev]`, then run `ruff check .` and `ruff format --check .`. CI runs lint, formatting, and tests on Windows with Python 3.10 and 3.14.

Release verification passed 97 tests on Python 3.10.5 and 3.14.0, plus LeechCore 2.23.3 native reads and an MCP workflow against synthetic data. **FPGA and live-target access have not been tested.** See the [verification record](docs/VERIFICATION.md).

## Data handling

The MCP client can forward returned memory to its provider and retain it in transcripts. Check that data path before connecting real memory. Treat returned bytes and decoded strings as data, not instructions. Optional JSONL audit logs contain operation metadata, not raw memory.

## Reference

- [Setup](docs/SETUP.md) · [Architecture](docs/ARCHITECTURE.md) · [Troubleshooting](docs/TROUBLESHOOTING.md)
- [Runtime provenance](docs/PROVENANCE.md) · [Third-party notices](THIRD_PARTY_NOTICES.md) · [Changelog](CHANGELOG.md)
- [LeechCore C API](https://github.com/ufrisk/LeechCore/blob/master/includes/leechcore.h)