mcp-debugger

MCP ACS 调试器服务

🔗 仓库

此软件包现由独立仓库维护：https://github.com/Digital-Defiance/mcp-debugger-server

此仓库是 GitHub 上 AI Capabilitites Suite 的一部分。

这是一款企业级模型上下文协议（MCP）服务，可通过 Chrome DevTools 协议为 Node.js 和 JavaScript 应用提供全面的调试功能。此服务可让 AI Agent（Kiro、Amazon Q、GitHub Copilot）使用 25 种以上的专用工具交互式调试 Node.js 代码，功能涵盖基础断点管理、高级 CPU／内存分析以及挂起检测。若要调试多种语言（Python、Java、Go 等），请使用基于调试适配器协议的 VS Code 扩展。

🎯 主要功能

核心调试功能

• Node.js／JavaScript 支持：通过 Chrome DevTools 协议调试 Node.js 应用和 JavaScript 代码
• TypeScript 支持：完整支持 TypeScript 调试，并可解析源映射
• 断点管理：设置、移除、切换和列出断点，并可选择添加条件、命中次数和日志点
• 执行控制：精确控制执行的继续、单步跳过、单步进入、单步跳出和暂停
• 变量检查：检查局部和全局变量、计算表达式，并监视变量变化
• 调用栈导航：查看和浏览调用栈帧，并切换上下文

高级功能

• 挂起检测：通过可配置的超时时间和采样间隔，检测无限循环和进程挂起
• 源映射支持：完整支持源映射，可调试 TypeScript 和转译后的 JavaScript，并显示原始源代码位置
• 性能分析：CPU 分析、内存分析、堆快照和性能时间线跟踪
• 测试框架集成：调试 Jest、Mocha 和 Vitest 测试
• 会话管理：支持多个并发调试会话，且会话之间完全隔离
• Chrome DevTools 协议：直接集成 Node.js Inspector 协议，实现底层调试

企业级功能

• 可观测性：结构化日志、指标收集、健康检查端点和 Prometheus 指标导出
• 安全性：身份验证、速率限制、敏感数据屏蔽、审计日志和会话超时强制执行
• 可用于生产环境：断路器、带指数退避的重试逻辑、优雅关闭和资源限制
• 监控：性能指标、会话录制和全面的错误跟踪

📦 安装

系统要求

• Node.js：>= 18.0.0
• NPM：>= 8.0.0
• 操作系统：macOS、Linux、Windows
• CPU 架构：x64、arm64

快速开始（推荐使用 NPM）

# Install globally
npm install -g @ai-capabilities-suite/mcp-debugger-server

# Verify installation
ts-mcp-server --version

其他安装方式

使用 NPX（无需安装）

# Run directly without installing
npx @ai-capabilities-suite/mcp-debugger-server

使用 Docker

# Pull and run the Docker image
docker pull digitaldefiance/mcp-debugger-server:latest
docker run -d --name mcp-debugger digitaldefiance/mcp-debugger-server:latest

# Or use docker-compose (see DOCKER-DEPLOYMENT.md)
docker-compose up -d

从源代码安装

# Clone the repository
git clone https://github.com/digital-defiance/ai-capabilities-suite.git
cd ai-capabilities-suite

# Install dependencies
npm install

# Build the packages
npx nx build @ai-capabilities-suite/mcp-debugger-core
npx nx build @ai-capabilities-suite/mcp-debugger-server

# Run the server
node packages/mcp-debugger-server/dist/src/cli.js

⚙️ 配置

Kiro 配置

添加到 .kiro/settings/mcp.json：

{
  "mcpServers": {
    "debugger": {
      "command": "ts-mcp-server",
      "args": [],
      "env": {
        "NODE_ENV": "production"
      },
      "disabled": false,
      "autoApprove": [
        "debugger_start",
        "debugger_set_breakpoint",
        "debugger_continue",
        "debugger_step_over",
        "debugger_inspect",
        "debugger_get_stack"
      ]
    }
  }
}

Claude Desktop 配置

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "debugger": {
      "command": "ts-mcp-server",
      "args": []
    }
  }
}

VS Code 配置

添加到 .vscode/settings.json：

{
  "mcp.servers": {
    "debugger": {
      "command": "ts-mcp-server",
      "args": [],
      "enabled": true
    }
  }
}

环境变量

用于高级配置的可选环境变量：

# Enable debug logging
DEBUG=mcp:*

# Set custom timeout (milliseconds)
MCP_DEBUGGER_TIMEOUT=60000

# Enable authentication
MCP_DEBUGGER_AUTH_TOKEN=your-secret-token

# Enable rate limiting
MCP_DEBUGGER_RATE_LIMIT=100

