# ProxyShield MCP (Lite)

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python: 3.10+](https://img.shields.io/badge/python-3.10+-brightgreen.svg)](https://python.org)
[![MCP Standard: Compatible](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io)

**Autonomous Smart Proxy Routing, Bandwidth Conservation & Header Evasion Plane for AI Web Agents**

ProxyShield MCP prevents AI browser agents (Claude Computer Use, Stagehand, browser-use, Playwright) from wasting expensive residential proxy data ($15-$25/GB) on heavy static assets. It routes requests intelligently, generates rotating browser evasion headers, and tracks bandwidth cost savings.

---

## 🚀 Features (Lite Edition)

- **Smart Tier Router (`route_request`):** Categorizes requests into direct, datacenter, and residential tiers. Diverts fonts, images, and videos away from paid residential pools.
- **Static Asset Classifier (`classify_asset`):** Automatically detects `.woff2`, `.png`, `.mp4`, `.css`, and heavy media.
- **Stealth Evasion Headers (`get_evasion_headers`):** Rotating modern browser fingerprints (Chrome 131, Firefox 133) with matching `Sec-CH-UA`, viewport dimensions, and language tags.
- **Bandwidth Savings Tracker (`get_bandwidth_savings`):** Quantifies total megabytes saved and estimated dollar savings in real time.

---

## 📦 Installation & Setup

```bash
git clone https://github.com/johannschiffer/proxyshield-mcp.git
cd proxyshield-mcp
pip install -e .
```

### Configuration with Claude Desktop / Cursor

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "proxyshield": {
      "command": "python3",
      "args": ["-m", "proxyshield.server"]
    }
  }
}
```

---

## ⚡ Quick CLI Usage

```bash
# Calculate route for a target URL
proxyshield route --url "https://example.com/assets/hero-video.mp4"

# Generate rotating evasion headers
proxyshield headers
```

---

## 💼 Upgrade to ProxyShield Pro

Need enterprise protection and deeper cost reduction?
- **Hybrid Proxy Tier Pool (SQLite WAL):** Health scoring, latency tracking, and automatic failover across Datacenter, ISP, and Residential providers.
- **TLS Client Hello & JA3/JA4 Rotator:** Custom TLS handshake emulation to bypass Cloudflare and Akamai bot defenses.
- **Content-Addressable Asset Cache:** Intercepts identical scripts and fonts by SHA-256 hash, reducing bandwidth by up to 85%.
- **Anti-Bot Circuit Breaker:** Instant quarantine on 403, 429, or Turnstile challenges with automatic session handover.
- **Docker & Docker Compose:** Ready for production deployment alongside agent clusters.

Available at [Gumroad](https://johanld.gumroad.com/).

---

## 📄 License

MIT © Johann Schiffer