MCP ACS Debugger Server

🔗 Repository

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

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

An enterprise-grade Model Context Protocol (MCP) server that provides comprehensive debugging capabilities for Node.js and JavaScript applications via Chrome DevTools Protocol. This server enables AI agents (Kiro, Amazon Q, GitHub Copilot) to interactively debug Node.js code with 25+ specialized tools, offering everything from basic breakpoint management to advanced CPU/memory profiling and hang detection. For multi-language debugging (Python, Java, Go, etc.), use the VS Code extension which leverages Debug Adapter Protocol.

🎯 Key Features

Core Debugging Capabilities

Node.js/JavaScript Support: Debug Node.js applications and JavaScript code via Chrome DevTools Protocol
TypeScript Support: Full TypeScript debugging with source map resolution
Breakpoint Management: Set, remove, toggle, and list breakpoints with optional conditions, hit counts, and logpoints
Execution Control: Continue, step over, step into, step out, and pause execution with precise control
Variable Inspection: Inspect local and global variables, evaluate expressions, and watch variables with change detection
Call Stack Navigation: View and navigate through call stack frames with context switching

Advanced Features

Hang Detection: Detect infinite loops and hanging processes with configurable timeouts and sampling intervals
Source Map Support: Full source map support for debugging TypeScript and transpiled JavaScript with original source locations
Performance Profiling: CPU profiling, memory profiling, heap snapshots, and performance timeline tracking
Test Framework Integration: Debug Jest, Mocha, and Vitest tests
Session Management: Support for multiple concurrent debug sessions with complete isolation
Chrome DevTools Protocol: Direct integration with Node.js Inspector Protocol for low-level debugging

Enterprise Features

Observability: Structured logging, metrics collection, health check endpoints, and Prometheus metrics export
Security: Authentication, rate limiting, sensitive data masking, audit logging, and session timeout enforcement
Production Ready: Circuit breakers, retry logic with exponential backoff, graceful shutdown, and resource limits
Monitoring: Performance metrics, session recording, and comprehensive error tracking

📦 Installation

System Requirements

Node.js: >= 18.0.0
NPM: >= 8.0.0
Operating Systems: macOS, Linux, Windows
CPU Architectures: x64, arm64

Quick Start (NPM - Recommended)

# Install globally
npm install -g @ai-capabilities-suite/mcp-debugger-server

# Verify installation
ts-mcp-server --version

Alternative Installation Methods

Using NPX (No Installation Required)

# Run directly without installing
npx @ai-capabilities-suite/mcp-debugger-server

Using Docker

# Pull and run the Docker image
docker pull digitaldefiance/mcp-debugger-server:latest
docker run -d --name mcp-debugger digitaldefiance/mcp-debugger-server:latest

# Or use docker-compose (see DOCKER-DEPLOYMENT.md)
docker-compose up -d

From Source

# Clone the repository
git clone https://github.com/digital-defiance/ai-capabilities-suite.git
cd ai-capabilities-suite

# Install dependencies
npm install

# Build the packages
npx nx build @ai-capabilities-suite/mcp-debugger-core
npx nx build @ai-capabilities-suite/mcp-debugger-server

# Run the server
node packages/mcp-debugger-server/dist/src/cli.js

⚙️ Configuration

Kiro Configuration

Add to .kiro/settings/mcp.json:

{
  "mcpServers": {
    "debugger": {
      "command": "ts-mcp-server",
      "args": [],
      "env": {
        "NODE_ENV": "production"
      },
      "disabled": false,
      "autoApprove": [
        "debugger_start",
        "debugger_set_breakpoint",
        "debugger_continue",
        "debugger_step_over",
        "debugger_inspect",
        "debugger_get_stack"
      ]
    }
  }
}

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "debugger": {
      "command": "ts-mcp-server",
      "args": []
    }
  }
}

VS Code Configuration

Add to .vscode/settings.json:

{
  "mcp.servers": {
    "debugger": {
      "command": "ts-mcp-server",
      "args": [],
      "enabled": true
    }
  }
}

Environment Variables

Optional environment variables for advanced configuration:

# Enable debug logging
DEBUG=mcp:*

# Set custom timeout (milliseconds)
MCP_DEBUGGER_TIMEOUT=60000

# Enable authentication
MCP_DEBUGGER_AUTH_TOKEN=your-secret-token

# Enable rate limiting
MCP_DEBUGGER_RATE_LIMIT=100

# Enable audit logging
MCP_DEBUGGER_AUDIT_LOG=true

🛠️ Available Tools

The MCP ACS Debugger Server provides 25 specialized tools organized into 8 categories:

Session Management

1. `debugger_start`

Start a new debug session with a Node.js process.

Parameters:

command (string, required): The command to execute (e.g., "node", "npm")
args (string[], optional): Command arguments (e.g., ["test.js"])
cwd (string, optional): Working directory for the process
timeout (number, optional): Timeout in milliseconds (default: 30000)

Example:

{
  "command": "node",
  "args": ["app.js"],
  "cwd": "/path/to/project",
  "timeout": 30000
}

Response:

{
  "status": "success",
  "sessionId": "session-123",
  "state": "paused",
  "pid": 12345
}

2. `debugger_stop_session`

Stop a debug session and cleanup all resources.

Parameters:

sessionId (string, required): The debug session ID

Example:

{
  "sessionId": "session-123"
}

Breakpoint Management

3. `debugger_set_breakpoint`

Set a breakpoint at a specific file and line number.

Parameters:

sessionId (string, required): The debug session ID
file (string, required): The file path (absolute or relative)
line (number, required): The line number (1-indexed)
condition (string, optional): Optional condition expression (e.g., "x > 10")

Example:

{
  "sessionId": "session-123",
  "file": "/path/to/file.js",
  "line": 42,
  "condition": "count > 5"
}

4. `debugger_remove_breakpoint`

Remove a breakpoint from the session.

Parameters:

sessionId (string, required): The debug session ID
breakpointId (string, required): The breakpoint ID to remove

5. `debugger_toggle_breakpoint`

Toggle a breakpoint between enabled and disabled states.

Parameters:

sessionId (string, required): The debug session ID
breakpointId (string, required): The breakpoint ID to toggle

6. `debugger_list_breakpoints`

Get all breakpoints for a debug session.

Parameters:

sessionId (string, required): The debug session ID

Response:

{
  "status": "success",
  "breakpoints": [
    {
      "id": "bp-1",
      "file": "/path/to/file.js",
      "line": 42,
      "condition": "x > 10",
      "enabled": true,
      "verified": true
    }
  ]
}

Execution Control

7. `debugger_continue`

Resume execution until the next breakpoint or program termination.

Parameters:

sessionId (string, required): The debug session ID

8. `debugger_step_over`

Execute the current line and pause at the next line in the same scope.

Parameters:

sessionId (string, required): The debug session ID

9. `debugger_step_into`

Execute the current line and pause at the first line inside any called function.

Parameters:

sessionId (string, required): The debug session ID

10. `debugger_step_out`

Execute until the current function returns and pause at the calling location.

Parameters:

sessionId (string, required): The debug session ID

11. `debugger_pause`

Pause a running debug session.

Parameters:

sessionId (string, required): The debug session ID

Variable Inspection

12. `debugger_inspect`

Evaluate a JavaScript expression in the current execution context.

Parameters:

sessionId (string, required): The debug session ID
expression (string, required): The JavaScript expression to evaluate

Example:

{
  "sessionId": "session-123",
  "expression": "user.name + ' ' + user.age"
}

13. `debugger_get_local_variables`

Get all local variables in the current scope.

Parameters:

sessionId (string, required): The debug session ID

14. `debugger_get_global_variables`

Get global variables accessible from the current scope.

Parameters:

sessionId (string, required): The debug session ID

15. `debugger_inspect_object`

Inspect an object's properties with nested resolution.

Parameters:

sessionId (string, required): The debug session ID
objectId (string, required): The object ID from a previous inspection
maxDepth (number, optional): Maximum depth to traverse (default: 2)

Variable Watching

16. `debugger_add_watch`

Add an expression to the watch list.

Parameters:

sessionId (string, required): The debug session ID
expression (string, required): The expression to watch

17. `debugger_remove_watch`

Remove an expression from the watch list.

Parameters:

sessionId (string, required): The debug session ID
watchId (string, required): The watch ID (expression) to remove

18. `debugger_get_watches`

Get all watched expressions with their current values.

Parameters:

sessionId (string, required): The debug session ID

Call Stack

19. `debugger_get_stack`

Get the current call stack with function names and file locations.

Parameters:

sessionId (string, required): The debug session ID

Response:

{
  "status": "success",
  "stack": [
    {
      "function": "myFunction",
      "file": "/absolute/path/to/file.js",
      "line": 42,
      "column": 10
    }
  ]
}

20. `debugger_switch_stack_frame`

Switch the execution context to a specific stack frame.

Parameters:

