Substrate

Stop wasting 48K tokens to read a webpage. Substrate compresses a typical content page into roughly 1–4K tokens your LLM can actually use — vs. ~48K of raw HTML.

Substrate is an MCP server that gives your AI agent eyes and hands on the web. It extracts a compressed semantic graph of any webpage — buttons, inputs, links, dropdowns, checkboxes — with precise pixel coordinates, and handles clicking, typing, and selection via spatial coordinates. No CSS selectors. No xpaths. No hallucination.

Why It Matters

Every other browser automation approach burns tokens on noise:

| Approach | Tokens | Extraction | What Your LLM Gets | |:---|:---|:---|:---| | Raw HTML (page.content()) | ~48,000 | 5ms | Full DOM tree — scripts, styles, hidden elements, ad markup. LLM drowns in noise and hallucinates clicks on invisible elements. | | Vision (screenshot + OCR) | ~8,000 | ~800ms | A pixel blob. LLM can "see" the page but can't target anything precisely. Clicks land 20px off. Forms fail. | | Substrate | ~1,000–4,000 | ~10–30ms | Structured JSON: what each element is, where it is, what state it's in. LLM clicks the right thing on the first try. |

The math: a ~110-element content page (say, Wikipedia) compresses to roughly ~2,300 tokens — about 1.8% of a typical 128K context window. You can fit roughly ~55 page extractions before the LLM runs out of room. With raw HTML, you get 2.

Token figures are order-of-magnitude, measured live on representative pages (example.com ~84 tok, Wikipedia ~3.5K, Hacker News front page ~4.4K, extraction 8–58ms). They scale with page density; the extractor caps output at MAX_ELEMENTS=400, so very dense pages are truncated rather than emitted in full. The math is arithmetic: on a ~2.3K-token page, ⌊128K/2.3K⌋ ≈ 55 extractions.

The real win — shorter action loops:

Without Substrate:                          With Substrate:
navigate → screenshot                       navigate
→ "I see a button" → click (wrong)          → {btn id=3 "Submit" [640,400]}
→ screenshot → "ah, more right"             → click(3) → done.
→ click → "not that either"                 
→ screenshot → ...                          2 tool calls. Task complete.
8-12 tool calls. Task complete.

That's not a marginal improvement. That's 5-6x fewer API calls, 5-6x less latency, and 5-6x lower cost per web task.

How It Works

Substrate runs as a headless Chromium browser via the Model Context Protocol (MCP). Your LLM agent talks to it through 10 simple tools:

| Tool | What It Does | |------|-------------| | navigate | Load a URL, get back the page graph (capped at 400 elements) | | click | Click any element by its numeric ID | | type_text | Type into an input field (auto-clears first) | | select_option | Pick a dropdown option by value | | press_key | Press a keyboard key (Escape, Enter, Tab, arrows, modifiers) | | scroll | Scroll up/down by 80% of viewport | | screenshot | Get a visual snapshot + the graph together | | go_back / go_forward | Browser history navigation | | get_current_url | Check where you are |

Every navigation and interaction tool returns the same compressed graph (get_current_url returns just the URL; screenshot returns the image plus the graph). Your LLM reads the graph, picks an element ID, and calls the next tool. No image interpretation. No HTML parsing. Just IDs and coordinates.

Installation & Setup

Substrate is a standalone Model Context Protocol (MCP) server. You do not need to write code to use it — you just plug it into your AI assistant.

Option 1: Claude Desktop (Recommended)

1. Open your Claude Desktop configuration file:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
2. Add the substrate-browser server to the mcpServers block:

{
  "mcpServers": {
    "substrate-browser": {
      "command": "npx",
      "args": ["-y", "substrate-browser"]
    }
  }
}

3. Restart Claude Desktop. You will now see the 10 browser tools available (a small hammer icon) and you can ask Claude to "Go to example.com and tell me what you see".

(Note: Playwright will automatically download the Chromium binary on the very first run. This requires Node.js 20+ installed on your system).

Option 2: Running from Source (For Developers)

If you want to modify the extraction logic or add your own tools:

git clone https://github.com/manuelinuxkr/substrate-b.git
cd substrate-b
npm install
npx playwright install chromium
npm run build
npm start

License

MIT