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

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. 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