sessionId (string, required): The debug session ID
frameIndex (number, required): The frame index (0 = top frame)

Hang Detection

21. `debugger_detect_hang`

Detect if a process hangs or enters an infinite loop.

Parameters:

command (string, required): The command to execute
args (string[], optional): Command arguments
cwd (string, optional): Working directory
timeout (number, required): Timeout in milliseconds
sampleInterval (number, optional): Sample interval for loop detection (default: 100ms)

Example:

{
  "command": "node",
  "args": ["script.js"],
  "timeout": 5000,
  "sampleInterval": 100
}

Response (hung):

{
  "status": "success",
  "hung": true,
  "location": "/path/to/file.js:42",
  "stack": [...],
  "message": "Process hung at /path/to/file.js:42",
  "duration": 5000
}

Response (completed):

{
  "status": "success",
  "hung": false,
  "completed": true,
  "exitCode": 0,
  "duration": 1234
}

🚀 Quick Start Guide

1. Install the Server

npm install -g @ai-capabilities-suite/mcp-debugger-server

2. Configure Your AI Agent

Add to your MCP configuration file (e.g., .kiro/settings/mcp.json):

{
  "mcpServers": {
    "debugger": {
      "command": "ts-mcp-server",
      "args": []
    }
  }
}

3. Start Debugging

Ask your AI agent to debug your code:

"Debug my Node.js script app.js and set a breakpoint at line 42"

The AI agent will use the MCP ACS Debugger Server to:

Start a debug session
Set the breakpoint
Run your code
Pause at the breakpoint
Inspect variables and help you fix issues

📚 Common Debugging Scenarios

Scenario 1: Debug a Simple Script

// 1. Start a debug session
{
  "tool": "debugger_start",
  "args": {
    "command": "node",
    "args": ["my-script.js"]
  }
}
// Returns: { sessionId: "session-123", state: "paused" }

// 2. Set a breakpoint
{
  "tool": "debugger_set_breakpoint",
  "args": {
    "sessionId": "session-123",
    "file": "/path/to/my-script.js",
    "line": 10
  }
}

// 3. Continue execution
{
  "tool": "debugger_continue",
  "args": {
    "sessionId": "session-123"
  }
}

// 4. When paused at breakpoint, inspect variables
{
  "tool": "debugger_get_local_variables",
  "args": {
    "sessionId": "session-123"
  }
}

// 5. Step through code
{
  "tool": "debugger_step_over",
  "args": {
    "sessionId": "session-123"
  }
}

// 6. Stop the session
{
  "tool": "debugger_stop_session",
  "args": {
    "sessionId": "session-123"
  }
}

Scenario 2: Debug a Failing Test

// 1. Start debugging a Jest test
{
  "tool": "debugger_start",
  "args": {
    "command": "node",
    "args": ["node_modules/.bin/jest", "my-test.spec.js", "--runInBand"],
    "timeout": 60000
  }
}

// 2. Set breakpoint in test file
{
  "tool": "debugger_set_breakpoint",
  "args": {
    "sessionId": "session-123",
    "file": "/path/to/my-test.spec.js",
    "line": 25
  }
}

// 3. Continue to breakpoint
{
  "tool": "debugger_continue",
  "args": {
    "sessionId": "session-123"
  }
}

// 4. Inspect test variables
{
  "tool": "debugger_inspect",
  "args": {
    "sessionId": "session-123",
    "expression": "expect.getState()"
  }
}

Scenario 3: Detect an Infinite Loop

// Use hang detection to identify infinite loops
{
  "tool": "debugger_detect_hang",
  "args": {
    "command": "node",
    "args": ["potentially-hanging-script.js"],
    "timeout": 5000,
    "sampleInterval": 100
  }
}
// Returns hang location and stack trace if hung

Scenario 4: Debug TypeScript Code

// TypeScript debugging works automatically with source maps
// 1. Ensure your tsconfig.json has "sourceMap": true

// 2. Start debugging the compiled JavaScript
{
  "tool": "debugger_start",
  "args": {
    "command": "node",
    "args": ["--enable-source-maps", "dist/app.js"]
  }
}

// 3. Set breakpoints using TypeScript file paths
{
  "tool": "debugger_set_breakpoint",
  "args": {
    "sessionId": "session-123",
    "file": "/path/to/src/app.ts",  // TypeScript source file
    "line": 42
  }
}
// The debugger automatically maps to the compiled JavaScript location

Scenario 5: Watch Variable Changes

// 1. Start session and set breakpoint
// ... (as in Scenario 1)

// 2. Add watched variables
{
  "tool": "debugger_add_watch",
  "args": {
    "sessionId": "session-123",
    "expression": "user.balance"
  }
}

// 3. Continue execution
{
  "tool": "debugger_continue",
  "args": {
    "sessionId": "session-123"
  }
}

// 4. Check watched variables at each pause
{
  "tool": "debugger_get_watches",
  "args": {
    "sessionId": "session-123"
  }
}
// Returns: { watches: [{ watchId: "user.balance", value: 100, changed: true, oldValue: 50, newValue: 100 }] }

🎬 Demo & Screenshots

Debugging in Action

Setting breakpoints and inspecting variables in a Node.js application

Detecting and diagnosing an infinite loop

Debugging TypeScript code with source map support

Note: Replace placeholder images with actual screenshots or animated GIFs demonstrating the debugger in action. See images/README.md for guidelines.

🔧 Troubleshooting

Common Issues and Solutions

Issue: "Session not found"

Symptoms: Error when trying to use a session ID Cause: The session ID is invalid or the session has been terminated Solution:

# Start a new debug session
{
  "tool": "debugger_start",
  "arguments": {
    "command": "node",
    "args": ["your-script.js"]
  }
}

Issue: "Process must be paused"

Symptoms: Cannot inspect variables or evaluate expressions Cause: Trying to inspect variables when the process is running Solution:

Set a breakpoint and continue to it, OR
Use debugger_pause to pause execution immediately

Issue: Breakpoint not hitting

Symptoms: Execution doesn't stop at the breakpoint Cause: Invalid breakpoint location or code path not executed Solution:

Verify the file path is correct (use absolute paths):

"file": "/absolute/path/to/your/file.js"  // ✅ Good
"file": "file.js"                          // ❌ Avoid

Check that the line number has executable code (not comments or blank lines)

Verify the breakpoint is set and verified:

{
  "tool": "debugger_list_breakpoints",
  "arguments": { "sessionId": "your-session-id" }
}

Issue: Hang detection false positives

Symptoms: Hang detection reports a hang when the script is running normally Cause: The timeout is too short for the script's normal execution time Solution:

{
  "tool": "debugger_detect_hang",
  "arguments": {
    "command": "node",
    "args": ["script.js"],
    "timeout": 60000,  // Increase timeout to 60 seconds
    "sampleInterval": 200  // Increase sample interval
  }
}

Issue: TypeScript breakpoints not working

Symptoms: Breakpoints in .ts files don't pause execution Cause: Source maps are not enabled or not found Solution:

Ensure "sourceMap": true in tsconfig.json:

{
  "compilerOptions": {
    "sourceMap": true
  }
}

Use --enable-source-maps flag when starting Node.js:
```
node --enable-source-maps dist/app.js
```
Verify .map files exist alongside compiled JavaScript:
```
ls dist/*.js.map
```

Issue: "Cannot find module" errors

Symptoms: Module not found errors when starting the server Cause: The packages haven't been built or dependencies not installed Solution:

# Install dependencies
npm install

# Build the packages
npx nx build @ai-capabilities-suite/mcp-debugger-core
npx nx build @ai-capabilities-suite/mcp-debugger-server

# Or if installed globally, reinstall
npm install -g @ai-capabilities-suite/mcp-debugger-server

Issue: WebSocket connection errors

Symptoms: "Failed to connect to inspector" or WebSocket errors Cause: The Inspector Protocol failed to start Solution:

Ensure Node.js version is 18 or higher:
```
node --version  # Should be >= 18.0.0
```
Check that no other debugger is attached to the process

Verify the process starts successfully:

node --inspect-brk your-script.js
# Should output: Debugger listening on ws://...

Issue: High memory usage

Symptoms: Server consumes excessive memory Cause: Too many concurrent sessions or large heap snapshots Solution:

Limit concurrent sessions

Stop unused sessions:

{
  "tool": "debugger_stop_session",
  "arguments": { "sessionId": "session-id" }
}

Configure resource limits (see Environment Variables section)

Issue: Slow performance

Symptoms: Debugging operations are slow Cause: Large objects, deep inspection, or many breakpoints Solution:

Limit object inspection depth:

{
  "tool": "debugger_inspect_object",
  "arguments": {
    "sessionId": "session-id",
    "objectId": "obj-id",
    "maxDepth": 2  // Limit depth
  }
}

Use conditional breakpoints to reduce pauses
Remove unnecessary breakpoints

Getting Help

If you encounter issues not covered here:

