mcprune

MCP middleware that prunes Playwright accessibility snapshots for LLM agents. Zero ML, 75-95% token reduction, all refs preserved.

The problem

Playwright MCP gives LLM agents browser control via accessibility snapshots — YAML trees of every element on the page. But real pages produce 100K-400K+ tokens per snapshot. That's too large for any LLM context window to handle effectively.

mcprune sits between the agent and Playwright MCP, intercepting every response and pruning snapshots down to only what the agent needs: interactive elements, prices, headings, and refs to click.

Agent  ←→  mcprune (proxy)  ←→  Playwright MCP  ←→  Browser
              ↓
         prune() + summarize()
         75-95% token reduction

Related MCP server: @playwright/mcp

Before / After

Amazon search page — raw Playwright snapshot: ~100,000 tokens. Includes every pixel-level wrapper, tracking URL, sidebar filter, energy label, legal footer, and duplicated link.

After mcprune: ~14,000 tokens. Product titles, prices, ratings, color options, "Add to basket" buttons, and clickable refs. Everything an agent needs to shop.

Amazon product page: ~28,000 tokens → ~3,300 tokens (88% reduction). Full buy flow preserved.

Quick start

As an MCP server (recommended)

Add to your Claude Code, Cursor, or any MCP client config:

{
  "mcpServers": {
    "browser": {
      "command": "node",
      "args": ["/path/to/mcprune/mcp-server.js"]
    }
  }
}

That's it. The agent gets all Playwright browser tools (browser_navigate, browser_click, browser_type, browser_snapshot, etc.) with automatic pruning on every response.

Options:

• --headless — run browser without visible window

• --mode auto|act|browse|navigate|full — pruning mode (default: auto, which picks act or browse per page from the URL and snapshot content)

As a library

import { prune, summarize } from 'mcprune';

const snapshot = await page.locator('body').ariaSnapshot();

const pruned = prune(snapshot, {
  mode: 'act',
  context: 'iPhone 15 price'  // optional: keywords for relevance filtering
});

const summary = summarize(snapshot);
// → "Apple iPhone 15 (128GB) - Black | pick color(5), set quantity, add to basket, buy now, 91 links"

How it works

A 9-step rule-based pipeline. No ML, no embeddings, no API calls.

Context-aware pruning

When the agent types a search query, mcprune captures it as context. Product cards that don't match any keywords are collapsed to just their title, while matching products keep full details.

Agent types "iPhone 15" in search box
  → mcprune captures context: ["iphone", "15"]
  → Matching cards: full price, rating, colors, buttons
  → Non-matching cards: title only

Pruning modes

The mode controls only how mcprune prunes the snapshot. Playwright MCP executes all browser actions identically regardless of mode.

Browse mode preserves paragraphs, code blocks, term/definition pairs, inline links, all headings, and figure captions — content that act mode drops because agents taking actions don't need article text.

Performance

Tested live via MCP proxy:

All refs ([ref=eN]) are preserved. The agent can click, type, and interact with every element in the pruned output.

Install

git clone https://github.com/hamr0/mcprune.git
cd mcprune
npm install
npx playwright install chromium

Test

npm test  # 148 tests

Project structure

mcprune/
  mcp-server.js       MCP proxy — entry point, spawns Playwright MCP
  src/
    prune.js           9-step pruning pipeline + summarize(), mode-aware filtering
    parse.js           Playwright ariaSnapshot YAML → tree
    serialize.js       Tree → YAML, URL cleaning
    roles.js           ARIA role taxonomy (LANDMARKS, INTERACTIVE, STRUCTURAL, ...)
    proxy-utils.js     Extracted proxy logic (snapshot detection, context, stats)
  test/
    parse.test.js      8 parser tests
    prune.test.js      12 prune + summarize tests
    proxy.test.js      51 proxy utility + auto-detection tests
    edge-cases.test.js 77 edge case + browse mode + regression tests
    fixtures/          9 real-world page snapshots (e-commerce, docs, forums, gov)
  scripts/             Dev tools for capturing live snapshots
  blueprint.md         Detailed technical documentation
  docs/                Structured project documentation

How the MCP proxy works

1. Spawns @playwright/mcp as a child process over stdio

2. Forwards all JSON-RPC messages bidirectionally

3. Tracks context from browser_type text and browser_navigate URL params

4. Intercepts all tool responses (not just browser_snapshot — Playwright embeds snapshots in browser_click, browser_type, etc.)

5. Detects snapshots via regex, runs prune() + summarize()

6. Prepends a stats header: [mcprune: 85.8% reduction, ~100K → ~14K tokens | page summary]

Robustness & security

mcprune processes whatever the open web hands back through Playwright, so the pipeline is built to fail safe:

• Zero runtime dependencies beyond @playwright/mcp — npm audit is clean.

• Bounded tree depth — pathological/malicious nesting can't crash the pruner (depth is capped; no refs are lost).

• Fail-open proxy — if a snapshot can't be parsed or pruned, the original response is forwarded unchanged rather than dropped, so the agent never wedges.

• Injection-safe stats header — page-derived text (titles, labels) is sanitized so it can't break out of the [mcprune: …] frame.

• Domain-anchored mode detection — look-alike hosts (e.g. wikipedia.org.attacker.net) can't spoof a pruning mode.

License

MIT