Node.js/JavaScript debugging engine using Chrome DevTools Protocol. Provides Inspector Protocol integration, breakpoint management, variable inspection, execution control, profiling, hang detection, and source map support for TypeScript and transpiled cod
npm install @ai-capabilities-suite/mcp-debugger-coreNode.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
``bash`
npm install @ai-capabilities-suite/mcp-debugger-core
`typescript
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();
`
`typescript
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');
}
`
`typescript
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);
`
`typescript
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);
`
`typescript
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
});
`
#### DebugSession
Main debugging session manager.
`typescript`
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
}
#### InspectorClient
Chrome DevTools Protocol client.
`typescript`
class InspectorClient {
constructor(wsUrl: string);
async connect(): Promise
async disconnect(): Promise
async sendCommand(method: string, params?: any): Promise
on(event: string, handler: Function): void;
}
#### BreakpointManager
Manages breakpoints across sessions.
`typescript`
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.
`typescript
class HangDetector {
async detect(options: HangDetectionOptions): Promise
}
interface HangDetectionOptions {
command: string;
args?: string[];
cwd?: string;
timeout: number;
sampleInterval?: number;
}
`
#### CPUProfiler
CPU profiling and performance analysis.
`typescript`
class CPUProfiler {
constructor(session: DebugSession);
async start(): Promise
async stop(): Promise
analyzeProfile(profile: CPUProfile): ProfileAnalysis;
}
#### MemoryProfiler
Memory profiling and leak detection.
`typescript`
class MemoryProfiler {
constructor(session: DebugSession);
async takeHeapSnapshot(): Promise
async detectMemoryLeaks(options: LeakDetectionOptions): Promise
async getMemoryUsage(): Promise
}
#### AuthManager
Authentication and authorization.
`typescript`
class AuthManager {
async authenticate(token: string): Promise
async validateSession(sessionId: string): Promise
async revokeSession(sessionId: string): Promise
}
#### RateLimiter
Rate limiting for operations.
`typescript`
class RateLimiter {
constructor(options: RateLimitOptions);
async checkLimit(key: string): Promise
async consumeToken(key: string): Promise
getRemainingTokens(key: string): number;
}
#### AuditLogger
Comprehensive audit logging.
`typescript`
class AuditLogger {
log(event: AuditEvent): void;
query(filter: AuditFilter): AuditEvent[];
export(format: 'json' | 'csv'): string;
}
#### DataMasker
PII detection and masking.
`typescript`
class DataMasker {
mask(data: any): any;
addPattern(pattern: RegExp, replacement: string): void;
detectPII(text: string): PIIMatch[];
}
#### MetricsCollector
Metrics collection and reporting.
`typescript`
class MetricsCollector {
recordMetric(name: string, value: number, tags?: Tags): void;
getMetrics(filter?: MetricFilter): Metric[];
export(format: 'prometheus' | 'json'): string;
}
`typescript`
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)
}
`typescript`
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)
}
`typescript`
interface RateLimitOptions {
maxRequests: number; // Max requests per window
windowMs: number; // Time window in milliseconds
keyGenerator?: (req: any) => string; // Custom key generator
}
`bashRun all tests
npm test
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
$3
Use the core library to build custom debugging tools, IDEs, or CLI debuggers.
$3
Integrate debugging capabilities into your test infrastructure for better test failure analysis.
$3
Use in production environments with enterprise features like auth, rate limiting, and audit logging.
$3
Profile CPU and memory usage to identify bottlenecks and optimize performance.
$3
Power AI agents with debugging capabilities through the MCP server (see @ai-capabilities-suite/mcp-debugger-server).
Examples
$3
`typescript
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();
}
`$3
`typescript
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);
}
`$3
`typescript
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:
- 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