Plasmate

The browser engine for agents.
HTML in. Semantic Object Model out.

Website · Docs · Benchmarks · Crates.io · npm · PyPI

Dependency and CI trust policy, local audit commands, and scorecard promotion rules are documented in Supply-chain policy.

Plasmate compiles HTML into a Semantic Object Model (SOM), a structured representation that LLMs can reason about directly. It runs JavaScript via V8 and implements a documented CDP subset for supported Puppeteer workflows. SOM output removes presentation and runtime markup; output size and tokenization are page-, configuration-, serialization-, and tokenizer-dependent.

Install

curl -fsSL https://plasmate.app/install.sh | sh

Or install the native engine with Cargo:

cargo install plasmate

The npm and PyPI packages named plasmate are client SDKs; they do not bundle or install the native plasmate executable. Install the native engine first, then add npm install plasmate or pip install plasmate to applications that need the corresponding SDK.

Quick Start

Fetch a page and get structured output

plasmate fetch https://news.ycombinator.com

Returns SOM JSON: structured regions, interactive elements with stable IDs, and content. Measure output size on the pages and configuration used by your application.

Start a CDP server (Puppeteer compatible)

plasmate serve --protocol cdp --host 127.0.0.1 --port 9222

Then connect with Puppeteer:

import puppeteer from 'puppeteer-core';

const browser = await puppeteer.connect({
  browserWSEndpoint: 'ws://127.0.0.1:9222',
  protocolTimeout: 10000,
});

const page = await browser.newPage();
await page.goto('https://example.com');

const title = await page.evaluate(() => document.title);
console.log(title);

await browser.close();

Start an AWP server (native protocol)

plasmate serve --protocol awp --host 127.0.0.1 --port 9222

AWP's foundational v0.1 core has seven wire methods: awp.hello, session.create, session.close, page.navigate, page.observe, page.act, and page.extract. The current native handler also exposes session-listing, network-interception, plugin, cookie, and proxy-pool extensions. Click, type, select, scroll, toggle, and clear are page.act actions, not separate wire methods.

Run a supervised stateful workflow

plasmate agent-run --plan examples/agent-workflow.json \
  --report agent-workflow-report.json --dry-run

Plans are versioned and bounded; mutating steps require separate --confirm-step <id> approvals, while JavaScript evaluation and cookie writes also require category opt-ins. See the workflow contract for schemas, secret references, containment, and execution examples.

Run as an MCP tool server (Model Context Protocol)

plasmate mcp

This exposes Plasmate over stdio as MCP tools:

• fetch_page - get structured SOM from any URL
• extract_text - get clean readable text
• extract_links - get deduplicated links from a page
• ard_discover - inspect bounded static ARD v0.9 draft catalog signals without invoking them
• crawl_policy - evaluate RFC 9309 robots.txt policy without changing fetch behavior
• inspect_page - return bounded SOM first, with deterministic optional visual fallback
• cache_status - inspect MCP SOM cache reuse and restorable page-state entries
• session_status - inspect active sessions, loaded URLs, HTML/SOM/node inventory, and disabled/readonly interactive counts
• trace_status - inspect bounded action-trace retention for one session
• trace_export - export privacy-safe plasmate.trace.v1 events
• trace_clear - discard retained events without resetting their sequence
• replay_validate - validate a retained action without executing it
• screenshot_page - capture a page screenshot, with SOM fallback
• open_page - start an interactive session (returns session_id, SOM, cache_restored)
• navigate_to - navigate an existing session
• evaluate - run JavaScript in the page context
• click - click elements by SOM element ID
• type_text - type into an input or textarea
• select_option - select a dropdown option
• scroll - scroll the page or an element
• toggle - toggle checkbox, radio, or details state
• clear - clear an input or textarea
• close_page - end a session
• get_cookies - read session cookies
• set_cookies - add or update session cookies
• clear_cookies - remove session cookies

For an authenticated local Streamable HTTP endpoint, set a capability token and select the HTTP transport explicitly:

PLASMATE_MCP_HTTP_TOKEN="$(openssl rand -hex 32)" \
  plasmate mcp --transport http --host 127.0.0.1 --port 9272

The endpoint is http://127.0.0.1:9272/mcp. Every request must include Authorization: Bearer <token>. The server implements JSON response mode for the stateful MCP 2025-11-25 transport and the stateless 2026-07-28 release candidate. It deliberately returns HTTP 405 for GET rather than claiming an SSE notification stream it does not implement. See docs/mcp-streamable-http.md for lifecycle, headers, and browser-Origin policy.

Example Claude Desktop config:

{
  "mcpServers": {
    "plasmate": {
      "command": "plasmate",
      "args": ["mcp"]
    }
  }
}

For AI Agents

Plasmate is purpose-built for AI agent pipelines. Several ways to wire it in:

MCP (Claude Desktop, Cursor, VS Code Copilot, Windsurf)

Add to your MCP config and every tool call automatically uses Plasmate:

{
  "mcpServers": {
    "plasmate": {
      "command": "plasmate",
      "args": ["mcp"]
    }
  }
}

Config file locations:

• Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
• Cursor — ~/.cursor/mcp.json
• VS Code Copilot — .vscode/mcp.json (workspace) or user settings
• Windsurf — ~/.codeium/windsurf/mcp_config.json

Once connected, the native server advertises its current tool surface through MCP tools/list. It includes stateless fetch/extraction/discovery tools, cache/session/trace inspection, screenshot and stateful page interaction, cookie operations, and validation-only replay. Query tools/list instead of depending on a hard-coded count; the authoritative registration is src/mcp/server.rs.

Tip: use selector="main" to strip nav/footer, selector="interactive" to return only actionable elements, or selector="action:click" to build a compact click-target menu before the LLM sees the content. Use cache_status after repeated fetches to inspect local MCP SOM cache hits, misses, selector entries, effective-HTML entries, and avoided HTML work. Use session_status before long interactive runs to inspect active browser session count, capacity, loaded URLs, raw/effective HTML sizes, SOM sizes, node-map counts, structured data presence, disabled/readonly interactive counts, age, and idle time. Stateful open_page and navigate_to return cache_restored=true when they reuse a content-hash-validated cache entry with both SOM and effective HTML. Set trace=true on open_page to opt into bounded, memory-only action tracing, then use trace_status, trace_export, and side-effect-free replay_validate. Typed values and page bodies are never exported. See docs/session-tracing.md for the privacy contract, bounds, drift classes, and validation-only limitation.

Before a multi-page crawl, use crawl_policy or the CLI equivalent:

plasmate crawl-policy https://example.com/private --product-token Plasmate

The versioned report distinguishes an unavailable robots file (4xx, access permitted by RFC 9309) from an unreachable one (network/5xx, access denied). It is advisory metadata, not authorization, and does not silently alter ordinary fetch or fetch_page. See docs/CRAWL-POLICY.md.