Curupira

# Curupira MCP Server Improvements Summary This document summarizes all the improvements made to the Curupira MCP server to enhance Chrome DevTools Protocol debugging capabilities. ## 🚀 Major Enhancements ### 1. **Enhanced React Detection for Production Builds** **Problem**: React detection was failing on production builds where React DevTools weren't available. **Solution**: Implemented multi-strategy detection approach: - **Fiber Property Detection**: Searches DOM elements for React Fiber properties - **Event Handler Analysis**: Detects React-specific event patterns - **Root Container Patterns**: Identifies common React root selectors - **Bundled Code Detection**: Analyzes script content for React patterns - **DOM Structure Analysis**: Recognizes React-typical DOM patterns **Files Modified**: - `src/integrations/react/detector.ts` - Enhanced detection strategies - `src/integrations/react/devtools-injector.ts` - New DevTools hook injector - `src/mcp/tools/providers/react-tools.factory.ts` - Updated to use new detector ### 2. **Console and Network Event Buffering** **Problem**: Console and network events were being lost due to timing issues. **Solution**: Implemented dedicated buffer services with session management: - **ConsoleBufferService**: Captures and stores console messages - **NetworkBufferService**: Tracks network requests/responses - Session-aware buffering with automatic cleanup - Size-limited buffers to prevent memory issues **Files Added**: - `src/chrome/services/console-buffer.service.ts` - `src/chrome/services/network-buffer.service.ts` ### 3. **MinIO Integration for Large Responses** **Problem**: Screenshots and PDFs were too large for MCP message protocol. **Solution**: Integrated MinIO/S3-compatible storage: - Screenshots automatically stored in MinIO when enabled - Returns signed URLs instead of base64 data - Configurable via YAML/environment variables - Fallback to base64 when MinIO unavailable **Configuration**: ```yaml storage: minio: enabled: true endPoint: "minio.infrastructure.plo.quero.local" port: 31900 bucket: "curupira-screenshots" ``` **Files Modified**: - `src/infrastructure/storage/minio.service.ts` - MinIO service implementation - `src/mcp/tools/providers/screenshot-tools.factory.ts` - Updated to use MinIO - `src/config/nexus-config.ts` - Added MinIO configuration schema ### 4. **Enhanced CDP Debugging Tools** **Problem**: Limited debugging capabilities for JavaScript execution. **Solution**: Added comprehensive debugging tools: - **debugger_evaluate_expression**: Execute JS with full CDP options - **debugger_set_exception_breakpoints**: Configure exception handling - **debugger_list_breakpoints**: Track active breakpoints - Enhanced stack trace capture with runtime evaluation **Files Modified**: - `src/mcp/tools/providers/debugger-tools.factory.ts` ### 5. **Improved Performance Metrics Collection** **Problem**: Basic performance metrics lacking detail and context. **Solution**: Enhanced performance analysis: - **Categorized Metrics**: Memory, timing, resources organized clearly - **Runtime Analysis**: Comprehensive performance snapshot - **Memory Profiling**: Detailed heap analysis with recommendations - **Web Vitals**: TTFB, FCP, and other key metrics **Files Modified**: - `src/mcp/tools/providers/performance-tools.factory.ts` ## 📋 Configuration Standards ### Nexus Configuration Hierarchy Following Nexus standards, configuration follows this hierarchy: 1. **Base YAML** (`config/base.yaml`) 2. **Environment YAML** (`config/staging.yaml`, `config/production.yaml`) 3. **Environment Variables** (highest precedence) ### Environment Variable Patterns ```bash # MinIO Configuration STORAGE_MINIO_ENABLED=true STORAGE_MINIO_ENDPOINT=minio.example.com STORAGE_MINIO_ACCESS_KEY=your-key STORAGE_MINIO_SECRET_KEY=your-secret # Chrome Configuration CHROME_SERVICE_URL=http://localhost:3000 CHROME_DISCOVERY_ENABLED=true CHROME_DISCOVERY_HOSTS=localhost,127.0.0.1 # Performance PERFORMANCE_MAX_MESSAGE_SIZE=10485760 ``` ## 🏗️ Architecture Improvements ### Dependency Injection All new services follow DI pattern: - Services registered in `app.container.ts` - Constructor injection for dependencies - Interface-based contracts ### Error Handling Consistent Result pattern usage: ```typescript Result.ok(value) // Success Result.err(error) // Failure ``` ### Logging Structured logging with context: ```typescript logger.info({ sessionId, url }, 'Navigation completed'); logger.error({ error, tool }, 'Tool execution failed'); ``` ## 🧪 Testing Recommendations ### 1. React Detection Testing ```bash # Test with production React app 1. Navigate to production React site 2. Run react_detect_version tool 3. Verify detection strategies in logs ``` ### 2. MinIO Integration Testing ```bash # Start local MinIO docker run -p 9000:9000 -p 9001:9001 \ minio/minio server /data --console-address ":9001" # Enable in config export STORAGE_MINIO_ENABLED=true # Take screenshot and verify URL response ``` ### 3. Performance Analysis ```bash # Run performance analysis 1. Use performance_analyze_runtime for snapshot 2. Use performance_get_metrics for detailed metrics 3. Monitor memory with performance_memory_snapshot ``` ## 🔄 Migration Notes ### For Existing Users 1. **Update Configuration**: Add MinIO settings if using screenshot storage 2. **Environment Variables**: Update any custom environment variables to new patterns 3. **Tool Names**: All tool names remain the same for compatibility ### Breaking Changes None - all changes are backward compatible. ## 🚦 Future Enhancements 1. **Automatic Screenshot Cleanup**: Implement TTL for stored screenshots 2. **Enhanced React Profiling**: Add React Profiler API integration 3. **Network HAR Export**: Export network activity as HAR files 4. **Performance Budgets**: Alert when metrics exceed thresholds 5. **WebSocket Debugging**: Enhanced WebSocket frame inspection ## 📚 References - [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) - [Model Context Protocol](https://modelcontextprotocol.io/) - [React DevTools Protocol](https://github.com/facebook/react/tree/main/packages/react-devtools)