Mcp Debugger Server

MCP ACS Debugger Server

[](https://www.npmjs.com/package/@ai-capabilities-suite/mcp-debugger-server) [](https://github.com/digital-defiance/mcp-debugger-server/releases) [](https://opensource.org/licenses/MIT) [](https://nodejs.org/) [](https://hub.docker.com/r/digitaldefiance/mcp-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:

1. Start a debug session
2. Set the breakpoint
3. Run your code
4. Pause at the breakpoint
5. 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 de

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Digital-Defiance
• Source: Digital-Defiance/mcp-debugger-server
• License: MIT

Install and usage instructions live in the source repository linked above.