cbrowser 18.63.0 → 18.63.2

package/docs/REMOTE-MCP-SERVER.md

@@ -1,569 +0,0 @@
-> **This documentation is no longer maintained here.**
->
-> For the latest version, please visit: **[Remote MCP Server Deployment Guide](https://cbrowser.ai/docs/REMOTE-MCP-SERVER)**
-
----
-
-# Remote MCP Server Deployment Guide
-
-Deploy CBrowser (Cognitive Browser) as a remote MCP server for claude.ai custom connectors. This allows your entire team to use CBrowser through Claude without local installation.
-
-## Architecture Overview
-
-```
-┌─────────────────┐     HTTPS      ┌─────────────────┐     HTTP      ┌─────────────────┐
-│   claude.ai     │ ──────────────>│  Nginx/Caddy    │ ────────────> │ CBrowser MCP    │
-│  (Custom MCP)   │   :443         │  Reverse Proxy  │  :3100        │    Server       │
-└─────────────────┘                └─────────────────┘               └─────────────────┘
-                                          │
-                                   ┌──────┴──────┐
-                                   │ Cloudflare  │ (optional)
-                                   │   or SSL    │
-                                   └─────────────┘
-```
-
-## Prerequisites
-
-### System Requirements
-
-| Requirement | Minimum | Recommended |
-|-------------|---------|-------------|
-| **OS** | Ubuntu 20.04+ / Debian 11+ | Ubuntu 22.04 LTS |
-| **RAM** | 2 GB | 4 GB |
-| **CPU** | 2 cores | 4 cores |
-| **Storage** | 10 GB | 20 GB |
-| **Node.js** | 18.x | 20.x LTS |
-
-### Required Software
-
-```bash
-# Update system
-sudo apt update && sudo apt upgrade -y
-
-# Install Node.js 20.x
-curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
-sudo apt install -y nodejs
-
-# Install nginx
-sudo apt install -y nginx
-
-# Verify installations
-node --version  # Should be v20.x
-nginx -v        # Should show nginx version
-```
-
-### Domain & DNS
-
-You'll need:
-- A domain name (e.g., `cbrowser-mcp.yourdomain.com`)
-- DNS A record pointing to your server's IP
-- SSL certificate (Let's Encrypt or Cloudflare Origin)
-
----
-
-## Step 1: Install CBrowser
-
-```bash
-# Create application directory
-sudo mkdir -p /opt/cbrowser
-cd /opt/cbrowser
-
-# Install CBrowser globally or locally
-npm init -y
-npm install cbrowser
-
-# Install Playwright browsers
-npx playwright install chromium firefox webkit
-npx playwright install-deps  # Install system dependencies
-
-# Create data directory
-sudo mkdir -p /home/$USER/.cbrowser/{sessions,screenshots,videos,har,personas,scenarios,helpers,audit,baselines,browser-state,cache,journeys,performance,visual,tests,repairs,config,visual-baselines,cross-browser,responsive,ab-comparison}
-sudo chown -R $USER:$USER /home/$USER/.cbrowser
-```
-
----
-
-## Step 2: Create Systemd Service
-
-Create the service file:
-
-```bash
-sudo nano /etc/systemd/system/cbrowser-mcp.service
-```
-
-Paste this configuration:
-
-```ini
-[Unit]
-Description=CBrowser Remote MCP Server
-After=network.target
-
-[Service]
-Type=simple
-User=YOUR_USERNAME
-Group=YOUR_GROUP
-WorkingDirectory=/opt/cbrowser
-
-# Create data directories on startup
-ExecStartPre=/bin/bash -c 'mkdir -p /home/YOUR_USERNAME/.cbrowser/{sessions,screenshots,videos,har,personas,scenarios,helpers,audit,baselines,browser-state,cache,journeys,performance,visual,tests,repairs,config,visual-baselines,cross-browser,responsive,ab-comparison}'
-
-# Start the MCP server
-ExecStart=/usr/bin/node node_modules/cbrowser/dist/mcp-server-remote.js
-
-Restart=on-failure
-RestartSec=5
-
-# Environment
-Environment=NODE_ENV=production
-Environment=PORT=3100
-Environment=HOST=127.0.0.1
-Environment=MCP_SESSION_MODE=stateless
-Environment=CBROWSER_DATA_DIR=/home/YOUR_USERNAME/.cbrowser
-
-# Authentication (optional - remove to allow open access)
-# Generate a secure key: openssl rand -hex 32
-Environment=MCP_API_KEY=your-secure-api-key-here
-# Or use multiple keys: Environment=MCP_API_KEYS=key1,key2,key3
-
-# Security hardening (optional but recommended)
-NoNewPrivileges=yes
-ProtectSystem=strict
-ProtectHome=read-only
-PrivateTmp=yes
-ReadWritePaths=/opt/cbrowser /home/YOUR_USERNAME/.cbrowser /home/YOUR_USERNAME/.cache/ms-playwright
-
-[Install]
-WantedBy=multi-user.target
-```
-
-**Important:** Replace `YOUR_USERNAME` and `YOUR_GROUP` with your actual user/group.
-
-Enable and start the service:
-
-```bash
-# Reload systemd
-sudo systemctl daemon-reload
-
-# Enable on boot
-sudo systemctl enable cbrowser-mcp
-
-# Start the service
-sudo systemctl start cbrowser-mcp
-
-# Check status
-sudo systemctl status cbrowser-mcp
-```
-
-Verify it's running:
-
-```bash
-curl http://localhost:3100/health
-# Should return: {"status":"ok","version":"7.x.x"}
-```
-
----
-
-## Step 3: Configure Nginx Reverse Proxy
-
-Create nginx configuration:
-
-```bash
-sudo nano /etc/nginx/sites-available/cbrowser-mcp.conf
-```
-
-### Option A: With Cloudflare (Recommended)
-
-```nginx
-# HTTP redirect to HTTPS
-server {
-    listen 80;
-    listen [::]:80;
-    server_name cbrowser-mcp.yourdomain.com;
-    return 301 https://$server_name$request_uri;
-}
-
-# HTTPS with Cloudflare Origin Certificate
-server {
-    listen 443 ssl http2;
-    listen [::]:443 ssl http2;
-    server_name cbrowser-mcp.yourdomain.com;
-
-    # Cloudflare Origin Certificate
-    ssl_certificate /etc/ssl/certs/yourdomain-origin.pem;
-    ssl_certificate_key /etc/ssl/private/yourdomain-origin.key;
-
-    # SSL security settings
-    ssl_protocols TLSv1.2 TLSv1.3;
-    ssl_prefer_server_ciphers on;
-    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
-
-    # Reverse proxy to MCP server
-    location / {
-        proxy_pass http://127.0.0.1:3100;
-        proxy_http_version 1.1;
-
-        # WebSocket/SSE support for MCP
-        proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection "upgrade";
-
-        # Standard proxy headers
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-
-        # Extended timeouts for long-running MCP operations
-        proxy_connect_timeout 300s;
-        proxy_send_timeout 300s;
-        proxy_read_timeout 300s;
-
-        # Disable buffering for SSE
-        proxy_buffering off;
-        proxy_cache off;
-
-        # MCP session header passthrough
-        proxy_pass_header Mcp-Session-Id;
-    }
-
-    # Logging
-    access_log /var/log/nginx/cbrowser-mcp.access.log;
-    error_log /var/log/nginx/cbrowser-mcp.error.log;
-}
-```
-
-### Option B: With Let's Encrypt
-
-```bash
-# Install Certbot
-sudo apt install certbot python3-certbot-nginx
-
-# Get certificate
-sudo certbot --nginx -d cbrowser-mcp.yourdomain.com
-```
-
-Enable the site:
-
-```bash
-# Enable site
-sudo ln -s /etc/nginx/sites-available/cbrowser-mcp.conf /etc/nginx/sites-enabled/
-
-# Test configuration
-sudo nginx -t
-
-# Reload nginx
-sudo systemctl reload nginx
-```
-
----
-
-## Step 4: Cloudflare Configuration (Optional)
-
-If using Cloudflare:
-
-### DNS Settings
-
-1. Add an **A record**:
-   - Name: `cbrowser-mcp`
-   - IPv4 address: Your server IP
-   - Proxy status: **Proxied** (orange cloud)
-
-### SSL/TLS Settings
-
-1. Go to **SSL/TLS → Overview**
-2. Set encryption mode to **Full (strict)**
-
-### Origin Certificates
-
-1. Go to **SSL/TLS → Origin Server**
-2. Click **Create Certificate**
-3. Generate with:
-   - Key type: RSA (2048)
-   - Hostnames: `cbrowser-mcp.yourdomain.com`
-   - Validity: 15 years
-4. Download and save:
-   - Certificate → `/etc/ssl/certs/yourdomain-origin.pem`
-   - Private key → `/etc/ssl/private/yourdomain-origin.key`
-
-### Page Rules (Recommended)
-
-Create a page rule to bypass caching:
-
-1. Go to **Rules → Page Rules**
-2. Create rule:
-   - URL: `cbrowser-mcp.yourdomain.com/*`
-   - Setting: **Cache Level → Bypass**
-
----
-
-## Step 5: Test the Deployment
-
-### Health Check
-
-```bash
-curl https://cbrowser-mcp.yourdomain.com/health
-# {"status":"ok","version":"7.4.6","auth":true,"auth_methods":{"api_key":true,"oauth":true}}
-```
-
-### Info Endpoint
-
-```bash
-curl https://cbrowser-mcp.yourdomain.com/info
-```
-
-### MCP Initialize (for debugging)
-
-```bash
-curl -X POST https://cbrowser-mcp.yourdomain.com/mcp \
-  -H "Content-Type: application/json" \
-  -H "Accept: application/json, text/event-stream" \
-  -d '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'
-```
-
----
-
-## Step 6: Connect to Claude.ai
-
-### Option A: With Auth0 OAuth (Recommended for production)
-
-For secure authentication with claude.ai, set up Auth0 OAuth:
-
-1. See the [Auth0 Setup Guide](AUTH0-SETUP.md) to configure Auth0
-2. Add Auth0 environment variables to your systemd service:
-   ```ini
-   Environment=AUTH0_DOMAIN=your-tenant.auth0.com
-   Environment=AUTH0_AUDIENCE=https://cbrowser-mcp.yourdomain.com/
-   ```
-3. Restart the service: `sudo systemctl restart cbrowser-mcp`
-4. Go to [claude.ai](https://claude.ai) → **Settings → Connectors**
-5. Click **Add Custom Connector**
-6. Enter URL: `https://cbrowser-mcp.yourdomain.com/mcp`
-7. Enter your Auth0 **Client ID** and **Client Secret** when prompted
-8. Complete the OAuth login flow
-
-### Option B: Open Access (Public Demo)
-
-For a public demo server without authentication:
-
-1. Remove `MCP_API_KEY` from your systemd service
-2. Remove `AUTH0_*` variables
-3. Add rate limiting in nginx (see Security section)
-4. Go to [claude.ai](https://claude.ai) → **Settings → Connectors**
-5. Add URL: `https://cbrowser-mcp.yourdomain.com/mcp`
-
-You should see 40 CBrowser tools become available in Claude.
-
----
-
-## Security Considerations
-
-### Firewall Rules
-
-```bash
-# Allow only necessary ports
-sudo ufw allow 22/tcp    # SSH
-sudo ufw allow 80/tcp    # HTTP (redirect)
-sudo ufw allow 443/tcp   # HTTPS
-sudo ufw enable
-```
-
-### Authentication (v7.4.6+)
-
-CBrowser Remote MCP Server supports two authentication methods:
-
-#### Method 1: Auth0 OAuth (for claude.ai)
-
-Claude.ai requires OAuth 2.1 authentication. Set up Auth0:
-
-```bash
-# Auth0 OAuth (enables claude.ai login)
-Environment=AUTH0_DOMAIN=your-tenant.auth0.com
-Environment=AUTH0_AUDIENCE=https://cbrowser-mcp.yourdomain.com/
-```
-
-See [Auth0 Setup Guide](AUTH0-SETUP.md) for full configuration.
-
-**OAuth Endpoints:**
-- `/.well-known/oauth-protected-resource` - OAuth metadata discovery
-- `/mcp` - MCP endpoint (requires valid JWT)
-
-#### Method 2: API Key (for Claude Code CLI)
-
-For programmatic access and Claude Code CLI:
-
-```bash
-# Single API key
-Environment=MCP_API_KEY=your-secure-key
-
-# Multiple API keys (for different users/services)
-Environment=MCP_API_KEYS=user1-key,user2-key,service-key
-```
-
-**Generate a secure key:**
-
-```bash
-openssl rand -hex 32
-```
-
-**Client usage:**
-
-```bash
-# Bearer token (recommended)
-curl -H "Authorization: Bearer your-api-key" https://your-server/mcp
-
-# X-API-Key header (alternative)
-curl -H "X-API-Key: your-api-key" https://your-server/mcp
-```
-
-#### Dual Authentication
-
-Both methods can be enabled simultaneously:
-- **OAuth** - For claude.ai web interface
-- **API Key** - For Claude Code CLI and scripts
-
-**Public Endpoints (no auth required):**
-- `/health` - Server health status
-- `/info` - Server information
-- `/.well-known/oauth-protected-resource` - OAuth metadata
-
-**Protected Endpoints:**
-- `/mcp` - MCP endpoint (requires valid auth)
-
-### Rate Limiting
-
-Add to nginx config:
-
-```nginx
-# In http block of /etc/nginx/nginx.conf
-limit_req_zone $binary_remote_addr zone=mcp:10m rate=10r/s;
-
-# In server block
-location / {
-    limit_req zone=mcp burst=20 nodelay;
-    # ... rest of config
-}
-```
-
----
-
-## Monitoring
-
-### View Logs
-
-```bash
-# Service logs
-sudo journalctl -u cbrowser-mcp -f
-
-# Nginx access logs
-sudo tail -f /var/log/nginx/cbrowser-mcp.access.log
-
-# Nginx error logs
-sudo tail -f /var/log/nginx/cbrowser-mcp.error.log
-```
-
-### Health Check Script
-
-Create `/opt/cbrowser/healthcheck.sh`:
-
-```bash
-#!/bin/bash
-response=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:3100/health)
-if [ "$response" != "200" ]; then
-    echo "CBrowser MCP unhealthy, restarting..."
-    sudo systemctl restart cbrowser-mcp
-fi
-```
-
-Add to cron:
-
-```bash
-# Run every 5 minutes
-*/5 * * * * /opt/cbrowser/healthcheck.sh
-```
-
----
-
-## Troubleshooting
-
-### Service Won't Start
-
-```bash
-# Check logs
-sudo journalctl -u cbrowser-mcp -n 50 --no-pager
-
-# Common fixes:
-# 1. Permission issues
-sudo chown -R $USER:$USER /home/$USER/.cbrowser
-sudo chmod -R 755 /home/$USER/.cbrowser
-
-# 2. Missing Playwright browsers
-cd /opt/cbrowser && npx playwright install
-
-# 3. Port already in use
-sudo lsof -i :3100
-```
-
-### "Read-only filesystem" Error
-
-The systemd security hardening may be too restrictive:
-
-```bash
-# Check ReadWritePaths includes all needed directories
-sudo systemctl cat cbrowser-mcp | grep ReadWritePaths
-```
-
-### Browser Timeout Errors
-
-```bash
-# Install all browser dependencies
-npx playwright install-deps
-
-# Or install specific deps for Ubuntu
-sudo apt install -y libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 \
-  libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 \
-  libxrandr2 libgbm1 libpango-1.0-0 libcairo2 libasound2
-```
-
-### Cloudflare 522 Errors
-
-1. Verify nginx is running: `sudo systemctl status nginx`
-2. Check CBrowser is listening: `curl localhost:3100/health`
-3. Check firewall allows 443: `sudo ufw status`
-
-### MCP Connection Fails in Claude
-
-1. Verify URL is correct: `https://your-domain/mcp` (not `/mcp/`)
-2. Check SSL certificate: `curl -v https://your-domain/health`
-3. Verify Accept header support (claude.ai sends `Accept: application/json, text/event-stream`)
-
----
-
-## Updating CBrowser
-
-```bash
-# Stop service
-sudo systemctl stop cbrowser-mcp
-
-# Update package
-cd /opt/cbrowser
-npm update cbrowser
-
-# Restart service
-sudo systemctl start cbrowser-mcp
-
-# Verify version
-curl https://cbrowser-mcp.yourdomain.com/health
-```
-
----
-
-## Alternative: Docker Deployment
-
-Coming soon. See [Docker documentation](./DOCKER.md).
-
----
-
-## Getting Help
-
-- **Issues:** [GitHub Issues](https://github.com/alexandriashai/cbrowser/issues)
-- **Discussions:** [GitHub Discussions](https://github.com/alexandriashai/cbrowser/discussions)
-- **Examples:** See the `deployment/` directory for reference configs