MCPluginForX96Dbg

这是一个双架构的 x32dbg/x64dbg 插件，通过 TCP 提供一个轻量级的 JSON-RPC "模型上下文协议"（MCP）桥接。该服务器允许自动化工具在不依赖调试器用户界面的情况下检查和控制正在调试的目标程序。

功能

• 从同一代码库构建 .dp32 和 .dp64 二进制文件——分别放入 x32\plugins 或 x64\plugins 目录。
• 当插件加载时自动启动 MCP 服务器（默认端口 0.0.0.0:51337）。
• JSON-RPC 端点：
  • 内存与模块：
    • readMemory – 从目标读取最多 4096 字节的数据。
    • writeMemory – 写入任意字节序列，可选地覆盖保护设置。
    • listModules – 列出已加载的模块（基地址、大小、路径、部分）。
    • getExports / getImports – 检查模块的导出/导入表。
    • getDisassembly – 在任何地址处反汇编指令。
    • patternScan – 使用 ?? 通配符模式搜索内存范围。
  • 页面与运行时诊断：
    • getPageRights / setPageRights – 检查或修改页面保护。
    • memIsCodePage – 标识可执行区域。
    • getTraceRecord – 获取页面的覆盖率元数据。
    • memBpSize – 报告地址处硬件断点的粒度。
    • getThreads – 列出调试器线程及其 CIP、TLS、定时和等待状态信息。
  • 断点管理：
    • setBreakpoint / enableBreakpoint / disableBreakpoint – 管理软件断点。
    • deleteBreakpoint – 移除软件或硬件断点。
    • listBreakpoints – 列出所有调试器断点，包括命中次数和条件。
  • 执行与状态：
    • getRegisters – 快照通用寄存器、段寄存器、调试寄存器及标志。
    • runTrace – 触发 traceinto/traceover 执行，可选步数。
    • ping – 轻量级健康检查。
• x96dbg 内部运行时命令：
  • mcp.status – 打印当前服务器状态。
  • mcp.restart – 重启服务器而不重新加载插件。
  • mcp.port <端口> – 持久化新的 TCP 端口（保存到 MCP 设置桶中）。
  • mcp.host <IPv4|0.0.0.0|*> – 持久化绑定地址（默认 127..0.0.1）。使用 0.0.0.0 接受局域网客户端。

内存工具快速参考

writeMemory

• 必需参数：address（十六进制字符串或整数），data（字节字符串）。
• 可选参数：
  • format: "hex"（默认）或 "ascii" 输入解码。
  • force: true 临时将页面保护提升至 RW（如果尚未可写）。
• 返回值：写入的字节数、回显的地址以及写入前后的保护设置。

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "writeMemory",
  "params": {
    "address": "0x401000",
    "data": "90 90 90 90",
    "force": true
  }
}

patternScan

• 必需参数：包含空格分隔的十六进制字节的 pattern；使用 ?? 表示单字节通配符。
• 范围：提供起始地址和结束地址，或者起始地址和大小（无符号整数）。
• 可选参数：maxResults 限制返回的匹配数量（默认不限）。
• 返回值：规范化模式、扫描边界、总扫描字节数以及匹配地址列表。

{
  "jsonrpc": "2.0",
  "id":  43,
  "method": "patternScan",
  "params": {
    "start": "0x400000",
    "end": "0x410000",
    "pattern": "48 8B ?? ?? 48 89 ??"
  }
}

构建

构建脚本从单一源树生成 32 位（.dp32）和 64 位（.dp64）插件二进制文件。选择适合您工作流程的方法：

方案 1：CMake 预设（推荐）

cmake --preset win32-release
cmake --build --preset win32-release
cmake --preset x64-release
cmake --build --preset x64-release

每个预设配置一个独立的构建树（build/win32 和 build/x64），针对 Visual Studio 2022 生成器。成功构建后产生：

• build/win32/bin/win32/Release/MCPluginForX96Dbg.dp32
• build/x64/bin/x64/Release/MCPluginForX96Dbg.dp64

方案 2：手动配置

cmake -S . -B build/win32 -A Win32 -DMCP_TARGET_ARCH=win32
cmake --build build/win32 --config Release
cmake -S . -B build/x64 -A x64 -DMCP_TARGET_ARCH=x64
cmake --build build/x64 --config Release

构建完成后，将 MCPluginForX96Dbg.dp32 及 MCPluginForX96Dbg.json 复制到 <x64dbg root>\x32\plugins，并将 .dp64 版本及相同清单复制到 <x64dbg root>\x64\plugins。