# Enable audit logging
MCP_DEBUGGER_AUDIT_LOG=true

🛠️ 可用工具

MCP ACS Debugger Server 提供 25 个专用工具，分为 8 个类别：

会话管理

1. debugger_start

启动一个新的调试会话，并运行 Node.js 进程。

参数：

• command（string，必需）：要执行的命令（例如，“node”、“npm”）
• args（string[]，可选）：命令参数（例如，["test.js"]）
• cwd（string，可选）：进程的工作目录
• timeout（number，可选）：超时时间（以毫秒为单位，默认值：30000）

示例：

{
  "command": "node",
  "args": ["app.js"],
  "cwd": "/path/to/project",
  "timeout": 30000
}

响应：

{
  "status": "success",
  "sessionId": "session-123",
  "state": "paused",
  "pid": 12345
}

2. debugger_stop_session

停止调试会话并清理所有资源。

参数：

• sessionId（string，必需）：调试会话 ID

示例：

{
  "sessionId": "session-123"
}

断点管理

3. debugger_set_breakpoint

在指定文件的特定行设置断点。

参数：

• sessionId（string，必需）：调试会话 ID
• file（string，必需）：文件路径（绝对路径或相对路径）
• line（number，必需）：行号（从 1 开始）
• condition（string，可选）：可选的条件表达式（例如，“x > 10”）

示例：

{
  "sessionId": "session-123",
  "file": "/path/to/file.js",
  "line": 42,
  "condition": "count > 5"
}

4. debugger_remove_breakpoint

从会话中移除断点。

参数：

• sessionId（string，必需）：调试会话 ID
• breakpointId（string，必需）：要移除的断点 ID

5. debugger_toggle_breakpoint

切换断点的启用和禁用状态。

参数：

• sessionId（string，必需）：调试会话 ID
• breakpointId（string，必需）：要切换状态的断点 ID

6. debugger_list_breakpoints

获取调试会话的所有断点。

参数：

• sessionId（string，必需）：调试会话 ID

响应：

{
  "status": "success",
  "breakpoints": [
    {
      "id": "bp-1",
      "file": "/path/to/file.js",
      "line": 42,
      "condition": "x > 10",
      "enabled": true,
      "verified": true
    }
  ]
}

执行控制

7. debugger_continue

继续执行，直到遇到下一个断点或程序终止。

参数：

• sessionId（string，必需）：调试会话 ID

8. debugger_step_over

执行当前行，并在同一作用域的下一行暂停。

参数：

• sessionId（string，必需）：调试会话 ID

9. debugger_step_into

执行当前行，并在任何被调用函数内部的第一行暂停。

参数：

• sessionId（string，必需）：调试会话 ID

10. debugger_step_out

执行代码，直到当前函数返回，并在调用位置暂停。

参数：

• sessionId（string，必需）：调试会话 ID

11. debugger_pause

暂停正在运行的调试会话。

参数：

• sessionId（string，必需）：调试会话 ID

变量检查

12. debugger_inspect

在当前执行上下文中计算 JavaScript 表达式。

参数：

• sessionId（string，必需）：调试会话 ID
• expression（string，必需）：要计算的 JavaScript 表达式

示例：

{
  "sessionId": "session-123",
  "expression": "user.name + ' ' + user.age"
}

13. debugger_get_local_variables

获取当前作用域中的所有局部变量。

参数：

• sessionId（string，必需）：调试会话 ID

14. debugger_get_global_variables

获取当前作用域可访问的全局变量。

参数：

• sessionId（string，必需）：调试会话 ID

15. debugger_inspect_object

检查对象属性，并解析嵌套属性。

参数：

• sessionId（string，必需）：调试会话 ID
• objectId（string，必需）：先前检查结果中的对象 ID
• maxDepth（number，可选）：遍历的最大深度（默认值：2）

变量监视

16. debugger_add_watch

将表达式添加到监视列表。

参数：

• sessionId（string，必填）：调试会话 ID
• expression（string，必填）：要监视的表达式

17. debugger_remove_watch

从监视列表中移除表达式。

参数：

• sessionId（string，必填）：调试会话 ID
• watchId（string，必填）：要移除的监视 ID（表达式）

18. debugger_get_watches

获取所有受监视的表达式及其当前值。

参数：

• sessionId（string，必填）：调试会话 ID

调用堆栈

19. debugger_get_stack

获取当前调用堆栈，包括函数名称和文件位置。

参数：

• sessionId（string，必填）：调试会话 ID

响应：

{
  "status": "success",
  "stack": [
    {
      "function": "myFunction",
      "file": "/absolute/path/to/file.js",
      "line": 42,
      "column": 10
    }
  ]
}

20. debugger_switch_stack_frame

