Skip to content
BranchesTags

Repository files navigation

Pidgey: Browser Optimizer MCP

Bridge AI Agents to Web Applications at 85% lower token cost with 10x faster execution and zero-downtime crash recovery.

The Inspiration / Problem

AI Agents are revolutionizing web automation, but interacting with modern websites is bottlenecked by severe limitations:

  • Massive Token Bloat: Standard web pages contain 50,000+ lines of redundant scripts, styles, SVGs, and tracking tags. Feeding raw HTML into LLMs drains context windows instantly.
  • Exorbitant API Expenses: Processing uncompressed web contexts costs dollars per agent loop, making large-scale web scraping and automation cost-prohibitive.
  • Fragile Browser Execution: Browsers crash, network connections drop, and Playwright sessions disconnect, causing AI agents to fail mid-workflow and lose context.
  • Redundant Browser Booting: Launching a full Chromium browser instance to read simple documentation or static web pages wastes time and system resources.

What it Does & Key Features

Pidgey is an intelligent Model Context Protocol (MCP) middleware operating between AI Agents and the Web. It intercepts navigation requests, strips non-essential markup, caches structural representations, recovers transparently from browser failures, and bypasses browser execution entirely when static documentation is detected.

Key Features

  • Extreme Token Compression: Decomposes non-essential DOM markup and extracts interactive UI controls into a hyper-compact JSON schema, saving up to 85% on context tokens.
  • LLM-Aware Website Discovery (llms.txt): Discovers /llms.txt specifications to determine if browser automation is required. Bypasses Playwright to fetch and compress static documentation directly via HTTP.
  • DOM Checkpointing & Browser Recovery: Captures versioned DOM checkpoints and Playwright state snapshots. Automatically restores browser sessions with weighted confidence validation upon crashes or network disconnects.
  • Semantic Caching & Structural Vector Embeddings: Embeds web page structures in a local SQLite database using structural vector embeddings and cosine similarity (>0.90) for sub-millisecond cache hits.
  • Multimodal VLM Fallback: Uses Groq Llama 3.2 Vision to extract interactive bounding boxes when encountering Canvas-heavy applications, CAPTCHAs, or pages lacking HTML controls.
  • Mission Control Live Dashboard: Serves a real-time web dashboard (HTTP port 8050) and WebSocket push poller (port 8765) to monitor live screenshots, token savings, cost metrics, and session replay timelines.

Tech Stack

  • Core Runtime: Python 3.10+
  • MCP Framework: FastMCP (MCP Protocol Version 2026-07-28 Compliance)
  • Browser Automation: Playwright Chromium
  • Parsing & Compression: BeautifulSoup4, lxml, xxhash
  • Machine Learning & NLP: LightGBM Page Classifier, Structural Vector Embedding Engine
  • Multimodal AI: Groq API (llama-3.2-11b-vision-preview)
  • Database & Storage: SQLite3 (cache.db), JSON Session Storage State
  • Observability: Built-in HTTP Server, WebSocket Poller, HTML5/CSS3 Mission Control Dashboard

Installation & Setup

Prerequisites

  • Python: v3.10 or higher
  • Git: Installed on your system
  • Groq API Key (Optional): Required for Multimodal VLM vision fallback on Canvas apps

Installation & Setup

Prerequisites

  • Python: v3.10 or higher (Python 3.11+ recommended)
  • Git: Installed on your system
  • Groq API Key (Optional): Required for Multimodal VLM vision fallback on Canvas apps

Option A: Install from PyPI (Recommended)

# 1. Install Pidgey MCP from PyPI
pip install pidgey-mcp

# 2. Run the auto-installer (Installs Playwright browsers & auto-configures connected AI agents)
pidgey install

# 3. Start the MCP server & Mission Control dashboard manually if testing locally
pidgey start

Or run instantly via uvx without pre-installing:

uvx pidgey-mcp start

🔌 Connecting your AI Agent (Post-PyPI Installation)

After downloading pidgey-mcp from PyPI, you connect the installed MCP server to your AI Agent environment so the agent can discover and invoke Pidgey's browser tools.

Method 1: Automated Auto-Configuration (Recommended)

Simply run:

pidgey install

The automated setup wizard will:

  1. Download Playwright Chromium browser binaries.
  2. Auto-detect installed AI clients (Claude Desktop, Antigravity IDE) on Windows and macOS.
  3. Inject the pidgey MCP server configuration into your client's config file automatically.

Method 2: Manual AI Agent Connection

If you want to configure your AI Agent manually after running pip install pidgey-mcp, add the corresponding JSON snippet below into your client's configuration file.

1. Claude Desktop

Location of claude_desktop_config.json:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Using PyPI-installed CLI (pip install pidgey-mcp):

