IDA Pro MCP 仓库开发指南：架构、线程模型、API 约定与测试体系

IDA Pro MCP 仓库开发指南架构、线程模型、API 约定与测试体系【免费下载链接】ida-pro-mcpAI-powered reverse engineering assistant that bridges IDA Pro with language models through MCP.项目地址: https://gitcode.com/gh_mirrors/id/ida-pro-mcp本指南基于仓库根目录 CLAUDE.md 展开它是进入ida-pro-mcp项目开发的总纲先交代项目三大组成部分与 API 模块地图再给出必须遵守的 IDA 线程安全规则、API 编写约定与不安全操作标记方式随后覆盖日常运行/安装命令、基于 idalib 的无头测试与覆盖率流程最后列出开发优先级与环境版本要求。读完本文你将掌握如何在该仓库中新增一个符合规范的 MCP 工具、如何用ida-mcp-test验证它以及如何用coverage衡量测试充分度。一、项目是什么架构与模块地图CLAUDE.md 开宗明义IDA Pro MCP Server的核心使命是把 IDA Pro / idalib 的能力以 MCPModel Context Protocol工具的形式暴露给 LLM 客户端实现AI 辅助逆向的工作流。整个仓库被划分为三个主要部分组件路径职责MCP 服务器入口src/ida_pro_mcp/server.py对外提供 MCP 服务stdio / HTTP / SSE并代理 JSON-RPC 请求到正在运行的 IDA 实例无头 idalib 服务器src/ida_pro_mcp/idalib_server.py基于idapro库以无 GUI 方式打开二进制、托管会话供无法启动 IDA GUI 的环境使用IDA / 插件侧 APIsrc/ida_pro_mcp/ida_mcp/全部 MCP 工具的实现在此运行在 IDA 进程内CLAUDE.md 进一步列出了十个重要 API 模块它们是 MCP 工具按业务域划分的载体api_core.pyIDB 元数据、函数、字符串、导入表api_analysis.py反编译、反汇编、交叉引用xrefs、路径、模式搜索api_memory.py字节 / 整数 / 字符串读写与补丁patchingapi_types.py结构体、类型推断、类型应用api_modify.py注释、重命名、汇编补丁api_stack.py栈帧操作api_sigmaker.py签名创建、扫描、xref 签名底层使用sigmaker.pyapi_debug.py调试器控制属于不安全、测试优先级低的模块api_python.py在 IDA 上下文中执行任意 Pythonapi_resources.pyida://形式的 MCP 资源。这十个模块对应着工具注册的两个入口MCP_SERVER在 rpc.py 中创建负责承载所有工具MCP_UNSAFE集合记录被标记为不安全的函数名MCP_EXTENSIONS则按分组管理默认隐藏的扩展工具例如ext(dbg)标记的调试工具需要通过?extdbg查询参数才可见。二、核心实现规则如何在 IDA 进程内安全写代码2.1 IDA 线程安全所有 SDK 调用必须回到主线程CLAUDE.md 给出了本项目最优先的工程约束所有 IDA SDK 调用必须在 IDA 主线程上执行。MCP 服务器自身的请求处理线程不能直接触碰ida_*模块必须通过统一装饰器完成同步from .rpc import tool from .sync import idasync tool idasync def my_tool(...): ...在 sync.py 中可以看到idasync的实现它把被装饰函数包装成functools.partial然后判断当前是否已有主线程 pumpheadless 场景下 IDA 只运行在 pump 线程上再决定是直接调用sync_wrapper还是把整个同步体提交给 pump 线程等待结果。最终通过idaapi.execute_sync(runned, idaapi.MFF_WRITE)在写模式下于 IDA 主线程执行并在执行期间强制开启批处理模式idc.batch(1)见 sync.py避免弹出交互对话框阻塞无头流程。值得注意的是 sync.py 的注释揭示了设计演进早期存在独立的idaread/idawrite两个装饰器但只读操作也可能需要写访问例如反编译因此现在统一为单一的idasync。这是理解本仓库 API 惯例的重要背景。sync_wrapper还承担了超时与取消管理sync.py默认工具超时 60 秒可通过环境变量IDA_MCP_TOOL_TIMEOUT_SEC覆盖超时通过两条路径生效一是threading.Timer触发ida_kernwin.set_cancelled()许多 IDA SDK 调用如ida_search.find_*、ida_hexrays.decompile*会轮询user_cancelled()并提前返回二是sys.setprofile注入的 profile 钩子检查单调时钟 deadline工具内部可通过get_tool_deadline()自省剩余时间在遍历大型结构时优雅返回部分结果若需要为单个工具覆盖超时可使用tool_timeout(seconds)装饰器必须放在idasync之后最内层见 sync.py。2.2 API 约定batch-first 与类型提示CLAUDE.md 列出四条 API 编写约定均在源码中有直接对应优先 batch-first API单对象操作与批量操作使用同一入口批量编辑类工具如重命名、注释、类型应用支持一次传入多条操作并普遍提供stop_on_error、dry_run等控制项见 utils.py 中RenameBatch的定义。许多函数同时接受逗号分隔字符串或列表这是为了降低 LLM 客户端生成参数的难度。使用完整类型提示与Annotated[...]描述参数说明直接成为 MCP 工具 schema 的一部分影响客户端如何生成参数。函数 docstring 即 MCP 工具描述tool装饰器rpc.py会把函数注册进MCP_SERVER.tool(func)docstring 被用作工具的能力说明。一个符合规范的示例def my_api(addrs: Annotated[str, Addresses (0x401000, main) or list]) - list[dict]: ...2.3 常用助手解析、归一化、分页与过滤CLAUDE.md 指定了三类必须复用的公共助手全部实现在 utils.pyparse_address()utils.py接受int、带0x前缀的十六进制串、十进制串失败时尝试用idaapi.get_name_ea做名字→地址解析支持传入main这样的符号名仍失败则抛出IDAError。normalize_list_input()/normalize_dict_list()utils.py前者把list或逗号分隔字符串归一化为list后者把dict/list[dict]/ JSON 字符串 / 逗号分隔字符串 /list[str]统一归一化为list[dict]并支持自定义string_parser把单个字符串解析成操作字典。分页与过滤助手paginate()utils.py实现offset/count分页并返回next_offset游标pattern_filter()utils.py支持三种过滤语义——/regex/flags形式正则、含*/?的 glob、以及普通子串匹配。2.4 不安全操作显式标记、默认禁用调试器操作或破坏性操作内存/汇编补丁、Python 执行等必须显式标记为 unsafe否则默认不对外暴露from .rpc import tool, unsafe unsafe tool idasync def dangerous_op(...): ...unsafe装饰器rpc.py只是把函数名加入全局集合MCP_UNSAFE。真正执行禁用逻辑的是服务器启动阶段在 idalib_server.py 中若未传--unsafe参数则从MCP_SERVER.tools.methods中弹出所有不安全工具并记录日志 Unsafe tools disabled (start with --unsafe to enable)。server.py同样透传--unsafe开关。这保证默认安装形态对客户端只暴露安全的只读/分析能力。三、开发命令运行、检查与安装卸载CLAUDE.md 给出的命令统一以uv run前缀执行项目用 uv 的[project.scripts]段。3.1 运行模式uv run ida-pro-mcp uv run ida-pro-mcp --transport http://127.0.0.1:8744/sse uv run idalib-mcp --stdio path/to/binary uv run idalib-mcp --host 127.0.0.1 --port 8745 path/to/binary uv run ida-pro-mcp --unsafe四条命令对应四种场景ida-pro-mcp默认 stdio 传输供 MCP 客户端直接以 stdio 方式拉起它本质是一个代理见 server.py 的dispatch_proxy除initialize与notifications/*之外的所有 JSON-RPC 请求都会被转发到正在运行的 IDA 实例默认127.0.0.1:13337可被--ida-rpc覆盖或自动发现若 IDA 未启动则返回错误提示Did you run Edit - Plugins - MCP (CtrlAltM) to start the server?。ida-pro-mcp --transport http://127.0.0.1:8744/sse以 HTTP/SSE 传输对外服务端口与路径取自 URL此时启用ProxyHttpRequestHandler除代理请求外还负责透传大输出下载/output/id.json。idalib-mcp --stdio path/to/binary与idalib-mcp --host 127.0.0.1 --port 8745 path/to/binary无头 idalib 模式前者走 stdio后者监听 HTTP默认端口 8745可直接指定要分析的二进制不带输入文件时可通过idb_open()工具动态加载见 idalib_server.py。--unsafe启用上节所述的不安全工具集合。3.2 MCP Inspectoruv run mcp dev src/ida_pro_mcp/server.py通过官方 MCP Inspector 以开发模式启动服务器便于交互式调试工具定义与调用。3.3 安装 / 卸载uv run ida-pro-mcp --install uv run ida-pro-mcp --uninstall--install会立即安装 IDA 插件并可接受逗号分隔的客户端目标如--install claude,cursor不指定目标时进入交互式选择器。相关 CLI 解析见 server.py还包括--allow-ida-free允许在安装有 IDA Free 的机器上安装、--transportstreamable-http/stdio/sse、--scopeproject/global安装范围、--config生成 MCP 配置 JSON与--list-clients等选项。安装逻辑本体位于 installer.py。四、测试与覆盖率无头回归体系CLAUDE.md 用最大篇幅描述了测试体系——这是该仓库开发工作流的重中之重全部基于 idalib 无头运行不依赖 IDA GUI。4.1 运行测试uv run ida-mcp-test tests/crackme03.elf -q uv run ida-mcp-test tests/typed_fixture.elf -q uv run ida-mcp-test tests/crackme03.elf -c api_analysis uv run ida-mcp-test tests/typed_fixture.elf -p *stack*ida-mcp-test的入口在 src/ida_pro_mcp/test.py核心参数对应-q、-c、-p参数说明-q, --quiet安静模式只输出汇总如Results: 120 passed, 2 failed, 3 skipped (45.12s)与失败列表-c, --category按模块类别过滤例如api_analysis只跑该模块相关测试-p, --pattern按测试名 glob 过滤例如*stack*只跑名字含 stack 的测试-x, --stop-on-failure首个失败即停止-l, --list只列出可用测试含 skip 标记而不运行-v, --verbose显示 IDA 控制台消息--mcp-mode端到端模式每个tool调用都经过真实 MCP 客户端/服务器往返并用 outputSchema 校验响应运行流程test.py先用idapro.open_database打开目标二进制并ida_auto.auto_wait()等待自动分析完成再用pkgutil.iter_modules动态导入ida_pro_mcp.ida_mcp.tests下所有test_*模块以注册test装饰器最后交给 framework.py 的run_tests()执行。测试的注册机制在 framework.pytest()装饰器把函数注册进全局TESTS字典自动从函数所在模块名提取类别test_api_core→api_core并支持两个关键参数test(binarycrackme03.elf)仅当目标二进制基名匹配时才运行用于二进制专属断言test(skipTrue)标记跳过。CLAUDE.md 特别提示非交互式输出应只显示失败项加汇总——这正是-q与failures_only逻辑共同保证的方便 CI 集成。4.2 覆盖率CLAUDE.md 给出的覆盖率流程在两个维护 fixture 上分别采集并合并uv run coverage erase uv run coverage run -m ida_pro_mcp.test tests/crackme03.elf -q uv run coverage run --append -m ida_pro_mcp.test tests/typed_fixture.elf -q uv run coverage report --show-missing--append使第二次运行的结果追加到同一数据文件--show-missing显示未被覆盖的行号。覆盖范围配置在 pyproject.tomlinclude [src/ida_pro_mcp/*]并排除测试模块与zeromcp/内置 MCP 实现。两个 fixture 的定位CLAUDE.md 明确说明tests/crackme03.elf紧凑的通用回归 fixture覆盖绝大多数 API 的常规路径tests/typed_fixture.elf类型化全局变量 / 结构体 / 局部变量 / 栈变量的覆盖 fixture其 C 源码即仓库中的 tests/typed_fixture.c可从源码了解其声明的全局结构、枚举与栈布局。4.3 测试期望质量红线CLAUDE.md 对测试质量提出了四条硬性期望参与贡献时必须遵守优先语义断言拒绝弱断言不要只写字段存在级别的检查例如仅assert name in result要验证数值与语义正确性对变更类 API 优先做往返测试round-trip写入后再读回验证真实生效测试暴露 API 明显错误时修 API 而非削弱测试即不要让测试去迁就错误行为聚焦 IDA 侧模块测试重点放在api_*、utils、framework等 IDA 相关实现上而不是服务器/配置的胶水逻辑同时接受 IDA / Hex-Rays 版本差异合理场景下允许用受保护断言或运行时跳过skip_test()来处理。4.4 通用测试 sanity checkCLAUDE.md 要求新增通用测试时除 fixture 外还应拿一个非 fixture 二进制试跑避免测试隐含 ELF 专属假设uv run ida-mcp-test C:\CodeBlocks\x64dbg\bin\x64\x64dbg.dll -q该示例使用 Windows 下的 PE 文件x64dbg.dll验证测试在非 ELF 目标上同样成立。对测试框架的更多细节可参考 devdocs/test-framework.md。五、范围优先级CLAUDE.md 明确列出开发优先级指导贡献者把精力放在何处高优先级api_analysis.py、api_types.py、api_modify.py、api_stack.py、api_memory.py、api_core.py、api_resources.py、utils.py、framework.py较低优先级api_debug.py、MCP 传输/托管细节、安装与配置变更逻辑。从测试文件分布src/ida_pro_mcp/ida_mcp/tests/ 下的test_api_*.py也能印证这一重心——分析、类型、修改、栈、内存、核心元数据均有成体系的测试模块。另一个与范围相关的机制是profile 白名单通过idalib-mcp --profile PATH可把暴露的工具限制为 profile 文件列出的名字每行一个工具名#开头为注释实现只读/受限部署。解析与过滤逻辑见 profile.py仓库自带两个示例profiles/readonly.txt 与 profiles/triage.txt前者通常只保留分析与读取类工具后者面向初步筛查场景。应用 profile 时idb_open/idb_list两个会话管理工具始终保留idalib_server.py。六、实用环境说明CLAUDE.md 在文末给出运行前提直接决定了开发环境的配置方式Python 版本服务器与插件代码要求 3.11pyproject.toml 中requires-python 3.11与之呼应IDA 版本支持 IDA Pro 8.3推荐 9.0不支持 IDA Free安装时可用--allow-ida-free强制放行server.py但官方不保证支持Python 解释器不匹配若 IDA 使用了错误的 Python使用idapyswitch切换 IDA 绑定的 Python 解释器。无头 idalib 场景还有两个实用细节idalib_server.py支持--verbose打开 IDA 控制台消息、--host/--port默认127.0.0.1:8745绑定监听地址若IDA_MCP_URL环境变量未设置下载基础 URL 会被自动设置为http://host:portidalib_server.py保证截断的大输出可通过该地址回源下载。结语CLAUDE.md 虽然篇幅不长却浓缩了ida-pro-mcp的全部开发纪律架构上服务器代理 IDA 插件 API双层分离线程上所有 SDK 调用经idasync收敛到主线程API 上统一 batch-first 与Annotated类型提示安全上以unsafe--unsafe双闸门管控破坏性操作质量上以ida-mcp-test无头回归 双 fixture 覆盖率为准绳。新贡献者只需按此约定在 src/ida_pro_mcp/ida_mcp/ 下新增模块、用tool注册、用test补齐用例即可无缝融入现有的 MCP 工具生态。【免费下载链接】ida-pro-mcpAI-powered reverse engineering assistant that bridges IDA Pro with language models through MCP.项目地址: https://gitcode.com/gh_mirrors/id/ida-pro-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考