MCP JS Debugger

MCP JS 调试器

一个 MCP（模型上下文协议）服务，提供 Chrome DevTools Protocol 调试功能，使 AI 助手能够调试 JavaScript 和 TypeScript 应用程序。

功能

• 连接到任何兼容 CDP 的调试器（Node.js、Chrome、Edge）
• 设置、列出和移除断点
• 单步执行代码（跳过、进入、跳出）
• 查看调用堆栈，并支持源映射
• 在任意堆栈帧中求值表达式
• 查看和修改变量
• 在异常处暂停
• 全面支持源映射，可用于调试转译后的代码

安装

npm install
npm run build

Claude Code 集成

将以下内容添加到 Claude Code 配置中：

claude mcp add mcp-js-debugger -- npx mcp-js-debugger

或添加到 .mcp.json：

{
  "mcpServers": {
    "mcp-js-debugger": {
      "command": "npx",
      "args": ["mcp-js-debugger"]
    }
  }
}

用法

启动调试目标

使用检查器启动 Node.js 应用程序：

# Pause on first line (recommended for setting initial breakpoints)
node --inspect-brk=9229 your-script.js

# Or start without pausing
node --inspect=9229 your-script.js

可用工具

工具	描述
connect_debugger	通过 WebSocket URL 连接到 CDP 端点
disconnect_debugger	断开调试会话
set_breakpoint	按 URL 和行号设置断点
remove_breakpoint	按 ID 移除断点
list_breakpoints	列出会话中的所有断点
resume_execution	暂停后继续执行
step_over	跳过当前语句
step_into	进入函数调用
step_out	跳出当前函数
pause_execution	暂停正在运行的执行
get_call_stack	获取带有源代码位置的当前调用堆栈
evaluate_expression	求值 JavaScript 表达式
get_scope_variables	获取作用域中的变量
set_variable_value	修改变量的值
set_pause_on_exceptions	配置异常处理
get_original_location	将生成代码的位置映射到原始源代码位置
get_script_source	获取脚本源代码
list_scripts	列出已加载的脚本

示例工作流

1. 使用 --inspect-brk 启动应用程序：

   node --inspect-brk=9229 app.js
   

2. 获取 WebSocket URL：

   curl http://localhost:9229/json
   

3. 连接调试器：

   connect_debugger(websocket_url: "ws://localhost:9229/<id>")
   

4. 设置断点：

   set_breakpoint(session_id: "...", url: "file:///path/to/app.js", line_number: 10)
   

5. 恢复执行，以命中断点：

   resume_execution(session_id: "...")
   

6. 暂停时检查状态：

   get_call_stack(session_id: "...")
   get_scope_variables(session_id: "...", call_frame_id: "...", scope_index: 0)
   evaluate_expression(session_id: "...", expression: "myVariable")
   

7. 继续调试：

   step_over(session_id: "...")
   resume_execution(session_id: "...")
   

源映射支持

该服务会自动为转译后的代码（TypeScript、打包后的 JavaScript 等）加载源映射。源映射可用时：

• 调用堆栈会显示原始源代码位置
• 可以在原始源文件中设置断点
• get_original_location 会将生成代码的位置映射到原始源代码位置
• get_script_source 可以返回原始源代码内容

开发

# Build
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Watch mode for development
npm run dev

架构

• cdp-client.ts - 底层 Chrome DevTools Protocol 客户端封装
• session-manager.ts - 管理多个调试会话
• source-map-manager.ts - 处理源映射加载和位置映射
• server.ts - 包含工具处理程序的 MCP 服务实现
• types.ts - TypeScript 类型定义

要求

• Node.js 18.0.0 或更高版本
• 兼容 CDP 的调试目标（Node.js、Chrome、Edge 等）

许可证

Apache-2.0