@peekdev/mcp

@peekdev/mcp

Let your AI coding agent debug what already happened in your real browser — peek reads your locally-recorded sessions (DOM history, console & network errors, the action right before a failure) over MCP and turns them into a runnable Playwright repro. Local-first: peek uploads nothing — what your MCP client does with the data is up to you.

Docs: https://peek.cubenest.in

@peekdev/mcp is two things in one binary:

• The stdio MCP server that AI coding agents (Claude Code, Cursor, Cline, Windsurf, Continue, Zed) speak to when querying your captured browser sessions.
• The native messaging host that Chrome's MV3 extension speaks to when writing into ~/.peek/sessions.db.

The same binary handles both roles — chosen by argv. You don't install this package directly in normal use; the @peekdev/cli peek init wizard wires it into your AI client's MCP config and into Chrome's NativeMessagingHosts/.

Requires Node.js ≥ 22. The native better-sqlite3 dependency only ships prebuilt binaries for Node 22+ — on Node 20 (notably Windows, which has no C/C++ toolchain by default) the install falls back to compiling from source and fails. Use Node 22 or newer.

You probably want @peekdev/cli instead

npm install -g @peekdev/cli
peek init

Read on if you're configuring the MCP server manually, building tooling against it, or want the protocol/tool reference.

What this is NOT

• Not a remote MCP server. Peek is local-only: stdio transport over a child-process pipe. There is no HTTP listener, no SSE endpoint, no remote auth. The MCP transport spec's Streamable HTTP variant is out of scope by design.
• Not a write-by-default tool. Read tools are unauthenticated. The write tools (execute_action, request_authorization) are gated by the per-origin permission model (off by default) + the destructive blocklist + the audit-log writer. The cross-process IPC that delivers them to the browser native host (LocalSocketHostBridge ↔ HostSocketServer over ~/.peek/host.sock) is now wired: at Level 3 every action prompts the side-panel confirm banner before it runs. The real-browser MAIN-world dispatch + banner UX are covered by the Playwright E2E (e2e/smoke.spec.ts); the bridge, relay, dispatcher, and confirm logic are unit-tested.
• Not a wrapper around Chrome DevTools Protocol. The server reads recorded events from SQLite; the extension owns capture. No live chrome.debugger access from the MCP server.

One-click install (Cursor)

Click the button (or paste the link into Cursor) and Cursor prompts to add peek to ~/.cursor/mcp.json — no terminal needed. This wires the MCP server only; to capture sessions you still run peek init once (registers the native messaging host) and install the Chrome extension.

Install as a Claude Code plugin

If you use Claude Code, install peek as a plugin in one step:

/plugin marketplace add Cubenest/rrweb-stack
/plugin install peekdev@peek

That wires up this MCP server (18 tools) plus the peek skill. You still need the recorder — run npx @peekdev/cli init once and install the peek Chrome extension — before there are sessions to read. Local-first: peek uploads nothing — what your MCP client does with the data is up to you.

Manual MCP-client config

If peek init doesn't recognize your client, paste this into your client's MCP server registry:

{
  "mcpServers": {
    "peek": {
      "command": "npx",
      "args": ["-y", "@peekdev/mcp@latest"]
    }
  }
}

The @latest tag is required while peek is in alpha: every published version is a prerelease (0.1.0-alpha.*), and a bare npx -y @peekdev/mcp resolves the implicit * range, which doesn't match prereleases (ETARGET: No matching version found for @peekdev/mcp@*). Pinning @latest forces the newest published build.

PEEK_HOME defaults to ~/.peek; set it via env only if you want a non-default capture directory.

The per-user config paths peek init writes to (canonical, see packages/peek-cli/src/lib/init-config.ts):

Client	Path
Claude Code	~/.claude.json (or claude mcp add)
Cursor	~/.cursor/mcp.json
VS Code (MCP)	~/.vscode/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
Cline	~/cline_mcp_settings.json

What the AI agent can do

