内容
<div align="center">
<img src="docs/assets/pocket-disasm-hero.png" alt="Pocket Disasm ASCII artwork" width="900">
# Pocket Disasm
**一个 MCP 端点。多個獨立的 IDALib 会话。**
一个轻量级、以代理为优先的控制层，用于无头二进制分析，搭配 IDA Pro MCP 工具集。
[](#需求)
[](#需求)
[](LICENSE)
</div>
> [!IMPORTANT]
> Pocket Disasm 是一个独立的开源项目。它与 Hex-Rays 无关，也不受 Hex-Rays 官方支持或赞助。IDA Pro 和 IDALib 是 Hex-Rays 的产品，需要单独有效的安装和许可证。Pocket Disasm 不分发 IDA、IDALib 或任何 Hex-Rays 软件。
Pocket Disasm 运行一个公共 MCP 路由器，并为每个二进制文件提供一个独立的 IDALib 工作进程。编码代理可以创建、选择、检查、保存和关闭分析会话，而无需为每个文件启动一个单独的交互式 IDA 窗口。
该项目使用 [mrexodia/ida-pro-mcp](https://github.com/mrexodia/ida-pro-mcp) 的固定修订版本作为其核心 MCP 分析实现和工具目录。Pocket Disasm 在该上游项目的基础上构建了一个统一的多会话路由器、进程隔离、代理集成、诊断和终端控制中心。
<div align="center">
<img src="docs/assets/tui-preview.png" alt="Pocket Disasm terminal control center" width="760">
</div>
## 安装
在 PowerShell 中运行一条命令：
```powershell
irm https://raw.githubusercontent.com/whoisqwerz/pocket_disasm/main/install.ps1 | iex
```
然后打开一个新终端并运行：
```powershell
pocket
```
安装程序在 `%LOCALAPPDATA%\PocketDisasm` 下创建一个隔离的 Python 环境，安装固定的依赖项，将 `pocket` 命令添加到用户 `PATH`，并打开终端控制中心。
## 为什么选择 Pocket Disasm
- **一个端点** — 代理连接到一个单一的可流式 HTTP MCP 端点。
- **真正的多会话分析** — 每个二进制文件都在一个独立的 IDALib 进程中运行。
- **并行代理工作流** — 多个代理可以同时分析不同的二进制文件。
- **IDA Pro MCP 兼容性** — 分析调用被路由到固定的 `ida-pro-mcp` 工具目录。
- **代理管理的会话** — LLM 可以通过 MCP 工具打开和切换二进制文件。
- **内置集成** — 从 TUI 配置 Codex、Claude Code、Cursor、VS Code 和 Windsurf。
- **无 IDA GUI 自动化** — 工作进程直接使用 IDALib，不需要交互式 IDA 窗口。
- **持久诊断** — 路由器、工作进程、安装程序、更新和生命周期事件都被记录。
- **自我更新支持** — TUI 在启动时检查 GitHub 并提供原地更新。
## 快速入门
1. 运行 `pocket`。
2. 选择 **配置 IDA** 并选择包含 `idalib.dll` 的目录。
3. 选择 **连接编码代理** 并选择全局或项目范围。
4. 根据需要调整 **并发 IDALib 会话**。
5. 选择 **启动 MCP 路由器**。
6. 重新启动或重新加载已配置的编码代理。
默认端点是：
```text
http://127.0.0.1:13339/mcp
```
端口可以从 TUI 更改。Pocket Disasm 更新其先前注册的所有 MCP 配置文件，并在需要时重新启动路由器。
## 代理工作流
代理不需要为每个二进制文件提供专用的 MCP 服务器。他们通过共享端点创建和路由会话：
```text
idb_open(input_path="C:\\samples\\first.exe", session_id="first", wait=true)
idb_open(input_path="C:\\samples\\second.dll", session_id="second", wait=true)
decompile(addr="main", database="first")
survey_binary(database="second")
```
选择也可以限定在当前 MCP 客户端：
```text
idb_select(database="first")
decompile(addr="main")
```
这允许一个模型管理多个二进制文件或多个代理通过同一个路由器工作，而无需共享选定的数据库。
## 架构
```mermaid
flowchart LR
A1["编码代理 A"] --> MCP["Pocket Disasm MCP<br/>127.0.0.1:13339/mcp"]
A2["编码代理 B"] --> MCP
A3["编码代理 N"] --> MCP
MCP --> S["多会话监督器"]
S --> W1["IDALib 工作进程<br/>二进制 A"]
S --> W2["IDALib 工作进程<br/>二进制 B"]
S --> WN["IDALib 工作进程<br/>二进制 N"]
```
每个活动会话都有自己的进程、内部端口、隔离的分析工作区、IDA 数据库和工作进程日志。可配置的工作进程限制防止无限创建进程；默认值为 8，TUI 接受 1 到 128 的值。
## 会话管理工具
Pocket Disasm 在常规 IDA MCP 目录中添加了以下工具：
| 工具 | 目的 |
| --- | --- |
| `idb_open` | 为本地二进制文件创建隔离会话 |
| `idb_list` | 列出会话、状态、进程和当前选择 |
| `idb_select` | 为当前 MCP 客户端选择默认会话 |
| `idb_health` | 读取工作进程启动和进程健康状态 |
| `idb_wait` | 等待 IDA 自动分析和 MCP 启动 |
| `idb_save` | 保存当前 IDA 数据库 |
| `idb_logs` | 读取某个工作进程的最近输出 |
| `idb_close` | 停止工作进程并释放其资源 |
常规分析工具（如 `survey_binary`、`lookup_funcs`、`func_query`、`find_bytes` 和 `decompile`）接受一个可选的 `database` 参数。如果省略，Pocket Disasm 将使用该 MCP 客户端选择的会话。
## 编码代理集成
TUI 仅将 `pocket-disasm` MCP 条目合并到现有的配置文件中；它不会替换整个文件。
| 代理 | 全局配置 | 项目配置 |
| --- | --- | --- |
| Codex | `~/.codex/config.toml` | 使用全局端点 |
| Claude Code | `~/.claude.json` | `.mcp.json` |
| Cursor | `~/.cursor/mcp.json` | `.cursor/mcp.json` |
| VS Code | 用户配置文件 `mcp.json` | `.vscode/mcp.json` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` | 使用全局端点 |
从 CLI 也可以执行相同的操作：
```powershell
pocket integrate codex claude cursor --scope global
pocket integrate claude cursor vscode --scope project --project-dir .
```
## CLI
TUI 涵盖了正常的安装和控制。CLI 仍然可用于自动化和诊断：
| 命令 | 描述 |
| --- | --- |
| `pocket` | 打开终端控制中心 |
| `pocket doctor` | 验证 Python、IDA、IDALib 和 MCP 依赖项 |
| `pocket start` | 在后台启动统一路由器 |
| `pocket stop` | 停止路由器及其工作进程 |
| `pocket restart` | 重启路由器 |
| `pocket status` | 显示端点和守护进程状态 |
| `pocket logs` | 打印最近的诊断输出 |
| `pocket port <port>` | 在已注册的代理配置中更改端点 |
| `pocket config --max-workers <n>` | 设置并发工作进程限制 |
| `pocket integrate <agents>` | 配置一个或多个编码代理 |
运行 `pocket <command> --help` 获取所有选项。
## 配置和日志
Pocket Disasm 将其用户状态存储在：
```text
%LOCALAPPDATA%\PocketDisasm
```
重要文件包括：
| 文件 | 内容 |
| --- | --- |
| `config.json` | IDA 路径、端点端口和工作进程限制 |
| `integrations.json` | Pocket Disasm 管理的 MCP 配置文件 |
| `events.log` | 结构化生命周期事件和异常回溯 |
| `pocket-disasm.out.log` | 路由器标准输出 |
| `pocket-disasm.err.log` | 路由器错误输出 |
| `sessions/<session>/worker.log` | IDALib 工作进程的持久输出 |
| `installer.log` | 安装和升级记录 |
| `update.log` | TUI 更新器输出 |
使用 TUI 中的 **检查日志** 或运行：
```powershell
pocket logs
```
## 更新
TUI 在启动时检查是否有新版本。当有更新可用时，**更新 Pocket Disasm** 将出现在操作列表中。更新器保留配置，更新隔离环境，重启 TUI，并在路由器之前在线运行时将其带回在线。
## 需求
- Windows 10 或 Windows 11。
- Python 3.11 或更新版本。安装程序可以通过 `winget` 安装 Python 3.12。
- 单独安装并授权的 IDA 版本，提供 IDALib。
- 安装、代理依赖设置和更新检查期间的网络访问。
Pocket Disasm **不** 包括 IDA、IDALib 或 IDA 许可证。它是一个独立的项目，与 Hex-Rays 无关，也不受 Hex-Rays 官方支持或赞助。
## 卸载
```powershell
$script = irm https://raw.githubusercontent.com/whoisqwerz/pocket_disasm/main/install.ps1
& ([scriptblock]::Create($script)) -Uninstall
```
代理 MCP 条目不会自动删除，因此在卸载过程中不会重写无关配置。如果不再需要，可以从相应的代理配置文件中删除它们。
## 致谢
- [mrexodia/ida-pro-mcp](https://github.com/mrexodia/ida-pro-mcp)，由 mrexodia 创建和维护，提供了 Pocket Disasm 使用的核心 IDA MCP 服务器和分析工具。上游项目在 MIT 许可证下分发。
- Hex-Rays 提供了 IDA 和 IDALib，需要用户单独安装和授权。
## 许可证
Pocket Disasm 在 [MIT 许可证](LICENSE) 下发布。
MCP 市场