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

cd /home/solar/docker-appliance/mcp-servers/web-proxy-mcp
npm install

Basic Usage

# 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:

{
  "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

// 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

// 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

// 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:

{
  "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:

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.