Tool	Action	Authorization
list_recent_sessions	List recently recorded sessions, newest first (id, origin, ts, event count)	none
search_sessions	Find sessions by text in title/URL/origin plus facets (origin, date range, status, console/network errors). Read-only; returns the same rows as list_recent_sessions.	none
get_session_summary	LLM-readable narrative summary of a session	none
get_session_console_errors	List console errors recorded in a session	none
get_session_network_errors	List failed/notable network requests in a session	none
get_user_action_before_error	Pre-assembled causal chain for a console error: time-ordered timeline (user action → DOM mutation → network/console error), grouped actions/domMutations/networkErrors, the seed error, a deterministic narrative, and windowMs bounding the correlated window. Backward-compatible: errorId/errorTs/actions are still present.	none
generate_playwright_repro	Generate a runnable Playwright test from a session. Emits semantic locators (getByTestId/getByRole/getByPlaceholder/getByText, uniqueness-checked, CSS fallback). Accepts an optional errorId that seeds a console-error-absence assertion so the repro fails while the bug is present and passes once fixed.	none
get_dom_snapshot	Reconstruct the DOM of a recorded session at a given timestamp (forensic)	none
query_dom_history	Two modes: selector mode — timeline of attribute/text changes for one node (as before); window mode (ts + optional windowMs, no selector) — all DOM changes in a time window with target hints.	none
get_page_view	Live, masked, ref-tagged list of interactive elements — target a ref in write actions instead of a CSS selector (cheaper + deterministic than get_dom_snapshot)	per-origin Level 1+
get_element_detail	Full masked detail for one ref from get_page_view (role, name, all aria-*, state, value, href, position, nearby heading, direct interactive children with their refs) — drill in only on the element you need to disambiguate or act on	per-origin Level 1+
request_authorization	Side-panel consent for write actions (Level 3)	per-action user prompt
execute_action	Dispatch a UI action (gated by permission level + destructive blocklist). Pass observe: true on a mutating action (click/type/scroll/enter/dblclick/navigate/…) to also get back a details.viewDelta of what changed (added/removed/changed refs) in one round-trip — instead of re-calling get_page_view	permission level + destructive blocklist
suggest_element	Highlight an element via a non-destructive overlay	per-origin Level 2+
clear_highlight	Remove the highlight overlay	per-origin Level 2+
set_intent	Set the control-shield status banner	per-origin Level 4
request_user_input	Pause and hand a field back to the user, then resume	per-origin Level 4
verify_audit_log	Verify peek's local action audit log (~/.peek/audit.log) is an intact, tamper-evident hash chain. Returns status (intact / broken / truncated / tail-tampered / prefix-tampered / gaps / incomplete-final / head-missing) + entry count and a short message. Read-only.	none

The full tool list is exposed via the MCP tools/list request (spec 2025-11-25 + back-compat for 2025-03-26). Tool docs ship with the binary via tools/list response description fields.

Permission model (the five levels)

Per-origin, 5 levels (0–4). Default is Level 1 — Read-only. Higher levels are opt-in per origin.

Level	Name	What it allows	Default
0	Off	Recording suppressed, tool surface disabled for the origin
1	Read-only	Read recorded sessions; no action execution	enabled
2	Suggest-only	Read + highlight DOM via overlay; no DOM mutation
3	Act-with-confirm	Read + execute actions, each prompting Allow once / Always for this site / Deny
4	YOLO this session	Read + execute non-destructive actions with no prompt (auto-expires on tab close or 60 min)

At Level 3 every execute_action call prompts the user via the side-panel banner (unless a one-shot confirmToken from a prior request_authorization is passed). At Level 4 (YOLO) non-destructive actions are auto-allowed with no prompt. Levels 0–2 deny execute_action.

Destructive-action blocklist (cross-level override) — independent of the level, any action whose resolved target text/label matches a destructive term (delete, remove, transfer, send, pay, withdraw, etc. — full base list in permissions/destructive.ts, extensible via ~/.peek/policy.json) always prompts for confirmation. This overrides all levels, including Level 4 YOLO — it is not a separate "Level 5".

Every execute_action and request_authorization call is appended to ~/.peek/audit.log (JSONL, mode 0600 — peek audit log --json prints it), including denied ones. Each entry carries a seq counter and a prevHash field (SHA-256 of the previous line); a sidecar audit.head.json records the tail hash for truncation detection. Run peek audit verify to recompute the chain and confirm it is intact. The log is tamper-evident, not tamper-proof — it detects corruption, truncation, and reordering, but not a determined attacker who recomputes the chain. No keys, no external anchor, no egress.

