Glama
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

## Conclusion
The Chrome debug MCP server implementation provided valuable insights into browser automation, script injection, and debugging. The solutions developed here can serve as a foundation for future browser automation and userscript management projects.