Chrome Debug MCP Server

# Chrome Debug MCP Server Implementation Learnings ## Overview This document captures key learnings from implementing a Chrome debug MCP server for userscript injection and debugging. ## Technical Insights ### GM Function Implementation 1. **Global Scope Injection** - Initially faced challenges with GM functions not being available in global scope - Solved by injecting functions directly into window object - Critical to inject before userscript execution 2. **LocalStorage Integration** - Used localStorage for persistent storage (GM_setValue/GM_getValue) - Wrapped localStorage operations in JSON.stringify/parse for data type preservation - Prefix keys with 'GM_' to avoid conflicts 3. **API Key Management** - Discovered importance of API key initialization timing - Must set API key before userscript execution - Verified through localStorage persistence ### Script Injection Sequence 1. **Optimal Injection Order** ```javascript // 1. First inject API key // 2. Then inject GM functions // 3. Finally inject userscript ``` 2. **Script Element Creation** - Used document.createElement('script') for injection - Append to document.head for execution - Separate scripts for different concerns (GM functions, userscript) ### Console Integration 1. **Log Capture** - Successfully captured various log levels (debug, info, error) - Implemented verbose logging for debugging - Console logs show API requests and responses ### Browser Integration 1. **Chrome DevTools Protocol** - Used CDP for browser control - Enabled runtime debugging capabilities - Maintained connection for live console monitoring 2. **Custom Chrome Executable Support** - Added ability to use existing Chrome installation - Implemented via executablePath parameter in launch options - Provides flexibility for users with specific Chrome versions or configurations 3. **Extension Support** - Implemented Chrome extension loading in automated mode - Added ability to disable all extensions except specified ones - Implemented option to disable Chrome's "Automation Controlled" mode - Extensions require non-headless mode to function properly ## Challenges and Solutions ### 1. Global Scope Access **Challenge**: GM functions not accessible to userscript **Solution**: Direct window object assignment and proper injection sequence ### 2. API Key Persistence **Challenge**: API key not available on page reload **Solution**: localStorage implementation with proper initialization timing ### 3. TypeScript Integration **Challenge**: Type definitions for GM functions **Solution**: Created proper TypeScript interfaces and type declarations ### 4. Extension Support **Challenge**: Chrome extensions don't work in headless mode **Solution**: Always launch Chrome in non-headless mode when extensions are needed ### 5. Automation Detection **Challenge**: Chrome's "Automation Controlled" banner can interfere with extensions **Solution**: Added option to disable automation detection via ignoreDefaultArgs ## Best Practices Identified 1. **Injection Order** - Always inject dependencies before dependent code - Verify script loading sequence - Handle initialization timing carefully 2. **Error Handling** - Implement try-catch blocks for script injection - Log errors for debugging - Provide meaningful error messages 3. **Storage Management** - Use consistent key prefixing - Implement proper data serialization - Verify storage operations 4. **Code Organization** - Separate concerns (GM functions, userscript, API key management) - Maintain clear initialization sequence - Document critical dependencies ## Future Improvements 1. **Enhanced Error Handling** - Add more detailed error messages - Implement retry mechanisms - Add error recovery strategies 2. **Performance Optimization** - Minimize script injection overhead - Optimize storage operations - Implement caching where appropriate 3. **Feature Expansion** - Add support for more GM functions - Implement additional debugging capabilities - Add script dependency management - Support for loading packed (.crx) extensions - Add extension management capabilities (enable/disable/reload) - Implement extension debugging features 4. **Extension Support Enhancements** - Add support for extension manifest v3 - Implement extension permission management - Add extension state persistence between sessions 5. **Chrome Profile Management** - Successfully implemented custom user data directory support - Profile settings and extensions persist between sessions - Extensions maintain their state and configurations - Default profile loads automatically if no custom profile specified - Cannot directly access extension internal data through CDP - Extension APIs (like chrome.management) are restricted due to security - Extensions must be interacted with through their UI or public APIs - Proper handling of profile paths and permissions required - Prevent Puppeteer from disabling extensions using ignoreDefaultArgs ## Puppeteer Integration Insights ### 1. MCP Tool Architecture - **Modular Command Structure** - Separate handlers for each Puppeteer command - Type guards ensure parameter validation - Clear separation of concerns in tool definitions ### 2. Type Safety - Created comprehensive TypeScript interfaces for all commands - Runtime type checking prevents invalid parameter passing - Error messages provide clear feedback on parameter issues ### 3. Testing Approach - HTML test page for verifying all commands - Sequential testing ensures command interdependencies - Real-time verification of command results - Screenshot capability helps verify visual outcomes ### 4. Error Handling - Proper handling of missing pages/contexts - Timeout handling for element waiting - Graceful failure handling for element interactions ### 5. Page Management - Active page tracking improves reliability - Automatic page creation when needed - Proper cleanup of page resources ### 6. Performance Considerations - Delayed typing mimics human interaction - Wait conditions prevent race conditions - Screenshot optimization options ### 7. Documentation - Clear command reference with examples - Parameter descriptions and requirements - Consistent documentation format across commands ### 8. Code Organization - Separate files for different concerns: - Tool definitions - Command handlers - Type definitions - Tests - Makes codebase more maintainable ## GitHub Update Process ### 1. Staged Commits - Make changes in logical, atomic units - Test each change before committing - Use descriptive commit messages that explain the "why" not just the "what" ### 2. Documentation Updates 1. First update implementation code 2. Test the changes thoroughly 3. Update documentation to reflect changes 4. Review documentation for accuracy 5. Commit documentation separately from code ### 3. Commit Message Structure ``` [Component] Brief description of change - Detailed explanation of changes - Reasoning behind changes - Impact on existing functionality ``` Example: ``` [Notifications] Enhance system with fallback support - Add multi-level fallback system - Improve permission handling - Add comprehensive testing - Update documentation with examples ``` ### 4. Testing Before Push 1. Build project locally 2. Run all tests 3. Verify documentation accuracy 4. Push changes only after all checks pass ## Notification System Learnings ### 1. Permission Handling - Request permissions early - Handle all permission states (granted, denied, default) - Provide graceful fallbacks for each state ### 2. Fallback System Design - Implement multiple fallback levels - Maintain consistent behavior across fallbacks - Log fallback usage for monitoring ### 3. Testing Improvements - Test all notification types - Verify callback execution - Check permission scenarios - Test sequential notifications - Monitor performance impact ### 4. UI Considerations - Consistent styling across fallbacks - Proper cleanup of UI elements - Handle window focus properly - Support emoji in notifications ### 5. Error Recovery - Graceful handling of failed notifications - Clear error logging - Multiple fallback options - User feedback preservation ## Conclusion The Chrome debug MCP server implementation provided valuable insights into browser automation, script injection, and debugging. The addition of Puppeteer commands and enhanced notification system significantly improved the server's capabilities, providing a robust foundation for automated browser interaction through the MCP interface. The structured GitHub update process ensures maintainable and well-documented code changes.