MCP ACS Debugger Core

Node.js/JavaScript debugging engine using Chrome DevTools Protocol. Provides comprehensive debugging capabilities including Inspector Protocol integration, breakpoint management, variable inspection, execution control, CPU/memory profiling, hang detection, and source map support. For multi-language debugging, use the VS Code extension which leverages Debug Adapter Protocol.

🔗 Repository

This package is now maintained in its own repository: https://github.com/Digital-Defiance/mcp-debugger-core

This repository is part of the AI Capabilitites Suite on GitHub.

Features

Core Debugging

• Node.js/JavaScript Support - Debug Node.js applications and JavaScript code
• TypeScript Support - Full TypeScript debugging with source map resolution
• Inspector Protocol Integration - Full Chrome DevTools Protocol (CDP) support
• Breakpoint Management - Set, remove, toggle, and list breakpoints with conditions
• Variable Inspection - Inspect local/global variables, evaluate expressions, watch variables
• Execution Control - Continue, step over/into/out, pause execution
• Call Stack Navigation - View and navigate through stack frames
• Source Map Support - Debug transpiled code with original source locations

Advanced Features

• Hang Detection - Detect infinite loops and hanging processes
• CPU Profiling - Profile CPU usage and identify bottlenecks
• Memory Profiling - Heap snapshots and memory leak detection
• Performance Timeline - Track performance events and metrics
• Test Framework Integration - Debug Jest, Mocha, and Vitest tests

Enterprise Features

• Authentication & Authorization - Token-based auth with session management
• Rate Limiting - Configurable rate limits per operation
• Audit Logging - Comprehensive audit trail with structured logging
• Data Masking - PII detection and masking for sensitive data
• Health Monitoring - Health checks and metrics collection
• Session Recording - Record and replay debugging sessions
• Circuit Breakers - Fault tolerance with automatic recovery
• Resource Limiting - Memory and CPU usage limits
• Prometheus Integration - Export metrics for monitoring

Installation

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

Quick Start

Basic Debugging Session

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();

Hang Detection

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 Profiling

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);

Memory Profiling

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);

Source Map Support

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 Reference

Core Classes

DebugSession

Main debugging session manager.

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

InspectorClient

Chrome DevTools Protocol client.

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

BreakpointManager

Manages breakpoints across sessions.

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

HangDetector

Detects hanging processes and infinite loops.

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

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

CPUProfiler

CPU profiling and performance analysis.

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

MemoryProfiler

Memory profiling and leak detection.

class MemoryProfiler {
  constructor(session: DebugSession);
  
  async takeHeapSnapshot(): Promise<HeapSnapshot>;
  async detectMemoryLeaks(options: LeakDetectionOptions): Promise<MemoryLeak[]>;
  async getMemoryUsage(): Promise<MemoryUsage>;
}

Enterprise Features

AuthManager

Authentication and authorization.

class AuthManager {
  async authenticate(token: string): Promise<Session>;
  async validateSession(sessionId: string): Promise<boolean>;
  async revokeSession(sessionId: string): Promise<void>;
}

RateLimiter

Rate limiting for operations.

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

AuditLogger

Comprehensive audit logging.

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

DataMasker

PII detection and masking.

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

MetricsCollector

Metrics collection and reporting.

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

Configuration

Debug Session Options

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)
}

Hang Detection Options

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)
}

Rate Limiting Options

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

Testing

# 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

Architecture

┌─────────────────────────────────────────┐
│         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)                   │
└─────────────────────────────────────────┘

Use Cases

1. Building Debugging Tools

Use the core library to build custom debugging tools, IDEs, or CLI debuggers.

2. Automated Testing

Integrate debugging capabilities into your test infrastructure for better test failure analysis.

3. Production Debugging

Use in production environments with enterprise features like auth, rate limiting, and audit logging.

4. Performance Analysis

Profile CPU and memory usage to identify bottlenecks and optimize performance.

5. AI Agent Integration

Power AI agents with debugging capabilities through the MCP server (see @ai-capabilities-suite/mcp-debugger-server).

Examples

Example 1: Debug a Failing Test

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();
}

Example 2: Detect Memory Leaks

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 < 5; i++) {
    await session.continue();
    await new Promise(resolve => 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);
}

Example 3: Profile Performance

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);
}

Related Packages

• @ai-capabilities-suite/mcp-debugger-server - MCP server that exposes debugging tools to AI agents

Requirements

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

Platform Support

• ✅ Linux (x64, arm64)
• ✅ macOS (x64, arm64)
• ✅ Windows (x64)

Contributing

Contributions are welcome! Please see the main repository for contribution guidelines.

License

MIT License - See LICENSE file for details.

Support

• GitHub Issues: ai-capabilities-suite/issues
• NPM Package: @ai-capabilities-suite/mcp-debugger-core
• Email: [email protected]

Changelog

Version 1.0.1

• Improved README documentation
• Added comprehensive API reference
• Added usage examples

Version 1.0.0

• Initial release
• Core debugging engine with Inspector Protocol integration
• Breakpoint management and execution control
• Variable inspection and call stack navigation
• CPU and memory profiling
• Hang detection
• Source map support
• Enterprise features (auth, rate limiting, audit logging)
• Test framework integration

Built by Digital Defiance