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: