Internal Debugger MCP

内部调试器MCP

InternalDebuggerMCP是围绕两个组件构建的Windows第一调试桥：

• 注入的x64 C++DLL，通过命名管道公开进程内检查功能；
• Python MCP服务器，它将MCP工具调用转换为管道请求，并根据需要为基于PID的请求注入DLL。

当前的实现侧重于受约束的进程内调试界面：

• 内存读取；
• 受保护的内存写入；
• 指针链解引用；
• 承诺记忆模式扫描；
• 模块枚举；
• 基于轮询的地址监视；
• 顶石支撑的MCP拆卸；
• 使用有界参数封送处理的直接进程内函数调用。

存储库布局

• src/DebuggerDLL：注入DLL和本机检查服务。
• src/McpServer：Python MCP服务器和管道客户端。
• tools/Injector：将DLL注入目标进程的辅助工具。
• tools/TestTarget：用于集成测试的确定性过程。
• docs：架构和工具合同说明。

构建

本机组件面向Windows x64，现在可以通过MSBuild直接使用Visual Studio构建工具2026构建。

& "C:\Program Files (x86)\Microsoft Visual Studio\18\BuildTools\MSBuild\Current\Bin\MSBuild.exe" ".\InternalDebuggerMCP.sln" /m '/p:Configuration=Release;Platform=x64'

如果你喜欢这种方式，存储库仍然包含CMake文件。

cmake -S . -B build -A x64
cmake --build build --config Release

Python MCP服务器需要Python 3.10+。

MCP服务器还公开了一个本地进程查找工具，因此您可以在调用基于PID的调试器工具之前解析PID。

发布包

在包根目录下使用本机二进制文件构建一个可分发的zip，并在 mcp-server.

.\scripts\package_release.ps1

默认情况下，脚本：

• 构建 Release|x64 使用MSBuild；
• 将包裹分为以下几个阶段 dist\staging\InternalDebuggerMCP;
• 副本 Injector.exe 和 InternalDebuggerDLL.dll 到包根；
• 将MCP服务器复制到 mcp-server 并将其Python依赖项提供给 mcp-server\vendor;
• 创造 dist\InternalDebuggerMCP--win-x64.zip.

推荐的包装布局：

• InternalDebuggerMCP\Injector.exe
• InternalDebuggerMCP\InternalDebuggerDLL.dll
• InternalDebuggerMCP\README.md
• InternalDebuggerMCP\QUICKSTART.txt
• InternalDebuggerMCP\package-manifest.json
• InternalDebuggerMCP\mcp-server\launch.py
• InternalDebuggerMCP\mcp-server\mcp_server\...
• InternalDebuggerMCP\mcp-server\vendor\...
• InternalDebuggerMCP\mcp-server\mcp.json.example

只要最终用户已经在本地安装了Python 3.10+，打包的MCP服务器就可以在提取后准备就绪。无需额外 pip install 这一步是必需的，因为软件包将服务器依赖关系提供给 mcp-server\vendor.

冒烟测试

使用此工作流验证本机DLL、注入器和VS Code MCP服务器是否协同工作。

1. 构建解决方案。

& "C:\Program Files (x86)\Microsoft Visual Studio\18\BuildTools\MSBuild\Current\Bin\MSBuild.exe" ".\InternalDebuggerMCP.sln" /m '/p:Configuration=Release;Platform=x64'

1. 启动确定性目标进程。

.\artifacts\Release\x64\TestTarget\TestTarget.exe

预期结果：

• 控制台打印PID；
• 控制台打印以下地址 g_counter, g_write_target, g_pattern, g_bytes, g_head, SampleFunction，以及导出的测试助手；
• g_counter 每一秒都在变化。

1. 确保工作区MCP服务器正在VS代码中运行。

预期结果：

• 这 internalDebugger 服务器列在VS Code的MCP服务器下；
• 服务器启动时不会对常规请求发送stderr垃圾邮件。

1. 从VS Code聊天或MCP工具界面验证核心MCP工具。

预期结果：

• find_process_pid("TestTarget.exe") 在任何基于PID的调试器调用之前返回实时PID。
• ping(pid) 返回目标PID和管道名称 `\\.\pipe\InternalDebuggerMCP_

`以及手表计数。第一个基于PID的调用应该在需要时自动注入。

• list_modules(pid) 包括 TestTarget.exe 和 InternalDebuggerDLL.dll和报告 toolhelp_snapshot 作为枚举方法。
• pattern_scan(pid, "49 4E 54 45 52 4E 41 4C 5F 44 45 42 55 47 47 45 52 5F 4D 43 50 5F 50 41 54 54 45 52 4E") 查找已知的标记字符串。
• read_memory(pid, , 29) 返回以下项的字节数 INTERNAL_DEBUGGER_MCP_PATTERN.
• write_memory(pid, , bytes_hex="AA BB CC DD EE FF 00 11") 成功并返回经过验证的回读字节。
• disassemble(pid, , 6) 回报 push rbp, mov rbp, rsp, nop，以及 ret 对于使用MCP服务器的Capstone支持路径的测试字节。
• invoke_function(pid, module="TestTarget.exe", export="ExportedFillBuffer", args=[...]) 返回函数结果和任何输出缓冲区。
• watch_address(pid, , 4) 紧随其后 poll_watch_events(pid) 显示目标运行时的更改。
• get_injection_setup() 仍然返回注射器路径、DLL路径和手动回退命令，用于故障排除或打包诊断。

1. 完成后停止目标进程。

集成测试

构建解决方案后运行Windows突发请求回归测试。

.\.venv\Scripts\python.exe -m unittest discover -s tests -p "test_*.py"

备注

• 使用打印的地址 TestTarget.exe 每次跑步；它们在发射之间会发生变化。
• 注入的DLL在当前实现中仅为x64。
• 默认情况下，基于PID的MCP工具会自动注入，并解析打包或存储库 InternalDebuggerDLL.dll通过一项习俗 dll_path 仅当您需要非默认构建时。
• write_memory 仅写入已可写的已提交页面，并强制执行有效负载大小上限。
• invoke_function 有意限制为最多6个Win64参数，并支持整数、指针、编码字符串、有界缓冲区， f32，以及 f64 封送处理，通过显式浮动返回解码 return_kind.
• 本机管道服务器现在接受突发客户端并在内部序列化执行，从而避免了第一个实现中出现的连接争用。

当前状态

第一批实现建立了本机协议、管道服务器、内存检查原语、监视管理器、注入器和确定性测试目标。Python MCP表面是单独搭建的，并使用相同的框架文本协议。