Check the logs: Enable debug logging with DEBUG=mcp:*
Search existing issues: GitHub Issues
Create a new issue: Include:
- Node.js version (node --version)
- Server version (ts-mcp-server --version)
- Error messages and stack traces
- Steps to reproduce
Email support: info@digitaldefiance.org

💡 Use Cases

1. AI-Assisted Debugging

Enable AI agents to autonomously debug your code:

Kiro: "Debug my failing test and tell me why it's failing"
Amazon Q: "Find the infinite loop in my script"
GitHub Copilot: "Set a breakpoint and inspect the user object"

2. Automated Testing & CI/CD

Integrate debugging into your CI/CD pipeline:

Debug failing tests automatically
Detect performance regressions
Identify memory leaks before deployment

3. Production Issue Investigation

Debug production-like environments safely:

Reproduce production issues locally
Inspect state without modifying code
Analyze performance bottlenecks

4. Learning & Education

Help developers learn debugging techniques:

Step through code execution
Understand call stacks and scope
Visualize variable changes

5. Performance Optimization

Identify and fix performance issues:

Profile CPU usage
Analyze memory allocation
Detect memory leaks
Track performance metrics

📊 Feature Comparison

Feature	MCP ACS Debugger Server	VS Code Debugger	Chrome DevTools	Node Inspector
AI Agent Integration	✅ Full MCP Support	❌ No	❌ No	❌ No
Breakpoints	✅ Advanced (conditional, hit count, logpoints)	✅ Yes	✅ Yes	✅ Basic
Variable Inspection	✅ Deep inspection with type info	✅ Yes	✅ Yes	✅ Basic
TypeScript Support	✅ Full source map support	✅ Yes	✅ Yes	⚠️ Limited
Hang Detection	✅ Automated with sampling	❌ No	❌ No	❌ No
CPU Profiling	✅ Yes	✅ Yes	✅ Yes	❌ No
Memory Profiling	✅ Yes with leak detection	✅ Yes	✅ Yes	❌ No
Multiple Sessions	✅ Isolated concurrent sessions	⚠️ Limited	⚠️ Limited	❌ No
Test Framework Integration	✅ Jest, Mocha, Vitest	✅ Yes	❌ No	❌ No
Remote Debugging	✅ Via MCP protocol	✅ Yes	✅ Yes	✅ Yes
Audit Logging	✅ Enterprise-grade	❌ No	❌ No	❌ No
Rate Limiting	✅ Yes	❌ No	❌ No	❌ No
Metrics Export	✅ Prometheus	❌ No	❌ No	❌ No

📋 Error Codes

The server returns structured error responses with the following codes:

Error Code	Description	Common Causes	Solution
`SESSION_NOT_FOUND`	Session ID doesn't exist	Invalid ID or terminated session	Start a new session
`SESSION_START_FAILED`	Failed to start debug session	Invalid command or permissions	Check command and file paths
`BREAKPOINT_SET_FAILED`	Failed to set breakpoint	Invalid file path or line number	Use absolute paths and valid lines
`BREAKPOINT_NOT_FOUND`	Breakpoint doesn't exist	Invalid breakpoint ID	List breakpoints to verify IDs
`CONTINUE_FAILED`	Failed to resume execution	Process crashed or terminated	Check process status
`STEP_OVER_FAILED`	Failed to step over	Not paused or invalid state	Ensure process is paused
`STEP_INTO_FAILED`	Failed to step into	Not paused or no function call	Ensure at function call
`STEP_OUT_FAILED`	Failed to step out	Not in a function	Check call stack
`PAUSE_FAILED`	Failed to pause execution	Process not running	Ensure process is running
`INSPECT_FAILED`	Failed to evaluate expression	Invalid expression or not paused	Check syntax and pause state
`GET_STACK_FAILED`	Failed to get call stack	Not paused	Pause execution first
`NOT_PAUSED`	Operation requires paused state	Process is running	Pause or set breakpoint
`HANG_DETECTION_FAILED`	Failed to detect hang	Invalid parameters	Check timeout and interval
`WATCH_NOT_FOUND`	Watch expression doesn't exist	Invalid watch ID	List watches to verify IDs
`RATE_LIMIT_EXCEEDED`	Too many requests	Exceeded rate limit	Wait and retry
`AUTH_FAILED`	Authentication failed	Invalid token	Check authentication token

Testing

Run Unit Tests

npx nx test @ai-capabilities-suite/mcp-core
npx nx test @ai-capabilities-suite/mcp-server

Run E2E Tests

npx nx test @ai-capabilities-suite/mcp-server --testPathPattern=e2e --testTimeout=60000

Manual Testing

node packages/mcp-server/test-mcp-manual.js

See TESTING.md for comprehensive testing documentation.

🏗️ Architecture

Technology Stack

The MCP ACS Debugger Server is built on enterprise-grade technologies:

MCP SDK: Model Context Protocol implementation for AI agent communication
Chrome DevTools Protocol (CDP): Node.js Inspector Protocol for low-level debugging
WebSocket: Real-time bidirectional communication with the Node.js Inspector
TypeScript: Type-safe implementation with full type definitions
Zod: Runtime type validation for tool parameters
Prometheus: Metrics collection and export

Component Architecture

┌─────────────────────────────────────────────────────────────┐
│                        AI Agent Layer                        │
│  (Kiro, Amazon Q, GitHub Copilot, Claude Desktop)          │
└────────────────────────┬────────────────────────────────────┘
                         │ MCP Protocol (stdio/JSON-RPC)
                         │
┌────────────────────────▼────────────────────────────────────┐
│                   MCP ACS Debugger Server                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Session    │  │  Breakpoint  │  │   Variable   │     │
│  │   Manager    │  │   Manager    │  │  Inspector   │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │     Hang     │  │     CPU      │  │    Memory    │     │
│  │   Detector   │  │   Profiler   │  │   Profiler   │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Source     │  │    Audit     │  │    Metrics   │     │
│  │  Map Manager │  │    Logger    │  │  Collector   │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└────────────────────────┬────────────────────────────────────┘
                         │ Inspector Protocol (CDP/WebSocket)
                         │
┌────────────────────────▼────────────────────────────────────┐
│                   Node.js Inspector                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Debugger   │  │   Runtime    │  │   Profiler   │     │
│  │    Domain    │  │    Domain    │  │    Domain    │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────┐
│                   Target Node.js Process                     │
│              (Application, Test Runner, etc.)                │
└─────────────────────────────────────────────────────────────┘

Data Flow

AI Agent Request: Agent sends MCP tool request via stdio
Tool Validation: Server validates parameters using Zod schemas
Session Management: Server creates or retrieves debug session
CDP Communication: Server sends CDP commands via WebSocket
Inspector Response: Node.js Inspector returns debugging data
Data Processing: Server processes and formats response
MCP Response: Server returns structured JSON response to agent

Security Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Security Layer                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │     Auth     │  │     Rate     │  │     Data     │     │
│  │   Manager    │  │   Limiter    │  │    Masker    │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Session    │  │    Audit     │  │   Circuit    │     │
│  │   Timeout    │  │    Logger    │  │   Breaker    │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└─────────────────────────────────────────────────────────────┘

⚡ Performance

Benchmarks

Performance metrics on a MacBook Pro (M1, 16GB RAM):

Operation	Average Latency	Throughput	Notes
Session Start	150ms	6.6/sec	Includes process spawn
Set Breakpoint	5ms	200/sec	Single breakpoint
Continue Execution	2ms	500/sec	Resume to next breakpoint
Step Over	8ms	125/sec	Single step operation
Variable Inspection	12ms	83/sec	Local variables only
Expression Evaluation	15ms	66/sec	Simple expressions
Call Stack Retrieval	10ms	100/sec	Full stack trace
Hang Detection	5000ms	0.2/sec	With 5s timeout
CPU Profile Start	3ms	333/sec	Start profiling
CPU Profile Stop	50ms	20/sec	Includes analysis
Heap Snapshot	200ms	5/sec	10MB heap

Resource Usage

Typical resource consumption:

Memory: 50-100MB base + 10-20MB per active session
CPU: < 1% idle, 5-10% during active debugging
Network: Minimal (local WebSocket only)
Disk: < 1MB for logs and metrics

Scalability

Concurrent Sessions: Tested with 100+ concurrent sessions
Breakpoints: Supports 1000+ breakpoints per session
Session Duration: Tested for 24+ hour sessions
Memory Stability: No memory leaks detected in 48-hour soak tests

Contributing

Contributions are welcome! Please follow these guidelines:

Fork the repository
Create a feature branch
Make your changes with tests
Run the test suite
Submit a pull request

Publishing to NPM

If you're a maintainer publishing updates:

Quick Setup: NPM-SETUP-GUIDE.md - 5-minute first-time setup
Full Guide: PUBLISHING.md - Comprehensive publishing documentation
Automated: GitHub Actions workflow handles publishing on release

Documentation

