@agentdeskai/browser-tools-server

Browser Tools Server

A powerful browser tools server for capturing and managing browser events, logs, and screenshots. This server works in conjunction with the Browser Tools Chrome Extension to provide comprehensive browser debugging capabilities.

Features

• Console log capture
• Network request monitoring
• Screenshot capture
• Element selection tracking
• WebSocket real-time communication
• Configurable log limits and settings
• Lighthouse-powered accessibility, performance, SEO, and best practices audits

Installation

npx @agentdeskai/browser-tools-server

Or install globally:

npm install -g @agentdeskai/browser-tools-server

Usage

1. Start the server:

npx @agentdeskai/browser-tools-server

2. The server will start on port 3025 by default

3. Install and enable the Browser Tools Chrome Extension

4. The server exposes the following endpoints:

• /console-logs - Get console logs
• /console-errors - Get console errors
• /network-errors - Get network error logs
• /network-success - Get successful network requests
• /all-xhr - Get all network requests
• /screenshot - Capture screenshots
• /selected-element - Get currently selected DOM element
• /accessibility-audit - Run accessibility audit on current page
• /performance-audit - Run performance audit on current page
• /seo-audit - Run SEO audit on current page

API Documentation

GET Endpoints

• GET /console-logs - Returns recent console logs
• GET /console-errors - Returns recent console errors
• GET /network-errors - Returns recent network errors
• GET /network-success - Returns recent successful network requests
• GET /all-xhr - Returns all recent network requests
• GET /selected-element - Returns the currently selected DOM element

POST Endpoints

• POST /extension-log - Receive logs from the extension
• POST /screenshot - Capture and save screenshots
• POST /selected-element - Update the selected element
• POST /wipelogs - Clear all stored logs
• POST /accessibility-audit - Run a WCAG-compliant accessibility audit on the current page
• POST /performance-audit - Run a performance audit on the current page
• POST /seo-audit - Run a SEO audit on the current page

Audit Functionality

The server provides Lighthouse-powered audit capabilities through four AI-optimized endpoints. These audits have been specifically tailored for AI consumption, with structured data, clear categorization, and smart prioritization.

Smart Limit Implementation

All audit tools implement a "smart limit" approach to provide the most relevant information based on impact severity:

• Critical issues: No limit (all issues are shown)
• Serious issues: Up to 15 items per issue
• Moderate issues: Up to 10 items per issue
• Minor issues: Up to 3 items per issue

This ensures that the most important issues are always included in the response, while less important ones are limited to maintain a manageable response size for AI processing.

Common Audit Response Structure

All audit responses follow a similar structure:

{
  "metadata": {
    "url": "https://example.com",
    "timestamp": "2025-03-06T16:28:30.930Z",
    "device": "desktop",
    "lighthouseVersion": "11.7.1"
  },
  "report": {
    "score": 88,
    "audit_counts": {
      "failed": 2,
      "passed": 17,
      "manual": 10,
      "informative": 0,
      "not_applicable": 42
    }
    // Audit-specific content
    // ...
  }
}

Accessibility Audit (/accessibility-audit)

The accessibility audit evaluates web pages against WCAG standards, identifying issues that affect users with disabilities.

Response Format