将执行上下文切换到指定的堆栈帧。

参数：

• sessionId（string，必填）：调试会话 ID
• frameIndex（number，必填）：帧索引（0 = 顶部帧）

挂起检测

21. debugger_detect_hang

检测进程是否挂起或进入无限循环。

参数：

• command（string，必填）：要执行的命令
• args（string[]，可选）：命令参数
• cwd（string，可选）：工作目录
• timeout（number，必填）：超时时间，单位为毫秒
• sampleInterval（number，可选）：循环检测的采样间隔（默认值：100ms）

示例：

{
  "command": "node",
  "args": ["script.js"],
  "timeout": 5000,
  "sampleInterval": 100
}

响应（已挂起）：

{
  "status": "success",
  "hung": true,
  "location": "/path/to/file.js:42",
  "stack": [...],
  "message": "Process hung at /path/to/file.js:42",
  "duration": 5000
}

响应（已完成）：

{
  "status": "success",
  "hung": false,
  "completed": true,
  "exitCode": 0,
  "duration": 1234
}

🚀 快速入门指南

1. 安装服务

npm install -g @ai-capabilities-suite/mcp-debugger-server

2. 配置你的 AI Agent

将以下内容添加到 MCP 配置文件中（例如，.kiro/settings/mcp.json）：

{
  "mcpServers": {
    "debugger": {
      "command": "ts-mcp-server",
      "args": []
    }
  }
}

3. 开始调试

让你的 AI Agent 调试代码：

"Debug my Node.js script app.js and set a breakpoint at line 42"

AI Agent 将使用 MCP ACS Debugger Server 来：

1. 启动调试会话
2. 设置断点
3. 运行代码
4. 在断点处暂停
5. 检查变量并帮助你修复问题

📚 常见调试场景

场景 1：调试简单脚本

// 1. Start a debug session
{
  "tool": "debugger_start",
  "args": {
    "command": "node",
    "args": ["my-script.js"]
  }
}
// Returns: { sessionId: "session-123", state: "paused" }

// 2. Set a breakpoint
{
  "tool": "debugger_set_breakpoint",
  "args": {
    "sessionId": "session-123",
    "file": "/path/to/my-script.js",
    "line": 10
  }
}

// 3. Continue execution
{
  "tool": "debugger_continue",
  "args": {
    "sessionId": "session-123"
  }
}

// 4. When paused at breakpoint, inspect variables
{
  "tool": "debugger_get_local_variables",
  "args": {
    "sessionId": "session-123"
  }
}

// 5. Step through code
{
  "tool": "debugger_step_over",
  "args": {
    "sessionId": "session-123"
  }
}

// 6. Stop the session
{
  "tool": "debugger_stop_session",
  "args": {
    "sessionId": "session-123"
  }
}

场景 2：调试失败的测试

// 1. Start debugging a Jest test
{
  "tool": "debugger_start",
  "args": {
    "command": "node",
    "args": ["node_modules/.bin/jest", "my-test.spec.js", "--runInBand"],
    "timeout": 60000
  }
}

// 2. Set breakpoint in test file
{
  "tool": "debugger_set_breakpoint",
  "args": {
    "sessionId": "session-123",
    "file": "/path/to/my-test.spec.js",
    "line": 25
  }
}

// 3. Continue to breakpoint
{
  "tool": "debugger_continue",
  "args": {
    "sessionId": "session-123"
  }
}

// 4. Inspect test variables
{
  "tool": "debugger_inspect",
  "args": {
    "sessionId": "session-123",
    "expression": "expect.getState()"
  }
}

场景 3：检测无限循环

// Use hang detection to identify infinite loops
{
  "tool": "debugger_detect_hang",
  "args": {
    "command": "node",
    "args": ["potentially-hanging-script.js"],
    "timeout": 5000,
    "sampleInterval": 100
  }
}
// Returns hang location and stack trace if hung

场景 4：调试 TypeScript 代码

// TypeScript debugging works automatically with source maps
// 1. Ensure your tsconfig.json has "sourceMap": true

// 2. Start debugging the compiled JavaScript
{
  "tool": "debugger_start",
  "args": {
    "command": "node",
    "args": ["--enable-source-maps", "dist/app.js"]
  }
}

// 3. Set breakpoints using TypeScript file paths
{
  "tool": "debugger_set_breakpoint",
  "args": {
    "sessionId": "session-123",
    "file": "/path/to/src/app.ts",  // TypeScript source file
    "line": 42
  }
}
// The debugger automatically maps to the compiled JavaScript location

场景 5：监视变量变化

// 1. Start session and set breakpoint
// ... (as in Scenario 1)

