MCP Debugger Core

MCP ACS调试器核心

Node.js/JavaScript调试引擎使用Chrome DevTools协议。提供全面的调试功能，包括检查器协议集成、断点管理、变量检查、执行控制、CPU/内存分析、挂起检测和源映射支持。对于多语言调试，请使用利用调试适配器协议的VS Code扩展。

🔗 仓库

此包现在保存在自己的存储库中： ****

此存储库是 AI 能力套件 在GitHub上。

特性

核心调试

• Node.js/JavaScript支持 -调试Node.js应用程序和JavaScript代码
• TypeScript支持 -使用源代码映射解析进行完整的TypeScript调试
• 检查器协议集成 -完全支持Chrome DevTools协议（CDP）
• 断点管理 -设置、删除、切换和列出带条件的断点
• 计量检验 -检查局部/全局变量、计算表达式、监视变量
• 执行控制 -继续、跨过/进入/退出、暂停执行
• 调用堆栈导航 -查看和浏览堆栈框架
• 源地图支持 -使用原始源代码位置调试转换后的代码

高级功能

• 挂起检测 -检测无限循环和挂起过程
• CPU性能分析 -分析CPU使用情况并确定瓶颈
• 内存配置文件 -堆快照和内存泄漏检测
• 绩效时间表 -跟踪绩效事件和指标
• 测试框架集成 -调试Jest、Mocha和Vitest测试

企业功能

• 身份验证和授权 -基于令牌的身份验证和会话管理
• 速率限制 -每次操作的可配置速率限制
• 审计日志 -具有结构化日志记录的全面审计跟踪
• 数据脱敏 -敏感数据的PII检测和屏蔽
• 健康监测 -健康检查和指标收集
• 会话录制 -记录和回放调试会话
• 断路器 -具有自动恢复功能的容错
• 资源限制 -内存和CPU使用限制
• 普罗米修斯集成 -导出用于监控的指标

安装

npm install @ai-capabilities-suite/mcp-debugger-core

快速开始

基本调试会话

import { DebugSession, ProcessSpawner } from '@ai-capabilities-suite/mcp-debugger-core';

// Spawn a Node.js process with inspector
const spawner = new ProcessSpawner();
const { process, inspectorUrl } = await spawner.spawn({
  command: 'node',
  args: ['app.js'],
  cwd: '/path/to/project'
});

// Create debug session
const session = new DebugSession(process, inspectorUrl);
await session.start();

// Set a breakpoint
await session.setBreakpoint({
  file: '/path/to/app.js',
  line: 42,
  condition: 'x > 10' // Optional condition
});

// Continue execution
await session.continue();

// When paused, inspect variables
const locals = await session.getLocalVariables();
console.log('Local variables:', locals);

// Step through code
await session.stepOver();
await session.stepInto();
await session.stepOut();

// Clean up
await session.stop();

挂起检测

import { HangDetector } from '@ai-capabilities-suite/mcp-debugger-core';

const detector = new HangDetector();

const result = await detector.detect({
  command: 'node',
  args: ['potentially-hanging-script.js'],
  timeout: 5000,
  sampleInterval: 100
});

if (result.hung) {
  console.log('Process hung at:', result.location);
  console.log('Stack trace:', result.stack);
} else {
  console.log('Process completed successfully');
}

CPU性能分析

import { CPUProfiler } from '@ai-capabilities-suite/mcp-debugger-core';

const profiler = new CPUProfiler(session);

// Start profiling
await profiler.start();

// Run your code...
await session.continue();

// Stop and analyze
const profile = await profiler.stop();
const analysis = profiler.analyzeProfile(profile);

console.log('Bottlenecks:', analysis.bottlenecks);
console.log('Hot functions:', analysis.hotFunctions);

内存配置文件

import { MemoryProfiler } from '@ai-capabilities-suite/mcp-debugger-core';

const profiler = new MemoryProfiler(session);

// Take heap snapshot
const snapshot = await profiler.takeHeapSnapshot();

// Detect memory leaks
const leaks = await profiler.detectMemoryLeaks({
  snapshots: [snapshot1, snapshot2, snapshot3],
  threshold: 1024 * 1024 // 1MB growth
});

console.log('Memory leaks detected:', leaks);

源地图支持

import { SourceMapManager } from '@ai-capabilities-suite/mcp-debugger-core';

const sourceMapManager = new SourceMapManager();

// Load source maps
await sourceMapManager.loadSourceMap('/path/to/app.js.map');

// Map TypeScript location to JavaScript
const jsLocation = await sourceMapManager.mapToGenerated({
  source: '/path/to/app.ts',
  line: 42,
  column: 10
});

