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:

browser_navigate - Successfully navigates to URLs (NEW implementation needed)
browser_screenshot - Captures screenshots perfectly (NEW implementation needed)
browser_click - Clicks elements successfully (NEW implementation needed)
browser_type - Types text into input fields (NEW implementation needed)
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

Exit Claude Code (or do not start it yet)

/exit

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

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

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)

Download/install Browser Tools Chrome extension from https://github.com/ahelme/mcp-claude-code-browser-tools/tree/main/chrome-extension
Activate Chrome Extension: Open Developer Tools (F12) & select Browser Tools tab

NOTE: Browser Tools tab MUST BE ACTIVE

Re/Start Claude Code in FIRST terminal window/tab: $ claude
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

Install Browser Tools extension once from https://browsertools.agentdesk.ai/
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
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:

Edit .mcp.json in codebase root
Restart Claude Code to apply changes
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

File Location: Place .mcp.json in codebase root directory configured using latest specification
Server Types: All servers use "type": "stdio" for JSON-RPC communication
Environment Variables: Configure ports and debug modes in the env section
Path Requirements: Use absolute paths for local scripts (e.g., our browser-tools-mcp-2025.js)
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)

Name		Name	Last commit message	Last commit date
Latest commit History 115 Commits
.claude		.claude
.github/workflows		.github/workflows
.tests		.tests
MANE		MANE
chrome-extension		chrome-extension
img		img
mcp-server		mcp-server
product-management		product-management
.clinerules-architect		.clinerules-architect
.clinerules-ask		.clinerules-ask
.clinerules-code		.clinerules-code
.clinerules-debug		.clinerules-debug
.clinerules-test		.clinerules-test
.gitignore		.gitignore
.mcp.json		.mcp.json
CLAUDE.md		CLAUDE.md
README.md		README.md
mcp-server-working-perfectly.zip		mcp-server-working-perfectly.zip
package-lock.json		package-lock.json
package.json		package.json

ahelme/mcp-claude-code-browser-tools

Folders and files

Latest commit

History

Repository files navigation