@peekdev/mcp 0.1.0-alpha.10 → 0.1.0-alpha.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +40 -25
  2. package/package.json +9 -3
package/README.md CHANGED
@@ -30,7 +30,7 @@ Read on if you're configuring the MCP server manually, building tooling against
30
30
  ## What this is NOT
31
31
 
32
32
  - 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.
33
- - Not a write-by-default tool. Read tools are unauthenticated; write tools (clicks, inputs, navigation, destructive actions) require explicit per-action authorization, recorded in `~/.peek/audit.log`.
33
+ - Not a write-by-default tool. Read tools are unauthenticated. The write tools (`execute_action`, `request_authorization`) are defined on the MCP surface and gated by the permission model + destructive blocklist + audit-log writer — but the cross-process IPC that delivers them to the browser native host is **in development**. Calling `execute_action` against `peek-mcp@0.1.0-alpha.10` returns `bridge not wired in this MCP process`; peek is effectively read-only until that bridge lands.
34
34
  - 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.
35
35
 
36
36
  ## Manual MCP-client config
@@ -42,45 +42,60 @@ If `peek init` doesn't recognize your client, paste this into your client's MCP
42
42
  "mcpServers": {
43
43
  "peek": {
44
44
  "command": "npx",
45
- "args": ["-y", "@peekdev/mcp"],
46
- "env": {
47
- "PEEK_HOME": "~/.peek"
48
- }
45
+ "args": ["-y", "@peekdev/mcp"]
49
46
  }
50
47
  }
51
48
  }
52
49
  ```
53
50
 
54
- For Claude Code, this goes in `~/.claude/mcp_servers.json` (per-project) or via `claude mcp add`. For Cursor: `~/Library/Application Support/Cursor/User/mcp_servers.json` (macOS). For Continue: in your `~/.continue/config.json` under `experimental.modelContextProtocolServers`.
51
+ `PEEK_HOME` defaults to `~/.peek`; set it via `env` only if you want a non-default capture directory.
52
+
53
+ The per-user config paths `peek init` writes to (canonical, see `packages/peek-cli/src/lib/init-config.ts`):
54
+
55
+ | Client | Path |
56
+ |---|---|
57
+ | Claude Code | `~/.claude.json` (or `claude mcp add`) |
58
+ | Cursor | `~/.cursor/mcp.json` |
59
+ | VS Code (MCP) | `~/.vscode/mcp.json` |
60
+ | Windsurf | `~/.codeium/windsurf/mcp_config.json` |
61
+ | Cline | `~/cline_mcp_settings.json` |
55
62
 
56
63
  ## What the AI agent can do
57
64
 
58
65
  | Tool | Action | Authorization |
59
66
  |---|---|---|
60
- | `list_sessions` | List recent recording sessions | none |
61
- | `get_session_metadata` | Get one session's metadata + counts | none |
62
- | `get_session_console_errors` | Filter console messages by level / time | none |
63
- | `get_session_network_errors` | Filter failed network requests (status >= 400) | none |
64
- | `get_session_events` | Return rrweb event slices for a time window | none |
67
+ | `list_recent_sessions` | List recently recorded sessions, newest first (id, origin, ts, event count) | none |
68
+ | `get_session_summary` | LLM-readable narrative summary of a session | none |
69
+ | `get_session_console_errors` | List console errors recorded in a session | none |
70
+ | `get_session_network_errors` | List failed/notable network requests in a session | none |
71
+ | `get_user_action_before_error` | Last N user actions before a console error | none |
72
+ | `generate_playwright_repro` | Generate a runnable Playwright test from a session | none |
65
73
  | `get_dom_snapshot` | Reconstruct the DOM at a given timestamp | none |
66
- | `search_session` | Free-text search across console + network for a session | none |
67
- | `generate_playwright_repro` | Emit a Playwright `.spec.ts` reproducing user actions | none |
68
- | `execute_action` | Click / input / navigate in the live tab | per-action user prompt |
69
- | `request_authorization` | Ask the user to permit a destructive action | per-action user prompt |
74
+ | `query_dom_history` | Timeline of attribute/text changes for a selector | none |
75
+ | `request_authorization` | Side-panel consent for write actions (Level 3) | per-action user prompt |
76
+ | `execute_action` | Dispatch a UI action (gated by permission level + destructive blocklist) | permission level + destructive blocklist |
70
77
 
71
78
  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.
72
79
 
73
80
  ## Permission model (the five levels)
74
81
 
75
- | Level | What it allows | Default |
76
- |---|---|---|
77
- | 1 — Read | Query the DB, reconstruct DOM, search events | enabled |
78
- | 2 — Read with confirm | (none currently mapped) | n/a |
79
- | 3 — Constrained write | Click whitelisted selectors | disabled |
80
- | 4 — Broad write | Click any selector, type text, navigate | disabled |
81
- | 5 — Destructive | Submit forms, navigate cross-origin, file uploads | disabled |
82
+ Per-origin, 5 levels (0–4). Default is **Level 1 — Read-only**. Higher levels are opt-in per origin.
83
+
84
+ | Level | Name | What it allows | Default |
85
+ |---|---|---|---|
86
+ | 0 | Off | Recording suppressed, tool surface disabled for the origin | |
87
+ | 1 | Read-only | Read recorded sessions; no action execution | enabled |
88
+ | 2 | Suggest-only | Read + highlight DOM via overlay; no DOM mutation | |
89
+ | 3 | Act-with-confirm | Read + execute actions, each prompting Allow once / Always for this site / Deny | |
90
+ | 4 | YOLO this session | Read + execute non-destructive actions with no prompt (auto-expires on tab close or 60 min) | |
91
+
92
+ 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`.
93
+
94
+ **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".
95
+
96
+ 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.
82
97
 
