Vscode Xdebug MCP

vscode xdebug mcp

将活动的PHP/Xdebug会话作为VS Code中的MCP服务器公开，以便代理客户端（Codex）可以检查和控制实时调试会话。 此mcp服务器目前被设计为与Codex一起运行。稍后将推出复制版本和独立服务器。

这个扩展有什么作用

• 在VS代码扩展主机内运行本地HTTP MCP服务器。服务器使用端口 3098 默认情况下，或者在以下情况下为动态分配的端口 3098 已在使用中（例如当多个VS Code实例正在运行时）。
• 桥接MCP工具调用活动PHP/Xdebug会话的VS代码调试适配器协议（DAP）。
• 提供列出会话、检查堆栈/变量、设置断点和控制执行的工具。

多个VS代码实例： 扩展会自动处理端口冲突。中频端口 3098 已绑定，它将回退到操作系统分配的端口。实际的URL通过VS代码提供给MCP客户端 McpHttpServerDefinition API

它是如何工作的（高级）

1. VS Code激活扩展 并启动HTTP MCP服务器。
2. MCP客户端连接 到 /mcp 并发出JSON-RPC请求。
3. MCP服务器转发请求 连接到与活动调试会话对话的DAP网桥。
4. 返回结果 MCP工具为代理输出结构化数据。

关键文件：

• src/extension.ts：VS代码入口点，注册MCP定义提供程序，启动/停止服务器。
• src/mcp/httpTransport.ts：HTTP服务器+MCP传输（单 /mcp 端点）。
• src/mcp/server.ts：向客户公开的MCP工具/资源。
• src/debug/dapBridge.ts：DAP桥接到活动调试会话。

需求

• VS代码与 engines.vscode 版本在 package.json
• 正在运行的PHP/Xdebug调试会话（通过VS代码调试器启动）

路径映射

Xdebug断点使用服务器端文件路径绑定。你的 launch.json 必须将该路径映射到本地工作区，以便VS Code（和此MCP服务器）可以解析同一文件。

示例（本地工作区根的远程路径）：

"pathMappings": {
  "/var/www/html/project": "${workspaceFolder}"
}

如果您的本地项目位于子文件夹中：

"pathMappings": {
  "/var/www/html/project": "${workspaceFolder}/project"
}

Xdebug配置（Xdebug 3示例）

确保Xdebug已启用并配置为连接到调试主机和端口。最低设置：

xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003

笔记：

• 如果PHP在Docker/WSL/VM中运行，请设置 xdebug.client_host 到从该环境可访问的主机（或使用 xdebug.discover_client_host=1).
• 端口必须与您的 launch.json port 价值。

在开发中运行

1. npm install
2. npm run watch （使构建输出保持最新）
3. 按 F5 启动扩展开发主机（EDH）。
4. 在EDH窗口中启动PHP/Xdebug调试会话。
5. MCP服务器URL由VS Code的MCP集成提供，无需手动连接。

注意：MCP服务器运行 里面 扩展主机。如果您的EDH是远程的（WSL/SSH/Dev容器），则端口是动态分配的，URL可以通过McpHttpServerDefinition发现。

在Vscode中使用Codex

1. 克隆仓库
2. 跑 npm install
3. 跑 npm run vsce:package 构建.vsix文件。
4. 在Vscode中，导航到扩展选项卡，单击右上角的省略号，然后单击“从VSIX安装”
5. 选择生成的文件并安装。
6. 重新加载vscode
7. MCP服务器由VS Code的MCP集成自动发现。打开codex聊天窗口，验证MCP服务器是否可用（无需手动配置URL）。
8. 在VS Code中启动PHP调试会话并设置断点。然后让codex代理访问执行范围内的调用帧或变量。

注： MCP服务器使用端口 3098 默认情况下为动态端口，如果 3098 已在使用中。VS Code的MCP集成自动处理URL发现——只有从外部VS Code连接的外部MCP客户端才需要手动配置。

MCP工具（概述）

岩芯检查：

• list_sessions → 列出已知的调试会话
• status → 会话状态（已停止/正在运行，线程）
• threads, stack, scopes, variables → 检查执行状态
• snapshot → 一次调用中的顶部框架+作用域+变量
• list_resource_templates → 列出资源模板（例如。， xdebug://variables/{frameId})

执行控制：

• continue, pause, step_over, step_in, step_out
• restart, terminate, disconnect

断点：

• set_breakpoint, clear_breakpoints
• set_logpoint （日志消息）
• set_function_breakpoints
• set_exception_breakpoints

评价：

• evaluate_expr → 计算给定帧中的表达式
• wait_for_stop → 轮询，直到调试器停止

提示：

• xdebug_mcp_capabilities → 引导发现工具/资源和使用要求

注意事项和限制

• Xdebug不支持真正的反向调试（后退）。
• 大多数工具默认为 活跃的 调试会话，除非 sessionId 提供。
• 一些DAP功能是特定于适配器的；可用性取决于Xdebug和您的调试适配器。
• 代理集文件断点是通过VS Code注册的，因此它们显示在“断点”面板中；提供与您匹配的工作区相对或绝对本地路径 pathMappings.
• xdebug://stack 是一个静态MCP资源，将出现在 list_mcp_resources变量资源是一个模板，可以通过以下方式发现 list_mcp_resource_templates 或 list_resource_templates 工具。

故障排除

• 断点不绑定：验证 pathMappings 匹配服务器端路径，并且调试会话实际上在您检查变量/堆栈时停止。
• 未列出MCP资源: xdebug://stack 是静态的，应该出现在 list_mcp_resources.模板如 xdebug://variables/{frameId} 通过以下方式显示 list_mcp_resource_templates 或 list_resource_templates 工具。
• 调试会话从不连接：确认Xdebug已启用， xdebug.mode=debug，以及 xdebug.client_host VS Code主机上的点数（或启用 xdebug.discover_client_host=1 在容器/远程设置中）。
• 端口不匹配：确保 xdebug.client_port 火柴 launch.json port.
• 日志点不记录：确保您的PHP调试适配器支持日志点；如果不是， logMessage 被忽略。

构建/打包

• npm run check-types --类型检查
• npm run package --捆绑生产
• npm run vsce:package --建造 .vsix