PlayGuard

An MCP proxy that sits between your AI agent and browser/design tools. It wraps Playwright MCP and optionally a Figma MCP, exposing a single unified MCP server while transparently adding:

• Automatic session recovery — dead browser sessions are revived; the agent never sees a crash error
• Token optimization — compact snapshots, delta diffs, snapshot cache, and eval caching reduce browser snapshot cost by 70–90%
• Figma response optimization — strips metadata, invisible layers, duplicate component instances, and SVG geometry blobs before the response reaches the agent
• Screenshot policy — redirect, warn, block, or allow screenshot calls

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

Architecture

Claude Code / Claude Desktop / Cursor / Codex
           │
           │  MCP (stdio)
           ▼
    ┌─────────────────┐
    │    PlayGuard    │  ← single proxy for everything
    │                 │
    │  • router       │  browser_* → Playwright MCP
    │  • recovery     │  figma_*   → Figma MCP (optional)
    │  • optimizer    │
    │  • cache        │
    │  • analytics    │
    └────────┬────────┘
             │
      ┌──────┴──────┐
      ▼             ▼
Playwright MCP   Figma MCP
      │
      ▼
  Chromium / Firefox / WebKit

Figma MCP is optional. If FIGMA_MCP_CMD is not set, PlayGuard runs in browser-only mode with no behavior changes. Playwright MCP is bundled as a dependency — no separate installation required.

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]

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

After browser_navigate, PlayGuard immediately fetches a snapshot in the background. The next browser_snapshot is served from cache instantly. An unchanged page returns UNCHANGED without hitting the browser.

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.

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). If your Figma MCP upstream returns pre-simplified YAML (e.g. Framelink figma-developer-mcp), those modules find nothing to strip — but inBytes/outBytes are still measured from the actual upstream response text, so the automatic YAML→JSON reformatting (typically ~2x on its own) and Module 5's metadata trim both still count as real savings. parseSkip in the NDJSON log means the response body couldn't be parsed as JSON or YAML at all, not that the optimizer no-op'd.

Module 1 — Metadata Cleaner: Removes fields irrelevant to layout: createdAt, updatedAt, creator, thumbnailUrl, pluginData, sharedPluginData, exportSettings, reactions, interactions, etc.

Module 2 — Invisible Layer Pruner: Recursively removes nodes where visible === false or opacity === 0.

Module 3 — Component Deduplication: Repeated instances of the same component are collapsed to a reference. 100 buttons → first full definition + 99 references with overrides only.

{ "type": "INSTANCE", "name": "Button/Primary", "_ref": "123:4", "overrides": [] }

Module 4 — SVG Refs: Replaces inline SVG geometry (fillGeometry) with { "_svgRef": "nodeId" }. The agent gets the shape identifier without thousands of path coordinates.

Module 6 — Layout Compressor: Removes absolute x/y from nodes inside Auto Layout containers — they are redundant because position is determined by layoutMode, gap, and padding.

Module 5 — Top-Level Metadata Trim: Drops metadata.thumbnailUrl (a signed, single-use preview URL) and metadata.lastModified from pre-simplified upstream shapes like Framelink's { metadata, nodes, globalVars } — fields Module 1 can't reach because it only walks document/children, not a sibling metadata key.

Requirements

• Node.js 18+
• npm

Installation

git clone https://github.com/ZenyaDAR/PlayGuard.git
cd playguard
npm install
npm run build

Usage

Claude Code

