Browser Tools for Claude Code

🚀 AgileAI Browser Tools - Revolutionary AI Collaborative Development

The world's first browser tools project built using AgileAI - a revolutionary Agile methodology for human-AI collaborative development!

🎯 What is AgileAI?

AgileAI combines XML-driven architecture, specialized AI agents, break-point methodology, and complete user control to create transparent, quality-assured collaborative development.

🛠️ Project Overview

A powerful set of 9 browser automation tools built collaboratively with specialized AI agents:

• Complete re-write using AgileAI methodology
• 100% June 2025 MCP specification compliant
• Chrome extension with modern Manifest V3 architecture

🚀 Quick Start with AgileAI

Ready to experience revolutionary AI collaboration? See AgileAI_KickStart.md for 5-minute setup!

PROJECT STATUS: AgileAI Ready!

• REVOLUTIONARY: World's first Agile methodology for human-AI collaborative development
• 8 Claude Identity Agents: Ready for interactive collaboration (GitHub Issues #40-47)
• Next Priority: Agent B - Framework Specialist for Chrome extension architecture
• Implementation: 100% June 2025 MCP-compliant with AgileAI break-point methodology
• MCP Method: mcp-server/server.mjs + mcp-server/http-bridge.mjs (port 3024)

🦁 AGILEAI FOUNDATION INFRASTRUCTURE COMPLETE ✅

World's first complete AI collaborative development platform!

• 🦁 AgileAI Methodology: Revolutionary Agile methodology for human-AI collaborative development
• ✅ Foundation Merged: Complete infrastructure with contracts, base classes, registry system
• 🏗️ Core Architecture: TypeScript interfaces, quality gates, monitoring system
• 🤖 Agent Universes: 9 agents in 4 logical batches for systematic development
• 📋 Contract-Driven: OpenAPI specifications and comprehensive quality requirements
• 🎯 Complete Documentation: AgileAI KickStart Guide | Agent Specifications

🏗️ AGILEAI FOUNDATION & BATCH SYSTEM

Current Status - Foundation Complete, Ready for Batch 2:

• ✅ Batch 1: Agent A (Foundation) - COMPLETED & MERGED
  • Contracts: OpenAPI 3.0 specification, quality gates
  • Core: Base classes, interfaces, registry system
  • Infrastructure: Service worker, monitoring, MCP handler
• 🎯 Batch 2: Agent B (Framework) - NEXT TO DEPLOY
  • UI Framework & Component System
• 🎯 Batch 3: Agents C,D,E (Core Tools) - Working in OLD extension, NEW implementation needed
  • browser_navigate, browser_screenshot, browser_click, browser_type, browser_wait
• 🎯 Batch 4: Agents F,G,H,I (Advanced Tools) - Broken in OLD extension, NEW implementation needed
  • browser_evaluate, browser_audit, browser_get_console, browser_get_content

⚡ AGILEAI BRANCH STRATEGY

• main: Default stable branch
• Agent branches: Each agent works in dedicated development reality
• Foundation: Infrastructure merged and operational

🔄 IMPLEMENTATION STATUS (All tools need NEW implementation):

Working in OLD AgentDesk Chrome Ext. Need to be Implemnted in OUR new Chrome Ext:

1. browser_navigate - Successfully navigates to URLs (NEW implementation needed)
2. browser_screenshot - Captures screenshots perfectly (NEW implementation needed)
3. browser_click - Clicks elements successfully (NEW implementation needed)
4. browser_type - Types text into input fields (NEW implementation needed)
5. browser_wait - Waits for elements to appear (NEW implementation needed)

Broken in OLD AgentDesk Chrome Ext. & Need to be Implemnted in OUR new Chrome Ext: 6. browser_evaluate - Timeout error when executing JavaScript (NEW implementation needed) 7. browser_get_content - Request timeout (NEW implementation needed) 8. browser_audit - Returns HTML instead of JSON (NEW implementation needed) 9. browser_get_console - Request timeout (NEW implementation needed)

🎯 Our Goal: Build ALL 9 tools from scratch using our foundation infrastructure (.mjs modules)

🛡️ Code Quality Standards

Enterprise-grade standards for all AgileAI agents:

• See gh issues 30-34

Features

Runs Headless:

• Facilitates multi-tasking: user can operate computer without interfering with autonomous browser-testing by AI agent
• Uses fewer resources
• Faster navigation

Console Monitoring:

• Accurate pick up of errors by AI agents
• Agents better at checking results of changes (user does not find app "broken" as often, while agent declares 100% fixed)
• AI agents faster at reading console errors than screenshots

Take Screenshots for UI Analysis:

• Autonomous AI agent screenshots as per Puppeteer, but faster
• One-click screenshots through Chrome extension

Lighthouse Audits:

• Accessibility
• SEO
• Performance

UI-based Configuration via AgentDesk's 'Browser Tools' Chrome extension:

• Leverage AgentDesk's original Chrome Extension "Browser Tools"
  • Set Port Number or let Extension scan ports
  • Update screenshots directory
  • Configure log/query/string length and wipe logs
  • Include Request/Response headers
  • Toggle Auto-Paste to Cursor

Why Did We Re-Write Browser Tools MCP Server?

We built our own browser tools MCP server to address critical protocol violations in the original npm package maintained by agentdeskai, which used the older > June 2025 MCP specification and no longer functioned.

Our Solution

• 100% 2025-06-18 MCP protocol compliant
• Clean stdio implementation
• Proper error handling

QuickStart Guide

1. Exit Claude Code (or do not start it yet)

/exit

2. Configure Claude Code MCP tools in .mcp.json: e.g. inside project directory .mcp.json

( TOGGLE DEBUG MODE either ON: "1" or OFF: "0" )

{
  "mcpServers": {
    "mcp-claude-code-browser-tools": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/Users/lennox/development/browser-tools-setup/mcp-server/server.mjs"
      ],
      "env": {
        "BROWSER_TOOLS_PORT": "3024",
        "MCP_DEBUG": "1"
      }
    }
  }
}