README.md - This file, main documentation
API.md - Detailed API documentation
TOOL-REFERENCE.md - Complete tool reference
AI-AGENT-INTEGRATION.md - AI agent integration guide
VSCODE-INTEGRATION.md - VS Code integration guide
TESTING.md - Testing documentation
PUBLISHING.md - NPM publishing guide
NPM-SETUP-GUIDE.md - Quick setup for publishers

🙏 Acknowledgments

This project builds upon excellent open-source technologies:

Model Context Protocol - Protocol specification and SDK
Chrome DevTools Protocol - Debugging protocol
Node.js Inspector - Node.js debugging API
TypeScript - Type-safe JavaScript
Zod - Runtime type validation

Special thanks to:

The MCP community for feedback and contributions
All contributors who have helped improve this project
Users who report issues and suggest improvements

📜 License

MIT License - See LICENSE file for details

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

🔗 Links

Homepage: https://digitaldefiance.org
GitHub: https://github.com/digital-defiance/ai-capabilities-suite
NPM: https://www.npmjs.com/package/@ai-capabilities-suite/mcp-debugger-server
Docker Hub: https://hub.docker.com/r/digitaldefiance/mcp-debugger-server
Documentation: https://github.com/digital-defiance/ai-capabilities-suite/tree/main/packages/mcp-debugger-server
Issues: https://github.com/digital-defiance/ai-capabilities-suite/issues
Discussions: https://github.com/digital-defiance/ai-capabilities-suite/discussions

Made with ❤️ by Digital Defiance

⭐ Star us on GitHub | 📦 View on NPM | 🐳 View on Docker Hub

❓ Frequently Asked Questions (FAQ)

General Questions

Q: What is the Model Context Protocol (MCP)? A: MCP is a protocol that enables AI agents to interact with external tools and services. The MCP ACS Debugger Server implements MCP to provide debugging capabilities to AI agents.

Q: Which AI agents are supported? A: The server works with any MCP-compatible AI agent, including:

Kiro
Amazon Q
GitHub Copilot
Claude Desktop
Custom MCP clients

Q: Can I use this for production debugging? A: Yes! The server includes enterprise features like authentication, rate limiting, audit logging, and circuit breakers specifically for production use. However, always test in a staging environment first.

Q: Is this free to use? A: Yes, the MCP ACS Debugger Server is open source under the MIT license and free for both personal and commercial use.

Technical Questions

Q: What Node.js versions are supported? A: Node.js >= 18.0.0 is required. We recommend using the latest LTS version.

Q: Does this work with TypeScript? A: Yes! Full TypeScript support with source maps. Set breakpoints in .ts files and inspect variables with their original TypeScript names.

Q: Can I debug remote processes? A: The server connects to local Node.js processes via the Inspector Protocol. For remote debugging, use SSH tunneling or deploy the server on the remote machine.

Q: How many concurrent debug sessions can I run? A: The server supports 100+ concurrent sessions. Each session is isolated and doesn't interfere with others.

Q: Does this work with Docker containers? A: Yes! We provide official Docker images. See DOCKER-DEPLOYMENT.md for details.

Debugging Questions

Q: Why isn't my breakpoint hitting? A: Common causes:

File path is relative instead of absolute
Line number doesn't have executable code
Code path isn't executed
Source maps are missing (for TypeScript)

Q: How do I debug a specific test? A: Start a debug session with your test runner:

{
  "tool": "debugger_start",
  "arguments": {
    "command": "node",
    "args": ["node_modules/.bin/jest", "my-test.spec.js", "--runInBand"]
  }
}

Q: Can I debug asynchronous code? A: Yes! The debugger fully supports async/await, Promises, and callbacks. Set breakpoints in async functions and step through them normally.

Q: How do I detect memory leaks? A: Use the memory profiling tools:

Take a heap snapshot at the start
Run your code
Take another heap snapshot
Compare the snapshots to identify growing objects

Performance Questions

Q: Will debugging slow down my application? A: Yes, debugging adds overhead. Expect 2-5x slowdown when actively debugging. Use conditional breakpoints and disable unnecessary breakpoints to minimize impact.

Q: How much memory does the server use? A: Base memory usage is 50-100MB, plus 10-20MB per active debug session.

Q: Can I use this in CI/CD pipelines? A: Yes! The server is designed for automation. Use hang detection and test debugging in your CI/CD pipeline to catch issues early.

Security Questions

Q: Is it safe to use in production? A: The server includes enterprise security features (authentication, rate limiting, audit logging), but debugging in production should be done carefully and only when necessary.

Q: How is sensitive data protected? A: The server includes automatic PII masking for common patterns (emails, SSNs, credit cards). Configure additional masking rules as needed.

Q: Can I restrict which operations are allowed? A: Yes! Use authentication and configure allowed operations per user/token. See the Security section in the documentation.

Integration Questions

Q: How do I integrate with VS Code? A: See VSCODE-INTEGRATION.md for detailed integration instructions.

Q: Can I use this with GitHub Copilot? A: Yes! GitHub Copilot can use MCP servers. Configure the server in your Copilot settings.

Q: Does this work with Mocha/Jest/Vitest? A: Yes! The server has built-in support for all major test frameworks. Just start a debug session with your test runner command.

💬 Support & Community

Getting Help

📖 Documentation: Full documentation
🐛 Bug Reports: GitHub Issues
💡 Feature Requests: GitHub Discussions
📧 Email Support: info@digitaldefiance.org
💬 Community Chat: Join our Discord (coming soon)

Resources

NPM Package: @ai-capabilities-suite/mcp-debugger-server
Docker Hub: digitaldefiance/mcp-debugger-server
GitHub Repository: ai-capabilities-suite
API Documentation: API.md
Tool Reference: TOOL-REFERENCE.md

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Sponsorship

Support the project:

GitHub Sponsors: Sponsor Digital Defiance
Open Collective: Support the project (coming soon)

📝 Changelog

Version 1.0.4 (Current)

Release Date: December 2025

New Features:

Enhanced documentation with comprehensive examples
Improved error messages and troubleshooting guides
Added performance benchmarks and metrics
Enhanced security features documentation

Bug Fixes:

Fixed WebSocket connection stability issues
Improved source map resolution for edge cases
Fixed memory leak in long-running sessions

Performance:

Reduced session startup time by 20%
Optimized variable inspection for large objects
Improved CPU profiling accuracy

Version 1.0.2

Release Date: November 2024

New Features:

Added Docker support with official images
Implemented Prometheus metrics export
Added health check endpoints
Enhanced audit logging with structured format

Improvements:

Better error handling for CDP protocol errors
Improved TypeScript source map support
Enhanced session isolation

Version 1.0.1

Release Date: November 2024

New Features:

Added CPU profiling support
Added memory profiling and heap snapshots
Implemented performance timeline tracking
Added advanced breakpoint types (logpoints, hit counts)

Improvements:

Enhanced hang detection algorithm
Improved variable inspection performance
Better handling of async code

Version 1.0.0

Release Date: October 2024

Initial Release:

25 comprehensive debugging tools
Full TypeScript support with source maps
Hang detection with configurable sampling
Multiple concurrent sessions with isolation
Test framework integration (Jest, Mocha, Vitest)
Variable watching with change detection
Call stack navigation
Conditional breakpoints
Object inspection with nested resolution
Enterprise security features
Observability and monitoring

🗺️ Roadmap

Version 1.1.0 (Planned - Q1 2025)

Time-travel debugging (record and replay)
Smart breakpoint suggestions using AI
Enhanced VS Code extension
WebAssembly debugging support
Distributed tracing integration

Version 1.2.0 (Planned - Q2 2025)

Browser debugging support (Chrome, Firefox)
Mobile debugging (React Native)
Collaborative debugging sessions
Advanced visualization tools
Plugin system for custom tools

Version 2.0.0 (Planned - Q3 2025)

Multi-language support (Python, Go, Rust)
Cloud-native debugging
Kubernetes integration
Advanced AI-powered debugging assistance
Real-time collaboration features

Want to influence the roadmap? Share your ideas

MCP ACS Debugger Server

🔗 Repository

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

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

🎯 Key Features

Core Debugging Capabilities

Node.js/JavaScript Support: Debug Node.js applications and JavaScript code via Chrome DevTools Protocol
TypeScript Support: Full TypeScript debugging with source map resolution
Breakpoint Management: Set, remove, toggle, and list breakpoints with optional conditions, hit counts, and logpoints
Execution Control: Continue, step over, step into, step out, and pause execution with precise control
Variable Inspection: Inspect local and global variables, evaluate expressions, and watch variables with change detection
Call Stack Navigation: View and navigate through call stack frames with context switching

Advanced Features

