PlayGuard

PlayGuard

A proxy MCP: one MCP server in your client config that runs several MCP servers under the hood, exposes all their tools through a single connection, and optimizes their responses.

You add playguard to your MCP client once. Which upstream MCPs it starts is decided by environment variables in that one config entry — an upstream without its variable is not started and its tools are not listed. Every response passes through PlayGuard on the way back, which adds:

• One connection, several upstreams — Playwright MCP (bundled, always on), Figma (Framelink or the official desktop server), Chrome DevTools MCP, Shopify Dev MCP and Context7. A failing optional upstream only removes its own tools; the others keep working
• Token optimization — compact/delta/UNCHANGED snapshots, Figma tree trimming, network-list summaries, rewritten documentation answers; browser snapshot cost drops 70–90%
• Session recovery — dead browser sessions and crashed upstream processes are revived; the agent doesn't see the crash
• Caching — snapshot, browser_evaluate, Figma and on-disk documentation caches
• Screenshot policy — redirect, warn, block, or allow screenshot calls
• Logged savings — every call is written to an NDJSON log; npm run analyze reports tokens saved per upstream
• Two tools of its own — playguard_a11y_audit (axe-core in the Playwright page) and playguard_compare_design (Figma node vs live DOM element, Framelink only)

Works with Claude Code, Claude Desktop, Cursor, Codex, or any MCP-compatible agent.

Website: playguard.dev · Docs: How PlayGuard works

Upstream MCPs at a glance

Figma is one option at a time: Framelink or the official desktop server (FIGMA_MCP_URL wins if both are set). Figma's remote server (mcp.figma.com) can't be proxied — see Official Figma MCP.

Choosing upstreams

The env block of the playguard entry decides what runs. Nothing to install separately: Playwright MCP ships with PlayGuard, the others are launched through the command you give. For example, Playwright + Framelink Figma + Shopify Dev:

{

"mcpServers": { "playguard": { "command": "npx", "args": ["-y", "playguard@latest"], "env": { "PLAYGUARD_SCREENSHOTS": "redirect", "FIGMA_MCP_CMD": "npx", "FIGMA_MCP_ARGS": "-y figma-developer-mcp --stdio", "FIGMA_API_KEY": "your-figma-api-key", "SHOPIFY_DEV_MCP_CMD": "npx -y @shopify/dev-mcp@latest" } } } }

Remove a variable to drop that upstream. Restart the MCP client after changing the config — the server and its upstreams are started once per client session.

Architecture

Claude Code / Claude Desktop / Cursor / Codex

│ │ MCP (stdio) — one connection ▼ ┌───────────────────┐ │ PlayGuard │ proxy MCP │ │ │ • router │ browser_* → Playwright MCP (always) │ • recovery │ Figma tools → Framelink / Figma (FIGMA_MCP_CMD / _URL) │ • optimizers │ DevTools tools → Chrome DevTools MCP (DEVTOOLS_MCP_CMD) │ • caches │ Shopify docs tools → Shopify Dev MCP (SHOPIFY_DEV_MCP_CMD) │ • analytics │ Context7 tools → Context7 (CONTEXT7_MCP_CMD) │ • own tools │ playguard_a11y_audit, playguard_compare_design └─────────┬─────────┘ │ one child process per enabled upstream ┌─────────┼───────────┬──────────┬───────────┬──────────┐ ▼ ▼ ▼ ▼ ▼ ▼ Playwright Figma Chrome Shopify Context7 (each optional MCP MCP DevTools Dev MCP except Playwright) │ │ ▼ ▼ Chromium / Firefox / WebKit Chrome (its own instance)

Every upstream except Playwright is optional. If none of FIGMA_MCP_CMD, FIGMA_MCP_URL, DEVTOOLS_MCP_CMD, SHOPIFY_DEV_MCP_CMD and CONTEXT7_MCP_CMD is set, PlayGuard runs with Playwright only. Playwright MCP is bundled as a dependency — no separate installation required. Optional upstreams start lazily and are isolated from each other; tools/list waits a bounded time for a slow one and announces its tools later with tools/list_changed.

Features

Browser (Playwright)

Automatic Session Recovery

PlayGuard intercepts dead-session errors before the agent sees them:

Target.*closed · Browser.*closed · connect ECONNREFUSED · crashed

It restarts Playwright MCP, restores the last URL, and retries the call transparently. Two concurrent calls during a crash → one restart, both calls continue.

Compact Snapshots