3. Install and Prepare Claude Code Browser Tools (first time only)

# Install the MCP server and scripts
==TO-BE-DETERMINED==

# First time only - install dependencies
npm install

# Make script executable (
chmod +x mcp-server/start.sh

4. Start the HTTP Bridge Server (port 3024) in NEW Terminal Tab/Window starts on **Port 3024

# Start MCP HTTP bridge (for Claude Code) - PREFERRED METHOD
./mcp-server/start.sh

# CRITICAL - Working Directory Matters:
# ✅ Use script: ./mcp-server/start.sh (handles working directory correctly)
# ✅ Or direct: node mcp-server/http-bridge.mjs (from project root)
# ❌ Never: cd mcp-server && node http-bridge.mjs (wrong working directory)

5. Download/install Browser Tools Chrome extension from https://github.com/ahelme/mcp-claude-code-browser-tools/tree/main/chrome-extension

6. Activate Chrome Extension: Open Developer Tools (F12) & select Browser Tools tab

NOTE: Browser Tools tab MUST BE ACTIVE

7. Re/Start Claude Code in FIRST terminal window/tab: $ claude

8. Configure Browser Tools Chrome Extension Port to 3024 Set via UI form field "Server Connection Settings > Server Port to 3024"

This will connect extension to Claude Code Browser Tools MCP Server (via http bridge).

📚 API Documentation

Complete Protocol Documentation is available for developers and AI agents:

# Start comprehensive documentation server
./chrome-extension/start-docs.sh

Available Endpoints:

• 📚 Documentation Portal: http://localhost:3020/docs - Combined REST & WebSocket docs
• 🔗 REST API docs: http://localhost:3020/rest-docs - OpenAPI/Swagger UI
• 🔌 WebSocket docs: http://localhost:3020/ws-docs - AsyncAPI protocol docs
• 📄 OpenAPI spec: http://localhost:3020/openapi.yaml - REST API contract
• 📡 AsyncAPI spec: http://localhost:3020/asyncapi.yaml - WebSocket protocol contract
• 🤖 AI-discoverable: http://localhost:3020/health - Complete protocol metadata
• 🔍 JSON formats: http://localhost:3020/openapi.json | http://localhost:3020/asyncapi.json

Features:

• ✅ Dual Protocol Support - REST (OpenAPI 3.0.3) + WebSocket (AsyncAPI 3.0.0)
• ✅ Interactive testing - test REST API directly from browser
• ✅ Protocol visualization - AsyncAPI Studio integration for WebSocket protocol
• ✅ AI-agent friendly - auto-discoverable endpoints and standard formats
• ✅ Contract-driven - single source of truth prevents documentation drift
• ✅ Always accurate - reflects actual implementation