Hang Detection: Detect infinite loops and hanging processes with configurable timeouts and sampling intervals
Source Map Support: Full source map support for debugging TypeScript and transpiled JavaScript with original source locations
Performance Profiling: CPU profiling, memory profiling, heap snapshots, and performance timeline tracking
Test Framework Integration: Debug Jest, Mocha, and Vitest tests
Session Management: Support for multiple concurrent debug sessions with complete isolation
Chrome DevTools Protocol: Direct integration with Node.js Inspector Protocol for low-level debugging

Enterprise Features

Observability: Structured logging, metrics collection, health check endpoints, and Prometheus metrics export
Security: Authentication, rate limiting, sensitive data masking, audit logging, and session timeout enforcement
Production Ready: Circuit breakers, retry logic with exponential backoff, graceful shutdown, and resource limits
Monitoring: Performance metrics, session recording, and comprehensive error tracking

📦 Installation

System Requirements

Node.js: >= 18.0.0
NPM: >= 8.0.0
Operating Systems: macOS, Linux, Windows
CPU Architectures: x64, arm64

Quick Start (NPM - Recommended)

# Install globally
npm install -g @ai-capabilities-suite/mcp-debugger-server

# Verify installation
ts-mcp-server --version

Alternative Installation Methods

Using NPX (No Installation Required)

# Run directly without installing
npx @ai-capabilities-suite/mcp-debugger-server

Using Docker

# Pull and run the Docker image
docker pull digitaldefiance/mcp-debugger-server:latest
docker run -d --name mcp-debugger digitaldefiance/mcp-debugger-server:latest

# Or use docker-compose (see DOCKER-DEPLOYMENT.md)
docker-compose up -d

From Source

# Clone the repository
git clone https://github.com/digital-defiance/ai-capabilities-suite.git
cd ai-capabilities-suite

# Install dependencies
npm install

# Build the packages
npx nx build @ai-capabilities-suite/mcp-debugger-core
npx nx build @ai-capabilities-suite/mcp-debugger-server

# Run the server
node packages/mcp-debugger-server/dist/src/cli.js

⚙️ Configuration

Kiro Configuration

Add to .kiro/settings/mcp.json:

{
  "mcpServers": {
    "debugger": {
      "command": "ts-mcp-server",
      "args": [],
      "env": {
        "NODE_ENV": "production"
      },
      "disabled": false,
      "autoApprove": [
        "debugger_start",
        "debugger_set_breakpoint",
        "debugger_continue",
        "debugger_step_over",
        "debugger_inspect",
        "debugger_get_stack"
      ]
    }
  }
}

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "debugger": {
      "command": "ts-mcp-server",
      "args": []
    }
  }
}

VS Code Configuration

Add to .vscode/settings.json:

{
  "mcp.servers": {
    "debugger": {
      "command": "ts-mcp-server",
      "args": [],
      "enabled": true
    }
  }
}

Environment Variables

Optional environment variables for advanced configuration:

# Enable debug logging
DEBUG=mcp:*

# Set custom timeout (milliseconds)
MCP_DEBUGGER_TIMEOUT=60000

# Enable authentication
MCP_DEBUGGER_AUTH_TOKEN=your-secret-token

# Enable rate limiting
MCP_DEBUGGER_RATE_LIMIT=100

# Enable audit logging
MCP_DEBUGGER_AUDIT_LOG=true

🛠️ Available Tools

The MCP ACS Debugger Server provides 25 specialized tools organized into 8 categories:

Session Management

1. `debugger_start`

Start a new debug session with a Node.js process.

Parameters:

command (string, required): The command to execute (e.g., "node", "npm")
args (string[], optional): Command arguments (e.g., ["test.js"])
cwd (string, optional): Working directory for the process
timeout (number, optional): Timeout in milliseconds (default: 30000)

Example:

{
  "command": "node",
  "args": ["app.js"],
  "cwd": "/path/to/project",
  "timeout": 30000
}

Response:

{
  "status": "success",
  "sessionId": "session-123",
  "state": "paused",
  "pid": 12345
}

2. `debugger_stop_session`

Stop a debug session and cleanup all resources.

Parameters:

sessionId (string, required): The debug session ID

Example:

{
  "sessionId": "session-123"
}

Breakpoint Management

3. `debugger_set_breakpoint`

Set a breakpoint at a specific file and line number.

Parameters:

sessionId (string, required): The debug session ID
file (string, required): The file path (absolute or relative)
line (number, required): The line number (1-indexed)
condition (string, optional): Optional condition expression (e.g., "x > 10")

Example:

{
  "sessionId": "session-123",
  "file": "/path/to/file.js",
  "line": 42,
  "condition": "count > 5"
}

4. `debugger_remove_breakpoint`

Remove a breakpoint from the session.

Parameters:

sessionId (string, required): The debug session ID
breakpointId (string, required): The breakpoint ID to remove

5. `debugger_toggle_breakpoint`

Toggle a breakpoint between enabled and disabled states.

Parameters:

sessionId (string, required): The debug session ID
breakpointId (string, required): The breakpoint ID to toggle

6. `debugger_list_breakpoints`

Get all breakpoints for a debug session.

Parameters:

sessionId (string, required): The debug session ID

Response:

{
  "status": "success",
  "breakpoints": [
    {
      "id": "bp-1",
      "file": "/path/to/file.js",
      "line": 42,
      "condition": "x > 10",
      "enabled": true,
      "verified": true
    }
  ]
}

Execution Control

7. `debugger_continue`

Resume execution until the next breakpoint or program termination.

Parameters:

sessionId (string, required): The debug session ID

8. `debugger_step_over`

Execute the current line and pause at the next line in the same scope.

Parameters:

sessionId (string, required): The debug session ID

9. `debugger_step_into`

Execute the current line and pause at the first line inside any called function.

Parameters:

sessionId (string, required): The debug session ID

10. `debugger_step_out`

Execute until the current function returns and pause at the calling location.

Parameters:

sessionId (string, required): The debug session ID

11. `debugger_pause`

Pause a running debug session.

Parameters:

sessionId (string, required): The debug session ID

Variable Inspection

12. `debugger_inspect`

Evaluate a JavaScript expression in the current execution context.

Parameters:

sessionId (string, required): The debug session ID
expression (string, required): The JavaScript expression to evaluate

Example:

{
  "sessionId": "session-123",
  "expression": "user.name + ' ' + user.age"
}

13. `debugger_get_local_variables`

Get all local variables in the current scope.

Parameters:

sessionId (string, required): The debug session ID

14. `debugger_get_global_variables`

Get global variables accessible from the current scope.

Parameters:

sessionId (string, required): The debug session ID

15. `debugger_inspect_object`

Inspect an object's properties with nested resolution.

Parameters:

sessionId (string, required): The debug session ID
objectId (string, required): The object ID from a previous inspection
maxDepth (number, optional): Maximum depth to traverse (default: 2)

Variable Watching

16. `debugger_add_watch`

Add an expression to the watch list.

Parameters:

sessionId (string, required): The debug session ID
expression (string, required): The expression to watch

17. `debugger_remove_watch`

Remove an expression from the watch list.

Parameters:

sessionId (string, required): The debug session ID
watchId (string, required): The watch ID (expression) to remove

18. `debugger_get_watches`

Get all watched expressions with their current values.

Parameters:

sessionId (string, required): The debug session ID

Call Stack

19. `debugger_get_stack`

Get the current call stack with function names and file locations.

Parameters:

sessionId (string, required): The debug session ID

Response:

{
  "status": "success",
  "stack": [
    {
      "function": "myFunction",
      "file": "/absolute/path/to/file.js",
      "line": 42,
      "column": 10
    }
  ]
}

20. `debugger_switch_stack_frame`

Switch the execution context to a specific stack frame.

Parameters:

sessionId (string, required): The debug session ID
frameIndex (number, required): The frame index (0 = top frame)

Hang Detection

21. `debugger_detect_hang`

Detect if a process hangs or enters an infinite loop.

Parameters:

command (string, required): The command to execute
args (string[], optional): Command arguments
cwd (string, optional): Working directory
timeout (number, required): Timeout in milliseconds
sampleInterval (number, optional): Sample interval for loop detection (default: 100ms)

Example:

{
  "command": "node",
  "args": ["script.js"],
  "timeout": 5000,
  "sampleInterval": 100
}

Response (hung):

{
  "status": "success",
  "hung": true,
  "location": "/path/to/file.js:42",
  "stack": [...],
  "message": "Process hung at /path/to/file.js:42",
  "duration": 5000
}

Response (completed):

{
  "status": "success",
  "hung": false,
  "completed": true,
  "exitCode": 0,
  "duration": 1234
}

🚀 Quick Start Guide

1. Install the Server

npm install -g @ai-capabilities-suite/mcp-debugger-server

2. Configure Your AI Agent

Add to your MCP configuration file (e.g., .kiro/settings/mcp.json):

{
  "mcpServers": {
    "debugger": {
      "command": "ts-mcp-server",
      "args": []
    }
  }
}

3. Start Debugging

Ask your AI agent to debug your code:

"Debug my Node.js script app.js and set a breakpoint at line 42"

