Debugger MCP Server

A comprehensive development companion tool that provides real-time debugging, code quality monitoring, and AI-enhanced insights for React/Next.js applications via the Model Context Protocol (MCP).

🚀 Features

Traditional Debugging

Error Capture: Caught/uncaught errors, console errors, promise rejections
Chrome DevTools Integration: Full browser debugging capabilities via Puppeteer
Breakpoint Management: Set, remove, and manage breakpoints with analytics
Conditional Breakpoints: Advanced breakpoint conditions and hit count tracking
Logpoints: Non-intrusive debugging with dynamic log messages
Network Monitoring: Track API calls, failed requests, performance
Real-time Streaming: Live error and performance data

Code Quality Monitoring

Complexity Analysis: Cyclomatic complexity, function metrics, nesting depth
Rule Enforcement: ESLint-style rules without running separate tools
Pattern Detection: Naming conventions, import patterns, architecture compliance
File Watching: Real-time analysis on code changes

React/Next.js Specific

Component Analysis: State tracking, prop drilling detection
Hook Monitoring: useEffect dependencies, hook rule compliance
Performance Insights: Render times, bundle analysis, SSR monitoring
Build Integration: Real-time feedback during development

📦 Installation

# Clone the repository
git clone <repository-url>
cd debugger-mcp

# Install dependencies
npm install

# Build the project
npm run build

🎯 Quick Start

1. Start the MCP Server

# Development mode (with hot reload)
npm run dev

# Production mode
npm start

2. Connect to Claude Desktop

Add this to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "debugger": {
      "command": "node",
      "args": ["/path/to/debugger-mcp/dist/index.js"],
      "env": {}
    }
  }
}

3. Test the Connection

In Claude Desktop, try these commands:

# Get current debugging session info
Use the get-debug-session tool

# Check for errors
Use the get-errors tool

# Analyze code complexity
Use the analyze-complexity tool with filePath: "src/components/MyComponent.tsx"

🛠 Available MCP Tools

Tool	Description	Parameters
`get-debug-session`	Get current debugging session information	None
`get-errors`	Get current errors and exceptions	`severity?`, `timeframe?`
`get-violations`	Get code quality rule violations	`severity?`, `filePath?`
`analyze-complexity`	Analyze complexity metrics for a file	`filePath`
`get-performance`	Get performance metrics and insights	`timeframe?`
`manage-breakpoints`	Set, remove, and manage debugging breakpoints	`action`, `location?`, `options?`, `breakpointId?`, `active?`
`update-config`	Update debugger configuration	`config`

📡 Available MCP Resources

Resource	Description	URI
Error Stream	Real-time stream of errors	`stream://errors`
Violation Stream	Real-time code quality violations	`stream://violations`
Performance Stream	Real-time performance metrics	`stream://performance`

🔍 Breakpoint Management

The debugger provides comprehensive breakpoint management capabilities through the manage-breakpoints tool:

Setting Breakpoints

# Set a simple breakpoint
Use the manage-breakpoints tool with:
- action: "set"
- location: { "filePath": "src/components/App.tsx", "lineNumber": 25 }

# Set a conditional breakpoint
Use the manage-breakpoints tool with:
- action: "set"
- location: { "filePath": "src/utils/api.ts", "lineNumber": 15 }
- options: { "condition": "response.status >= 400" }

# Set a logpoint (non-intrusive debugging)
Use the manage-breakpoints tool with:
- action: "set"
- location: { "filePath": "src/hooks/useAuth.ts", "lineNumber": 30 }
- options: { "logMessage": "User login attempt: ${user.email}" }

Managing Breakpoints

# List all breakpoints
Use the manage-breakpoints tool with action: "list"

# Remove a specific breakpoint
Use the manage-breakpoints tool with:
- action: "remove"
- breakpointId: "bp-123"

# Clear all breakpoints
Use the manage-breakpoints tool with action: "clear"

# Toggle breakpoints on/off
Use the manage-breakpoints tool with:
- action: "toggle"
- active: false

Breakpoint Analytics

# Get breakpoint analytics and hit statistics
Use the manage-breakpoints tool with action: "analytics"

This provides detailed information about:

Total breakpoints and hit counts
Most frequently hit breakpoints
Hit statistics by file and time
Recent breakpoint activity

⚙️ Configuration

The debugger creates a .debugger-mcp.json configuration file with these options:

{
  "complexity": {
    "maxFileLines": 300,
    "maxFunctionComplexity": 10,
    "maxFunctionParams": 5,
    "maxNestingDepth": 4
  },
  "patterns": {
    "namingConventions": {
      "components": "^[A-Z][a-zA-Z0-9]*$",
      "hooks": "^use[A-Z][a-zA-Z0-9]*$"
    }
  },
  "watching": {
    "paths": ["src", "pages", "components"],
    "ignored": ["node_modules", ".git", "dist"]
  },
  "browser": {
    "autoConnect": true,
    "port": 9222
  },
  "breakpoints": {
    "maxRecentHits": 100,
    "autoRemoveAfterHits": null,
    "enableAnalytics": true,
    "persistBreakpoints": true,
    "logpointTimeout": 5000,
    "enableConditionalBreakpoints": true,
    "enableLogpoints": true
  }
}

🔧 Development

# Run in development mode
npm run dev

# Build the project
npm run build

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format

📋 Architecture

┌─────────────────────────────────────────────────────────┐
│                 Debugger MCP Server                     │
├─────────────────────────────────────────────────────────┤
│  MCP Interface                                          │
│  • Tools for querying data   │  • SSE streaming         │
│  • Configuration management  │  • Real-time updates     │
├─────────────────────────────────────────────────────────┤
│  Core Debugging Engine                                  │
│  • Chrome DevTools Protocol  │  • File System Watcher   │
│  • Code Quality Analysis     │  • Performance Monitor   │
│  • Error Tracking           │  • Stream Management     │
├─────────────────────────────────────────────────────────┤
│  Real-time Communication                               │
│  • Live error streaming     │  • Configuration updates │
│  • Performance metrics      │  • Code quality alerts   │
└─────────────────────────────────────────────────────────┘

🎯 Use Cases

During Development

Real-time feedback on code quality as you type
Immediate error detection without waiting for builds
Performance monitoring of your React components
Architecture compliance checking

Code Review

Complexity analysis of changed files
Pattern compliance verification
Performance impact assessment

Debugging

Live error tracking across browser and build
Network request monitoring
Component state inspection
Performance bottleneck identification

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

📄 License

MIT License - see LICENSE file for details

🆘 Support

Issues: Report bugs and feature requests on GitHub
Documentation: Check the docs/ directory for detailed guides
Examples: See examples/ directory for usage examples

Built with ❤️ for the React/Next.js development community