io.github.Digital-Defiance/mcp-debugger

Install

Config snippet generator goes here (5 client tabs)

README

# MCP ACS Debugger Server

[![NPM Version](https://img.shields.io/npm/v/@ai-capabilities-suite/mcp-debugger-server)](https://www.npmjs.com/package/@ai-capabilities-suite/mcp-debugger-server)
[![GitHub Release](https://img.shields.io/github/v/release/digital-defiance/mcp-debugger-server?label=Release&logo=github)](https://github.com/digital-defiance/mcp-debugger-server/releases)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
[![Docker Pulls](https://img.shields.io/docker/pulls/digitaldefiance/mcp-debugger-server)](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](https://github.com/Digital-Defiance/mcp-debugger-server)**

This repository is part of the [AI Capabilitites Suite](https://github.com/Digital-Defiance/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)

```bash
# 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)

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

#### Using Docker

```bash
# 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

```bash
# 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`:

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