The AI agent will use the MCP ACS Debugger Server to:

Start a debug session
Set the breakpoint
Run your code
Pause at the breakpoint
Inspect variables and help you fix issues

📚 Common Debugging Scenarios

Scenario 1: Debug a Simple Script

// 1. Start a debug session
{
  "tool": "debugger_start",
  "args": {
    "command": "node",
    "args": ["my-script.js"]
  }
}
// Returns: { sessionId: "session-123", state: "paused" }

// 2. Set a breakpoint
{
  "tool": "debugger_set_breakpoint",
  "args": {
    "sessionId": "session-123",
    "file": "/path/to/my-script.js",
    "line": 10
  }
}

// 3. Continue execution
{
  "tool": "debugger_continue",
  "args": {
    "sessionId": "session-123"
  }
}

// 4. When paused at breakpoint, inspect variables
{
  "tool": "debugger_get_local_variables",
  "args": {
    "sessionId": "session-123"
  }
}

// 5. Step through code
{
  "tool": "debugger_step_over",
  "args": {
    "sessionId": "session-123"
  }
}

// 6. Stop the session
{
  "tool": "debugger_stop_session",
  "args": {
    "sessionId": "session-123"
  }
}

Scenario 2: Debug a Failing Test

// 1. Start debugging a Jest test
{
  "tool": "debugger_start",
  "args": {
    "command": "node",
    "args": ["node_modules/.bin/jest", "my-test.spec.js", "--runInBand"],
    "timeout": 60000
  }
}

// 2. Set breakpoint in test file
{
  "tool": "debugger_set_breakpoint",
  "args": {
    "sessionId": "session-123",
    "file": "/path/to/my-test.spec.js",
    "line": 25
  }
}

// 3. Continue to breakpoint
{
  "tool": "debugger_continue",
  "args": {
    "sessionId": "session-123"
  }
}

// 4. Inspect test variables
{
  "tool": "debugger_inspect",
  "args": {
    "sessionId": "session-123",
    "expression": "expect.getState()"
  }
}

Scenario 3: Detect an Infinite Loop

// Use hang detection to identify infinite loops
{
  "tool": "debugger_detect_hang",
  "args": {
    "command": "node",
    "args": ["potentially-hanging-script.js"],
    "timeout": 5000,
    "sampleInterval": 100
  }
}
// Returns hang location and stack trace if hung

Scenario 4: Debug TypeScript Code

// TypeScript debugging works automatically with source maps
// 1. Ensure your tsconfig.json has "sourceMap": true

// 2. Start debugging the compiled JavaScript
{
  "tool": "debugger_start",
  "args": {
    "command": "node",
    "args": ["--enable-source-maps", "dist/app.js"]
  }
}

// 3. Set breakpoints using TypeScript file paths
{
  "tool": "debugger_set_breakpoint",
  "args": {
    "sessionId": "session-123",
    "file": "/path/to/src/app.ts",  // TypeScript source file
    "line": 42
  }
}
// The debugger automatically maps to the compiled JavaScript location

Scenario 5: Watch Variable Changes

// 1. Start session and set breakpoint
// ... (as in Scenario 1)

// 2. Add watched variables
{
  "tool": "debugger_add_watch",
  "args": {
    "sessionId": "session-123",
    "expression": "user.balance"
  }
}

// 3. Continue execution
{
  "tool": "debugger_continue",
  "args": {
    "sessionId": "session-123"
  }
}

// 4. Check watched variables at each pause
{
  "tool": "debugger_get_watches",
  "args": {
    "sessionId": "session-123"
  }
}
// Returns: { watches: [{ watchId: "user.balance", value: 100, changed: true, oldValue: 50, newValue: 100 }] }

🎬 Demo & Screenshots

Debugging in Action

Setting breakpoints and inspecting variables in a Node.js application

Detecting and diagnosing an infinite loop

Debugging TypeScript code with source map support

Note: Replace placeholder images with actual screenshots or animated GIFs demonstrating the debugger in action. See images/README.md for guidelines.

🔧 Troubleshooting

Common Issues and Solutions

Issue: "Session not found"

Symptoms: Error when trying to use a session ID Cause: The session ID is invalid or the session has been terminated Solution:

# Start a new debug session
{
  "tool": "debugger_start",
  "arguments": {
    "command": "node",
    "args": ["your-script.js"]
  }
}

Issue: "Process must be paused"

Symptoms: Cannot inspect variables or evaluate expressions Cause: Trying to inspect variables when the process is running Solution:

Set a breakpoint and continue to it, OR
Use debugger_pause to pause execution immediately

Issue: Breakpoint not hitting

Symptoms: Execution doesn't stop at the breakpoint Cause: Invalid breakpoint location or code path not executed Solution:

Verify the file path is correct (use absolute paths):

"file": "/absolute/path/to/your/file.js"  // ✅ Good
"file": "file.js"                          // ❌ Avoid

Check that the line number has executable code (not comments or blank lines)

Verify the breakpoint is set and verified:

{
  "tool": "debugger_list_breakpoints",
  "arguments": { "sessionId": "your-session-id" }
}

Issue: Hang detection false positives

Symptoms: Hang detection reports a hang when the script is running normally Cause: The timeout is too short for the script's normal execution time Solution:

{
  "tool": "debugger_detect_hang",
  "arguments": {
    "command": "node",
    "args": ["script.js"],
    "timeout": 60000,  // Increase timeout to 60 seconds
    "sampleInterval": 200  // Increase sample interval
  }
}

Issue: TypeScript breakpoints not working

Symptoms: Breakpoints in .ts files don't pause execution Cause: Source maps are not enabled or not found Solution:

Ensure "sourceMap": true in tsconfig.json:

{
  "compilerOptions": {
    "sourceMap": true
  }
}

Use --enable-source-maps flag when starting Node.js:
```
node --enable-source-maps dist/app.js
```
Verify .map files exist alongside compiled JavaScript:
```
ls dist/*.js.map
```

Issue: "Cannot find module" errors

Symptoms: Module not found errors when starting the server Cause: The packages haven't been built or dependencies not installed Solution:

# Install dependencies
npm install

# Build the packages
npx nx build @ai-capabilities-suite/mcp-debugger-core
npx nx build @ai-capabilities-suite/mcp-debugger-server

# Or if installed globally, reinstall
npm install -g @ai-capabilities-suite/mcp-debugger-server

Issue: WebSocket connection errors

Symptoms: "Failed to connect to inspector" or WebSocket errors Cause: The Inspector Protocol failed to start Solution:

Ensure Node.js version is 18 or higher:
```
node --version  # Should be >= 18.0.0
```
Check that no other debugger is attached to the process

Verify the process starts successfully:

node --inspect-brk your-script.js
# Should output: Debugger listening on ws://...

Issue: High memory usage

Symptoms: Server consumes excessive memory Cause: Too many concurrent sessions or large heap snapshots Solution:

Limit concurrent sessions

Stop unused sessions:

{
  "tool": "debugger_stop_session",
  "arguments": { "sessionId": "session-id" }
}

Configure resource limits (see Environment Variables section)

Issue: Slow performance

Symptoms: Debugging operations are slow Cause: Large objects, deep inspection, or many breakpoints Solution:

Limit object inspection depth:

{
  "tool": "debugger_inspect_object",
  "arguments": {
    "sessionId": "session-id",
    "objectId": "obj-id",
    "maxDepth": 2  // Limit depth
  }
}

Use conditional breakpoints to reduce pauses
Remove unnecessary breakpoints

Getting Help

If you encounter issues not covered here:

Check the logs: Enable debug logging with DEBUG=mcp:*
Search existing issues: GitHub Issues
Create a new issue: Include:
- Node.js version (node --version)
- Server version (ts-mcp-server --version)
- Error messages and stack traces
- Steps to reproduce
Email support: info@digitaldefiance.org

💡 Use Cases

1. AI-Assisted Debugging

Enable AI agents to autonomously debug your code:

Kiro: "Debug my failing test and tell me why it's failing"
Amazon Q: "Find the infinite loop in my script"
GitHub Copilot: "Set a breakpoint and inspect the user object"

2. Automated Testing & CI/CD

Integrate debugging into your CI/CD pipeline:

Debug failing tests automatically
Detect performance regressions
Identify memory leaks before deployment

3. Production Issue Investigation

Debug production-like environments safely:

Reproduce production issues locally
Inspect state without modifying code
Analyze performance bottlenecks

4. Learning & Education

Help developers learn debugging techniques:

Step through code execution
Understand call stacks and scope
Visualize variable changes

5. Performance Optimization

Identify and fix performance issues:

Profile CPU usage
Analyze memory allocation
Detect memory leaks
Track performance metrics

📊 Feature Comparison