browser_snapshot normally returns the full accessibility tree. PlayGuard keeps only lines with [ref=] (interactive elements) and structural landmarks (nav, main, form, dialog, …). Static text and decorative images have no refs and are not needed for navigation.

[PlayGuard compact: 312/1840 lines, ~83% removed, 124.3KB→14.1KB]

Snapshot Filtering

For pages where even the compact tree is large, browser_snapshot accepts optional params to narrow the result to one subtree:

• section — return only the landmark subtree whose label starts with or contains this string (e.g. "form", "navigation \"Footer\"")
• around — return only the landmark subtree containing this [ref=N], useful once you know a specific element's ref
• depth — cap the returned subtree's depth (combine with section/around for a high-level overview first, or use alone to flatten the whole tree)

Falls back to the full snapshot with a [PlayGuard: ... not found] warning if the requested section/ref doesn't exist. Switching filters between calls always forces a fresh snapshot — it never returns a stale UNCHANGED/cached result from a differently-filtered request.

Smart Wait

Set PLAYGUARD_SMART_WAIT=1 to have browser_snapshot retry when a page looks mid-load — few interactive refs plus a loading/spinner/skeleton indicator in the text. Retries PLAYGUARD_SMART_WAIT_MAX_RETRIES times, PLAYGUARD_SMART_WAIT_MS apart, before returning (with a warning if it still looks like it's loading). Off by default — it adds latency to every snapshot call.

Set PLAYGUARD_COMPACT=false to receive the raw snapshot.

Delta Snapshots

When a page changes only slightly, PlayGuard returns a diff instead of the full snapshot:

[PlayGuard delta: +3 added, 1 removed, ~91% saved]

ADDED:

• button "Submit" [ref=47]

REMOVED:

• button "Loading..." [ref=44]

Snapshot Cache + Prefetch

An unchanged page returns UNCHANGED without hitting the browser.

Optional prefetch (PLAYGUARD_PREFETCH_SNAPSHOT=true, off by default since 0.8.0): after browser_navigate, PlayGuard fetches a snapshot in the background so the next browser_snapshot is served from cache. It only pays off for agents that snapshot right after navigating — any browser_evaluate or action in between discards it, and the background call competes with that action for the browser.

Shorter Playwright Responses

PlayGuard starts the bundled Playwright MCP with --codegen none, which drops the ### Ran Playwright code block from every response (80–150 characters per call). Not applied to a custom PLAYWRIGHT_MCP_CMD or when --codegen is already in PLAYWRIGHT_MCP_ARGS; set PLAYGUARD_CODEGEN=keep to restore it.

Batching Hints

Every browser_evaluate / browser_run_code_unsafe call waits at least ~0.5 s inside Playwright MCP for the page to settle. PlayGuard appends a one-line hint to those tools' descriptions (and to browser_wait_for) nudging the agent to combine checks into fewer calls. PLAYGUARD_HINTS=false turns this off.

Screenshot Policy

Eval Cache + Output Compaction

Repeated browser_evaluate calls with the same script on the same URL are served from cache (configurable TTL). Large eval output is truncated to a character limit to avoid blowing the context window.

Accessibility Audit

playguard_a11y_audit runs axe-core (bundled) inside the page the browser_* tools have open and returns a short report instead of axe's raw JSON:

[PlayGuard a11y: 6 violations (6 elements) · 7 rules passed · axe 4.14.0 · wcag2a,wcag2aa,… · https://shop.test/]

critical image-alt — Images must have alternative text (1)

• img Element does not have an alt attribute (+4 more) https://dequeuniversity.com/rules/axe/4.14/image-alt

serious color-contrast — Elements must meet minimum color contrast ratio thresholds (1)

• main > p Low contrast text Element has insufficient color contrast of 1.91 (foreground color: #bbbbbb, …). Expected contrast ratio of 4.5:1

Rules are sorted by impact; each lists at most 5 elements (the rest are counted) with a CSS selector, a 140-char html excerpt and the first way to fix it. Rules axe could not decide are named under "Needs manual review".

Automated checks don't cover keyboard flow or screen-reader wording. The page keeps axe loaded after the first audit.

Figma Optimizer

PlayGuard intercepts Figma MCP responses and runs them through an optimization pipeline before delivering to the agent.

[PlayGuard figma: -68% (284.0KB→91.0KB)]

Note: Modules 1–4 and 6 target raw Figma REST API JSON (document.children, componentId, fillGeometry). I