# memory-disassembler-mcp

**Repository Path**: PassCrc/CE

## Basic Information

- **Project Name**: memory-disassembler-mcp
- **Description**: 一个用于AI的内存搜索工具 
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-04-15
- **Last Updated**: 2026-04-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Memory Disassembler MCP

[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-1.0%2B-orange.svg)](https://modelcontextprotocol.io/)
[![Version](https://img.shields.io/badge/version-2.0.0-brightgreen.svg)](CHANGELOG.md)

基于 MCP (Model Context Protocol) 的内存反汇编调试服务器，为 AI IDE 提供强大的逆向工程能力。

## 项目概述

Memory Disassembler MCP 是一个功能完善的内存调试和逆向工程工具，通过 MCP 协议为 AI IDE（如 Claude、Cursor 等）提供标准化的工具接口。项目支持 Windows 和 Linux 平台，包含丰富的调试、分析和自动化功能。

### 核心特性

- **进程管理**: 附加/分离进程，支持窗口标题查找、进程伪装检测
- **内存操作**: 读写内存，支持多种数据格式（hex/int/float/string/struct）
- **内存搜索**: CE风格增量搜索，批量多值搜索，并行搜索
- **反汇编/汇编**: 基于 Capstone/Keystone，支持 x86/x64/ARM 架构
- **调试功能**: 软件/硬件断点、条件断点、单步执行、寄存器操作
- **指针扫描**: 自动查找指针链，多级指针解析
- **结构体分析**: 自动识别数据结构，多值关联搜索
- **代码注入**: Hook、NOP、字节注入、DLL注入
- **窗口控制**: OCR识别、鼠标键盘操作、操作序列执行
- **加解密工具**: 哈希、加密、编码转换
- **高级分析**: 控制流图、交叉引用、虚表分析、栈回溯
- **脚本支持**: Lua脚本引擎

### 项目统计

- **工具数量**: 49个（符合MCP 50个限制）
- **源代码文件**: 55个 Python 文件
- **测试覆盖**: 5个测试模块
- **代码量**: 约150KB+

## 目录结构

```
memory-disassembler-mcp/
├── src/                    # 源代码目录
│   ├── server.py          # MCP服务器主模块
│   ├── core/              # 核心功能模块
│   │   ├── disassembler.py        # 反汇编引擎
│   │   ├── incremental_search.py  # CE风格增量搜索
│   │   ├── pointer_scanner.py     # 指针扫描器
│   │   ├── structure_analyzer_v2.py # 结构体分析
│   │   ├── code_injector.py       # 代码注入
│   │   ├── window_input.py        # 窗口输入控制
│   │   ├── window_ocr.py          # OCR识别
│   │   └── ...                    # 其他核心模块
│   ├── platform/          # 平台抽象层
│   │   ├── base.py        # 平台抽象基类
│   │   ├── windows.py     # Windows平台实现
│   │   └── linux.py       # Linux平台实现
│   └── utils/             # 工具函数
├── tests/                 # 测试目录
├── docs/                  # 文档目录
├── ui/                    # Web UI界面
├── pyproject.toml         # 项目配置
├── requirements.txt       # 依赖列表
└── README.md              # 本文档
```

## 安装

### 方式1: pip 安装（推荐）

```bash
pip install memory-disassembler-mcp
```

### 方式2: 源码安装

```bash
git clone https://gitee.com/spr997/CE.git memory-disassembler-mcp
cd memory-disassembler-mcp
pip install -e .
```

### 方式3: 使用安装脚本（Windows）

```bash
# 双击运行 install.bat
# 或在命令行执行
install.bat
```

### 平台依赖

**Windows 平台**:
```bash
pip install pywin32
```

**OCR 功能**（可选）:
```bash
pip install pytesseract easyocr
```

**完整依赖**:
```bash
pip install -r requirements.txt
```

## 配置 MCP

### 在 AI IDE 中配置

在 AI IDE 的 MCP 配置文件中添加：

**方式0: 使用仓库内代理脚本（推荐给 Codex/Desktop）**
```toml
[mcp_servers.memory_disassembler]
command = "node"
args = ["C:/path/to/memory-disassembler-mcp/memory-disassembler-mcp-proxy.js"]

[mcp_servers.memory_disassembler.env]
MCP_PROXY_LOG_FILE = "C:/Users/you/.codex/logs/memory-disassembler-mcp-proxy.log"
```

说明：
- 代理脚本就在仓库根目录，方便跟源码一起迁移到新机器
- 默认调用 `PATH` 里的 `uv`，如果你的 `uv` 不在 `PATH`，可额外设置 `MCP_PROXY_UV`
- 代理默认以 `uv run --extra windows --extra lua python run.py mcp` 启动服务

**方式1: 直接运行**
```json
{
  "mcpServers": {
    "memory-disassembler": {
      "command": "python",
      "args": ["run.py", "mcp"],
      "cwd": "c:/path/to/memory-disassembler-mcp"
    }
  }
}
```

**方式2: 使用 uvx**
```json
{
  "mcpServers": {
    "memory-disassembler": {
      "command": "uvx",
      "args": ["memory-disassembler-mcp"]
    }
  }
}
```

**方式3: 模块方式**
```json
{
  "mcpServers": {
    "memory-disassembler": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/memory-disassembler-mcp"
    }
  }
}
```

### 配置示例

参考项目根目录的 `mcp.json` 文件获取完整配置示例。

## 快速开始

### 1. 附加进程

```python
# 通过进程名
attach_process(process_name="game.exe")

# 通过窗口标题
attach_process(window_title="我的游戏")

# 通过 PID
attach_process(pid=12345)
```

### 2. 搜索内存

```python
# 首次搜索
search_memory(action="new", value=100, value_type="int32")

# 增量筛选
search_memory(action="filter", session_id="xxx", condition="decreased")

# 获取结果
search_memory(action="results", session_id="xxx")
```

### 3. 读写内存

```python
# 读取
read_memory(address="0x12345678", size=100, format="int")

# 写入
write_memory(address="0x12345678", data="100", data_type="int")
```

### 4. 窗口控制

```python
# OCR 识别
window_control(action="ocr", hwnd="0x12345")

# 鼠标点击
window_control(action="click", hwnd="0x12345", x=100, y=200)

# 键盘输入
window_control(action="type", hwnd="0x12345", text="hello")
```

## 工具列表

### 进程管理（3个）

| 工具 | 说明 |
|------|------|
| `list_processes` | 列出所有进程 |
| `attach_process` | 附加到目标进程 |
| `detach_process` | 分离当前进程 |

### 内存操作（5个）

| 工具 | 说明 |
|------|------|
| `read_memory` | 读取内存数据 |
| `write_memory` | 写入内存数据 |
| `search_memory` | CE风格增量搜索 |
| `batch_search` | 批量多值搜索 |
| `memory_info` | 查询内存区域信息 |

### 反汇编（2个）

| 工具 | 说明 |
|------|------|
| `disassemble` | 反汇编机器码 |
| `assemble` | 汇编指令 |

### 调试（6个）

| 工具 | 说明 |
|------|------|
| `breakpoint` | 断点管理（软件/硬件/条件） |
| `registers` | 寄存器读写 |
| `step` | 单步执行 |
| `continue_exec` | 继续执行 |
| `threads` | 线程管理 |
| `watch` | 监视点 |

### 分析（8个）

| 工具 | 说明 |
|------|------|
| `analyze_structure` | 结构体分析 |
| `scan_pointers` | 指针扫描 |
| `snapshot` | 内存快照 |
| `diff` | 差异分析 |
| `signature` | 签名生成 |
| `cfg` | 控制流图分析 |
| `xref` | 交叉引用分析 |
| `vtable` | 虚表分析 |

### 注入（3个）

| 工具 | 说明 |
|------|------|
| `inject` | 代码注入 |
| `alloc` | 内存分配 |
| `lua` | Lua脚本执行 |

### 监控（3个）

| 工具 | 说明 |
|------|------|
| `trace` | 数据跟踪 |
| `access_trace` | 访问追踪 |
| `call_trace` | 调用追踪 |

### 其他工具

| 工具 | 说明 |
|------|------|
| `window_control` | 窗口控制/OCR |
| `crypto` | 加解密工具 |
| `pe_parser` | PE文件解析 |
| `pdb_parser` | PDB符号解析 |

## 高级用法

### 分散式数据处理

游戏可能将数据分散存储，使用以下方法处理：

```python
# 批量多值搜索（分组模式）
batch_search(
    action="new",
    values=[100, 200, 50],  # 气血、法力、等级
    grouped=True,
    max_distance=256
)

# 多值关联搜索
analyze_structure(
    action="correlated",
    values=[100, 200, 50],
    max_distance=256
)

# HP/MP 专用模式
analyze_structure(
    action="hp_mp",
    current_hp=100, max_hp=100,
    current_mp=200, max_mp=200
)
```

### 指针链查找

```python
# 扫描指针链
scan_pointers(
    target_address="0x12345678",
    max_level=5,
    max_offset=4096,
    base_module="game.exe"
)

# 解析指针链
pointer_chain(
    action="resolve",
    expression="[[game.exe+0x1000]+0x10]+0x8"
)
```

### 代码注入

```python
# 创建 Hook
inject(
    action="hook",
    address="0x401000",
    hook_address="0x500000",
    hook_type="jmp"
)

# NOP 填充
inject(action="nop", address="0x401000", size=5)

# 写入汇编
inject(action="asm", address="0x401000", assembly="mov eax, 100; ret")

# DLL 注入
inject(action="dll", dll_path="C:/path/to/dll.dll")
```

### 窗口自动化

```python
# 执行操作序列
window_control(
    action="sequence",
    hwnd="0x12345",
    actions=[
        {"type": "click", "x": 100, "y": 200},
        {"type": "wait", "duration": 0.5},
        {"type": "type", "text": "hello"},
        {"type": "key", "key": "enter"},
        {"type": "combo", "keys": ["ctrl", "s"]}
    ]
)
```

### 控制流图分析

```python
# 生成控制流图
cfg(
    action="generate",
    address="0x401000",
    depth=3
)

# 可视化导出
cfg(
    action="export",
    format="dot"  # 或 "json", "svg"
)
```

### 加解密操作

```python
# 哈希计算
crypto(action="hash", algorithm="sha256", data="hello")

# AES 加密
crypto(action="encrypt", algorithm="aes", data="secret", key="mykey")

# Base64 编码
crypto(action="encode", algorithm="base64", data="hello")
```

## AI 助手使用指南

Memory Disassembler MCP 的核心目标是让 AI 具备像人类逆向工程师一样的思考和操作能力。我们专门为 AI（如 Claude、Cursor 等）设计了这套工具。

### 核心能力赋予

1. **自主内存搜索 (CE 风格)**
   - AI 可以自主附加进程并启动首次内存扫描。
   - 当扫描结果过多时，AI 会提示用户在游戏中触发数值变化，然后通过增量筛选 (`action="filter"`) 定位最终地址。
2. **自动化指针分析**
   - 找到动态地址后，AI 可以调用 `scan_pointers` 自动逆推指针链，找出稳定的基址和偏移量。
3. **结构体自动推断**
   - AI 能读取内存区块并结合 `analyze_structure` 推测出角色的数据结构（HP、MP、坐标等相邻属性）。
4. **安全的代码注入**
   - AI 在编写汇编代码或执行 Hook 前，会自动分析上下文并分配安全内存 (`alloc`)，实现一键无损注入。

> 🤖 **给 AI 的提示**: 详细的操作规范、搜索策略和防错指南，请参阅 [AI 使用指南 (AI_USAGE_RULES.md)](docs/AI_USAGE_RULES.md) 和 [技能配置 (.trae/skills/memory-disassembler/SKILL.md)](.trae/skills/memory-disassembler/SKILL.md)。

## 运行模式

### MCP 服务器模式

```bash
python run.py mcp
```

### Web 服务器模式

```bash
python run.py web --host 127.0.0.1 --port 8765
```

访问 `http://127.0.0.1:8765` 使用 Web UI。

### CLI 交互模式

```bash
python run.py cli
```

### 直接运行工具

```bash
python run.py run <tool_name> --args '{"key": "value"}'
```

## 系统要求

- **Python**: 3.10 或更高版本
- **操作系统**: 
  - Windows 10/11（完整功能支持）
  - Linux（基础功能支持）
- **权限**: 管理员权限（调试功能需要）
- **内存**: 建议 4GB 以上

## 依赖项

### 核心依赖

| 库名 | 版本 | 用途 |
|------|------|------|
| mcp | >=1.0.0 | MCP协议实现 |
| capstone | >=5.0.0 | 反汇编引擎 |
| keystone-engine | >=0.9.2 | 汇编引擎 |
| pycryptodome | >=3.19.0 | 加密解密 |
| psutil | >=5.9.0 | 进程管理 |
| aiohttp | >=3.9.0 | 异步HTTP |
| pillow | >=10.0.0 | 图像处理 |

### 可选依赖

| 库名 | 用途 |
|------|------|
| pywin32 | Windows API |
| pytesseract | OCR识别 |
| easyocr | OCR识别（推荐） |
| fastapi | Web服务器 |
| uvicorn | ASGI服务器 |

## 测试

### 运行测试

```bash
# 运行所有测试
pytest

# 运行特定测试
pytest tests/test_incremental_search.py

# 带覆盖率报告
pytest --cov=src tests/
```

### 测试覆盖

- 加密模块测试
- 数据解码测试
- 差异分析测试
- 增量搜索测试
- 签名生成测试

## 文档

- [使用指南](docs/使用指南.md)
- [部署教程](docs/DEPLOYMENT.md)
- [AI 使用指南与规则](docs/AI_USAGE_RULES.md)
- [技能文档](docs/SKILLS.md)
- [坐标查找指南](docs/coordinate-finding-guide.md)
- [结构体分析指南](docs/structure-analysis-guide.md)
- [更新日志](CHANGELOG.md)

## 常见问题

### Q: 为什么需要管理员权限？

A: 调试功能（断点、单步执行等）需要访问进程内存和修改执行流，这需要管理员权限。

### Q: 支持 Linux 吗？

A: 支持，但功能有限。Windows 平台提供完整的调试功能，Linux 平台提供基础的内存操作功能。

### Q: 如何在 AI IDE 中使用？

A: 在 AI IDE 的 MCP 配置文件中添加服务器配置，然后重启 IDE。详细步骤请参考 [部署教程](docs/DEPLOYMENT.md)。

### Q: 工具数量限制是多少？

A: MCP 协议建议工具数量不超过 50 个。本项目提供 49 个工具，符合限制要求。

## 许可证

本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。

## 贡献

欢迎提交 Issue 和 Pull Request！

### 贡献指南

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

### 代码规范

- 使用 `black` 格式化代码
- 使用 `mypy` 进行类型检查
- 编写单元测试覆盖新功能

## 致谢

- [Capstone](http://www.capstone-engine.org/) - 反汇编引擎
- [Keystone](http://www.keystone-engine.org/) - 汇编引擎
- [MCP](https://modelcontextprotocol.io/) - Model Context Protocol

## 联系方式

- 项目主页: https://gitee.com/spr997/CE
- 问题反馈: https://gitee.com/spr997/CE/issues

---

**注意**: 本工具仅供学习和研究使用，请勿用于非法用途。使用本工具进行逆向工程时，请遵守相关法律法规和软件许可协议。