Feature	MCP ACS Debugger Server	VS Code Debugger	Chrome DevTools	Node Inspector
AI Agent Integration	✅ Full MCP Support	❌ No	❌ No	❌ No
Breakpoints	✅ Advanced (conditional, hit count, logpoints)	✅ Yes	✅ Yes	✅ Basic
Variable Inspection	✅ Deep inspection with type info	✅ Yes	✅ Yes	✅ Basic
TypeScript Support	✅ Full source map support	✅ Yes	✅ Yes	⚠️ Limited
Hang Detection	✅ Automated with sampling	❌ No	❌ No	❌ No
CPU Profiling	✅ Yes	✅ Yes	✅ Yes	❌ No
Memory Profiling	✅ Yes with leak detection	✅ Yes	✅ Yes	❌ No
Multiple Sessions	✅ Isolated concurrent sessions	⚠️ Limited	⚠️ Limited	❌ No
Test Framework Integration	✅ Jest, Mocha, Vitest	✅ Yes	❌ No	❌ No
Remote Debugging	✅ Via MCP protocol	✅ Yes	✅ Yes	✅ Yes
Audit Logging	✅ Enterprise-grade	❌ No	❌ No	❌ No
Rate Limiting	✅ Yes	❌ No	❌ No	❌ No
Metrics Export	✅ Prometheus	❌ No	❌ No	❌ No

📋 Error Codes

The server returns structured error responses with the following codes:

Error Code	Description	Common Causes	Solution
`SESSION_NOT_FOUND`	Session ID doesn't exist	Invalid ID or terminated session	Start a new session
`SESSION_START_FAILED`	Failed to start debug session	Invalid command or permissions	Check command and file paths
`BREAKPOINT_SET_FAILED`	Failed to set breakpoint	Invalid file path or line number	Use absolute paths and valid lines
`BREAKPOINT_NOT_FOUND`	Breakpoint doesn't exist	Invalid breakpoint ID	List breakpoints to verify IDs
`CONTINUE_FAILED`	Failed to resume execution	Process crashed or terminated	Check process status
`STEP_OVER_FAILED`	Failed to step over	Not paused or invalid state	Ensure process is paused
`STEP_INTO_FAILED`	Failed to step into	Not paused or no function call	Ensure at function call
`STEP_OUT_FAILED`	Failed to step out	Not in a function	Check call stack
`PAUSE_FAILED`	Failed to pause execution	Process not running	Ensure process is running
`INSPECT_FAILED`	Failed to evaluate expression	Invalid expression or not paused	Check syntax and pause state
`GET_STACK_FAILED`	Failed to get call stack	Not paused	Pause execution first
`NOT_PAUSED`	Operation requires paused state	Process is running	Pause or set breakpoint
`HANG_DETECTION_FAILED`	Failed to detect hang	Invalid parameters	Check timeout and interval
`WATCH_NOT_FOUND`	Watch expression doesn't exist	Invalid watch ID	List watches to verify IDs
`RATE_LIMIT_EXCEEDED`	Too many requests	Exceeded rate limit	Wait and retry
`AUTH_FAILED`	Authentication failed	Invalid token	Check authentication token

Testing

Run Unit Tests

npx nx test @ai-capabilities-suite/mcp-core
npx nx test @ai-capabilities-suite/mcp-server

Run E2E Tests

npx nx test @ai-capabilities-suite/mcp-server --testPathPattern=e2e --testTimeout=60000

Manual Testing

node packages/mcp-server/test-mcp-manual.js

See TESTING.md for comprehensive testing documentation.

🏗️ Architecture

Technology Stack

The MCP ACS Debugger Server is built on enterprise-grade technologies:

MCP SDK: Model Context Protocol implementation for AI agent communication
Chrome DevTools Protocol (CDP): Node.js Inspector Protocol for low-level debugging
WebSocket: Real-time bidirectional communication with the Node.js Inspector
TypeScript: Type-safe implementation with full type definitions
Zod: Runtime type validation for tool parameters
Prometheus: Metrics collection and export

Component Architecture

┌─────────────────────────────────────────────────────────────┐
│                        AI Agent Layer                        │
│  (Kiro, Amazon Q, GitHub Copilot, Claude Desktop)          │
└────────────────────────┬────────────────────────────────────┘
                         │ MCP Protocol (stdio/JSON-RPC)
                         │
┌────────────────────────▼────────────────────────────────────┐
│                   MCP ACS Debugger Server                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Session    │  │  Breakpoint  │  │   Variable   │     │
│  │   Manager    │  │   Manager    │  │  Inspector   │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │     Hang     │  │     CPU      │  │    Memory    │     │
│  │   Detector   │  │   Profiler   │  │   Profiler   │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Source     │  │    Audit     │  │    Metrics   │     │
│  │  Map Manager │  │    Logger    │  │  Collector   │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└────────────────────────┬────────────────────────────────────┘
                         │ Inspector Protocol (CDP/WebSocket)
                         │
┌────────────────────────▼────────────────────────────────────┐
│                   Node.js Inspector                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Debugger   │  │   Runtime    │  │   Profiler   │     │
│  │    Domain    │  │    Domain    │  │    Domain    │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────┐
│                   Target Node.js Process                     │
│              (Application, Test Runner, etc.)                │
└─────────────────────────────────────────────────────────────┘

Data Flow

AI Agent Request: Agent sends MCP tool request via stdio
Tool Validation: Server validates parameters using Zod schemas
Session Management: Server creates or retrieves debug session
CDP Communication: Server sends CDP commands via WebSocket
Inspector Response: Node.js Inspector returns debugging data
Data Processing: Server processes and formats response
MCP Response: Server returns structured JSON response to agent

Security Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Security Layer                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │     Auth     │  │     Rate     │  │     Data     │     │
│  │   Manager    │  │   Limiter    │  │    Masker    │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Session    │  │    Audit     │  │   Circuit    │     │
│  │   Timeout    │  │    Logger    │  │   Breaker    │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└─────────────────────────────────────────────────────────────┘

⚡ Performance

Benchmarks

Performance metrics on a MacBook Pro (M1, 16GB RAM):

Operation	Average Latency	Throughput	Notes
Session Start	150ms	6.6/sec	Includes process spawn
Set Breakpoint	5ms	200/sec	Single breakpoint
Continue Execution	2ms	500/sec	Resume to next breakpoint
Step Over	8ms	125/sec	Single step operation
Variable Inspection	12ms	83/sec	Local variables only
Expression Evaluation	15ms	66/sec	Simple expressions
Call Stack Retrieval	10ms	100/sec	Full stack trace
Hang Detection	5000ms	0.2/sec	With 5s timeout
CPU Profile Start	3ms	333/sec	Start profiling
CPU Profile Stop	50ms	20/sec	Includes analysis
Heap Snapshot	200ms	5/sec	10MB heap

Resource Usage

Typical resource consumption:

Memory: 50-100MB base + 10-20MB per active session
CPU: < 1% idle, 5-10% during active debugging
Network: Minimal (local WebSocket only)
Disk: < 1MB for logs and metrics

Scalability

Concurrent Sessions: Tested with 100+ concurrent sessions
Breakpoints: Supports 1000+ breakpoints per session
Session Duration: Tested for 24+ hour sessions
Memory Stability: No memory leaks detected in 48-hour soak tests

Contributing

Contributions are welcome! Please follow these guidelines:

Fork the repository
Create a feature branch
Make your changes with tests
Run the test suite
Submit a pull request

Publishing to NPM

If you're a maintainer publishing updates:

Quick Setup: NPM-SETUP-GUIDE.md - 5-minute first-time setup
Full Guide: PUBLISHING.md - Comprehensive publishing documentation
Automated: GitHub Actions workflow handles publishing on release

Documentation

README.md - This file, main documentation
API.md - Detailed API documentation
TOOL-REFERENCE.md - Complete tool reference
AI-AGENT-INTEGRATION.md - AI agent integration guide
VSCODE-INTEGRATION.md - VS Code integration guide
TESTING.md - Testing documentation
PUBLISHING.md - NPM publishing guide
NPM-SETUP-GUIDE.md - Quick setup for publishers

🙏 Acknowledgments

This project builds upon excellent open-source technologies:

Model Context Protocol - Protocol specification and SDK
Chrome DevTools Protocol - Debugging protocol
Node.js Inspector - Node.js debugging API
TypeScript - Type-safe JavaScript
Zod - Runtime type validation

Special thanks to:

The MCP community for feedback and contributions
All contributors who have helped improve this project
Users who report issues and suggest improvements

📜 License

MIT License - See LICENSE file for details

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

🔗 Links

Homepage: https://digitaldefiance.org
GitHub: https://github.com/digital-defiance/ai-capabilities-suite
NPM: https://www.npmjs.com/package/@ai-capabilities-suite/mcp-debugger-server
Docker Hub: https://hub.docker.com/r/digitaldefiance/mcp-debugger-server
Documentation: https://github.com/digital-defiance/ai-capabilities-suite/tree/main/packages/mcp-debugger-server
Issues: https://github.com/digital-defiance/ai-capabilities-suite/issues
Discussions: https://github.com/digital-defiance/ai-capabilities-suite/discussions