// 2. Add watched variables
{
  "tool": "debugger_add_watch",
  "args": {
    "sessionId": "session-123",
    "expression": "user.balance"
  }
}

// 3. Continue execution
{
  "tool": "debugger_continue",
  "args": {
    "sessionId": "session-123"
  }
}

// 4. Check watched variables at each pause
{
  "tool": "debugger_get_watches",
  "args": {
    "sessionId": "session-123"
  }
}
// Returns: { watches: [{ watchId: "user.balance", value: 100, changed: true, oldValue: 50, newValue: 100 }] }

🎬 演示与截图

调试实况

在 Node.js 应用程序中设置断点并检查变量

检测并诊断无限循环

借助源映射支持调试 TypeScript 代码

注意：请将占位图片替换为展示调试器运行情况的实际截图或动画 GIF。请参阅 images/README.md 了解相关指南。

🔧 故障排除

常见问题及解决方案

问题：“Session not found”

症状：尝试使用会话 ID 时出错 原因：会话 ID 无效，或会话已终止 解决方案：

# Start a new debug session
{
  "tool": "debugger_start",
  "arguments": {
    "command": "node",
    "args": ["your-script.js"]
  }
}

问题：“Process must be paused”

症状：无法检查变量或计算表达式 原因：进程正在运行时尝试检查变量 解决方案：

• 设置断点并继续执行，直到命中断点，或
• 使用 debugger_pause 立即暂停执行

问题：断点未命中

症状：执行未在断点处停止 原因：断点位置无效，或代码路径未执行 解决方案：

1. 确认文件路径正确（使用绝对路径）：

   "file": "/absolute/path/to/your/file.js"  // ✅ Good
   "file": "file.js"                          // ❌ Avoid
   

2. 确认该行包含可执行代码（而非注释或空行）

3. 确认断点已设置并验证：

   {
     "tool": "debugger_list_breakpoints",
     "arguments": { "sessionId": "your-session-id" }
   }
   

问题：误报挂起

症状：脚本正常运行时，挂起检测报告了挂起 原因：对于脚本的正常执行时间而言，超时时间太短 解决方案：

{
  "tool": "debugger_detect_hang",
  "arguments": {
    "command": "node",
    "args": ["script.js"],
    "timeout": 60000,  // Increase timeout to 60 seconds
    "sampleInterval": 200  // Increase sample interval
  }
}

问题：TypeScript 断点不起作用

症状：在 .ts 文件中设置的断点不会暂停执行 原因：未启用或未找到源映射 解决方案：

1. 确保在 tsconfig.json 中设置了 "sourceMap": true：

   {
     "compilerOptions": {
       "sourceMap": true
     }
   }
   

2. 启动 Node.js 时使用 --enable-source-maps 标志：

   node --enable-source-maps dist/app.js
   

