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.
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.
- 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
- 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
- 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
npm install @ai-capabilities-suite/mcp-debugger-coreimport { 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');
}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
});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[]>;
}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;
}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;
}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;
}CPU profiling and performance analysis.
class CPUProfiler {
constructor(session: DebugSession);
async start(): Promise<void>;
async stop(): Promise<CPUProfile>;
analyzeProfile(profile: CPUProfile): ProfileAnalysis;
}Memory profiling and leak detection.
class MemoryProfiler {
constructor(session: DebugSession);
async takeHeapSnapshot(): Promise<HeapSnapshot>;
async detectMemoryLeaks(options: LeakDetectionOptions): Promise<MemoryLeak[]>;
async getMemoryUsage(): Promise<MemoryUsage>;
}Authentication and authorization.
class AuthManager {
async authenticate(token: string): Promise<Session>;
async validateSession(sessionId: string): Promise<boolean>;
async revokeSession(sessionId: string): Promise<void>;
}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;
}Comprehensive audit logging.
class AuditLogger {
log(event: AuditEvent): void;
query(filter: AuditFilter): AuditEvent[];
export(format: 'json' | 'csv'): string;
}PII detection and masking.
class DataMasker {
mask(data: any): any;
addPattern(pattern: RegExp, replacement: string): void;
detectPII(text: string): PIIMatch[];
}Metrics collection and reporting.
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 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 the core library to build custom debugging tools, IDEs, or CLI debuggers.
Integrate debugging capabilities into your test infrastructure for better test failure analysis.
Use in production environments with enterprise features like auth, rate limiting, and audit logging.
Profile CPU and memory usage to identify bottlenecks and optimize performance.
Power AI agents with debugging capabilities through the MCP server (see @ai-capabilities-suite/mcp-debugger-server).
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();
}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);
}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-capabilities-suite/mcp-debugger-server - MCP server that exposes debugging tools to AI agents
- Node.js >= 18.0.0
- npm >= 8.0.0
- ✅ Linux (x64, arm64)
- ✅ macOS (x64, arm64)
- ✅ Windows (x64)
Contributions are welcome! Please see the main repository for contribution guidelines.
MIT License - See LICENSE file for details.
- GitHub Issues: ai-capabilities-suite/issues
- NPM Package: @ai-capabilities-suite/mcp-debugger-core
- Email: info@digitaldefiance.org
- Improved README documentation
- Added comprehensive API reference
- Added usage examples
- 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