{
  "metadata": {
    "url": "https://example.com",
    "timestamp": "2025-03-06T16:28:30.930Z",
    "device": "desktop",
    "lighthouseVersion": "11.7.1"
  },
  "report": {
    "score": 88,
    "audit_counts": {
      "failed": 2,
      "passed": 17,
      "manual": 10,
      "informative": 0,
      "not_applicable": 42
    },
    "issues": [
      {
        "id": "meta-viewport",
        "title": "`[user-scalable=\"no\"]` is used in the `<meta name=\"viewport\">` element or the `[maximum-scale]` attribute is less than 5.",
        "impact": "critical",
        "category": "a11y-best-practices",
        "elements": [
          {
            "selector": "head > meta",
            "snippet": "<meta name=\"viewport\" content=\"width=device-width,initial-scale=1,maximum-scale=1,user-scalable=0\">",
            "label": "head > meta",
            "issue_description": "Fix any of the following: user-scalable on <meta> tag disables zooming on mobile devices"
          }
        ],
        "score": 0
      }
    ],
    "categories": {
      "a11y-navigation": { "score": 0, "issues_count": 0 },
      "a11y-aria": { "score": 0, "issues_count": 1 },
      "a11y-best-practices": { "score": 0, "issues_count": 1 }
    },
    "critical_elements": [
      {
        "selector": "head > meta",
        "snippet": "<meta name=\"viewport\" content=\"width=device-width,initial-scale=1,maximum-scale=1,user-scalable=0\">",
        "label": "head > meta",
        "issue_description": "Fix any of the following: user-scalable on <meta> tag disables zooming on mobile devices"
      }
    ],
    "prioritized_recommendations": [
      "Fix ARIA attributes and roles",
      "Fix 1 issues in a11y-best-practices"
    ]
  }
}

Key Features

• Issues Categorized by Impact: Critical, serious, moderate, and minor
• Element-Specific Information: Selectors, snippets, and labels for affected elements
• Issue Categories: ARIA, navigation, color contrast, forms, keyboard access, etc.
• Critical Elements List: Quick access to the most serious issues
• Prioritized Recommendations: Actionable advice in order of importance

Performance Audit (/performance-audit)

The performance audit analyzes page load speed, Core Web Vitals, and optimization opportunities.

Response Format

{
  "metadata": {
    "url": "https://example.com",
    "timestamp": "2025-03-06T16:27:44.900Z",
    "device": "desktop",
    "lighthouseVersion": "11.7.1"
  },
  "report": {
    "score": 60,
    "audit_counts": {
      "failed": 11,
      "passed": 21,
      "manual": 0,
      "informative": 20,
      "not_applicable": 8
    },
    "metrics": [
      {
        "id": "lcp",
        "score": 0,
        "value_ms": 14149,
        "passes_core_web_vital": false,
        "element_selector": "div.heading > span",
        "element_type": "text",
        "element_content": "Welcome to Example"
      },
      {
        "id": "fcp",
        "score": 0.53,
        "value_ms": 1542,
        "passes_core_web_vital": false
      },
      {
        "id": "si",
        "score": 0,
        "value_ms": 6883
      },
      {
        "id": "tti",
        "score": 0,
        "value_ms": 14746
      },
      {
        "id": "cls",
        "score": 1,
        "value_ms": 0.001,
        "passes_core_web_vital": true
      },
      {
        "id": "tbt",
        "score": 1,
        "value_ms": 43,
        "passes_core_web_vital": true
      }
    ],
    "opportunities": [
      {
        "id": "render_blocking_resources",
        "savings_ms": 1270,
        "severity": "serious",
        "resources": [
          {
            "url": "styles.css",
            "savings_ms": 781
          }
        ]
      }
    ],
    "page_stats": {
      "total_size_kb": 2190,
      "total_requests": 108,
      "resource_counts": {
        "js": 86,
        "css": 1,
        "img": 3,
        "font": 3,
        "other": 15
      },
      "third_party_size_kb": 2110,
      "main_thread_blocking_time_ms": 693
    },
    "prioritized_recommendations": ["Improve Largest Contentful Paint (LCP)"]
  }
}

Key Features

• Core Web Vitals Analysis: LCP, FCP, CLS, TBT with pass/fail status
• Element Information for LCP: Identifies what's causing the largest contentful paint
• Optimization Opportunities: Specific actions to improve performance with estimated time savings
• Resource Breakdown: By type, size, and origin (first vs. third party)
• Main Thread Analysis: Blocking time metrics to identify JavaScript performance issues
• Resource-Specific Recommendations: For each optimization opportunity

SEO Audit (/seo-audit)

