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