83
- Levels 3-5 require explicit per-action authorization via `request_authorization`. Every authorized action is appended to `~/.peek/audit.log` (JSONL — `peek audit log --json` prints it). There is a hardcoded destructive-action blocklist (`window.close`, `document.write`, etc.) that cannot be authorized.
98
+ **Shipped today (alpha.10) vs queued for a follow-up alpha:** the five-level model, the destructive blocklist, and the audit-log writer all ship — they're enforced inside `peek-mcp` and observable via `~/.peek/audit.log`. The cross-process IPC that lets `execute_action` actually fire a click in the browser (`LocalSocketHostBridge`) is **not yet wired**; calling `execute_action` against alpha.10 returns the `bridge not wired in this MCP process` error. Track the bridge work via [issues on the rrweb-stack repo](https://github.com/Cubenest/rrweb-stack/issues).
84
99
 
85
100
  ## Database
86
101
 
@@ -95,8 +110,8 @@ For consumers building tooling on top of peek:
95
110
  ```ts
96
111
  import { generatePlaywrightRepro } from '@peekdev/mcp/mcp/playwright-repro';
97
112
  import { loadSessionEvents } from '@peekdev/mcp/mcp/event-blobs';
98
- import { openDb } from '@peekdev/mcp/db';
99
- import { startNativeHost } from '@peekdev/mcp/native-host';
113
+ import { openDb, peekHomeDir } from '@peekdev/mcp/db';
114
+ import { buildManifest, installManifests } from '@peekdev/mcp/native-host';
100
115
  ```
101
116
 
102
117
  These are the subpath exports the `@peekdev/cli` package uses. API surface is small but stable.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@peekdev/mcp",
3
- "version": "0.1.0-alpha.10",
4
- "description": "peek native messaging host + stdio MCP server. Owns ~/.peek/sessions.db (better-sqlite3) and bridges the browser extension, CLI, and AI tools to a single local source of truth (ADR-0007).",
3
+ "version": "0.1.0-alpha.12",
4
+ "description": "peek native messaging host + stdio MCP server. Owns ~/.peek/sessions.db (better-sqlite3) and bridges the browser extension, CLI, and AI tools to a single local source of truth.",
5
5
  "keywords": [
6
6
  "peek",
7
7
  "mcp",
@@ -58,7 +58,7 @@
58
58
  "@modelcontextprotocol/sdk": "^1.29.0",
59
59
  "better-sqlite3": "^12.10.0",
60
60
  "zod": "^3.25.76",
61
- "@cubenest/rrweb-core": "0.1.0-alpha.4"
61
+ "@cubenest/rrweb-core": "0.1.0-alpha.5"
62
62
  },
63
63
  "devDependencies": {
64
64
  "@types/better-sqlite3": "^7.6.13",
@@ -73,7 +73,13 @@
73
73
  "url": "https://github.com/Cubenest/rrweb-stack",
74
74
  "directory": "packages/peek-mcp"
75
75
  },
76
+ "bugs": {
77
+ "url": "https://github.com/Cubenest/rrweb-stack/issues"
78
+ },
76
79
  "homepage": "https://peek.cubenest.in",
80
+ "engines": {
81
+ "node": ">=20.18.0"
82
+ },
77
83
  "scripts": {
78
84
  "build": "tsc -p tsconfig.json && node ./scripts/postbuild.mjs",
79
85
  "typecheck": "tsc -p tsconfig.json --noEmit",