movibe-ai/buggy-mcp

🎭 Buggy MCP Server

Credits: Toei Animation

Structured debugging workflows for Claude Code with systematic documentation and iterative problem-solving

🎯 Problem Statement

The Challenge: Debugging in software development is often chaotic, unstructured, and lacks systematic documentation. Developers frequently:

• 🔄 Repeat failed approaches without learning from previous attempts
• 📝 Lose track of debugging progress across multiple sessions
• 🤔 Miss systematic methodologies leading to inefficient problem-solving
• 🔍 Cannot leverage past debugging knowledge for similar future issues
• ⚡ Lack structured workflows for different types of debugging scenarios

💡 The Buggy MCP Solution

Buggy MCP is a specialized Model Context Protocol (MCP) server that transforms chaotic debugging into systematic, documentable, and iterative workflows. It integrates seamlessly with Claude Code to provide structured debugging sessions with progress tracking and knowledge accumulation.

🚀 Core Features

1. Intelligent Workflow Orchestration

• Smart Flag Detection: Automatically triggers structured workflows when debug flags (--dbg, --debug, --buggy) are detected
• Context-Aware Templates: Provides specialized workflows for different debugging categories (authentication, performance, etc.)
• TodoWrite Integration: Creates comprehensive, trackable todo lists compatible with Claude Code's task management system

2. Systematic Session Management

• State Persistence: Maintains debugging session state across interactions
• Progress Tracking: Monitors workflow completion and debugging attempt outcomes
• Error Recovery: Built-in resilience with circuit breakers and graceful error handling
• Memory Management: Optimized resource usage with semantic compression

3. Knowledge Base Integration

• Context7 MCP Integration: Seamlessly searches existing debugging documentation
• Structured Documentation: Auto-generates debug documents following consistent formats
• Pattern Recognition: Learns from previous debugging sessions to suggest relevant approaches
• Solution Archival: Preserves successful debugging solutions for future reference

4. Iterative Debugging Loop

• Attempt Tracking: Records each debugging approach with detailed results and notes
• Failure Analysis: Documents failed attempts to prevent repetition
• Progressive Enhancement: Builds upon previous attempts to reach solutions
• Validation Gates: Ensures thorough testing and verification of solutions

🛠️ Available Tools

📈 Value & Benefits

For Developers

• 🎯 Systematic Approach: Structured workflows eliminate ad-hoc debugging
• 📚 Knowledge Retention: Never lose debugging insights or repeat failed attempts
• ⏱️ Time Efficiency: Faster resolution through proven methodologies and past knowledge
• 🔍 Pattern Recognition: Learn from previous debugging sessions and team knowledge
• 📊 Progress Visibility: Clear tracking of debugging efforts and outcomes

For Teams

• 📖 Shared Knowledge: Centralized debugging documentation and solutions
• 🔄 Consistency: Standardized debugging approaches across team members
• 🎓 Learning Culture: Accumulated debugging wisdom benefits entire team
• 📈 Quality Improvement: Better debugging practices lead to higher code quality
• 🚀 Onboarding: New team members can learn from documented debugging patterns

For Organizations

• 💰 Reduced Debugging Costs: Faster issue resolution through systematic approaches
• 🛡️ Risk Mitigation: Better error handling and recovery mechanisms
• 📊 Debugging Analytics: Insights into common issues and resolution patterns
• 🔧 Process Improvement: Data-driven debugging process optimization
• ⚡ Faster Time to Resolution: Structured workflows reduce debugging cycles

🚀 Quick Start

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Run tests
npm test

⚙️ Configuration

Add to your Claude Code MCP configuration:

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

Configuration Options

{
  "debug_docs_path": "./debug-docs",
  "max_sessions": 10,
  "auto_cleanup_days": 30,
  "context7_integration": true
}

🎭 Usage Examples

Basic Debugging Workflow

User: "I'm having authentication issues --debug"
Buggy MCP: Creates structured workflow with steps for:
1. Enabling Context7 for auth documentation search
2. Searching for similar auth issues
3. Verifying auth flow and token validation
4. Testing endpoints and middleware
5. Documenting findings and implementing fixes

Performance Debugging

User: "Application is slow --dbg --performance"
Buggy MCP: Generates performance-specific workflow:
1. Performance profiling and bottleneck identification
2. Database query analysis
3. Memory usage review
4. Performance testing and measurement
5. Optimization documentation

Knowledge Search

User: "Search for JWT token validation issues"
Buggy MCP: Searches accumulated debugging docs and returns:
- Similar past issues and their solutions
- Relevant debugging approaches that worked
- Documentation and code examples

🏗️ Architecture

src/
├── server.ts                     # Main MCP server entry point
├── engines/                      # Core workflow engines
│   ├── flag-detection.ts         # Detect debugging context and patterns  
│   ├── workflow.ts               # Orchestrate debugging workflows
│   └── document.ts               # Manage debugging documentation
├── integrations/                 # External integrations
│   └── context7.ts               # Context7 MCP integration for knowledge search
├── utils/                        # Utilities and helpers
│   ├── state-manager.ts          # Session state management and persistence
│   ├── response-optimizer.ts     # Response compression and optimization
│   ├── error-recovery.ts         # Error handling with circuit breakers
│   ├── semantic-compression.ts   # Content compression for large responses
│   └── security.ts               # Security utilities and validation
└── types/                        # TypeScript type definitions
    ├── session.ts                # Debug session and context types
    ├── workflow.ts               # Workflow and todo management types
    └── schemas.ts                # Zod validation schemas

🔧 Development

# Watch mode for development
npm run test:watch

# Linting
npm run lint  

# Build for production
npm run build

# Start production server
npm start

🧪 Testing

# Run all tests
npm test

# Run with coverage
npm run test -- --coverage

# Test specific modules
npm test -- --testPathPattern="workflow"

🛡️ Security Features

• Input Validation: Comprehensive Zod schema validation for all inputs
• OWASP Compliance: Built-in security measures following OWASP guidelines
• Safe State Management: Secure session state handling with proper cleanup
• Error Recovery: Graceful error handling prevents system compromise
• Circuit Breakers: Automatic failure detection and recovery mechanisms

📊 Performance Optimizations

• Response Compression: Semantic compression reduces token usage by 30-50%
• Memory Management: Intelligent state cleanup and resource management
• Caching: Context7 integration includes intelligent caching mechanisms
• Parallel Processing: Concurrent operation support for improved performance
• Resource Monitoring: Built-in performance monitoring and optimization

🤝 Integration Ecosystem

Context7 MCP

• Purpose: Knowledge base search and documentation retrieval
• Benefit: Leverages accumulated debugging knowledge for faster resolution

Claude Code TodoWrite

• Purpose: Task management and progress tracking
• Benefit: Seamless integration with Claude Code's workflow management system

Future Integrations

• Sequential MCP: For complex multi-step reasoning
• Magic MCP: For UI debugging scenarios
• Morphllm MCP: For bulk code transformations during bug fixes

📄 License

MIT License - see for details

Transform your debugging from chaos to system. From guesswork to knowledge. From repetition to iteration. 🎭✨