Made with ❤️ by Digital Defiance

⭐ Star us on GitHub | 📦 View on NPM | 🐳 View on Docker Hub

❓ Frequently Asked Questions (FAQ)

General Questions

Q: Which AI agents are supported? A: The server works with any MCP-compatible AI agent, including:

Kiro
Amazon Q
GitHub Copilot
Claude Desktop
Custom MCP clients

Q: Is this free to use? A: Yes, the MCP ACS Debugger Server is open source under the MIT license and free for both personal and commercial use.

Technical Questions

Q: What Node.js versions are supported? A: Node.js >= 18.0.0 is required. We recommend using the latest LTS version.

Q: Does this work with TypeScript? A: Yes! Full TypeScript support with source maps. Set breakpoints in .ts files and inspect variables with their original TypeScript names.

Q: Can I debug remote processes? A: The server connects to local Node.js processes via the Inspector Protocol. For remote debugging, use SSH tunneling or deploy the server on the remote machine.

Q: How many concurrent debug sessions can I run? A: The server supports 100+ concurrent sessions. Each session is isolated and doesn't interfere with others.

Q: Does this work with Docker containers? A: Yes! We provide official Docker images. See DOCKER-DEPLOYMENT.md for details.

Debugging Questions

Q: Why isn't my breakpoint hitting? A: Common causes:

File path is relative instead of absolute
Line number doesn't have executable code
Code path isn't executed
Source maps are missing (for TypeScript)

Q: How do I debug a specific test? A: Start a debug session with your test runner:

{
  "tool": "debugger_start",
  "arguments": {
    "command": "node",
    "args": ["node_modules/.bin/jest", "my-test.spec.js", "--runInBand"]
  }
}

Q: Can I debug asynchronous code? A: Yes! The debugger fully supports async/await, Promises, and callbacks. Set breakpoints in async functions and step through them normally.

Q: How do I detect memory leaks? A: Use the memory profiling tools:

Take a heap snapshot at the start
Run your code
Take another heap snapshot
Compare the snapshots to identify growing objects

Performance Questions

Q: How much memory does the server use? A: Base memory usage is 50-100MB, plus 10-20MB per active debug session.

Q: Can I use this in CI/CD pipelines? A: Yes! The server is designed for automation. Use hang detection and test debugging in your CI/CD pipeline to catch issues early.

Security Questions

Q: How is sensitive data protected? A: The server includes automatic PII masking for common patterns (emails, SSNs, credit cards). Configure additional masking rules as needed.

Q: Can I restrict which operations are allowed? A: Yes! Use authentication and configure allowed operations per user/token. See the Security section in the documentation.

Integration Questions

Q: How do I integrate with VS Code? A: See VSCODE-INTEGRATION.md for detailed integration instructions.

Q: Can I use this with GitHub Copilot? A: Yes! GitHub Copilot can use MCP servers. Configure the server in your Copilot settings.

Q: Does this work with Mocha/Jest/Vitest? A: Yes! The server has built-in support for all major test frameworks. Just start a debug session with your test runner command.

💬 Support & Community

Getting Help

📖 Documentation: Full documentation
🐛 Bug Reports: GitHub Issues
💡 Feature Requests: GitHub Discussions
📧 Email Support: info@digitaldefiance.org
💬 Community Chat: Join our Discord (coming soon)

Resources

NPM Package: @ai-capabilities-suite/mcp-debugger-server
Docker Hub: digitaldefiance/mcp-debugger-server
GitHub Repository: ai-capabilities-suite
API Documentation: API.md
Tool Reference: TOOL-REFERENCE.md

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Sponsorship

Support the project:

GitHub Sponsors: Sponsor Digital Defiance
Open Collective: Support the project (coming soon)

📝 Changelog

Version 1.0.4 (Current)

Release Date: December 2025

New Features:

Enhanced documentation with comprehensive examples
Improved error messages and troubleshooting guides
Added performance benchmarks and metrics
Enhanced security features documentation

Bug Fixes:

Fixed WebSocket connection stability issues
Improved source map resolution for edge cases
Fixed memory leak in long-running sessions

Performance:

Reduced session startup time by 20%
Optimized variable inspection for large objects
Improved CPU profiling accuracy

Version 1.0.2

Release Date: November 2024

New Features:

Added Docker support with official images
Implemented Prometheus metrics export
Added health check endpoints
Enhanced audit logging with structured format

Improvements:

Better error handling for CDP protocol errors
Improved TypeScript source map support
Enhanced session isolation

Version 1.0.1

Release Date: November 2024

New Features:

Added CPU profiling support
Added memory profiling and heap snapshots
Implemented performance timeline tracking
Added advanced breakpoint types (logpoints, hit counts)

Improvements:

Enhanced hang detection algorithm
Improved variable inspection performance
Better handling of async code

Version 1.0.0

Release Date: October 2024

Initial Release:

25 comprehensive debugging tools
Full TypeScript support with source maps
Hang detection with configurable sampling
Multiple concurrent sessions with isolation
Test framework integration (Jest, Mocha, Vitest)
Variable watching with change detection
Call stack navigation
Conditional breakpoints
Object inspection with nested resolution
Enterprise security features
Observability and monitoring

🗺️ Roadmap

Version 1.1.0 (Planned - Q1 2025)

Time-travel debugging (record and replay)
Smart breakpoint suggestions using AI
Enhanced VS Code extension
WebAssembly debugging support
Distributed tracing integration

Version 1.2.0 (Planned - Q2 2025)

Browser debugging support (Chrome, Firefox)
Mobile debugging (React Native)
Collaborative debugging sessions
Advanced visualization tools
Plugin system for custom tools

Version 2.0.0 (Planned - Q3 2025)

Multi-language support (Python, Go, Rust)
Cloud-native debugging
Kubernetes integration
Advanced AI-powered debugging assistance
Real-time collaboration features

Want to influence the roadmap? Share your ideas

MCP Debugger Server

MCP ACS Debugger Server

🔗 Repository

🎯 Key Features

Core Debugging Capabilities

Advanced Features

Enterprise Features

📦 Installation

System Requirements

Quick Start (NPM - Recommended)

Alternative Installation Methods

Using NPX (No Installation Required)

Using Docker

From Source

⚙️ Configuration

Kiro Configuration

Claude Desktop Configuration

VS Code Configuration

Environment Variables

🛠️ Available Tools

Session Management

1. debugger_start

2. debugger_stop_session

Breakpoint Management

3. debugger_set_breakpoint

4. debugger_remove_breakpoint

5. debugger_toggle_breakpoint

6. debugger_list_breakpoints

Execution Control

7. debugger_continue

8. debugger_step_over

9. debugger_step_into

10. debugger_step_out

11. debugger_pause

Variable Inspection

12. debugger_inspect

13. debugger_get_local_variables

14. debugger_get_global_variables

15. debugger_inspect_object

Variable Watching

16. debugger_add_watch

17. debugger_remove_watch

18. debugger_get_watches

Call Stack

19. debugger_get_stack

20. debugger_switch_stack_frame

Hang Detection

21. debugger_detect_hang

🚀 Quick Start Guide

1. Install the Server

2. Configure Your AI Agent

3. Start Debugging

📚 Common Debugging Scenarios

Scenario 1: Debug a Simple Script

Scenario 2: Debug a Failing Test

Scenario 3: Detect an Infinite Loop

Scenario 4: Debug TypeScript Code

Scenario 5: Watch Variable Changes

🎬 Demo & Screenshots

Debugging in Action

🔧 Troubleshooting

Common Issues and Solutions

Issue: "Session not found"

Issue: "Process must be paused"

Issue: Breakpoint not hitting

Issue: Hang detection false positives

Issue: TypeScript breakpoints not working

Issue: "Cannot find module" errors

Issue: WebSocket connection errors

Issue: High memory usage

Issue: Slow performance

Getting Help

💡 Use Cases

1. AI-Assisted Debugging

2. Automated Testing & CI/CD

3. Production Issue Investigation

4. Learning & Education

5. Performance Optimization

📊 Feature Comparison

📋 Error Codes

1. `debugger_start`

2. `debugger_stop_session`

3. `debugger_set_breakpoint`

4. `debugger_remove_breakpoint`

5. `debugger_toggle_breakpoint`

6. `debugger_list_breakpoints`

7. `debugger_continue`

8. `debugger_step_over`

9. `debugger_step_into`

10. `debugger_step_out`

11. `debugger_pause`

12. `debugger_inspect`

13. `debugger_get_local_variables`

14. `debugger_get_global_variables`

15. `debugger_inspect_object`

16. `debugger_add_watch`

17. `debugger_remove_watch`

18. `debugger_get_watches`

19. `debugger_get_stack`

20. `debugger_switch_stack_frame`

21. `debugger_detect_hang`

1. `debugger_start`