// Map JavaScript location back to TypeScript
const tsLocation = await sourceMapManager.mapToOriginal({
  source: '/path/to/app.js',
  line: 156,
  column: 5
});

API 参考

核心类

调试会话

主调试会话管理器。

class DebugSession {
  constructor(process: ChildProcess, inspectorUrl: string);
  
  // Lifecycle
  async start(): Promise;
  async stop(): Promise;
  
  // Breakpoints
  async setBreakpoint(options: BreakpointOptions): Promise;
  async removeBreakpoint(id: string): Promise;
  async toggleBreakpoint(id: string): Promise;
  async listBreakpoints(): Promise
;
  
  // Execution Control
  async continue(): Promise;
  async stepOver(): Promise;
  async stepInto(): Promise;
  async stepOut(): Promise;
  async pause(): Promise;
  
  // Variable Inspection
  async getLocalVariables(): Promise;
  async getGlobalVariables(): Promise;
  async evaluateExpression(expr: string): Promise;
  async inspectObject(objectId: string): Promise;
  
  // Call Stack
  async getCallStack(): Promise;
  async switchStackFrame(index: number): Promise;
  
  // Watching
  async addWatch(expression: string): Promise;
  async removeWatch(id: string): Promise;
  async getWatches(): Promise;
}

检查员客户

Chrome DevTools协议客户端。

class InspectorClient {
  constructor(wsUrl: string);
  
  async connect(): Promise;
  async disconnect(): Promise;
  async sendCommand(method: string, params?: any): Promise;
  on(event: string, handler: Function): void;
}

断点管理器

跨会话管理断点。

class BreakpointManager {
  createBreakpoint(options: BreakpointOptions): Breakpoint;
  getBreakpoint(id: string): Breakpoint | undefined;
  listBreakpoints(): Breakpoint[];
  removeBreakpoint(id: string): boolean;
  toggleBreakpoint(id: string): boolean;
}

悬挂探测器

检测挂起过程和无限循环。

class HangDetector {
  async detect(options: HangDetectionOptions): Promise;
}

interface HangDetectionOptions {
  command: string;
  args?: string[];
  cwd?: string;
  timeout: number;
  sampleInterval?: number;
}

CPP配置文件

CPU性能分析。

class CPUProfiler {
  constructor(session: DebugSession);
  
  async start(): Promise;
  async stop(): Promise;
  analyzeProfile(profile: CPUProfile): ProfileAnalysis;
}

内存分析器

内存分析和泄漏检测。

class MemoryProfiler {
  constructor(session: DebugSession);
  
  async takeHeapSnapshot(): Promise;
  async detectMemoryLeaks(options: LeakDetectionOptions): Promise;
  async getMemoryUsage(): Promise;
}

企业功能

身份验证管理器

身份验证和授权。

class AuthManager {
  async authenticate(token: string): Promise;
  async validateSession(sessionId: string): Promise;
  async revokeSession(sessionId: string): Promise;
}

限流器

操作速率限制。

class RateLimiter {
  constructor(options: RateLimitOptions);
  
  async checkLimit(key: string): Promise;
  async consumeToken(key: string): Promise;
  getRemainingTokens(key: string): number;
}

AuditLogger

全面的审计日志记录。

class AuditLogger {
  log(event: AuditEvent): void;
  query(filter: AuditFilter): AuditEvent[];
  export(format: 'json' | 'csv'): string;
}

数据询问器

PII检测和屏蔽。

class DataMasker {
  mask(data: any): any;
  addPattern(pattern: RegExp, replacement: string): void;
  detectPII(text: string): PIIMatch[];
}

指标收集器

指标收集和报告。

class MetricsCollector {
  recordMetric(name: string, value: number, tags?: Tags): void;
  getMetrics(filter?: MetricFilter): Metric[];
  export(format: 'prometheus' | 'json'): string;
}

配置

调试会话选项

interface DebugSessionOptions {
  timeout?: number;              // Session timeout (default: 30000ms)
  enableSourceMaps?: boolean;    // Enable source map support (default: true)
  maxCallStackDepth?: number;    // Max call stack depth (default: 50)
  maxObjectDepth?: number;       // Max object inspection depth (default: 3)
}

悬挂检测选项

interface HangDetectionOptions {
  command: string;               // Command to execute
  args?: string[];              // Command arguments
  cwd?: string;                 // Working directory
  timeout: number;              // Timeout in milliseconds
  sampleInterval?: number;      // Sample interval (default: 100ms)
  minSamples?: number;          // Min samples for hang (default: 50)
}

速率限制选项

interface RateLimitOptions {
  maxRequests: number;          // Max requests per window
  windowMs: number;             // Time window in milliseconds
  keyGenerator?: (req: any) => string;  // Custom key generator
}