3. 确认编译后的 JavaScript 文件旁存在 .map 文件：

   ls dist/*.js.map
   

问题：出现“Cannot find module”错误

症状：启动服务时出现找不到模块的错误 原因：尚未构建这些包，或尚未安装依赖项 解决方案：

# Install dependencies
npm install

# Build the packages
npx nx build @ai-capabilities-suite/mcp-debugger-core
npx nx build @ai-capabilities-suite/mcp-debugger-server

# Or if installed globally, reinstall
npm install -g @ai-capabilities-suite/mcp-debugger-server

问题：WebSocket 连接错误

症状：出现“Failed to connect to inspector”或 WebSocket 错误 原因：Inspector Protocol 启动失败 解决方案：

1. 确保 Node.js 版本为 18 或更高：

   node --version  # Should be >= 18.0.0
   

2. 检查是否有其他调试器连接到该进程

3. 确认进程已成功启动：

   node --inspect-brk your-script.js
   # Should output: Debugger listening on ws://...
   

问题：内存使用量过高

症状：服务占用过多内存 原因：并发会话过多，或堆快照过大 解决方案：

1. 限制并发会话数

2. 停止未使用的会话：

   {
     "tool": "debugger_stop_session",
     "arguments": { "sessionId": "session-id" }
   }
   

3. 配置资源限制（参见“环境变量”部分）

问题：性能缓慢

症状：调试操作运行缓慢 原因：对象过大、检查深度过深，或断点过多 解决方案：

1. 限制对象检查深度：

   {
     "tool": "debugger_inspect_object",
     "arguments": {
       "sessionId": "session-id",
       "objectId": "obj-id",
       "maxDepth": 2  // Limit depth
     }
   }
   

2. 使用条件断点以减少暂停次数

3. 移除不必要的断点

获取帮助

如果遇到此处未涵盖的问题：

1. 检查日志：使用 DEBUG=mcp:* 启用调试日志
2. 搜索现有问题：GitHub Issues
3. 创建新问题：请提供：
   • Node.js 版本（node --version）
   • 服务版本（ts-mcp-server --version）
   • 错误消息和堆栈跟踪
   • 复现步骤
4. 发送支持邮件：[email protected]

💡 使用场景

1. AI 辅助调试

让 AI Agent 能够自主调试代码：

• Kiro：“调试我的失败测试，并告诉我失败原因”
• Amazon Q：“找出脚本中的无限循环”
• GitHub Copilot：“设置断点并检查 user 对象”

2. 自动化测试与 CI/CD

将调试集成到 CI/CD 工作流中：

• 自动调试失败的测试
• 检测性能回归
• 在部署前识别内存泄漏

3. 生产问题排查

安全地调试类似生产环境的环境：

• 在本地复现生产问题
• 检查状态而不修改代码
• 分析性能瓶颈

4. 学习与教育

帮助开发者学习调试技巧：

• 逐步执行代码
• 理解调用栈和作用域
• 直观呈现变量变化

5. 性能优化

识别并修复性能问题：

• 分析 CPU 使用情况
• 分析内存分配
• 检测内存泄漏
• 跟踪性能指标

📊 功能对比

功能	MCP ACS Debugger Server	VS Code Debugger	Chrome DevTools	Node Inspector
AI Agent 集成	✅ 完整支持 MCP	❌ 不支持	❌ 不支持	❌ 不支持
断点	✅ 高级功能（条件、命中次数、日志点）	✅ 支持	✅ 支持	✅ 基础
变量检查	✅ 深度检查并提供类型信息	✅ 支持	✅ 支持	✅ 基础
TypeScript 支持	✅ 完整支持源映射	✅ 支持	✅ 支持	⚠️ 有限
挂起检测	✅ 自动检测并进行采样	❌ 不支持	❌ 不支持	❌ 不支持
CPU 性能分析	✅ 支持	✅ 支持	✅ 支持	❌ 不支持
内存性能分析	✅ 支持泄漏检测	✅ 支持	✅ 支持	❌ 不支持
多个会话	✅ 隔离的并发会话	⚠️ 有限	⚠️ 有限	❌ 不支持
测试框架集成	✅ Jest、Mocha、Vitest	✅ 支持	❌ 不支持	❌ 不支持
远程调试	✅ 通过 MCP 协议	✅ 支持	✅ 支持	✅ 支持
审计日志	✅ 企业级	❌ 不支持	❌ 不支持	❌ 不支持
速率限制	✅ 支持	❌ 不支持	❌ 不支持	❌ 不支持
指标导出	✅ Prometheus	❌ 不支持	❌ 不支持	❌ 不支持

📋 错误代码

服务会返回包含以下代码的结构化错误响应：

错误代码	描述	常见原因	解决方案
SESSION_NOT_FOUND	会话 ID 不存在	ID 无效或会话已终止	启动新会话
SESSION_START_FAILED	启动调试会话失败	命令无效或权限不足	检查命令和文件路径
BREAKPOINT_SET_FAILED	设置断点失败	文件路径或行号无效	使用绝对路径和有效行号
BREAKPOINT_NOT_FOUND	断点不存在	断点 ID 无效	列出断点以验证 ID
CONTINUE_FAILED	恢复执行失败	进程崩溃或已终止	检查进程状态
STEP_OVER_FAILED	单步跳过失败	未暂停或状态无效	确保进程已暂停
STEP_INTO_FAILED	单步进入失败	未暂停或没有函数调用	确保位于函数调用处
STEP_OUT_FAILED	单步跳出失败	当前不在函数中	检查调用栈
PAUSE_FAILED	暂停执行失败	进程未运行	确保进程正在运行
INSPECT_FAILED	求值表达式失败	表达式无效或未暂停	检查语法和暂停状态
GET_STACK_FAILED	获取调用栈失败	未暂停	先暂停执行
NOT_PAUSED	此操作需要处于暂停状态	进程正在运行	暂停进程或设置断点
HANG_DETECTION_FAILED	检测挂起失败	参数无效	检查超时时间和间隔
WATCH_NOT_FOUND	监视表达式不存在	监视 ID 无效	列出监视项以验证 ID
RATE_LIMIT_EXCEEDED	请求过多	超出速率限制	等待后重试
AUTH_FAILED	身份验证失败	令牌无效	检查身份验证令牌

测试

运行单元测试

npx nx test @ai-capabilities-suite/mcp-core
npx nx test @ai-capabilities-suite/mcp-server

运行端到端测试

npx nx test @ai-capabilities-suite/mcp-server --testPathPattern=e2e --testTimeout=60000

手动测试

node packages/mcp-server/test-mcp-manual.js

有关全面的测试文档，请参阅 TESTING.md。

🏗️ 架构

技术栈

MCP ACS Debugger Server 基于企业级技术构建：

• MCP SDK：用于 AI Agent 通信的 Model Context Protocol 实现
• Chrome DevTools Protocol (CDP)：用于底层调试的 Node.js Inspector Protocol
• WebSocket：与 Node.js Inspector 实时双向通信
• TypeScript：具备完整类型定义的类型安全实现
• Zod：对工具参数进行运行时类型验证
• Prometheus：指标收集与导出

组件架构

┌─────────────────────────────────────────────────────────────┐
│                        AI Agent Layer                        │
│  (Kiro, Amazon Q, GitHub Copilot, Claude Desktop)          │
└────────────────────────┬────────────────────────────────────┘
                         │ MCP Protocol (stdio/JSON-RPC)
                         │
┌────────────────────────▼────────────────────────────────────┐
│                   MCP ACS Debugger Server                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Session    │  │  Breakpoint  │  │   Variable   │     │
│  │   Manager    │  │   Manager    │  │  Inspector   │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │     Hang     │  │     CPU      │  │    Memory    │     │
│  │   Detector   │  │   Profiler   │  │   Profiler   │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Source     │  │    Audit     │  │    Metrics   │     │
│  │  Map Manager │  │    Logger    │  │  Collector   │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└────────────────────────┬────────────────────────────────────┘
                         │ Inspector Protocol (CDP/WebSocket)
                         │
┌────────────────────────▼────────────────────────────────────┐
│                   Node.js Inspector                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Debugger   │  │   Runtime    │  │   Profiler   │     │
│  │    Domain    │  │    Domain    │  │    Domain    │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────┐
│                   Target Node.js Process                     │
│              (Application, Test Runner, etc.)                │
└─────────────────────────────────────────────────────────────┘

数据流

1. AI Agent 请求：Agent 通过 stdio 发送 MCP 工具请求
2. 工具验证：服务使用 Zod schemas 验证参数
3. 会话管理：服务创建或获取调试会话
4. CDP 通信：服务通过 WebSocket 发送 CDP 命令
5. Inspector 响应：Node.js Inspector 返回调试数据
6. 数据处理：服务处理并格式化响应
7. MCP 响应：服务向 Agent 返回结构化 JSON 响应

安全架构

┌─────────────────────────────────────────────────────────────┐
│                      Security Layer                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │     Auth     │  │     Rate     │  │     Data     │     │
│  │   Manager    │  │   Limiter    │  │    Masker    │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Session    │  │    Audit     │  │   Circuit    │     │
│  │   Timeout    │  │    Logger    │  │   Breaker    │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└─────────────────────────────────────────────────────────────┘

⚡ 性能

基准测试

MacBook Pro（M1，16GB RAM）上的性能指标：

操作	平均延迟	吞吐量	备注
会话启动	150ms	6.6/sec	包含进程启动
设置断点	5ms	200/sec	单个断点
继续执行	2ms	500/sec	恢复执行至下一个断点
单步跳过	8ms	125/sec	单步操作
变量检查	12ms	83/sec	仅限局部变量
表达式求值	15ms	66/sec	简单表达式
调用栈获取	10ms	100/sec	完整堆栈跟踪
挂起检测	5000ms	0.2/sec	超时设为 5s
CPU 分析启动	3ms	333/sec	启动分析
CPU 分析停止	50ms	20/sec	包含分析
堆快照	200ms	5/sec	10MB 堆

资源使用情况

典型资源消耗：

• 内存：基础占用 50-100MB，每个活动会话额外占用 10-20MB
• CPU：空闲时 < 1%，主动调试时 5-10%
• 网络：极少（仅本地 WebSocket）
• 磁盘：日志和指标占用 < 1MB

可扩展性

• 并发会话：已通过 100 个以上并发会话的测试
• 断点：每个会话支持 1000 个以上断点
• 会话时长：已通过 24 小时以上会话的测试
• 内存稳定性：48 小时压力测试中未检测到内存泄漏

参与贡献

欢迎贡献！请遵循以下指南：

1. Fork 此仓库
2. 创建功能分支
3. 编写测试并进行修改
4. 运行测试套件
5. 提交拉取请求

发布到 NPM

如果你是负责发布更新的维护者：

• 快速设置：NPM-SETUP-GUIDE.md - 首次设置仅需 5 分钟
• 完整指南：PUBLISHING.md - 全面的发布文档
• 自动化：GitHub Actions 工作流会在发布时处理发布操作

文档

• README.md - 本文件，主要文档
• API.md - 详细的 API 文档
• TOOL-REFERENCE.md - 完整的工具参考
• AI-AGENT-INTEGRATION.md - AI Agent 集成指南
• VSCODE-INTEGRATION.md - VS Code 集成指南
• TESTING.md - 测试文档
• PUBLISHING.md - NPM 发布指南
• NPM-SETUP-GUIDE.md - 面向发布者的快速设置

🙏 致谢

本项目基于出色的开源技术构建：

• Model Context Protocol - 协议规范和 SDK
• Chrome DevTools Protocol - 调试协议
• Node.js Inspector - Node.js 调试 API
• TypeScript - 类型安全的 JavaScript
• Zod - 运行时类型校验

特别感谢：

• MCP 社区提供的反馈和贡献
• 所有帮助改进本项目的贡献者
• 报告问题并提出改进建议的用户

📜 许可证

MIT 许可证 - 详情请参阅 LICENSE 文件

版权所有 (c) 2024 Digital Defiance

特此免费授予任何获得本软件及相关文档文件（“软件”）副本的人不受限制地处理本软件的权利，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售本软件副本的权利，以及允许获得本软件的人这样做的权利，但须遵守以下条件：

上述版权声明和本许可声明应包含在本软件的所有副本或实质性部分中。

本软件按“原样”提供，不作任何明示或暗示的保证，包括但不限于适销性、特定用途适用性和非侵权性的保证。在任何情况下，作者或版权持有人均不对因本软件或本软件的使用或其他相关事宜引起的任何索赔、损害或其他责任承担责任，无论是基于合同、侵权还是其他原因。

🔗 链接

• 主页：https://digitaldefiance.org
• GitHub：https://github.com/digital-defiance/ai-capabilities-suite
• NPM：https://www.npmjs.com/package/@ai-capabilities-suite/mcp-debugger-server
• Docker Hub：https://hub.docker.com/r/digitaldefiance/mcp-debugger-server
• 文档：https://github.com/digital-defiance/ai-capabilities-suite/tree/main/packages/mcp-debugger-server
• 问题反馈：https://github.com/digital-defiance/ai-capabilities-suite/issues
• 讨论：https://github.com/digital-defiance/ai-capabilities-suite/discussions

---

❓ 常见问题解答（FAQ）

一般问题

问：什么是模型上下文协议（MCP）？ 答：MCP 是一种协议，可让 AI Agent 与外部工具和服务交互。MCP ACS 调试器服务通过实现 MCP，为 AI Agent 提供调试功能。

问：支持哪些 AI Agent？ 答：该服务可与任何兼容 MCP 的 AI Agent 配合使用，包括：

• Kiro
• Amazon Q
• GitHub Copilot
• Claude Desktop
• 自定义 MCP 客户端

问：我可以将它用于生产环境调试吗？ 答：可以！该服务包含专为生产环境设计的企业级功能，例如身份验证、速率限制、审计日志和熔断器。不过，请务必先在预发布环境中进行测试。

问：这是免费的吗？ 答：是的，MCP ACS 调试器服务基于 MIT 许可证开源，个人和商业用途均可免费使用。

技术问题

问：支持哪些 Node.js 版本？ 答：需要 Node.js >= 18.0.0。我们建议使用最新的 LTS 版本。

问：支持 TypeScript 吗？ 答：支持！提供完整的 TypeScript 支持和源映射。可在 .ts 文件中设置断点，并使用原始 TypeScript 名称检查变量。

问：可以调试远程进程吗？ 答：服务通过 Inspector Protocol 连接到本地 Node.js 进程。若要进行远程调试，请使用 SSH 隧道，或在远程计算机上部署服务。

问：可以同时运行多少个调试会话？ 答：服务支持 100+ 个并发会话。每个会话彼此隔离，不会相互影响。

问：支持 Docker 容器吗？ 答：支持！我们提供官方 Docker 镜像。详情请参阅 DOCKER-DEPLOYMENT.md。

调试问题

问：为什么断点没有命中？ 答：常见原因：

1. 文件路径是相对路径，而非绝对路径
2. 行号所在位置没有可执行代码
3. 未执行相应的代码路径
4. 缺少源映射（适用于 TypeScript）

问：如何调试特定测试？ 答：使用测试运行器启动调试会话：

{
  "tool": "debugger_start",
  "arguments": {
    "command": "node",
    "args": ["node_modules/.bin/jest", "my-test.spec.js", "--runInBand"]
  }
}

问：可以调试异步代码吗？ 答：可以！调试器全面支持 async/await、Promises 和回调。可在异步函数中设置断点，并像平常一样逐步调试。

问：如何检测内存泄漏？ 答：使用内存分析工具：

1. 在开始时拍摄堆快照
2. 运行代码
3. 再拍摄一个堆快照
4. 对比快照，找出不断增长的对象

性能问题

问：调试会拖慢我的应用程序吗？ 答：会，调试会带来额外开销。主动调试时，速度预计会降低 2-5 倍。使用条件断点并禁用不必要的断点，以尽量减小影响。

问：服务会占用多少内存？ 答：基础内存用量为 50-100MB，每个活动调试会话还会额外占用 10-20MB。

问：可以在 CI/CD 管道中使用吗？ 答：可以！服务专为自动化设计。在 CI/CD 管道中使用挂起检测和测试调试，以便及早发现问题。

安全问题

问：在生产环境中使用安全吗？ 答：服务包含企业级安全功能（身份验证、速率限制、审计日志），但在生产环境中调试应谨慎进行，且仅在必要时进行。

问：如何保护敏感数据？ 答：服务会自动遮蔽常见格式的 PII（电子邮件、SSN、信用卡）。可根据需要配置其他遮蔽规则。

问：可以限制允许执行的操作吗？ 答：可以！使用身份验证，并为每个用户/令牌配置允许的操作。请参阅文档中的 Security 部分。

集成问题

问：如何与 VS Code 集成？ 答：详细的集成说明请参阅 VSCODE-INTEGRATION.md。

问：可以与 GitHub Copilot 一起使用吗？ 答：可以！GitHub Copilot 可以使用 MCP 服务。请在 Copilot 设置中配置该服务。

问：支持 Mocha/Jest/Vitest 吗？ 答：支持！服务内置支持所有主流测试框架。只需使用测试运行器命令启动调试会话即可。

💬 支持与社区

获取帮助

• 📖 文档：完整文档
• 🐛 错误报告：GitHub Issues
• 💡 功能请求：GitHub Discussions
• 📧 电子邮件支持：[email protected]
• 💬 社区聊天：加入我们的 Discord (即将推出)

资源

• NPM Package： @ai-capabilities-suite/mcp-debugger-server
• Docker Hub：digitaldefiance/mcp-debugger-server
• GitHub Repository：ai-capabilities-suite
• API 文档：API.md
• 工具参考：TOOL-REFERENCE.md

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解指南。

赞助

支持此项目：

• GitHub Sponsors：赞助 Digital Defiance
• Open Collective：支持此项目 (即将推出)

📝 更新日志

Version 1.0.4（当前版本）

发布日期：2025 年 12 月

新功能：

• 增强文档，提供全面的示例
• 改进错误消息和故障排除指南
• 添加性能基准和指标
• 增强安全功能文档

错误修复：

• 修复 WebSocket 连接稳定性问题
• 改进边缘情况下的源映射解析
• 修复长时间运行的会话中的内存泄漏

性能：

• 将会话启动时间缩短 20%
• 优化大型对象的变量检查
• 提高 CPU 性能分析的准确性

Version 1.0.2

发布日期：2024 年 11 月

新功能：

• 添加对 Docker 的支持并提供官方映像
• 实现 Prometheus 指标导出
• 添加健康检查端点
• 通过结构化格式增强审计日志记录

改进：

• 更好地处理 CDP 协议错误
• 改进 TypeScript 源映射支持
• 增强会话隔离

Version 1.0.1

发布日期：2024 年 11 月

新功能：

• 添加 CPU 性能分析支持
• 添加内存性能分析和堆快照
• 实现性能时间线跟踪
• 添加高级断点类型（日志点、命中次数）

改进：

• 增强卡顿检测算法
• 提高变量检查性能
• 更好地处理异步代码

Version 1.0.0

发布日期：2024 年 10 月

首次发布：

• 25 个全面的调试工具
• 完整的 TypeScript 支持和源映射
• 支持可配置采样的卡顿检测
• 支持多个并发会话并相互隔离
• 测试框架集成（Jest、Mocha、Vitest）
• 变量监视与变更检测
• 调用堆栈导航
• 条件断点
• 对象检查与嵌套解析
• 企业级安全功能
• 可观测性和监控

🗺️ 路线图

Version 1.1.0（计划于 2025 年第一季度推出）

• 时间旅行调试（录制和回放）
• 使用 AI 智能推荐断点
• 增强 VS Code 扩展
• WebAssembly 调试支持
• 分布式追踪集成

Version 1.2.0（计划于 2025 年第二季度推出）

• 浏览器调试支持（Chrome、Firefox）
• 移动端调试（React Native）
• 协作调试会话
• 高级可视化工具
• 自定义工具插件系统

Version 2.0.0（计划于 2025 年第三季度推出）

• 多语言支持（Python、Go、Rust）
• 云原生调试
• Kubernetes 集成
• 高级 AI 驱动的调试辅助
• 实时协作功能

想影响路线图？分享你的想法