The SEO audit checks search engine optimization best practices and identifies issues that could affect search ranking.

Response Format

{
  "metadata": {
    "url": "https://example.com",
    "timestamp": "2025-03-06T16:29:12.455Z",
    "device": "desktop",
    "lighthouseVersion": "11.7.1"
  },
  "report": {
    "score": 91,
    "audit_counts": {
      "failed": 1,
      "passed": 10,
      "manual": 1,
      "informative": 0,
      "not_applicable": 3
    },
    "issues": [
      {
        "id": "is-crawlable",
        "title": "Page is blocked from indexing",
        "impact": "critical",
        "category": "crawlability",
        "score": 0
      }
    ],
    "categories": {
      "content": { "score": 0, "issues_count": 0 },
      "mobile": { "score": 0, "issues_count": 0 },
      "crawlability": { "score": 0, "issues_count": 1 },
      "other": { "score": 0, "issues_count": 0 }
    },
    "prioritized_recommendations": [
      "Fix crawlability issues (1 issues): robots.txt, sitemaps, and redirects"
    ]
  }
}

Key Features

• Issues Categorized by Impact: Critical, serious, moderate, and minor
• SEO Categories: Content, mobile friendliness, crawlability
• Issue Details: Information about what's causing each SEO problem
• Prioritized Recommendations: Actionable advice in order of importance

Best Practices Audit (/best-practices-audit)

The best practices audit evaluates adherence to web development best practices related to security, trust, user experience, and browser compatibility.

Response Format

{
  "metadata": {
    "url": "https://example.com",
    "timestamp": "2025-03-06T17:01:38.029Z",
    "device": "desktop",
    "lighthouseVersion": "11.7.1"
  },
  "report": {
    "score": 74,
    "audit_counts": {
      "failed": 4,
      "passed": 10,
      "manual": 0,
      "informative": 2,
      "not_applicable": 1
    },
    "issues": [
      {
        "id": "deprecations",
        "title": "Uses deprecated APIs",
        "impact": "critical",
        "category": "security",
        "score": 0,
        "details": [
          {
            "value": "UnloadHandler"
          }
        ]
      },
      {
        "id": "errors-in-console",
        "title": "Browser errors were logged to the console",
        "impact": "serious",
        "category": "user-experience",
        "score": 0,
        "details": [
          {
            "source": "console.error",
            "description": "ReferenceError: variable is not defined"
          }
        ]
      }
    ],
    "categories": {
      "security": { "score": 75, "issues_count": 1 },
      "trust": { "score": 100, "issues_count": 0 },
      "user-experience": { "score": 50, "issues_count": 1 },
      "browser-compat": { "score": 100, "issues_count": 0 },
      "other": { "score": 75, "issues_count": 2 }
    },
    "prioritized_recommendations": [
      "Address 1 security issues: vulnerabilities, CSP, deprecations",
      "Improve 1 user experience issues: console errors, user interactions"
    ]
  }
}

Key Features

• Issues Categorized by Impact: Critical, serious, moderate, and minor
• Best Practice Categories: Security, trust, user experience, browser compatibility
• Detailed Issue Information: Specific problems affecting best practices compliance
• Security Focus: Special attention to security vulnerabilities and deprecated APIs
• Prioritized Recommendations: Actionable advice in order of importance

License

MIT

Puppeteer Service

A comprehensive browser automation service built on Puppeteer to provide reliable cross-platform browser control capabilities.

Features

• Cross-Platform Browser Support:

  • Windows, macOS, and Linux support
  • Chrome, Edge, Brave, and Firefox detection
  • Fallback strategy for finding browser executables

• Smart Browser Management:

  • Singleton browser instance with automatic cleanup
  • Connection retry mechanisms
  • Temporary user data directories with cleanup

• Rich Configuration Options:

  • Custom browser paths
  • Network condition emulation
  • Device emulation (mobile, tablet, desktop)
  • Resource blocking
  • Cookies and headers customization
  • Locale and timezone emulation