综合发布捆绑包

使用辅助脚本将两个二进制文件（及清单）压缩成一个可分发的归档文件：

powershell -ExecutionPolicy Bypass -File tools/package-plugin.ps1 -OutputPath dist/MCPluginForX96Dbg-bundle.zip

默认情况下，脚本期望在 build/win32 和 build/x64 中有 Release 输出。如果您使用不同的构建文件夹，请用 -Win32BuildDir 或 -X64BuildDir 覆盖位置。

Visual Studio Code 设置

1. 在 Visual Studio Code 中安装 CMake Tools 和 C/C++ 扩展。
2. 打开此仓库文件夹并允许 CMake Tools 检测项目。
3. 从命令面板选择 CMake: Select a Kit 并选择与目标架构匹配的 Visual Studio 工具链（Win32 对应 .dp32，x64 对应 .dp64）。
4. 运行 CMake: Configure 针对所需的预设/构建文件夹（例如 win32-release 或 x64-release）。
5. 运行 CMake: Build（或按 Ctrl+Shift+B）针对 Release 配置。输出位于 build/<arch>/bin/<arch>/Release/，带有适当的 .dp32 或 .dp64 后缀。
6. 将生成的 .dp32 或 .dp64 二进制文件及 MCPluginForX96Dbg.json 复制到调试器的 x32\plugins 或 x64\plugins 目录，然后启动相应的调试器——加载插件将在 127.0.0.1:51337 默认启动 MCP 服务器。

注意：服务器使用换行符分隔的 JSON-RPC。如果您在浏览器中打开该端口，您会收到纯文本帮助消息而不是 JSON 响应。

MCP 客户端配置（Cursor / VS Code）

Cursor（或 VS Code）可以通过 Model Context Protocol 桥接将请求转发给插件的 MCP 服务器。创建或更新您的全局 MCP 配置（例如，%APPDATA%/Cursor/User/globalStorage/mcp-servers.json），添加以下条目：

{
  "mcpServers": {
    "x96dbg-mcp": {
      "command": "python",
      "args": [
        "C:/Path/To/MCPluginForX96Dbg/tools/mcp_tcp_bridge.py",
        "--host",
        "10.0.0.16", // 或 "127.0.0.1" 如果是本地
        "--port",
        "51337"
      ],
      "description": "连接 VS Code 至运行在本地机器上的 x96dbg MCP 插件。"
    }
  }
}

注意：

• 替换 C:/Path/To/... 为桥接脚本的实际绝对路径。
• 插件支持远程查询！如果 x96dbg 在另一台机器上运行（例如，IP 地址为 10.0.0.16 的虚拟机），只需更改此配置中的 --host 参数指向那个 IP 地址。确保插件本身绑定到 0.0.0.0（默认）或特定的局域网 IP 地址，通过检查 x96dbg 的日志窗口来确认。

💡 确保 Python 3.9+ 在您的 PATH 中。辅助脚本仅在 VS Code 和插件之间转发换行符分隔的 JSON。在 VS Code 连接之前先在 x96dbg 中加载插件。插件默认绑定到 0.0.0.0；根据需要调整 --host 参数，或在 x96dbg 中运行 mcp.host 127.0.0.1 以限制访问仅限回环。

协议概述

连接接受于 127.0.0.1:<端口>，使用单行 JSON-RPC 框架（换行符分隔）。示例交互：

{"jsonrpc":"2.0","id":1,"method":"readMemory","params":{"address":"0x401000","size":16}}

成功的响应镜像相同的 id 并包含一个 result 对象。失败返回一个带有数字 code 和可打印 message 的 error 块。

安全注意事项

• 默认情况下，插件监听所有接口（0.0.0.0）。如需更改端口，请使用 mcp.port <值>，并可选地通过 mcp.host 127.0.0.1 返回仅限回环模式以增强安全性。
• 若要服务局域网客户端，请运行 mcp.host 0.0.0.0（或特定的 IPv4）。记住这将使 JSON-RPC 接口暴露于本地机器之外——仅在可信网络中使用。
• 请求需要附加的被调试程序。当调试器处于空闲状态时，操作将以“未附加被调试程序”优雅失败。
• 内存读取限制为每次请求 4096 字节，以避免大量传输。

下一步

• 在 CI 中为每次推送/标签自动化双架构构建。
• 扩展 MCP 命令的测试覆盖率（模拟被调试程序场景）。
• 探索远程 MCP 会话的可选 TLS 传输。

捐赠

https://www.paypal.com/donate/?hosted_button_id=JX66BE5XAGVQE