# 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

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

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

```json
{
  "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:

```json
{
  "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

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