cbrowser 18.63.0 → 18.63.2

package/docs/INSTALL.md

@@ -1,274 +0,0 @@
-> **This documentation is no longer maintained here.**
->
-> For the latest version, please visit: **[CBrowser Installation Guide](https://cbrowser.ai/docs/INSTALL)**
-
----
-
-# CBrowser Installation Guide
-
-## Installation Options
-
-### Option 1: Claude Skill (Claude Code Users)
-
-If you use [Claude Code](https://claude.ai/claude-code), install CBrowser as a skill:
-
-```bash
-# One-line installation
-curl -fsSL https://raw.githubusercontent.com/alexandriashai/cbrowser/main/scripts/install-skill.sh | bash
-
-# Or via npm CLI
-npx cbrowser install-skill
-```
-
-After installation:
-
-1. Add to `~/.claude/skills/skill-index.json`:
-```json
-{"CBrowser": "~/.claude/skills/CBrowser/SKILL.md"}
-```
-
-2. Install dependencies:
-```bash
-npm install -g cbrowser
-npx playwright install
-```
-
-See the [Claude Skill Installation wiki page](https://github.com/alexandriashai/cbrowser/wiki/Claude-Skill-Installation) for full details.
-
----
-
-### Option 2: npm Package (Standard)
-
-```bash
-# npm
-npm install cbrowser
-
-# yarn
-yarn add cbrowser
-
-# bun
-bun add cbrowser
-
-# pnpm
-pnpm add cbrowser
-```
-
-## Browser Setup
-
-CBrowser uses Playwright for browser automation. After installing, you need to install the browser binaries:
-
-```bash
-npx playwright install chromium
-```
-
-This downloads Chromium (~150MB). For full browser support:
-
-```bash
-npx playwright install  # Installs Chromium, Firefox, and WebKit
-```
-
-## Verify Installation
-
-```bash
-npx cbrowser help
-```
-
-You should see the help text with all available commands.
-
-## Configuration
-
-### Data Directory
-
-By default, CBrowser stores data in `~/.cbrowser/`. To change this:
-
-```bash
-# Set environment variable
-export CBROWSER_DATA_DIR="/path/to/custom/dir"
-
-# Or per-command
-CBROWSER_DATA_DIR="./data" npx cbrowser navigate "https://example.com"
-```
-
-### Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `CBROWSER_DATA_DIR` | `~/.cbrowser` | Data storage directory |
-| `CBROWSER_HEADLESS` | `true` | Run headless by default (set to `false` for GUI) |
-| `CBROWSER_TIMEOUT` | `30000` | Default timeout (ms) |
-| `CBROWSER_VIEWPORT_WIDTH` | `1280` | Default viewport width |
-| `CBROWSER_VIEWPORT_HEIGHT` | `800` | Default viewport height |
-| `CBROWSER_VERBOSE` | `false` | Enable verbose logging |
-
-### Persistent Configuration
-
-Create a `.cbrowserrc` file in your project or home directory:
-
-```json
-{
-  "headless": true,
-  "timeout": 60000,
-  "viewportWidth": 1920,
-  "viewportHeight": 1080
-}
-```
-
-## Platform-Specific Notes
-
-### Linux
-
-If running on a headless server, you may need additional dependencies:
-
-```bash
-# Ubuntu/Debian
-sudo apt-get install libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1 libpango-1.0-0 libcairo2 libasound2
-
-# Or use Playwright's helper
-npx playwright install-deps chromium
-```
-
-### macOS
-
-No additional setup required. Works out of the box.
-
-### Windows
-
-No additional setup required. Works out of the box.
-
-### Docker
-
-```dockerfile
-FROM node:20-slim
-
-# Install Playwright dependencies
-RUN apt-get update && apt-get install -y \
-    libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \
-    libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 \
-    libgbm1 libpango-1.0-0 libcairo2 libasound2 \
-    && rm -rf /var/lib/apt/lists/*
-
-WORKDIR /app
-COPY package*.json ./
-RUN npm install
-
-# Install browser
-RUN npx playwright install chromium
-
-COPY . .
-
-# Run in headless mode
-ENV CBROWSER_HEADLESS=true
-
-CMD ["npx", "cbrowser", "help"]
-```
-
-## CI/CD Integration
-
-### GitHub Actions
-
-```yaml
-name: Browser Tests
-
-on: [push, pull_request]
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-
-      - run: npm install
-      - run: npx playwright install chromium
-
-      - name: Run CBrowser tests
-        run: npm test
-        env:
-          CBROWSER_HEADLESS: true
-```
-
-### GitLab CI
-
-```yaml
-test:
-  image: mcr.microsoft.com/playwright:v1.40.0
-  script:
-    - npm install
-    - npm test
-  variables:
-    CBROWSER_HEADLESS: "true"
-```
-
-## Troubleshooting
-
-### "Browser not found" Error
-
-```bash
-# Reinstall browser
-npx playwright install chromium --force
-```
-
-### Permission Denied on Linux
-
-```bash
-# Make data directory writable
-sudo chown -R $USER:$USER ~/.cbrowser
-chmod -R 755 ~/.cbrowser
-```
-
-### Timeout Errors
-
-Increase the default timeout:
-
-```bash
-CBROWSER_TIMEOUT=60000 npx cbrowser navigate "https://slow-site.com"
-```
-
-### Display Issues (Linux Server)
-
-Use headless mode:
-
-```bash
-CBROWSER_HEADLESS=true npx cbrowser navigate "https://example.com"
-```
-
-Or set up a virtual display:
-
-```bash
-# Install Xvfb
-sudo apt-get install xvfb
-
-# Run with virtual display
-xvfb-run npx cbrowser navigate "https://example.com"
-```
-
-## Upgrading
-
-```bash
-# npm
-npm update cbrowser
-
-# Check version
-npx cbrowser --version
-```
-
-## Uninstalling
-
-```bash
-# Remove package
-npm uninstall cbrowser
-
-# Remove data directory (optional)
-rm -rf ~/.cbrowser
-
-# Remove Playwright browsers (optional)
-rm -rf ~/.cache/ms-playwright
-```
-
-## Getting Help
-
-- Check [README.md](../README.md) for usage examples
-- Open an issue on GitHub for bugs
-- See [CONTRIBUTING.md](../CONTRIBUTING.md) for development setup

package/docs/MCP-INTEGRATION.md

@@ -1,301 +0,0 @@
-> **This documentation is no longer maintained here.**
->
-> For the latest version, please visit: **[MCP Server Integration](https://cbrowser.ai/docs/MCP-INTEGRATION)**
-
----
-
-# MCP Server Integration
-
-CBrowser provides full Model Context Protocol (MCP) integration for Claude Desktop and claude.ai.
-
-## Quick Setup
-
-### Local MCP (Claude Desktop)
-
-Add to your `claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "cbrowser": {
-      "command": "npx",
-      "args": ["cbrowser", "mcp-server"]
-    }
-  }
-}
-```
-
-### Remote MCP (claude.ai)
-
-**Public Demo Server** (rate-limited, for evaluation):
-```
-URL: https://demo.cbrowser.ai/mcp
-Rate limit: 5 requests/minute, burst of 10
-```
-
-**Deploy Your Own:**
-```bash
-# Default (no auth)
-npx cbrowser mcp-remote
-
-# With API key
-MCP_API_KEY=your-secret npx cbrowser mcp-remote
-
-# With Auth0 OAuth
-AUTH0_DOMAIN=your-tenant.auth0.com \
-AUTH0_AUDIENCE=https://your-server/ \
-npx cbrowser mcp-remote
-
-# Custom port
-PORT=8080 npx cbrowser mcp-remote
-```
-
-## All 91 MCP Tools
-
-### Navigation (5 tools)
-
-| Tool | Description |
-|------|-------------|
-| `navigate` | Navigate to URL with intelligent wait detection |
-| `screenshot` | Capture page screenshot |
-| `extract` | Extract structured data (links, headings, forms, images, text) |
-| `cloudflare_detect` | Detect Cloudflare protection |
-| `cloudflare_wait` | Wait for Cloudflare challenge completion |
-
-### Interaction (4 tools)
-
-| Tool | Description |
-|------|-------------|
-| `click` | Click element by selector or description |
-| `smart_click` | Self-healing click with retry and selector recovery |
-| `fill` | Fill form input with value |
-| `scroll` | Scroll page or element |
-
-### Testing (3 tools)
-
-| Tool | Description |
-|------|-------------|
-| `nl_test_file` | Run natural language test suite from file |
-| `nl_test_inline` | Run natural language tests from inline content |
-| `repair_test` | AI-powered test repair for broken tests |
-| `detect_flaky_tests` | Identify unreliable tests by running multiple times |
-
-### Visual Testing (6 tools)
-
-| Tool | Description |
-|------|-------------|
-| `visual_baseline` | Capture visual baseline for URL |
-| `visual_regression` | Compare current page against baseline |
-| `cross_browser_test` | Test across Chrome, Firefox, Safari |
-| `cross_browser_diff` | Quick metrics comparison across browsers |
-| `responsive_test` | Test across viewport sizes |
-| `ab_comparison` | Compare two URLs visually |
-
-### Cognitive Simulation (3 tools)
-
-| Tool | Description |
-|------|-------------|
-| `cognitive_journey_init` | Initialize cognitive user simulation |
-| `cognitive_journey_update_state` | Update mental state during journey |
-| `compare_personas` | Compare experience across personas |
-
-### Persona Questionnaire (3 tools) - *New in v16.6.0*
-
-| Tool | Description |
-|------|-------------|
-| `persona_questionnaire_get` | Generate questionnaire questions for custom persona |
-| `persona_questionnaire_build` | Build trait profile from questionnaire answers |
-| `persona_trait_lookup` | Look up behaviors for specific trait value |
-
-### Analysis (5 tools)
-
-| Tool | Description |
-|------|-------------|
-| `hunt_bugs` | Autonomous bug hunting and issue discovery |
-| `chaos_test` | Inject failures and test resilience |
-| `agent_ready_audit` | Analyze site for AI-agent friendliness |
-| `competitive_benchmark` | Compare UX across competitor sites |
-| `empathy_audit` | Simulate users with disabilities |
-
-### Performance (3 tools)
-
-| Tool | Description |
-|------|-------------|
-| `perf_baseline` | Capture performance baseline |
-| `perf_regression` | Detect performance regression |
-| `list_baselines` | List all saved baselines |
-
-### Stealth (5 tools)
-
-| Tool | Description |
-|------|-------------|
-| `stealth_enable` | Enable stealth mode |
-| `stealth_disable` | Disable stealth mode |
-| `stealth_status` | Check current stealth status |
-| `stealth_check` | Check for bot detection |
-| `stealth_diagnose` | Diagnose detection issues |
-
-### Utility (4 tools)
-
-| Tool | Description |
-|------|-------------|
-| `save_session` | Save browser session (cookies, storage) |
-| `load_session` | Load saved session |
-| `list_sessions` | List saved sessions |
-| `delete_session` | Delete saved session |
-
-### Persona (4 tools)
-
-| Tool | Description |
-|------|-------------|
-| `list_cognitive_personas` | List all available personas |
-| `find_element_by_intent` | AI-powered semantic element finding |
-| `dismiss_overlay` | Dismiss modal overlays (cookies, popups) |
-| `status` | Get CBrowser environment status |
-
-## Tool Usage Examples
-
-### Cognitive Journey with Custom Persona
-
-```
-// Step 1: Get questionnaire
-persona_questionnaire_get({ comprehensive: false })
-
-// Step 2: Build traits from answers
-persona_questionnaire_build({
-  answers: { patience: 0.25, curiosity: 0.75 },
-  name: "anxious-explorer"
-})
-
-// Step 3: Run journey with custom persona
-cognitive_journey_init({
-  persona: "anxious-explorer",
-  startUrl: "https://example.com",
-  goal: "complete checkout"
-})
-```
-
-### Agent-Ready Audit
-
-```
-agent_ready_audit({ url: "https://example.com" })
-
-// Returns:
-// - Overall score (0-100)
-// - Grade (A-F)
-// - Findability, stability, accessibility scores
-// - Issues with remediation suggestions
-```
-
-### Visual Regression
-
-```
-// Capture baseline
-visual_baseline({ url: "https://example.com", name: "homepage" })
-
-// Later, compare against baseline
-visual_regression({ url: "https://staging.example.com", baselineName: "homepage" })
-```
-
-### Competitive Benchmark
-
-```
-competitive_benchmark({
-  sites: [
-    "https://yoursite.com",
-    "https://competitor-a.com",
-    "https://competitor-b.com"
-  ],
-  goal: "sign up for free trial",
-  persona: "first-timer"
-})
-```
-
-## Authentication Methods
-
-### API Key Authentication
-
-For Claude Code CLI and scripts:
-
-```bash
-# Bearer token
-curl -H "Authorization: Bearer your-api-key" https://your-server/mcp
-
-# X-API-Key header
-curl -H "X-API-Key: your-api-key" https://your-server/mcp
-```
-
-Configure multiple keys:
-```bash
-MCP_API_KEYS=key1,key2,key3 npx cbrowser mcp-remote
-```
-
-### Auth0 OAuth
-
-For claude.ai web interface:
-
-1. Set up Auth0 tenant
-2. Configure environment:
-   ```bash
-   AUTH0_DOMAIN=your-tenant.auth0.com
-   AUTH0_AUDIENCE=https://your-server/
-   ```
-3. In claude.ai: Settings > Integrations > Custom Connectors
-4. Add connector URL and complete OAuth flow
-
-Features:
-- OAuth 2.1 with PKCE
-- JWT and opaque token validation
-- 30-minute token caching
-- Protected Resource Metadata via `/.well-known/oauth-protected-resource`
-
-### Dual Authentication
-
-Both OAuth and API keys can be enabled simultaneously for maximum flexibility.
-
-## Server Endpoints
-
-| Endpoint | Description | Auth |
-|----------|-------------|------|
-| `/mcp` | MCP protocol endpoint | Required if configured |
-| `/health` | Health check | Always open |
-| `/info` | Server info | Always open |
-| `/.well-known/oauth-protected-resource` | OAuth metadata | If Auth0 configured |
-
-## Docker Deployment
-
-```yaml
-# docker-compose.yml
-version: "3.8"
-services:
-  cbrowser-mcp:
-    image: ghcr.io/alexandriashai/cbrowser:latest
-    command: ["mcp-remote"]
-    ports:
-      - "3000:3000"
-    environment:
-      - MCP_API_KEY=${MCP_API_KEY}
-      - PORT=3000
-```
-
-## Troubleshooting
-
-### Connection Issues
-
-1. Verify server is running: `curl http://localhost:3000/health`
-2. Check authentication: `curl -H "Authorization: Bearer key" http://localhost:3000/info`
-3. Verify MCP endpoint: `curl -X POST http://localhost:3000/mcp`
-
-### Claude Desktop Not Detecting Tools
-
-1. Restart Claude Desktop after config changes
-2. Verify config path: `~/.config/claude/claude_desktop_config.json`
-3. Check npx is in PATH
-4. Verify cbrowser is installed: `npx cbrowser --version`
-
-### Rate Limiting on Demo Server
-
-The demo server is rate-limited for evaluation. For production use:
-1. Deploy your own server
-2. Use API key authentication
-3. Configure appropriate rate limits