{
  "mcpServers": {
    "pidgey": {
      "command": "pidgey",
      "args": ["start"],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Using Zero-Install uvx:

{
  "mcpServers": {
    "pidgey": {
      "command": "uvx",
      "args": ["pidgey-mcp", "start"],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

2. Antigravity IDE

Location of mcp_config.json:

  • Path: ~/.gemini/config/mcp_config.json

Using PyPI-installed CLI:

{
  "mcpServers": {
    "pidgey": {
      "command": "pidgey",
      "args": ["start"]
    }
  }
}

Using uvx:

{
  "mcpServers": {
    "pidgey": {
      "command": "uvx",
      "args": ["pidgey-mcp", "start"]
    }
  }
}

3. Cursor IDE

  1. Open Cursor Settings (Ctrl + , or Cmd + ,).
  2. Navigate to Features -> MCP Servers.
  3. Click + Add New MCP Server.
  4. Configure details:
    • Name: pidgey
    • Type: command (stdio)
    • Command: pidgey start (or uvx pidgey-mcp start)
  5. Click Save.

4. Windsurf IDE

Add to .codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "pidgey": {
      "command": "pidgey",
      "args": ["start"]
    }
  }
}

5. VS Code (Continue Extension)

Add to ~/.continue/config.json:

{
  "mcpServers": [
    {
      "name": "pidgey",
      "command": "pidgey",
      "args": ["start"]
    }
  ]
}

6. Custom Python Agents (LangChain, LlamaIndex, AutoGen)

Connect programmatically using the official mcp Python SDK:

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

server_params = StdioServerParameters(
    command="pidgey",
    args=["start"]
)

async def main():
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            
            # List exposed Pidgey MCP tools
            tools = await session.call_tool("list_tools", {})
            print("Connected tools:", len(tools.content))
            
            # Extract compressed page context
            result = await session.call_tool("extract_context", {"url": "https://example.com"})
            print("Extracted Context:", result)

if __name__ == "__main__":
    asyncio.run(main())

How the Connection Works Under the Hood

+-----------------------+                    +-------------------------+
|                       |  1. Spawn command  |                         |
|  AI Agent / IDE Client| -----------------> |  pidgey (PyPI package)  |
| (Claude, Cursor, etc.)|                    |                         |
|                       |  2. stdio protocol |                         |
|                       | <----------------> |  MCP FastMCP Server     |
+-----------------------+    (JSON-RPC 2.0)  +-------------------------+
  1. Subprocess Spawning: When the AI Agent starts, it reads its MCP configuration JSON and spawns a background subprocess executing pidgey start (or uvx pidgey-mcp start).
  2. Standard I/O Transport (stdio): Communication flows over standard input/output using JSON-RPC 2.0 messages.
  3. Tool Registration: The AI Agent sends a tools/list handshake to discover all 28 native Pidgey tools and injects them into the LLM's context window.
  4. Execution & Context Return: When the LLM decides to browse or act on a web page, the AI Agent invokes extract_context or execute_action over stdin. Pidgey executes the request and returns the hyper-compressed context over stdout.

🛠️ Complete MCP Tools Reference

Pidgey exposes 28 native tools for AI Agents:

Core Context & Execution

  • extract_context(url, session_id): Navigates to a URL, checks llms.txt discovery for direct fetch, extracts and compresses DOM.
  • execute_action(action, selector, value, session_id): Executes browser actions (click, type, fill, select, scroll, wait, navigate) with error recovery retries.
  • page_diff(url, session_id): Computes DOM element deltas (added/removed) since the previous observation.
  • summarize_page(url, session_id): Returns structural element counts and page snippet summary.
  • classify_page(url, session_id): Returns page category classification (LOGIN, PRODUCT, SEARCH, CHECKOUT, etc.).
  • wait_until_ready(url, timeout, session_id): Navigates and pauses until network load stabilizes.
  • cache_lookup(url, session_id): Queries local SQLite semantic cache directly.

DOM Checkpointing & Recovery

  • create_checkpoint(session_id, trigger): Captures a versioned DOM checkpoint.
  • load_latest_checkpoint(session_id): Retrieves the latest DOM checkpoint for a session.
  • restore_checkpoint(session_id): Triggers recovery restoration from the latest checkpoint.
  • compare_checkpoint(session_id, checkpoint_id): Compares current page state against a stored checkpoint.
  • delete_session_checkpoints(session_id): Purges stored checkpoints for a session.

LLM-Aware Website Discovery (llms.txt)

  • discover_llms(url, force_refresh): Discovers and parses /llms.txt specifications for a domain.
  • parse_llms(markdown, base_url): Parses raw Markdown string into a structured catalog.
  • get_cached_llms(hostname): Retrieves stored llms.txt discovery cache entry.
  • select_navigation_strategy(url): Queries Decision Engine for strategy (DIRECT_FETCH, PLAYWRIGHT, HYBRID).
  • fetch_documentation(url): Direct HTTP download and DOM compression without Playwright.
  • invalidate_llms_cache(hostname): Purges stored llms.txt cache entry for a hostname.

Automation, Monitoring & Dashboard

  • start_macro_recording(session_id): Begins recording browser actions for skill creation.
  • save_macro(name, page_type, parameters_map, session_id): Saves parameterized action sequences into reusable skills.
  • list_skills(page_type): Lists recorded skill macros.
  • suggest_skill(page_type): Recommends highest confidence macro and routing strategy.
  • replay_skill(macro_id, parameters, expected_url, expected_page_type, session_id, replay_handle): Replays recorded macro with MRTR stateless handle resumption.
  • watch_page(url, interval_seconds, session_id): Starts background WebSocket poller streaming live DOM diffs.
  • stop_watch_page(session_id): Stops background WebSocket page watching task.
  • get_session_replay(session_id): Retrieves append-only action log for a session.
  • get_metrics(): Returns real-time token savings, cost estimates, cache ratios, and discovery stats.
  • open_dashboard(): Launches Mission Control live dashboard in the default browser.

👥 Team Members

  • Manthan Railkar and Ayush Mhatre
  • Hackateers Team

🔮 Future Roadmap

  • Multi-Browser Driver Engine: Add support for Firefox and WebKit browser engines alongside Chromium.
  • Distributed Redis Cache: Upgrade local SQLite cache to Redis Vector DB for enterprise team cache sharing.
  • Autonomous Skill Synthesis: Enable LLMs to automatically record, package, and publish macro skills to a shared registry.
  • Mobile Viewport Emulation: Provide mobile device viewport emulation and touch gesture action APIs.

About

A Middleware between AI Agents and Websites which make Web Automation tasks cost-effective

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages