convez.ai
AgenteDevOps & InfraestruturaIntermediário
sentrysurface

SurfaceProxy — Proxy Semântico para Agentes de IA

sentrysurface/surfaceproxy-core

Comprime DOM 60–90% para agentes de IA, reduz tokens de entrada 13×

Ver no GitHub
BomPluginScore · de 0 a 100

Gateway de proxy lightweight em Go que intercepta tráfego Chrome DevTools Protocol entre agentes de IA e navegadores, comprimindo o DOM em 60–90% removendo ruído HTML (scripts, styles, SVG, elementos invisíveis) e retornando Markdown semântico puro. Reduz drasticamente o uso de tokens (13× economia em casos reais) sem configuração, funcionando como daemon local com firewall integrado.

Instalação

$npx convez-ai sentrysurface/surfaceproxy-core

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
75%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Automação de navegação web com browser-use, Playwright ou Puppeteer
  • Integração com IDEs de IA (Cursor, Windsurf, Claude Desktop) para pesquisa e extração web
  • Redução de custos de tokens em loops de browser automation com LLMs
  • Firewall semântico para tráfego CDP entre agentes e navegadores

Veredito

Solução técnica focada e eficaz para um problema real: overhead de HTML em agentes. Binary estático em Go, zero dependências, impacto mensurável em custo. Bem documentado, mas requer conforto com daemons locais e CDP.

README

A tradução para o português deste README ainda está na fila.

SurfaceProxy

Stop paying the HTML context tax. Compress browser DOM trees 60–90% before they hit your LLM.

SurfaceProxy is a zero-config local proxy that intercepts Chrome DevTools Protocol traffic between your AI agent and the browser. It strips layout noise (scripts, styles, SVG, invisible elements) and returns clean semantic Markdown — so your agent pays for signal, not whitespace.

┌────────────────────────────────────────────────────────────────────────┐
│                         DEVELOPER MACHINE                              │
│                                                                        │
│  ┌──────────────────────────────┐        ┌──────────────────────────┐  │
│  │  Your Agent / IDE            │  MCP / │   SurfaceProxy           │  │
│  │                              │ ──────►│   (Go Binary)            │  │
│  │  • browser-use               │        │                          │  │
│  │  • Cursor / Claude Desktop   │ ◄──────│  • Semantic pruning      │  │
│  │  • Playwright                │ Pruned │  • DOM diff cache        │  │
│  │  • Custom agent script       │   MD   │  • Firewall rules        │  │
│  └──────────────────────────────┘        └──────────┬───────────────┘  │
│                                                     │ CDP              │
│                                                     ▼                  │
│                                         ┌──────────────────────────┐  │
│                                         │   Headless Chrome        │  │
│                                         │   (auto-launched)        │  │
│                                         └──────────────────────────┘  │
└────────────────────────────────────────────────────────────────────────┘

Why SurfaceProxy

Modern web pages routinely contain 2,000–8,000 tokens of raw HTML noise per navigation step — script tags, inline styles, SVG paths, tracking pixels, hidden elements. Your agent doesn't need any of it.

ScenarioRaw HTML tokensAfter SurfaceProxyReduction
GitHub repo page~8,400~62093%
Wikipedia article~12,000~1,80085%
PyPI search results~6,200~48092%
SaaS admin dashboard~15,000~2,10086%

At Claude 3.5 Sonnet pricing ($3/MTok input), a 5-step browser-use loop reading GitHub, PyPI, and Wikipedia pages costs roughly $0.18 per run without SurfaceProxy and $0.014 with it — a 13× reduction.

SurfaceProxy is a single static Go binary. No Python runtime, no Node.js, no Docker required. It runs as a local daemon and works with any framework that supports the Chrome DevTools Protocol.


⚡ 60-Second Quickstart

1. Install

# macOS / Linux — one-liner installer
curl -sSL https://raw.githubusercontent.com/sentrysurface/surfaceproxy-core/main/scripts/install.sh | sh

# Or build from source (requires Go 1.23+)
git clone https://github.com/sentrysurface/surfaceproxy-core
cd surfaceproxy-core
go build -o surface-proxy ./cmd/surface-proxy

2. Start the daemon

./surface-proxy
# [INIT] SurfaceProxy dev — Bootstrapping core engine
# [BROWSER] Auto-detected Google Chrome binary: /usr/bin/google-chrome
# [BROWSER] Launched headless Google Chrome (PID 12345) on port 54321
# [PROXY] CDP Proxy listening on ws://localhost:8443
# [UI] Dashboard listening on http://localhost:8080

Chrome is launched automatically. No configuration required.

3. Connect your agent (pick your framework)

browser-use (Python)

from browser_use import Agent, Browser, BrowserConfig
browser = Browser(config=BrowserConfig(
    cdp_url="ws://localhost:8443/v1/session"
))

Playwright (TypeScript)

