mirror of
https://github.com/Kowntaewook/MCPTrace.git
synced 2026-11-02 04:45:09 +01:00
kwonta3wook
57 lines
2.1 KiB
Markdown
57 lines
2.1 KiB
Markdown
# MCPTrace
|
|
|
|
A Volatility 3 plugin for extracting MCP/JSON-RPC message candidates from Windows x64 and Linux x86-64 memory dumps. Preserves message content, process IDs, virtual addresses, and SHA-256 hashes, with optional JSONL export.
|
|
|
|
## Installation
|
|
|
|
Requires Python 3.10+. Run in an activated virtual environment:
|
|
|
|
```sh
|
|
git clone https://github.com/Kowntaewook/MCPTrace.git
|
|
cd MCPTrace
|
|
python -m pip install .
|
|
```
|
|
|
|
## Usage
|
|
|
|
Run from the repository root. Choose the plugin matching the **dump's OS** and replace the example paths and PIDs.
|
|
|
|
**Windows**
|
|
|
|
```sh
|
|
vol -f windows.raw windows.pslist.PsList
|
|
mkdir output-windows
|
|
vol -p plugins -f windows.raw -o output-windows windows.mcptrace.MCPTrace --pid 4242 --dump
|
|
```
|
|
|
|
**Linux**
|
|
|
|
Place ISF symbols matching the dump's kernel build in `symbols/linux/` first.
|
|
|
|
```sh
|
|
vol -s symbols -f linux.lime linux.pslist.PsList
|
|
mkdir output-linux
|
|
vol -p plugins -s symbols -f linux.lime -o output-linux linux.mcptrace.MCPTrace --pid 4242 --dump
|
|
```
|
|
|
|
- Omit `--pid` to scan all processes, or pass multiple PIDs: `--pid 4242 5252`.
|
|
- `--dump` exports per-process JSONL files to the directory specified by `-o`.
|
|
- Use `vol -p plugins windows.mcptrace.MCPTrace -h` (or the Linux equivalent) for all options.
|
|
|
|
## Benchmark
|
|
|
|
Windows Server 2022, Python MCP SDK over stdio: **3 independent RAM captures**,
|
|
64 tool calls / 133 messages per condition per capture. Results combine both endpoints.
|
|
|
|
| Condition | Messages / 133: mean (range) | Tool pairs / 64: mean (range) |
|
|
| --- | ---: | ---: |
|
|
| No retained-frame list | 59.7 (55-66) | 18.3 (15-21) |
|
|
| Retained-frame control | 133.0 (133-133) | 64.0 (64-64) |
|
|
|
|
CLI median: **53.95 s** (53.32-54.48 s, 9 scans of 4 endpoint processes).
|
|
Acquisition and initial symbol setup are excluded; scans are not cold-cache measurements.
|
|
|
|
**2/3 captures hit candidate search limits** (4 and 3 events); these limited results are included.
|
|
Ground-truth logging affects memory, and retained frames are a favorable control.
|
|
This is fixture-specific recovery, not general recall. [Methodology and full results](docs/windows-memory-benchmark.md).
|