Web Proxy MCP Server

# Web Proxy MCP Server Intelligent HTTP/HTTPS proxy server with Model Context Protocol (MCP) integration for automated traffic monitoring, analysis, and browser setup. ## 🌟 Features ### Core Proxy Capabilities - **Selective Proxying**: Only monitor specific domains while allowing direct access to others - **HTTP/HTTPS Support**: Full support for HTTP requests and HTTPS tunneling via CONNECT - **PAC File Generation**: Automatic Proxy Auto-Configuration file generation - **Traffic Capture**: Detailed request/response logging with optional header/body capture ### MCP Integration - **16 MCP Tools**: Complete automation via Model Context Protocol - **Dynamic Configuration**: Add/remove monitored domains at runtime - **Real-time Analysis**: Traffic pattern analysis and performance metrics - **HAR Export**: Standard HTTP Archive format for external analysis ### Browser Setup Automation - **Multi-Browser Support**: Chrome, Firefox, cURL, and system-wide proxy setup - **Script Generation**: Automated setup script generation for different platforms - **One-Click Configuration**: Simple browser proxy configuration ## 🚀 Quick Start ### Installation ```bash cd /home/solar/docker-appliance/mcp-servers/web-proxy-mcp npm install ``` ### Basic Usage ```bash # Start the proxy server npm start # Or run directly node index.js ``` ### Add to VS Code MCP Configuration Add to your VS Code `mcp.json`: ```json { "mcpServers": { "web-proxy-mcp": { "command": "node", "args": ["/home/solar/docker-appliance/mcp-servers/web-proxy-mcp/index.js"], "env": {} } } } ``` ## 🔧 MCP Tools ### Target Management - `proxy_add_target`: Add domains to monitor - `proxy_remove_target`: Remove domains from monitoring - `proxy_list_targets`: List all configured targets - `proxy_update_target`: Update target configuration ### Server Control - `proxy_start_server`: Start the proxy server - `proxy_stop_server`: Stop the proxy server - `proxy_server_status`: Get server status and statistics ### Browser Setup - `proxy_generate_setup`: Generate browser setup scripts - `proxy_get_pac_file`: Get PAC file content ### Traffic Analysis - `proxy_get_traffic_log`: View captured traffic - `proxy_export_har`: Export traffic as HAR file - `proxy_clear_traffic_log`: Clear traffic logs - `proxy_analyze_traffic`: Analyze traffic patterns ### Configuration - `proxy_import_config`: Import configuration from file - `proxy_export_config`: Export configuration to file ### Advanced Analysis - `proxy_analyze_traffic`: Traffic pattern analysis - `proxy_get_performance_metrics`: Performance monitoring ## 📊 Usage Examples ### 1. Monitor Specific API ```javascript // Add target domain await mcp.callTool('proxy_add_target', { domain: 'api.example.com', description: 'Main API endpoint', captureHeaders: true, captureBody: true }); // Start proxy server await mcp.callTool('proxy_start_server', { port: 8080, host: 'localhost' }); // Generate browser setup await mcp.callTool('proxy_generate_setup', { proxyHost: 'localhost', proxyPort: 8080 }); ``` ### 2. Traffic Analysis ```javascript // Get traffic log const traffic = await mcp.callTool('proxy_get_traffic_log', { domain: 'api.example.com', limit: 50 }); // Analyze patterns const analysis = await mcp.callTool('proxy_analyze_traffic', { domain: 'api.example.com', timeframe: '24h', groupBy: 'method' }); // Export HAR file await mcp.callTool('proxy_export_har', { domain: 'api.example.com', filename: 'api-traffic-analysis' }); ``` ### 3. Browser Configuration ```javascript // Get PAC file for manual setup const pac = await mcp.callTool('proxy_get_pac_file', { proxyHost: 'localhost', proxyPort: 8080 }); // Generate all setup scripts const setup = await mcp.callTool('proxy_generate_setup', { browsers: ['chrome', 'firefox', 'system'] }); ``` ## 🔄 Workflow Integration ### Development Debugging 1. Add your development domains to the proxy 2. Start the proxy server 3. Configure your browser to use the proxy 4. Monitor API calls and responses in real-time 5. Export traffic logs for analysis ### API Testing 1. Configure proxy for your test endpoints 2. Run automated tests through the proxy 3. Capture all HTTP traffic automatically 4. Analyze response times and error patterns 5. Export detailed HAR files for reporting ### Security Analysis 1. Monitor specific domains for security testing 2. Capture detailed request/response headers 3. Analyze traffic patterns for anomalies 4. Export logs for security review ## 📁 Project Structure ``` web-proxy-mcp/ ├── index.js # Main MCP server entry point ├── package.json # Node.js dependencies ├── src/ │ ├── proxy/ │ │ ├── target-manager.js # Domain target management │ │ └── proxy-server.js # HTTP/HTTPS proxy server │ ├── traffic/ │ │ └── traffic-analyzer.js # Traffic capture and analysis │ ├── setup/ │ │ └── browser-setup.js # Browser configuration scripts │ └── tools/ │ ├── tool-definitions.js # MCP tool schemas │ └── tool-handlers.js # MCP tool implementations ├── data/ │ ├── targets.json # Persistent target configuration │ └── traffic-log.json # Persistent traffic logs └── setup-scripts/ # Generated browser setup scripts ├── chrome-proxy-setup.sh ├── firefox-proxy-setup.sh ├── curl-proxy-setup.sh ├── system-proxy-setup.sh └── proxy.pac ``` ## ⚙️ Configuration ### Target Configuration Targets are stored in `data/targets.json`: ```json { "httpbin.org": { "domain": "httpbin.org", "description": "HTTP testing service", "enabled": true, "captureHeaders": true, "captureBody": false, "createdAt": "2025-01-11T10:00:00.000Z" } } ``` ### Traffic Analysis - **Max Entries**: 5,000 traffic entries (configurable) - **Persistence**: Automatic save/load from `data/traffic-log.json` - **HAR Export**: Standard HTTP Archive format - **Real-time Metrics**: Performance and usage statistics ### Proxy Server - **Default Port**: 8080 (configurable) - **PAC File**: Automatic generation at `/proxy.pac` - **Protocol Support**: HTTP and HTTPS (via CONNECT tunneling) - **Performance Monitoring**: Built-in metrics collection ## 🔒 Security Considerations - **Local Only**: Default configuration binds to localhost only - **Selective Monitoring**: Only configured domains are proxied - **No Body Capture by Default**: Sensitive data protection - **Configurable Headers**: Optional header capture for debugging ## 🤝 Integration with Other Tools ### VS Code Workflow 1. Add to MCP configuration in VS Code 2. Use AI assistant to manage proxy configuration 3. Automate traffic analysis through AI commands 4. Generate reports and documentation automatically ### Development Workflow 1. Monitor local development APIs 2. Test staging environment interactions 3. Debug production API calls (headers only) 4. Performance testing and analysis ## 📈 Performance - **Minimal Overhead**: Only proxied domains incur processing cost - **Efficient Storage**: Configurable traffic log retention - **Background Processing**: Non-blocking traffic capture - **Memory Management**: Automatic cleanup of old entries ## 🛠️ Advanced Features ### Custom PAC Generation The proxy generates intelligent PAC files that only route monitored domains through the proxy, maintaining normal browsing speed for other sites. ### Traffic Pattern Analysis Built-in analysis tools help identify: - API usage patterns - Response time trends - Error rate monitoring - Domain-specific metrics ### Multi-Browser Support Automated setup scripts for: - Chrome (with security flags for testing) - Firefox (with custom profile) - System-wide proxy (Linux/macOS) - Command-line tools (cURL) ## 🔧 Troubleshooting ### Common Issues 1. **Port in use**: Change the proxy port in server configuration 2. **Browser not using proxy**: Verify PAC file URL or manual proxy settings 3. **HTTPS issues**: Check certificate handling in browser settings 4. **No traffic captured**: Ensure domains are added to target list ### Debug Mode Run with debug logging: ```bash DEBUG=web-proxy-mcp node index.js ``` ### Logs Location - Server logs: Console output - Traffic logs: `data/traffic-log.json` - Target config: `data/targets.json` ## 📝 License This project is part of the Docker Appliance MCP server collection and follows the same licensing terms. ## 🤖 AI Assistant Integration This proxy is designed to work seamlessly with AI assistants through MCP: - **Natural Language Control**: "Start monitoring api.example.com" - **Automated Analysis**: "Analyze the last hour of API traffic" - **Report Generation**: "Export traffic data for the payment API" - **Configuration Management**: "Set up Chrome to use the proxy" The MCP integration makes this proxy particularly powerful for AI-assisted development and debugging workflows.