const browser = await chromium.connectOverCDP("ws://localhost:8443/v1/session");

Cursor / Claude Desktop (MCP — one command)

./surface-proxy init --cursor    # Auto-registers in Cursor's mcp.json
./surface-proxy init --vscode    # Auto-registers in VS Code's mcp.json

Framework Integrations

browser-use

browser-use's BrowserConfig.cdp_url connects directly to SurfaceProxy's CDP proxy endpoint. Every get_dom_content() call your agent makes is automatically intercepted, pruned, and returned as Markdown — no changes to your agent code beyond the config line.

# Before (expensive)
browser = Browser()

# After (up to 90% cheaper — one line change)
browser = Browser(config=BrowserConfig(
    cdp_url="ws://localhost:8443/v1/session"
))

Per-session domain filtering:

# Lock this agent run to only the domains it needs
cdp_url="ws://localhost:8443/v1/session?allowlist=*.github.com,*.pypi.org"

→ Full examples: examples/browser-use/

Playwright / Puppeteer

// Playwright
const browser = await chromium.connectOverCDP("ws://localhost:8443/v1/session");

// Puppeteer
const browser = await puppeteer.connect({ browserWSEndpoint: "ws://localhost:8443/v1/session" });

→ Full examples: examples/playwright/

Cursor IDE (MCP)

surface-proxy init --cursor
# ✓  Registered surface-proxy in Cursor config:
#    /home/user/.config/Cursor/User/mcp.json
#    Restart Cursor to pick up the new MCP server.

Then in Cursor chat: Browse https://docs.python.org and summarise the getting started section.

→ Full guide: docs/cursor-setup.md

Claude Desktop (MCP)

→ Full guide: docs/claude-desktop-setup.md


Session-Level Firewall

Every /v1/session connection accepts query parameters that scope the firewall rules to that session without touching the global config:

ParameterDescriptionExample
allowlistComma-separated URL glob patternsallowlist=*.gov.au,*.edu
blocklistBlock specific domainsblocklist=*.doubleclick.net
targetOverride browser endpointtarget=ws://localhost:9222/...
# This agent can only navigate to Australian government and university domains
cdp_url="ws://localhost:8443/v1/session?allowlist=*.gov.au,*.edu.au"

MCP Tools (for Cursor / Claude Desktop)

ToolWhat it doesArguments
browseNavigate and return pruned Markdown{ "url": "https://..." }
getDOMCurrent page snapshot with structural diff{}
clickClick element by CSS selector{ "selector": "#btn" }
typeType into an input field{ "selector": "#q", "text": "hello" }
screenshotCapture PNG (base64){}

Live Dashboard

Open http://localhost:8080 while the daemon is running to see real-time token savings, active sessions, compression ratios, and dollar savings across all connected agents.


Core Architecture

[ CDP / MCP Traffic In ]
         │
┌────────┴──────────────────┐
│  Firewall Rule Engine     │  Compiled regex, atomic pointer swap, <1ms eval
│  (allowlist / blocklist)  │
└────────┬──────────────────┘
         │ allowed
┌────────┴──────────────────┐
│  Semantic Pruning Engine  │  Streaming HTML tokenizer, sync.Pool buffers
│  strip: script, style,    │  DOM diff cache (SHA-256 ring buffer)
│  svg, noscript, iframe    │  Output: Markdown or JSON
└────────┬──────────────────┘
         │
┌────────┴──────────────────┐
│  Telemetry Ledger         │  Per-session byte/token accounting
│  (in-memory, thread-safe) │  Dollar savings calculation
└───────────────────────────┘
PropertyImplementation
Single static binaryNo runtime dependencies, CGO_ENABLED=0
Sub-2ms proxy overheadGoroutine-isolated sessions, non-blocking channels
Zero-allocation hot pathssync.Pool byte buffers, streaming tokenizer
Hot-reload configfsnotify watches surface-proxy.json at runtime
Panic isolationSafeGo() wraps every goroutine with recover()
Cross-platform Chrome detectionPATH → Windows registry → well-known OS paths

Development

# Run tests
go test ./...

# Build for current platform
go build -o surface-proxy ./cmd/surface-proxy

# Generate go.sum (requires Docker)
.\scripts\generate-gosum.ps1    # Windows
bash scripts/generate-gosum.sh  # macOS / Linux

# Build Docker dev image
docker-compose -f docker-compose.dev.yml up

Documentation

GuideDescription
Cursor SetupConnect Cursor IDE via MCP
Claude Desktop SetupConnect Claude Desktop via MCP
Playwright QuickstartPlaywright & Puppeteer CDP integration
ContributingHow to contribute

License

Business Source License 1.1 — see BSL-LICENSE.txt.

Feedback & Support

For issues, feedback, and inquiries, please contact support@sentrysurface.io or visit https://sentrysurface.io/contact

Ver o original no GitHub

Bom para

Relacionados