Add to ~/.claude/claude_desktop_config.json (or your project's .claude/settings.json):

Browser only:

{
  "mcpServers": {
    "playguard": {
      "command": "node",
      "args": ["/path/to/playguard/dist/index.js"],
      "env": {
        "PLAYGUARD_SCREENSHOTS": "redirect"
      }
    }
  }
}

Browser + Figma:

{
  "mcpServers": {
    "playguard": {
      "command": "node",
      "args": ["/path/to/playguard/dist/index.js"],
      "env": {
        "PLAYGUARD_SCREENSHOTS": "redirect",
        "FIGMA_MCP_CMD": "npx @figma/mcp",
        "FIGMA_API_KEY": "your-figma-api-key",
        "FIGMA_CACHE_TTL": "60000"
      }
    }
  }
}

Do not add Playwright MCP separately — PlayGuard spawns it automatically from its bundled dependency.

Claude Desktop

Same JSON format. Config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Windows paths

Use forward slashes in JSON strings. Spaces in paths do not need escaping:

"args": ["C:/Users/YourName/projects/playguard/dist/index.js"]

Environment Variables

Playwright

Figma

Configuration Examples

Headless browser + Figma with cache:

"env": {
  "PLAYWRIGHT_MCP_ARGS": "--headless",
  "FIGMA_MCP_CMD": "npx @figma/mcp",
  "FIGMA_API_KEY": "your-figma-api-key",
  "FIGMA_CACHE_TTL": "120000"
}

Firefox + block screenshots:

"env": {
  "PLAYWRIGHT_MCP_ARGS": "--browser firefox",
  "PLAYGUARD_SCREENSHOTS": "block"
}

Persist cookies between sessions:

"env": {
  "PLAYWRIGHT_MCP_ARGS": "--storage-state /tmp/browser-state.json"
}

Redirect screenshots + hard token cap:

"env": {
  "PLAYGUARD_SCREENSHOTS": "redirect",
  "PLAYGUARD_TOKEN_BUDGET": "4000"
}

Analytics

All tool calls are logged to logs/YYYY-MM-DD.ndjson. Run the report:

npm run analyze

Sample output:

── Snapshot token savings ────────────────────────────────
  Cache hits:      12/47 snapshots (8 from prefetch)
  Bytes saved by cache:    84.3 KB  (~21 075 tokens)
  Bytes saved by compact:  312.1 KB (~78 025 tokens)
  Total saved:             396.4 KB (~99 100 tokens)
  Reduction vs raw:        83%  (82.1 KB sent vs 478.5 KB without PlayGuard)

── PlayGuard interceptions ───────────────────────────────
  Screenshot → snapshot: 5 redirected (2 from cache, ~18 400 tokens saved)
  Eval cache hits:       8/11 evaluates (~240ms saved at 30ms avg)

── Figma optimizer ───────────────────────────────────────
  Calls:       24 total  (6 cache hits, 18 optimized)
  Tokens in:   ~71 000  →  out: ~22 750  (saved ~48 250, -68%)

── Latency by tool ───────────────────────────────────────
| tool              | count | errors | err% | intercepted | avg ms | p50 | p95 |

Each NDJSON line includes all fields for downstream analysis:

• Playwright: rawBytes, keptBytes, savedBytes, delta, cacheHit, prefetchHit, snapCount, scriptHash
• Figma: fileKey, nodeId, inBytes, outBytes, savedTokens, metaKeysDeleted, invisiblePruned, svgRefsReplaced, instancesCollapsed, layoutCoordsRemoved

Benchmark

npm run bench

Measures proxy overhead, snapshot vs screenshot size, cache hit rate, and crash recovery time. No LLM in the loop — raw numbers only.

Tests

npm test

Covers collapseRuns, compactSnap (including token budget boundary), and the full Figma optimizer pipeline (optimizeFigmaResponse) in test/playguard.test.mjs, plus dead() crash detection, splitArgs() quoting, the shared ttlCache() helper, and the decideSnapshot() cache/delta/hint decision logic in test/playguard-core.test.mjs.

CI (GitHub Actions, .github/workflows/ci.yml) runs npm test on every push and pull request to main.

Comparison

Project Structure

playguard/
├── src/
│   └── index.ts                    All server logic (~690 lines)
├── dist/                           Compiled output (generated by npm run build)
├── bench/
│   ├── run.mjs                     Benchmark: latency, token savings, crash recovery
│   └── analyze.mjs                 Analytics report from NDJSON logs
├── test/
│   ├── playguard.test.mjs          Compact/Figma optimizer tests (Node built-in test runner)
│   └── playguard-core.test.mjs     Crash detection, arg parsing, caching, snapshot decision tests
├── .github/workflows/ci.yml        Runs npm test on push/PR
├── logs/                           Per-day NDJSON call logs (auto-created at runtime)
├── package.json
└── tsconfig.json

License

MIT