X96dbg MCP Server Plugin

MCPluginForX96Dbg

一个双架构x32dbg/x64dbg插件，它在TCP上公开了一个轻量级的JSON-RPC“模型上下文协议”（MCP）桥。服务器允许自动化检查和控制活动的被调试对象，而不依赖于调试器UI。

特性

• 建筑 .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 –枚举所有调试器断点，包括命中计数和条件。 - 执行状态（&S）： - getRegisters –快照通用、分段和调试寄存器以及标记。 - runTrace –触发器 traceinto/traceover 具有可选步数的执行。 - ping –轻量级的健康检查。

• x96dbg中的运行时命令：

- mcp.status –打印当前服务器状态。 - mcp.restart –在不重新加载插件的情况下重新启动服务器。 - mcp.port –保留一个新的TCP端口（保存到 MCP 设置桶）。 - mcp.host –保留绑定地址（默认 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 包含空格分隔的十六进制字节；使用 ?? 对于单字节通配符。
• 范围：提供其中之一 start & end 地址或 start & size （无符号整数）。
• 可选的: 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 进入 \x32\plugins，以及 .dp64 变体加上相同的清单 \x64\plugins.

组合发布捆绑包

使用辅助脚本将两个二进制文件（和清单）压缩到一个可分发的存档中：

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

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

Visual Studio代码设置

1. 安装 CMake工具 和 C/C++ Visual Studio代码中的扩展。
2. 打开此存储库文件夹，并允许CMake Tools检测项目。
3. 从命令选项板中选择 CMake：选择一个工具包 并选择与目标体系结构（Win32 for .dp32，x64适用于 .dp64).
4. 跑 CMake：配置 与所需的预设/构建文件夹（例如 win32-release 或 x64-release).
5. 跑 CMake：构建 （或按 Ctrl+Shift+B)瞄准 发布 配置。产出土地 build//bin//Release/ 与适当 .dp32 或 .dp64 后缀。
6. 复制结果 .dp32 或 .dp64 二进制 和 MCPluginForX96Dbg.json 进入调试器 x32\plugins 或 x64\plugins 目录，然后启动匹配的调试器——加载插件将在上生成MCP服务器 127.0.0.1:51337 默认情况下。

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

游标/VS代码的MCP客户端配置

游标（或VS代码）可以通过模型上下文协议桥将请求转发到插件的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", // or "127.0.0.1" if local
        "--port",
        "51337"
      ],
      "description": "Connects VS Code to the x96dbg MCP plugin running on the local machine."
    }
  }
}

注：

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

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

协议概述

连接已接受 127.0.0.1: 使用单行JSON-RPC帧（换行符分隔）。交互示例：

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

成功的响应反映了相同的情况 id 并包含a result 对象。失败返回 error 带数字的块 code 可打印 message.

安全须知

• 默认情况下，插件会监听所有接口(0.0.0.0).通过以下方式更改端口 mcp.port 如果需要，可以选择返回仅环回模式 mcp.host 127.0.0.1 为了更严格的安全。
• 要为LAN客户端提供服务，请运行 mcp.host 0.0.0.0 （或特定的IPv4）。记住，这会在本地机器之外暴露JSON-RPC接口——将使用限制在受信任的网络上。
• 请求需要附加调试对象。操作将优雅地失败 No debuggee attached 当调试器处于空闲状态时。
• 每次请求的内存读取上限为4096字节，以避免大量传输。

后续步骤

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

捐款

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