# IDA Pro MCP 插件（Python 3.9 兼容版）

基于 [namename333/idapromcp_333](https://github.com/namename333/idapromcp_333) 修复，解决了依赖安装和 Python 兼容性问题。

## 兼容性

| 组件              | 版本                   |
| ----------------- | ---------------------- |
| IDA Pro           | 7.x - 8.x (测试于 8.4) |
| IDA Python        | 3.9+                   |
| MCP Server Python | 3.11+                  |

## 简介

通过 MCP (Model Context Protocol) 将 LLM 客户端连接到 IDA Pro，实现：

- 函数/变量自动重命名和类型推断
- 混淆检测和反调试识别
- 算法识别（RC4、AES、Base64等）
- 批量分析和报告导出
- 支持 Cursor、Windsurf、Claude Desktop 等客户端

## 修复内容

本版本修复了原项目的以下问题：

1. 添加缺失的 `requirements.txt`
2. 修复 Python 3.9 兼容性（原版要求 3.11+）
   - 添加 `from __future__ import annotations`
   - 使用 `typing_extensions.NotRequired`
   - 修复 TypedDict/Generic 继承问题
3. 修正依赖版本冲突（typing-inspection 0.9.0 → 0.4.0）
4. 采用独立 Python 环境，避免破坏 IDA Pro

---

## 功能特性

基于原版 [mrexodia/ida-pro-mcp](https://github.com/mrexodia/ida-pro-mcp)，由 [namename333/idapromcp_333](https://github.com/namename333/idapromcp_333) 增强。

### 核心功能

- **自动化分析**：一句 prompt 完成函数/变量重命名、类型修复、注释、结构体声明
- **多客户端支持**：Cursor、Cline、Roo Code、Windsurf、Claude Desktop、LM Studio
- **批量处理**：批量重命名、注释、类型修复、patch 点定位

### 增强功能（namename333 版本）

- **混淆检测增强**：

  - 控制流平坦化（flattening）
  - switch/case 混淆
  - 间接跳转
  - 死代码（dead_code）
  - 字符串加密（string_encryption）
  - 反调试检测（anti_debug）：TLS、PEB、int 0x2d 等
- **算法识别增强**：

  - 加密算法：RC4、AES、DES、TEA
  - 哈希算法：MD5、SHA1、SHA256、CRC32
  - 编码算法：Base64、Base32/58/85、ROT13、XOR
  - 压缩算法：Zlib、LZMA
  - 其他：Mersenne Twister（随机数生成）
  - 提供算法类型和置信度
- **报告生成**：

  - Markdown 格式多维度分析报告
  - 包含入口点、关键函数、反调试点、算法、混淆特征
  - 主流程图、代码复杂度、交叉引用热点
- **动态分析**：

  - 生成 angr/frida 脚本
  - 符号执行、动态 hook
  - 寄存器/内存监控
- **其他**：

  - 流程图可视化（mermaid/graphviz）
  - 增量变更追踪
  - 全中文注释

---

## 架构说明

采用双 Python 环境，避免版本冲突：

- **IDA Pro 插件**：使用 IDA 自带的 Python 3.9，监听 127.0.0.1:13337
- **MCP 服务器**：使用独立的 Python 3.12，通过 HTTP 连接插件

**注意**：不要切换 IDA Pro 的 Python 版本，否则可能导致 IDA 无法启动。

---

## 安装

### 环境要求

- IDA Pro 7.x - 8.x
- 系统安装 Python 3.12（独立于 IDA Pro）
- macOS / Windows / Linux

### 快速安装

#### 完整安装命令（3 步）

```bash
# 1. 克隆项目
git clone https://github.com/cybermaxluo/IDAProMCP_Max.git
cd IDAProMCP_Max/

# 2. 安装依赖（使用独立 Python 3.12，不是 IDA Pro 的 Python）
# 将下面的路径替换为您系统的实际 Python 3.12 路径

# macOS (Miniconda) 示例
/opt/miniconda3/bin/python3.12 -m pip install -r requirements.txt
/opt/miniconda3/bin/python3.12 -m pip install -e .

# macOS (Homebrew) 示例
/usr/local/bin/python3.12 -m pip install -r requirements.txt
/usr/local/bin/python3.12 -m pip install -e .

# Windows
C:\Python312\python.exe -m pip install -r requirements.txt
C:\Python312\python.exe -m pip install -e .

# Linux
/usr/bin/python3.12 -m pip install -r requirements.txt
/usr/bin/python3.12 -m pip install -e .

# 3. 安装 IDA Pro 插件和 LLM 客户端配置
# macOS 示例（替换为您的实际路径）
/opt/miniconda3/bin/python3.12 -m ida_pro_mcp.server --install

# Windows
C:\Python312\python.exe -m ida_pro_mcp.server --install

# Linux
/usr/bin/python3.12 -m ida_pro_mcp.server --install
```

**这会自动完成**：

- ✅ 安装插件到 `~/.idapro/plugins/mcp-plugin.py`
- ✅ 配置 Cursor (`~/.cursor/mcp.json`)
- ✅ 配置 Claude Desktop
- ✅ 配置 Windsurf
- ✅ 配置 Claude Code

#### 使用自动安装脚本（macOS）

```bash
# 或者使用一键安装脚本（需要先编辑脚本中的 Python 路径）
chmod +x install.sh
./install.sh
```

#### 步骤 3: 配置 LLM 客户端

安装后会自动生成配置文件，或手动创建：

**macOS 示例** (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "ida-pro-mcp": {
      "command": "python3.12",
      "args": ["-m", "ida_pro_mcp.server"],
      "timeout": 1800,
      "disabled": false
    }
  }
}
```

> 注：将 `python3.12` 替换为您系统的完整路径，如 `/opt/miniconda3/bin/python3.12`

**Windows 示例**:

```json
{
  "mcpServers": {
    "ida-pro-mcp": {
      "command": "C:\\Python312\\python.exe",
      "args": [
        "-m",
        "ida_pro_mcp.server"
      ],
      "timeout": 1800,
      "disabled": false
    }
  }
}
```

### 3. 验证安装

#### 方法 1: 使用自动测试脚本（推荐）⭐

```bash
cd ~/tools/idapromcp_333
python3 test_plugin.py
```

**预期输出**：

```
🧪 IDA Pro MCP 插件测试套件
✅ 通过: 语法检查
✅ 通过: 模块导入
✅ 通过: Python 版本
✅ 通过: MCP 服务器
总计: 4/4 测试通过
🎉 所有测试通过！
```

#### 方法 2: 手动检查

```bash
# 检查依赖是否安装成功（使用独立 Python）
/opt/miniconda3/bin/python3.12 -c "import mcp; print(f'MCP version: {mcp.__version__}')"

# 检查 IDA 插件是否安装
# macOS
ls -la ~/.idapro/plugins/mcp-plugin.py

# Windows
dir "%APPDATA%\Hex-Rays\IDA Pro\plugins\mcp-plugin.py"

# 测试插件语法（Python 3.9）
/Library/Developer/CommandLineTools/Library/Frameworks/Python3.framework/Versions/3.9/bin/python3 -m py_compile ~/.idapro/plugins/mcp-plugin.py
```

---

## 🚀 使用方法

### 工作原理

```
┌─────────────────┐         ┌──────────────────┐         ┌─────────────┐
│  LLM 客户端      │         │  MCP 服务器       │         │  IDA Pro    │
│  (Cursor/Cline) │ ◄─────► │  (Python 3.12)   │ ◄─────► │  插件(3.9)  │
└─────────────────┘  stdio  └──────────────────┘  HTTP   └─────────────┘
                                                   :13337
```

1. LLM 客户端启动 MCP 服务器（Python 3.12）
2. 你在 IDA Pro 中启动 MCP 插件（Python 3.9）
3. MCP 服务器通过 HTTP 连接到 IDA Pro 插件
4. 两者协同工作，互不干扰

### 启动步骤

#### 步骤 1: 启动 IDA Pro 和插件

1. 打开 IDA Pro
2. 加载目标二进制文件
3. 按 `Ctrl+Alt+M`（macOS: `Ctrl+Option+M`）
4. 或通过菜单 `Edit -> Plugins -> MCP`

你应该会看到：

```
[MCP] 服务器已启动: http://127.0.0.1:13337
```

#### 步骤 2: 在 LLM 客户端中使用

打开 Cursor/Cline 等客户端，输入指令：

```
请连接到 IDA Pro 并获取当前分析的二进制文件信息
```

MCP 服务器会自动连接到 IDA Pro 的插件（端口 13337）并执行操作。

---

## 📋 使用示例

### 基础操作

```text
# 检查连接
请检查 IDA Pro 连接状态

# 获取元数据
获取当前 IDB 的基本信息

# 列出函数
列出前 100 个函数
```

### 高级分析

```text
# 函数分析
分析函数 sub_401000，包括：
1. 参数和返回值分析
2. 控制流程说明
3. 算法识别
4. 混淆和反调试检测

# 批量重命名
对所有 sub_ 开头的函数进行智能重命名

# 生成报告
生成完整的结构化分析报告
```

### 混淆检测

```text
# 检测单个函数
检测函数 sub_401234 的混淆特征

# 全局扫描
扫描所有函数，找出使用混淆的函数列表
```

### 算法识别

```text
# 识别加密算法
分析函数 sub_405000，识别使用的加密算法

# 批量识别
对所有函数进行算法特征扫描
```

---

## 🐛 常见问题

### Q1: IDA Pro 无法启动

**可能原因**：Python 版本被错误切换

**解决方法**：

```bash
# 恢复到 Python 3.9
cd "/Applications/IDA Pro 8.4/ida64.app/Contents/MacOS"
./idapyswitch -s /Library/Developer/CommandLineTools/Library/Frameworks/Python3.framework/Versions/3.9/Python3
```

### Q2: 提示 "无法连接到 IDA Pro"

**检查清单**：

1. ✅ IDA Pro 是否已启动
2. ✅ 是否已按 `Ctrl+Alt+M` 启动插件
3. ✅ 端口 13337 是否被占用
4. ✅ IDA Pro 输出窗口是否有错误信息

**调试方法**：

```bash
# 查看端口是否监听
lsof -i :13337

# 测试连接
curl http://127.0.0.1:13337/mcp
```

### Q3: 安装时提示 "No matching distribution found for mcp>=1.6.0"

**原因**：使用了 Python 3.9 安装依赖

**解决方法**：

```bash
# 必须使用 Python 3.11+ 安装 MCP 依赖
/opt/miniconda3/bin/python3.12 -m pip install -r requirements.txt

# 不要使用 IDA Pro 的 Python 3.9
```

### Q4: typing-inspection 版本错误

**已在本版本中修复**，使用 `typing-inspection>=0.4.0`

### Q5: 没有找到 Python 3.12

**安装 Python 3.12**：

**macOS (Homebrew)**:

```bash
brew install python@3.12
```

**macOS (Miniconda)**:

```bash
curl -O https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh
bash Miniconda3-latest-MacOSX-arm64.sh
```

**Windows**:

- 下载：https://www.python.org/downloads/
- 安装时勾选 "Add Python to PATH"

**Linux (Ubuntu/Debian)**:

```bash
sudo apt update
sudo apt install python3.12 python3.12-pip
```

### Q6: LLM 客户端配置文件在哪里

| 客户端         | 配置文件路径 (macOS)                                                |
| -------------- | ------------------------------------------------------------------- |
| Cursor         | `~/.cursor/mcp.json`                                              |
| Cline          | VSCode 扩展设置                                                     |
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windsurf       | `~/.codeium/windsurf/mcp_config.json`                             |
| Claude Code    | `~/.claude.json`                                                  |

Windows 路径将 `~` 替换为 `%USERPROFILE%`

---

## 📁 项目结构

```
idapromcp_333/
├── 📄 README.md                   # 主文档（本文档）
├── 📄 CHANGELOG.md                # 详细更新日志
├── 📄 TESTING.md                  # 测试指南
├── 📄 SUMMARY.md                  # 修复总结
├── 🧪 test_plugin.py              # 自动测试脚本 ⭐
├── 🔧 install.sh                  # 自动安装脚本
├── 📦 requirements.txt            # Python 依赖（修复版）
├── 📄 pyproject.toml              # 项目配置
├── 📁 src/
│   └── ida_pro_mcp/
│       ├── __init__.py
│       ├── server.py              # MCP 服务器（Python 3.12）
│       ├── idalib_server.py       # IDALib 服务器（独立模式）
│       └── mcp-plugin.py          # ✅ IDA Pro 插件（Python 3.9 兼容）
├── 📁 build/                      # 构建输出
└── 📄 LICENSE                     # MIT 协议
```

---

## ⚙️ 高级配置

### 命令行参数

```bash
python -m ida_pro_mcp.server [options]

选项：
  --install              安装 MCP 服务器和 IDA 插件
  --uninstall            卸载 MCP 服务器和 IDA 插件
  --transport PROTOCOL   指定通信协议 (stdio | http://host:port)
  --ida-rpc URL          指定 IDA RPC 服务器地址 (默认: http://127.0.0.1:13337)
  --unsafe               启用不安全函数（调试器操作等）
  --config               生成 MCP 配置 JSON
```

### 环境变量

```bash
export IDA_HOST="127.0.0.1"
export IDA_PORT="13337"
export MCP_LOG_LEVEL="DEBUG"
```

### 自定义端口

如果端口 13337 被占用：

1. 修改 IDA 插件端口（`mcp-plugin.py:202`）：

```python
PORT = 13338  # 改为其他端口
```

2. 启动 MCP 服务器时指定：

```bash
python -m ida_pro_mcp.server --ida-rpc http://127.0.0.1:13338
```

---

## 🤝 贡献指南

欢迎提交 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

### 贡献方向

- 🐛 Bug 修复
- ✨ 新功能开发
- 📝 文档完善
- 🎨 代码优化
- 🌍 多语言支持
- 🧪 测试用例
- 🔧 安装脚本改进

---

## 📝 更新日志

### v1.0.1 (2025-01-26) - 完全修复版

#### 🐛 关键修复

- ✅ **修复缺失的 `requirements.txt`**
- ✅ **完全修复 Python 3.9 兼容性问题**
  - 修复版本检查 (3.11 → 3.9)
  - 添加 `from __future__ import annotations`
  - 使用 `typing_extensions.NotRequired` 兼容
  - 修复 `TypedDict` 和 `Generic` 继承问题
- ✅ **修正依赖版本冲突** (`typing-inspection` 0.9.0 → 0.4.0)
- ✅ **防止 IDA Pro 启动失败**（采用独立 Python 环境）

#### ✨ 新增功能

- ✅ 自动安装脚本 (`install.sh`)
- ✅ 自动测试脚本 (`test_plugin.py`)
- ✅ 完整的测试套件（4 项测试）
- ✅ 详细的故障排除文档

#### 📝 文档改进

- ✅ 完善的安装指南（macOS/Windows/Linux）
- ✅ 工作原理图示
- ✅ 6+ 个常见问题 FAQ
- ✅ 测试和验证指南

#### ✅ 测试状态

- ✅ 插件语法检查通过
- ✅ Python 3.9 兼容性验证
- ✅ 所有依赖安装成功
- ✅ IDA Pro 可以正常加载插件

### v1.0.0 (原版)

- 基于 mrexodia/ida-pro-mcp
- 增强混淆检测
- 增强算法识别
- 结构化报告生成

---

## 📝 开源协议

本项目基于 MIT License 开源。

### 致谢

- 原始项目：[mrexodia/ida-pro-mcp](https://github.com/mrexodia/ida-pro-mcp) by Duncan Ogilvie
- 增强版本：[namename333/idapromcp_333](https://github.com/namename333/idapromcp_333)  by Chenjun Wang
- 感谢所有贡献者和社区支持

---

## 📞 联系方式

- **Issues**: [GitHub Issues](https://github.com/cybermaxluo/IDAProMCP_Max/issues)
- **Discussions**: [GitHub Discussions](https://github.com/cybermaxluo/IDAProMCP_Max/discussions)

---

## 🌟 Star History

如果本项目对您有帮助，请点亮 ⭐ Star 支持我们！