The write-path is wired end to end: the five-level model, the destructive blocklist, and the audit-log writer are enforced inside peek-mcp (observable via ~/.peek/audit.log), and the cross-process IPC that lets execute_action fire a click in the browser now lands — a LocalSocketHostBridge (MCP process) ↔ HostSocketServer (native host) over ~/.peek/host.sock, a MAIN-world action dispatcher (click/type/navigate/scroll), and a side-panel confirm banner. Both write levels are implemented: Level 3 (act-with-confirm — every action prompts the banner) and Level 4 (YOLO — non-destructive actions auto-allow, destructive ones still prompt via the blocklist override). Both are opt-in per origin; the default stays Level 1 (read-only). Level 2 highlight (suggest_element / clear_highlight) and the Level-4 control tools (set_intent, request_user_input) are also implemented. The real-browser dispatch + banner are covered by the Playwright E2E (e2e/smoke.spec.ts).

Database

~/.peek/sessions.db — SQLite (better-sqlite3, WAL mode). Schema in src/db/migrations/. The CLI opens this DB read-mostly; the native host writes it during extension capture; the MCP server reads it for tool calls.

The native host is the only writer. The CLI and MCP server only read (except for the audit log, which is append-only JSONL on disk, not in the DB).

Subpath exports

For consumers building tooling on top of peek:

import { generatePlaywrightRepro } from '@peekdev/mcp/mcp/playwright-repro';
import { loadSessionEvents } from '@peekdev/mcp/mcp/event-blobs';
import { openDb, peekHomeDir } from '@peekdev/mcp/db';
import { buildManifest, installManifests } from '@peekdev/mcp/native-host';

These are the subpath exports the @peekdev/cli package uses. API surface is small but stable.

Versioning & compatibility

Semantic Versioning. Currently 0.1.0-alpha.x — pre-release; tool schemas are stable in spirit but new tools may land in patch releases. See SUPPORTED.md for the compatibility matrix (MCP protocol versions, Chrome stable channels, Node versions).

Per-release changes are recorded in the CHANGELOG.

Privacy

Local-only. No network destinations. No telemetry. The MCP transport is stdio over a child-process pipe — your AI client launches peek-mcp, talks to it over stdin/stdout, and kills it when done. The binary holds no persistent state outside ~/.peek/.

Full data-handling policy: docs/peek/PRIVACY_POLICY.md. Threat model: docs/peek/THREATMODEL.md.

Distribution (maintainer-facing)

This section is for the maintainer's submission workflow at Phase 5 launch. If you're a user, you don't need any of this — just npx @peekdev/cli init.

peek is listed (or queued for listing) on the discovery surfaces below. Each linked file is a submission scaffold with pre-filled metadata audited against the registry's current schema as of 2026-05-30 — not a user-facing install guide.

• Official MCP Registry submission — server.json for registry.modelcontextprotocol.io via mcp-publisher CLI. Downstream registries (PulseMCP, others) ingest from here.
• PulseMCP submission — URL-only form + auto-ingest from the MCP Registry.
• Smithery submission — MCPB bundle uploaded via smithery mcp publish.
• mcp.so submission — web-form submission with the source content paste-ready.
• Claude Code skill standalone install — curl recipe for users who want the Claude Code skill without running peek init.

Launch order is documented in docs/peek/distribution/README.md (CWS first, then the MCP-registry fan-out). The Chrome Web Store listing is submitted + live: chromewebstore.google.com/detail/peek/dmgpmkeneheenpdnfmpjjahnkknkaejb.

Related packages

• @peekdev/cli — the peek init wizard that wires this MCP server into your AI client and installs the native messaging host. Start here.
• @peekdev/extension — the Chrome MV3 extension that records masked browser sessions and writes them to ~/.peek/sessions.db. Available on the Chrome Web Store; contributors can also load it unpacked from packages/peek-extension/chrome-mv3/ for local builds. The npm package stays private (not published to npm).

License

Apache 2.0. The bundled rrweb engine remains MIT-licensed; see NOTICE.

Contributions are accepted under the Developer Certificate of Origin (DCO) — sign your commits with git commit -s. See CONTRIBUTING.md + SECURITY.md.