# 🚀 JEBMCP: JEB 与 MCP 集成的增强插件

## 📋 项目简介

JEBMCP 是一个功能强大的 JEB Pro 插件，旨在提供丰富的代码分析、自动化和修改功能，帮助逆向工程师和安全研究人员更高效地进行二进制分析。

本项目基于 [ida-pro-mcp](https://github.com/mrexodia/ida-pro-mcp) 架构进行开发，保留了其核心功能并针对 JEB Pro 进行了优化和扩展，更适合中文使用者。

## ✨ 功能特性

### 🎯 核心功能
- **无缝集成**：将 JEB Pro 与各种 MCP 客户端连接，实现 AI 辅助逆向工程
- **多平台支持**：适用于 Windows、Linux 和 macOS
- **可扩展架构**：易于添加新功能和命令
- **自动安装**：支持一键安装 JEB 插件

### 📊 分析功能
- **反编译分析**：获取类和方法的反编译代码
- **APK 清单解析**：访问 APK 清单信息
- **方法调用关系**：分析方法调用者和覆盖关系
- **字符串提取**：提取 APK 中的所有字符串
- **常量识别**：识别代码中的常量

### 🔧 代码操作
- **重命名功能**：支持重命名类、方法和字段
- **注释管理**：向地址添加注释
- **数据类型修改**：修改方法和字段的数据类型

### 🐛 调试支持
- **调试会话管理**：启动和停止调试会话
- **断点控制**：设置和移除断点
- **单步执行**：支持 step into/over/out
- **寄存器查看**：获取寄存器值
- **堆栈跟踪**：访问堆栈跟踪
- **内存操作**：读写内存

### 🔗 交叉引用分析
- **全量交叉引用**：获取地址的所有交叉引用
- **引用来源分析**：查看指向地址的交叉引用
- **引用目标分析**：查看从地址出发的交叉引用

### 🔢 数据分析
- **数字转换**：支持多种格式转换（十进制、十六进制、字节、ASCII、二进制）
- **全局变量分析**：获取全局变量信息

### 🛠️ 配置管理
- **版本信息**：获取插件版本
- **配置信息**：获取服务器配置
- **加载文件列表**：查看当前加载的文件

## 📋 版本更新 (v2.0.0)

### 新增功能
- **配置管理模块**：提供版本、配置和加载文件信息
- **增强的数字转换**：支持多种格式转换
- **命令行工具**：添加 `jeb-mcp` 命令行入口
- **自动插件安装**：支持一键安装 JEB 插件
- **自定义安装路径**：支持指定 JEB 安装目录

### 优化改进
- **架构升级**：更贴合 ida-pro-mcp 的设计
- **代码优化**：添加详细的中文注释
- **错误处理**：增强错误处理和日志记录
- **依赖管理**：更新项目配置和依赖

## 🚀 快速开始

### 📦 安装

#### 1. 克隆仓库
```bash
git clone https://github.com/namename333/jebmcp.git
cd jebmcp
```

#### 2. 安装依赖
```bash
pip install -e jeb-mcp
```

#### 3. 安装 JEB 插件

##### 3.1 默认安装（推荐）
```bash
jeb-mcp --install-plugin
```

插件将被安装到系统默认目录：
- **Windows**: `%APPDATA%\JEB\plugins\MCP.py`
- **macOS**: `~/Library/Application Support/JEB/plugins/MCP.py`
- **Linux**: `~/.jeb/plugins/MCP.py`

##### 3.2 自定义安装目录
如果您使用的是自定义 JEB 安装目录，可以使用 `--jeb-path` 参数指定：

```bash
jeb-mcp --install-plugin --jeb-path "E:\\path\\to\\your\\JEB"
```

**示例**：
```bash
jeb-mcp --install-plugin --jeb-path "E:\\Android\\tools\\JEB_demo_5.29.0.202505042038_by_CXV"
```

插件将被安装到指定目录的 `plugins` 子目录中，例如：
```
E:\Android\tools\JEB_demo_5.29.0.202505042038_by_CXV\plugins\MCP.py
```

**重要提示**：
1. 请确保完全重启 JEB Pro 和您的 MCP 客户端，以便安装生效
2. 使用绝对路径指定 JEB 安装目录
3. 在 Windows 系统中，路径分隔符需要使用双反斜杠 `\\` 或单正斜杠 `/`
4. 确保您对指定的目录有写入权限

### 🎮 使用方法

#### 1. 启动 MCP 服务器
在 JEB Pro 中：
- 加载二进制文件
- 从 `Scripts` 菜单启动 `MCP` 插件
- 或使用快捷键 `Ctrl+Alt+M` (Windows/Linux) 或 `Ctrl+Option+M` (Mac)

#### 2. 连接 MCP 客户端
使用您喜欢的 MCP 客户端连接到服务器：
- 默认地址：`http://localhost:16161/mcp`

#### 3. 支持的 MCP 客户端
- Amazon Q Developer CLI
- Augment Code
- Claude/Claude Code
- Cline
- Codex
- Copilot CLI
- Crush
- Cursor
- Gemini CLI
- Kilo Code
- Kiro
- LM Studio
- Opencode
- Qodo Gen
- Qwen Coder
- Roo Code
- Trae
- VS Code
- Warp
- Windsurf
- Zed

## 📖 API 参考

### 🔧 基本操作
- `ping()` - 检查服务器是否运行
- `get_manifest(filepath)` - 获取 APK 清单
- `get_method_decompiled_code(filepath, method_signature)` - 获取方法反编译代码
- `get_class_decompiled_code(filepath, class_signature)` - 获取类反编译代码

### 🔢 数字转换
- `convert_number(text, size)` - 转换数字为不同格式

### 🔧 代码修改
- `rename_class(filepath, class_signature, new_name)` - 重命名类
- `rename_method(filepath, method_signature, new_name)` - 重命名方法
- `rename_field(filepath, field_signature, new_name)` - 重命名字段
- `add_comment(filepath, address, comment)` - 添加注释

### 🐛 调试功能
- `start_debugger(filepath, debug_type)` - 启动调试器
- `set_breakpoint(filepath, address)` - 设置断点
- `remove_breakpoint(filepath, address)` - 移除断点
- `step_into(filepath)` - 单步进入
- `step_over(filepath)` - 单步跳过
- `step_out(filepath)` - 单步跳出
- `continue_execution(filepath)` - 继续执行
- `stop_debugger(filepath)` - 停止调试器

### 🔗 交叉引用
- `get_all_xrefs(filepath, address)` - 获取所有交叉引用
- `get_xrefs_to(filepath, address)` - 获取指向地址的交叉引用
- `get_xrefs_from(filepath, address)` - 获取从地址出发的交叉引用

### 🛠️ 配置管理
- `get_version()` - 获取插件版本
- `get_config()` - 获取服务器配置
- `get_loaded_files()` - 获取加载文件列表

## 📝 使用示例

### 示例 1：分析 APK 文件

```python
# 获取 APK 清单
get_manifest("/path/to/your.apk")

# 获取类的反编译代码
get_class_decompiled_code("/path/to/your.apk", "Lcom/example/MyClass;")

# 获取方法的反编译代码
get_method_decompiled_code("/path/to/your.apk", "Lcom/example/MyClass;->myMethod()V")

# 重命名方法
rename_method("/path/to/your.apk", "Lcom/example/MyClass;->a()V", "init")
```

### 示例 2：数字转换

```python
# 转换数字为多种格式
convert_number("0x414243", size=3)
# 输出：
# {
#   "decimal": "6684675",
#   "hexadecimal": "0x6684675",
#   "bytes": "43 42 41",
#   "ascii": "CBA",
#   "binary": "0b110011010000100011001110101"
# }
```

### 示例 3：调试操作

```python
# 启动调试器
start_debugger("/path/to/your.apk", "java")

# 设置断点
set_breakpoint("/path/to/your.apk", "0x12345678")

# 单步执行
step_into("/path/to/your.apk")

# 查看寄存器
get_registers("/path/to/your.apk")

# 停止调试器
stop_debugger("/path/to/your.apk")
```

## 🎯 提示工程建议

为了获得最佳结果，建议您在提示中包含以下内容：

1. 明确说明您想要分析的内容
2. 指定要使用的具体方法
3. 提供清晰的上下文
4. 对于数字转换，使用 `convert_number` 工具
5. 对于复杂分析，分步骤进行

**示例提示**：
```
请分析这个 APK 文件的主入口点，告诉我它的主要功能是什么。

1. 首先获取 APK 清单
2. 然后找到主活动类
3. 分析主活动的 onCreate 方法
4. 解释它的主要功能

文件路径：/path/to/your.apk
```

## 📊 项目架构

```
jebmcp/
├── jeb-mcp/                 # 主项目目录
│   ├── src/                  # 源代码目录
│   │   └── jeb_mcp/          # 主要代码包
│   │       ├── MCP.py        # JEB 插件和 MCP 服务器实现
│   │       ├── server.py     # MCP 服务器启动脚本
│   │       └── server_generated.py  # 自动生成的 MCP 工具定义
│   └── pyproject.toml        # 项目配置和依赖
├── .gitignore               # Git 忽略文件
├── LICENSE                  # 许可证文件
├── README.md                # 项目文档
├── sample_cline_mcp_settings.json  # MCP 客户端示例配置
└── sample_jeb_mcp_config.json  # JSON 配置示例文件
```

## 🔧 命令行工具

### 安装 JEB 插件
```bash
jeb-mcp --install-plugin
```

### 自定义插件安装目录
```bash
jeb-mcp --install-plugin --jeb-path "E:\\path\\to\\your\\JEB"
```

### 启动 MCP 服务器
```bash
jeb-mcp
```

### 查看帮助信息
```bash
jeb-mcp --help
```

## 📋 JSON 配置文件

您可以使用 JSON 配置文件来管理和启动 JEB MCP 服务器，类似于其他 MCP 服务器（如 IDA Pro MCP）的配置方式。

### 配置字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| `mcpServers` | Object | 包含所有 MCP 服务器配置的对象 |
| `command` | String | 启动服务器的命令（如 `python` 或 `cmd`） |
| `args` | Array | 传递给命令的参数列表 |
| `timeout` | Number | 服务器超时时间（秒） |
| `disabled` | Boolean | 是否禁用该服务器配置 |
| `autoApprove` | Array | 自动批准的命令列表，无需用户交互 |

### 配置示例

创建一个名为 `mcp_config.json` 的文件，内容如下：

```json
{
  "mcpServers": {
    "jeb-pro-mcp": {
      "command": "python",
      "args": [
        "E:\\path\\to\\jebmcp\\jeb-mcp\\src\\jeb_mcp\\server.py"
      ],
      "timeout": 1800,
      "disabled": false,
      "autoApprove": [
        "ping",
        "get_manifest",
        "get_class_decompiled_code",
        "get_method_decompiled_code",
        "get_method_callers",
        "get_method_overrides",
        "check_connection",
        "get_version",
        "get_config",
        "get_loaded_files",
        "convert_number"
      ]
    }
  }
}
```

### 配置说明

1. **command**: 使用 `python` 命令直接调用 Python 解释器
2. **args**: 包含 Python 脚本的完整路径
3. **timeout**: 设置为 1800 秒（30分钟），防止服务器长时间无响应
4. **disabled**: 设置为 `false` 启用该配置
5. **autoApprove**: 列出了常用的 JEB MCP 命令，这些命令将自动执行，无需用户批准

### 使用方法

根据您使用的 MCP 客户端，将配置文件放置在相应位置：

- **Cline**: 将配置文件保存为 `cline_mcp_settings.json` 并放置在用户目录下
- **其他客户端**: 请参考对应客户端的文档，了解如何指定 MCP 服务器配置文件

### 自定义配置

您可以根据需要自定义配置：

- 修改 `command` 和 `args` 以适应您的环境
- 添加或删除 `autoApprove` 中的命令
- 调整 `timeout` 以适应您的工作流程
- 添加多个服务器配置，方便在不同环境中切换

### 环境变量支持

某些 MCP 客户端支持在配置文件中使用环境变量，例如：

```json
{
  "mcpServers": {
    "jeb-pro-mcp": {
      "command": "python",
      "args": [
        "${JEB_MCP_PATH}\\jeb-mcp\\src\\jeb_mcp\\server.py"
      ],
      "timeout": 1800,
      "disabled": false,
      "autoApprove": ["ping", "check_connection"]
    }
  }
}
```

请参考您使用的 MCP 客户端文档，了解是否支持环境变量以及具体的语法。

## 📋 系统要求

- **Python**：3.11 或更高版本
- **JEB Pro**：8.0 或更高版本
- **MCP 客户端**：支持 MCP 协议的客户端（如 Claude、Cursor、VS Code 等）

## 🚀 安装方法

### 方法一：直接安装

```bash
pip install jeb-mcp
jeb-mcp --install-plugin
```

### 方法二：从源码安装

```bash
git clone https://github.com/namename333/jebmcp.git
cd jebmcp
pip install -e jeb-mcp
jeb-mcp --install-plugin
```

## 🔧 故障排除

### 常见问题

1. **服务器无法启动**
   - 检查端口 16161 是否已被占用
   - 确保您已正确安装依赖
   - 查看 JEB 日志以获取更多信息

2. **客户端无法连接**
   - 确保 JEB 中已加载 MCP 插件
   - 检查服务器地址和端口是否正确
   - 确保防火墙允许连接

3. **命令执行失败**
   - 检查参数是否正确
   - 确保文件路径是绝对路径
   - 查看 JEB 日志以获取更多信息

4. **插件未在 JEB 中显示**
   - 确保插件已正确安装到 JEB 的 `plugins` 目录
   - 尝试重启 JEB Pro
   - 检查 JEB 日志以获取错误信息

5. **自定义安装后插件未生效**
   - 确保使用了正确的 JEB 安装路径
   - 检查插件是否已安装到指定目录的 `plugins` 子目录
   - 尝试重启 JEB Pro

### 日志位置

- **JEB 日志**：在 JEB 中通过 "View" → "Logs" 查看
- **MCP 服务器日志**：在 JEB 控制台中查看

## 🤝 贡献指南

我们欢迎您的贡献！要贡献代码：

1. Fork 仓库
2. 创建新分支 (`git checkout -b feature-branch`)
3. 进行您的更改
4. 推送到分支 (`git push origin feature-branch`)
5. 打开拉取请求

请确保您的代码遵循我们的编码标准和测试指南。

## 📝 许可证

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

## 🌟 灵感来源

该项目的灵感来自于 [ida-pro-mcp](https://github.com/mrexodia/ida-pro-mcp) 项目，并参考了其架构设计，为 JEB 用户带来类似的功能。

## 📞 支持

如有问题或建议，请在 GitHub 仓库上打开 issue。

## 📄 免责声明

该工具仅供合法的逆向工程和安全研究使用。请遵守相关法律法规，不要将其用于非法用途。

---

感谢您使用 JEBMCP！我们希望它能在您的逆向工程工作中有所帮助。