测试

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test suites
npm run test:unit          # Unit tests only
npm run test:integration   # Integration tests only
npm run test:profiling     # Profiling tests only

建筑

┌─────────────────────────────────────────┐
│         Application Layer               │
│  (MCP Server, CLI, Custom Apps)         │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│      MCP ACS Debugger Core Library          │
├─────────────────────────────────────────┤
│  DebugSession  │  SessionManager        │
│  Breakpoints   │  Variable Inspector    │
│  Execution     │  Call Stack            │
│  Profiling     │  Hang Detection        │
│  Source Maps   │  Test Integration      │
├─────────────────────────────────────────┤
│  Enterprise Features                    │
│  Auth │ Rate Limit │ Audit │ Metrics    │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│    Inspector Protocol (CDP)             │
│    Chrome DevTools Protocol             │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│      Node.js Inspector                  │
│      (Target Process)                   │
└─────────────────────────────────────────┘

用例

1.构建调试工具

使用核心库构建自定义调试工具、IDE或CLI调试器。

2.自动化测试

将调试功能集成到您的测试基础架构中，以便更好地分析测试失败。

3.生产调试

在具有身份验证、速率限制和审计日志记录等企业功能的生产环境中使用。

4.性能分析

分析CPU和内存使用情况，以识别瓶颈并优化性能。

5.人工智能代理集成

通过MCP服务器为具有调试功能的AI代理供电（请参阅 @ai功能套件/mcp调试器服务器).

例子

示例1：调试失败的测试

import { DebugSession, ProcessSpawner } from '@ai-capabilities-suite/mcp-debugger-core';

async function debugTest() {
  const spawner = new ProcessSpawner();
  const { process, inspectorUrl } = await spawner.spawn({
    command: 'node',
    args: ['node_modules/.bin/jest', 'failing-test.spec.js', '--runInBand']
  });

  const session = new DebugSession(process, inspectorUrl);
  await session.start();

  // Set breakpoint in test
  await session.setBreakpoint({
    file: '/path/to/failing-test.spec.js',
    line: 25
  });

  await session.continue();

  // When paused, inspect test state
  const locals = await session.getLocalVariables();
  console.log('Test variables:', locals);

  await session.stop();
}

示例2：检测内存泄漏

import { DebugSession, MemoryProfiler } from '@ai-capabilities-suite/mcp-debugger-core';

async function detectLeaks() {
  // ... create session ...
  
  const profiler = new MemoryProfiler(session);
  const snapshots = [];

  // Take snapshots over time
  for (let i = 0; i  setTimeout(resolve, 1000));
    snapshots.push(await profiler.takeHeapSnapshot());
  }

  // Analyze for leaks
  const leaks = await profiler.detectMemoryLeaks({
    snapshots,
    threshold: 1024 * 1024 // 1MB
  });

  console.log('Memory leaks:', leaks);
}

示例3：配置文件性能

import { DebugSession, CPUProfiler, PerformanceTimeline } from '@ai-capabilities-suite/mcp-debugger-core';

async function profilePerformance() {
  // ... create session ...
  
  const cpuProfiler = new CPUProfiler(session);
  const timeline = new PerformanceTimeline();

  // Start profiling
  await cpuProfiler.start();
  timeline.startRecording();

  // Run code
  await session.continue();

  // Stop and analyze
  const cpuProfile = await cpuProfiler.stop();
  const events = timeline.stopRecording();

  const analysis = cpuProfiler.analyzeProfile(cpuProfile);
  console.log('CPU bottlenecks:', analysis.bottlenecks);
  console.log('Performance events:', events);
}

相关套餐

• @ai功能套件/mcp调试器服务器 -向AI代理公开调试工具的MCP服务器

需求

• Node.js>=18.0.0
• npm>=8.0.0

平台支持

• ✅ Linux（x64，arm64）
• ✅ macOS（x64，arm64）
• ✅ Windows（x64）

贡献

欢迎投稿！请参阅 主存储库 关于贡献指南。

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

支持

• GitHub问题: 人工智能能力套件/问题
• NPM包: @ai功能套件/mcp调试器核心
• 电子邮件:

更新日志

版本1.0.1

• 改进的README文档
• 增加了全面的API参考
• 添加使用示例

版本1.0.0

• 初始版本
• 集成Inspector协议的核心调试引擎
• 断点管理和执行控制
• 变量检查和调用堆栈导航
• CPU和内存分析
• 挂起检测
• 源地图支持
• 企业功能（身份验证、速率限制、审计日志）
• 测试框架集成

______________________________________________________________________

建造于 数字挑战