Metadata-Version: 2.4
Name: pidgey-mcp
Version: 2.1.6
Summary: Token-Optimized Middleware Engine & DOM Checkpointing Framework for AI Browser Automation
Author-email: Manthan Railkar <manthan.railkar@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Manthan-Railkar/Hackateers
Project-URL: Repository, https://github.com/Manthan-Railkar/Hackateers.git
Project-URL: Documentation, https://github.com/Manthan-Railkar/Hackateers/blob/main/docs.md
Project-URL: Bug Tracker, https://github.com/Manthan-Railkar/Hackateers/issues
Keywords: mcp,model-context-protocol,browser-automation,playwright,dom-compression,ai-agents,llms.txt,pidgey,browser-optimizer
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: playwright>=1.40.0
Requires-Dist: mcp>=1.30.0
Requires-Dist: fastmcp>=3.5.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: loguru>=0.7.0
Requires-Dist: lxml>=4.9.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: xxhash>=3.0.0
Requires-Dist: cachetools>=5.0.0
Requires-Dist: websockets>=12.0
Requires-Dist: tiktoken>=0.5.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: scikit-learn>=1.3.0
Requires-Dist: lightgbm>=4.0.0
Requires-Dist: pandas>=2.0.0
Provides-Extra: test
Requires-Dist: pytest>=7.4.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
Dynamic: license-file

# 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)

```bash
# 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:

```bash
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:
```bash
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`):**
```json
{
  "mcpServers": {
    "pidgey": {
      "command": "pidgey",
      "args": ["start"],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}
```

**Using Zero-Install `uvx`:**
```json
{
  "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:**
```json
{
  "mcpServers": {
    "pidgey": {
      "command": "pidgey",
      "args": ["start"]
    }
  }
}
```

**Using `uvx`:**
```json
{
  "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`:
```json
{
  "mcpServers": {
    "pidgey": {
      "command": "pidgey",
      "args": ["start"]
    }
  }
}
```

#### 5. VS Code (Continue Extension)

Add to `~/.continue/config.json`:
```json
{
  "mcpServers": [
    {
      "name": "pidgey",
      "command": "pidgey",
      "args": ["start"]
    }
  ]
}
```

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

Connect programmatically using the official `mcp` Python SDK:

```python
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

```text
+-----------------------+                    +-------------------------+
|                       |  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.