Port Layout:

• 3020 - API Documentation Server
• 3024 - MCP HTTP Bridge (main functionality)
• 3025+ - Multi-project instances

Testing and Debugging

Check if working:

# See configured server
cat .claude/mcp.json | grep browser-tools

# Test MCP HTTP bridge (port 3024)
curl http://localhost:3024/health

# Debug MCP server
MCP_DEBUG=1 node mcp-server/server.mjs

Configure MCP Server to Debug Mode:

Set MCP_DEBUG=1 in .mcp.json (see above).

Alternative Direct HTTP Method (backup option if MCP server fails)

Option to run direct http connection via Port 3026

# Starts the direct MCP HTTP bridge on port 3026
./mcp-server/mcp-server/start-direct-browser-tools.sh

# Test Direct HTTP bridge (port 3026)
curl http://localhost:3026/health

Architecture

Main Method (MCP): Claude Code <--[stdio]--> MCP Server <--[HTTP:3024]--> MCP Bridge <--[WebSocket]--> Chrome Extension
Backup Method (Direct): External Tool <--[HTTP:3026]--> Direct Bridge <--[WebSocket]--> Chrome Extension

Chrome Extension

• Monitors XHR requests/responses and console logs
• Tracks selected DOM elements
• Sends all logs and current element to the BrowserTools Connector
• Connects to Websocket server to capture/send screenshots
• Allows user to configure token/truncation limits + screenshot folder path

Node Server HTTP Bridge

• Acts as middleware between the Chrome extension and MCP server
• Receives logs and currently selected element from Chrome extension
• Processes requests from MCP server to capture logs, screenshot or current element
• Sends Websocket command to the Chrome extension for capturing a screenshot
• Intelligently truncates strings and # of duplicate objects in logs to avoid token limits
• Removes cookies and sensitive headers to avoid sending to LLMs in MCP clients

MCP Server

• Implements the Model Context Protocol
• Provides standardized tools for AI clients
• Compatible with various MCP clients (Cursor, Cline, Zed, Claude Desktop, etc.)

See mcp-server/mcp-server_docs/CODE-ARCHITECTURE.md for more details.

IMPORTANT: Port 3024 is reserved for MCP server method.

🚀 Multi-Project Usage

Run browser tools across multiple projects simultaneously without port conflicts!

The MCP server uses environment variables to allow custom port configuration, making it easy to run multiple instances.

Method 1: Per-Project .mcp.json Configuration

Each project can specify its own port in .mcp.json:

{
  "mcpServers": {
    "mcp-claude-code-browser-tools": {
      "type": "stdio",
      "command": "node",
      "args": ["path/to/mcp-server/server.mjs"],
      "env": {
        "BROWSER_TOOLS_PORT": "3025",  // Custom port for this project
        "MCP_DEBUG": "1"
      }
    }
  }
}

Method 2: Environment Variable Override

Start with custom ports using environment variables:

# Project A (default port)
cd /path/to/project-a
./mcp-server/start.sh
# → Runs on port 3024

# Project B (custom port)
cd /path/to/project-b
BROWSER_TOOLS_PORT=3025 ./mcp-server/start.sh
# → Runs on port 3025

# Project C (another custom port)
cd /path/to/project-c
BROWSER_TOOLS_PORT=3026 ./mcp-server/start.sh
# → Runs on port 3026

Chrome Extension Setup for Multiple Projects

1. Install Browser Tools extension once from https://browsertools.agentdesk.ai/
2. Switch between projects by changing the port in extension settings:
   • Project A: Set port to 3024
   • Project B: Set port to 3025
   • Project C: Set port to 3026
3. Or use multiple Chrome profiles - each with different port settings

Quick Multi-Project Example

# Terminal 1 - Project A (React app)
cd ~/projects/my-react-app
./mcp-server/start.sh  # port 3024
claude  # Start Claude Code

# Terminal 2 - Project B (Vue app)
cd ~/projects/my-vue-app
BROWSER_TOOLS_PORT=3025 ./mcp-server/start.sh  # port 3025
claude  # Start Claude Code

# Terminal 3 - Project C (Angular app)
cd ~/projects/my-angular-app
BROWSER_TOOLS_PORT=3026 ./mcp-server/start.sh  # port 3026
claude  # Start Claude Code

Now you can work on multiple projects simultaneously! 🎉

Port Range Recommendations

• 3024: Default (Project A)
• 3025-3030: Additional projects
• 3031+: Available for other tools

Tools and Examples

Individual Tools (NOT ALL WORKING YET)

All tools are prefixed with mcp__browser-tools__:

• navigate - Go to URL
• screenshot - Capture page/element
• click - Click elements
• type - Enter text
• evaluate - Run JavaScript
• get_content - Get HTML
• audit - Run Lighthouse
• wait - Wait for elements
• get_console - Get console logs

Example Usage

// Navigate to a page
mcp__browser-tools__navigate({ url: "https://example.com" })

// Take screenshot
mcp__browser-tools__screenshot({ fullPage: true })

// Click button
mcp__browser-tools__click({ selector: "#submit-button" })

Tools Guide

Guide to usage of available tools: TOOLS_GUIDE.md

Important Files

MCP Method (Port 3024)

• mcp-server/server.mjs - MCP server
• mcp-server/http-bridge.mjs - MCP HTTP bridge
• mcp-server/start.sh - Start script for MCP

BACKUP: Direct Method (Port 3026)

• mcp-server/mcp-server/direct-http-bridge.js - Direct HTTP bridge
• mcp-server/mcp-server/start-direct-browser-tools.sh - Start script for direct

Configuration, Files & Directories

• ~/.claude/mcp.json - ==(DANGEROUS TO MODIFY)== User-level MCP configuration (Claude Code)
• .mcp.json - Project-level MCP configuration (local config and team collaboration)
• .screenshots/ - Screenshot outputs

🔧 Environment Variables

The MCP server supports several environment variables for customization:

Core Configuration

Variable	Default	Description	Example
BROWSER_TOOLS_PORT	3024	HTTP bridge port for MCP server	3025
MCP_HTTP_BRIDGE_PORT	3024	Alternative name for same setting	3026
MCP_DEBUG	0	Enable detailed debug logging	1

Port Conflict Issues

Problem: "Error: listen EADDRINUSE: address already in use :::3024"

Solutions:

# 1. Check what's using the port
lsof -i :3024

# 2. Kill existing process
pkill -f "mcp-http-bridge"

# 3. Or use a different port
BROWSER_TOOLS_PORT=3025 ./mcp-server/start.sh

Multi-Project Port Conflicts

Problem: Running multiple projects simultaneously

Solution: Use different ports per project

# Check active browser tools processes
ps aux | grep mcp-http-bridge

# See which ports are in use
lsof -i :3024-3030

# Start each project with unique port
cd project-a && BROWSER_TOOLS_PORT=3024 ./mcp-server/start.sh
cd project-b && BROWSER_TOOLS_PORT=3025 ./mcp-server/start.sh

Configuration

MCP Server Settings

To modify MCP server configurations:

1. Edit .mcp.json in codebase root
2. Restart Claude Code to apply changes
3. Test server connectivity with debug mode: MCP_DEBUG=1

{
  "mcpServers": {
    "claude-code-browser-tools": {
      "type": "stdio",
      "command": "node",
      "args": [
        "mcp-server/claude-code-browser-tools.js"
      ],
      "env": {
        "BROWSER_TOOLS_PORT": "3024",
        "MCP_DEBUG": "1"
      }
    }
  }
}

Configuration Tips & Guidelines

1. File Location: Place .mcp.json in codebase root directory configured using latest specification
2. Server Types: All servers use "type": "stdio" for JSON-RPC communication
3. Environment Variables: Configure ports and debug modes in the env section
4. Path Requirements: Use absolute paths for local scripts (e.g., our browser-tools-mcp-2025.js)
5. NPX Dependencies: External packages can be run with npx -y for auto-installation

Compatibility

• Works with Claude Code
• May work with other MCP-compatible clients e.g. Cursor IDE integration

Documentation

• TOOLS-GUIDE.md - Guide to use of available tools
• CODE-ARCHITECTURE.md - Full technical details

Important Notes

• MCP HTTP bridge uses port 3024 (for Claude Code)
• Direct HTTP bridge uses port 3026 (for API access)
• Chrome extension required for browser control
• MCP servers that are configured in .mcp.json auto-start with Claude Code
• Debug output goes to stderr only (MCP_DEBUG=1)

Resources

• Original Chrome Extension by AgentDesk
• Original Browser Tools MCP by AgentDesk
• MCP Specification