MCP Debugger

MCP ACS Debugger Server

🔗 Repository

This package is now maintained in its own repository: [https://github.com/Digital-Defiance/mcp-debugger-server](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": tr