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

$3

- 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

$3

- 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

$3

- 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

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

Quick Start

$3

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

$3

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

$3

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

$3

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

$3

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

API Reference

$3

#### 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;
}
`

$3

#### 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;
}
`

Configuration

$3

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

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

$3

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

Testing

`bash


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

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

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:

Changelog

$3

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

$3

- 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