Bring your real authenticated browser session to AI coding agents. Local-first MCP server + Chrome MV3 extension. No cloud. No telemetry.

@peekdev/mcp

让你的 AI 编码 Agent 调试真实浏览器中已经发生的问题——peek 会通过 MCP 读取本地录制的会话（DOM 历史记录、控制台和网络错误、故障发生前的操作），并将其转换为可运行的 Playwright 复现。以本地为先：peek 不会上传任何内容——你的 MCP 客户端如何处理这些数据由你决定。

文档：https://peek.cubenest.in

@peekdev/mcp 是一个二进制程序，包含两种功能：

1. stdio MCP 服务，AI 编码 Agent（Claude Code、Cursor、Cline、Windsurf、Continue、Zed）通过它查询你录制的浏览器会话。
2. 原生消息传递主机，Chrome 的 MV3 扩展通过它写入 ~/.peek/sessions.db。

同一个二进制程序通过 argv 选择并处理这两种角色。通常使用时无需直接安装此软件包；@peekdev/cli 的 peek init 向导会将其接入你的 AI 客户端 MCP 配置以及 Chrome 的 NativeMessagingHosts/。

需要 Node.js ≥ 22。 原生 better-sqlite3 依赖仅提供 Node 22 及更高版本的预构建二进制文件——在 Node 20 上（尤其是默认没有 C/C++ 工具链的 Windows），安装会退回到从源代码编译并失败。请使用 Node 22 或更高版本。

你可能更需要 @peekdev/cli

npm install -g @peekdev/cli
peek init

如果你要手动配置 MCP 服务、基于它构建工具，或想查看协议／工具参考，请继续阅读。

这不是什么

• 不是远程 MCP 服务。Peek 仅在本地运行：通过子进程管道使用 stdio 传输。它没有 HTTP 监听器、SSE 端点或远程身份验证。MCP 传输规范中的 Streamable HTTP 变体不在设计范围内。
• 不是默认可写的工具。读取工具无需身份验证。写入工具（execute_action、request_authorization）受按来源的权限模型（默认关闭）、破坏性操作阻止列表和审计日志写入器的限制。将它们传递给浏览器原生主机的跨进程 IPC（LocalSocketHostBridge ↔ HostSocketServer，通过 ~/.peek/host.sock）现已接通：在 Level 3 下，每项操作运行前都会弹出侧边面板确认横幅。真实浏览器 MAIN 世界中的分发和横幅 UX 由 Playwright E2E（e2e/smoke.spec.ts）覆盖；桥接器、中继器、分发器和确认逻辑均经过单元测试。
• 不是 Chrome DevTools Protocol 的封装器。该服务从 SQLite 读取录制的事件；扩展负责采集。MCP 服务不会实时访问 chrome.debugger。

一键安装（Cursor）

点击按钮（或将链接粘贴到 Cursor 中），Cursor 会提示将 peek 添加到 ~/.cursor/mcp.json — 无需使用终端。这只会配置 MCP 服务；要捕获会话，你仍需运行一次 peek init（注册原生消息传递主机）并安装 Chrome 扩展程序。

安装为 Claude Code 插件

如果你使用 Claude Code，只需一步即可将 peek 安装为插件：

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

这会配置此 MCP 服务（18 个工具）以及 peek 技能。要读取会话，你仍需安装录制器 — 运行一次 npx @peekdev/cli init 并安装 peek Chrome 扩展程序。以本地为先：peek 不会上传任何内容 — MCP 客户端如何处理这些数据由你决定。

手动配置 MCP 客户端

如果 peek init 无法识别你的客户端，请将以下内容粘贴到客户端的 MCP 服务注册表中：

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

peek 处于 alpha 阶段时必须使用 @latest 标签：每个已发布版本都是预发布版本（0.1.0-alpha.*），而不带标签的 npx -y @peekdev/mcp 会解析隐式的 * 范围，该范围不匹配预发布版本（ETARGET: No matching version found for @peekdev/mcp@*）。指定 @latest 可强制使用最新发布的构建版本。

PEEK_HOME 默认为 ~/.peek；只有当你想使用非默认捕获目录时，才通过 env 设置它。

peek init 写入的每用户配置路径（规范路径，参见 packages/peek-cli/src/lib/init-config.ts）：

客户端	路径
Claude Code	~/.claude.json（或 claude mcp add）
Cursor	~/.cursor/mcp.json
VS Code (MCP)	~/.vscode/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
Cline	~/cline_mcp_settings.json

AI Agent 可以执行的操作

工具	操作	授权
list_recent_sessions	列出最近记录的会话，按时间从新到旧排序（id、来源、时间戳、事件数）	无
search_sessions	根据标题/URL/来源中的文本以及筛选条件（来源、日期范围、状态、控制台/网络错误）查找会话。只读；返回与 list_recent_sessions 相同的行。	无
get_session_summary	以大模型可读的叙述形式总结会话	无
get_session_console_errors	列出会话中记录的控制台错误	无
get_session_network_errors	列出会话中失败或值得注意的网络请求	无
get_user_action_before_error	为控制台错误预先组装因果链：按时间排序的 timeline（用户操作 → DOM 变更 → 网络/控制台错误）、分组的 actions/domMutations/networkErrors、种子 error、确定性的 narrative，以及界定相关时间窗口的 windowMs。向后兼容：仍会提供 errorId/errorTs/actions。	无
generate_playwright_repro	根据会话生成可运行的 Playwright 测试。生成语义定位器（getByTestId/getByRole/getByPlaceholder/getByText，经过唯一性检查，失败时回退到 CSS）。可选接受 errorId，以此加入控制台错误不存在的断言，使复现测试在缺陷存在时失败、修复后通过。	无
get_dom_snapshot	重建记录会话在指定时间戳时的 DOM（用于取证）	无
query_dom_history	两种模式：选择器模式 — 一个节点的属性/文本变更时间线（同之前）；时间窗口模式（ts + 可选的 windowMs，不带选择器）— 时间窗口内的所有 DOM 变更，并附带 target 提示。	无
get_page_view	实时、经过遮蔽并带有 ref 标签的交互元素列表 — 在写入操作中使用 ref 作为目标，而非 CSS 选择器（比 get_dom_snapshot 更省资源且结果确定）	每个来源需达到 Level 1+
get_element_detail	获取 get_page_view 中某个 ref 的完整遮蔽详情（role、名称、所有 aria-*、状态、值、href、位置、附近标题、带有各自 ref 的直接交互子元素）— 仅深入查看需要消除歧义或执行操作的元素	每个来源需达到 Level 1+
request_authorization	针对写入操作的侧边栏授权（Level 3）	每项操作均需用户提示
execute_action	执行 UI 操作（受权限级别 + 破坏性操作阻止列表限制）。在变更操作（click/type/scroll/enter/dblclick/navigate/…）中传入 observe: true，还可在一次往返中获取变更内容 details.viewDelta（新增/移除/变更的 ref）— 无需再次调用 get_page_view	权限级别 + 破坏性操作阻止列表
suggest_element	通过非破坏性叠加层高亮元素	每个来源需达到 Level 2+
clear_highlight	移除高亮叠加层	每个来源需达到 Level 2+
set_intent	设置控制护盾状态横幅	每个来源需达到 Level 4
request_user_input	暂停并将字段交还给用户，然后恢复	每个来源需达到 Level 4
verify_audit_log	验证 peek 的本地操作审计日志（~/.peek/audit.log）是否为完整且具备防篡改能力的哈希链。返回状态（intact / broken / truncated / tail-tampered / prefix-tampered / gaps / incomplete-final / head-missing）+ 条目数和简短消息。只读。	无

完整工具列表通过 MCP tools/list 请求公开（支持规范 2025-11-25 + 向后兼容 2025-03-26）。工具文档随二进制文件一同提供，位于 tools/list 响应的 description 字段中。

权限模型（五个级别）

每个来源有 5 个级别（0–4）。默认级别为 级别 1 — 只读。更高级别需按来源选择启用。

级别	名称	允许的操作	默认状态
0	关闭	禁止记录，停用该来源的工具接口
1	只读	读取已记录的会话；不执行操作	已启用
2	仅建议	读取 + 通过叠加层高亮 DOM；不修改 DOM
3	执行前确认	读取 + 执行操作，每次都会提示“允许一次 / 始终允许此网站 / 拒绝”
4	本次会话 YOLO 模式	读取 + 无需提示即可执行非破坏性操作（标签页关闭或 60 分钟后自动过期）

在 级别 3 下，每次调用 execute_action 都会通过侧边栏横幅提示用户（除非传入先前 request_authorization 调用返回的一次性 confirmToken）。在 级别 4（YOLO） 下，非破坏性操作会自动获准，无需提示。级别 0–2 会拒绝 execute_action。

破坏性操作阻止列表（跨级别覆盖） —— 无论权限级别如何，只要解析后的目标文本/标签匹配破坏性词语（delete、remove、transfer、send、pay、withdraw 等——完整基础列表见 permissions/destructive.ts，可通过 ~/.peek/policy.json 扩展），就始终需要确认。这会覆盖所有级别，包括级别 4 YOLO 模式——它不是单独的“级别 5”。

每次调用 execute_action 和 request_authorization 都会追加到 ~/.peek/audit.log（JSONL，模式为 0600——运行 peek audit log --json 可打印日志），包括被拒绝的调用。每条记录都有一个 seq 计数器和一个 prevHash 字段（前一行的 SHA-256）；旁置文件 audit.head.json 会记录尾部哈希，用于检测截断。运行 peek audit verify 可重新计算哈希链并确认其完整性。该日志可检测篡改，但无法防止篡改——它能检测损坏、截断和重排，但无法抵御会重新计算哈希链的蓄意攻击者。没有密钥、没有外部锚点、没有数据外传。

写入路径已端到端打通： 五级权限模型、破坏性操作阻止列表和审计日志写入器均在 peek-mcp 内部执行（可通过 ~/.peek/audit.log 查看），并且允许 execute_action 在浏览器中触发点击的跨进程 IPC 现已打通——LocalSocketHostBridge（MCP 进程）通过 ~/.peek/host.sock 与 HostSocketServer（原生主机）通信，配有 MAIN 世界操作分发器（点击/输入/导航/滚动）和侧边栏确认横幅。两个写入级别均已实现：级别 3（执行前确认——每项操作都会触发横幅提示）和 级别 4（YOLO——非破坏性操作自动获准，破坏性操作仍会因阻止列表覆盖而触发提示）。两个级别都需按来源选择启用；默认仍为级别 1（只读）。级别 2 高亮（suggest_element / clear_highlight）和级别 4 控制工具（set_intent、request_user_input）也已实现。Playwright E2E（e2e/smoke.spec.ts）覆盖了真实浏览器分发和横幅。

数据库

~/.peek/sessions.db — SQLite（better-sqlite3，WAL 模式）。架构位于 src/db/migrations/。CLI 以主要读取的方式打开此数据库；原生主机会在扩展捕获期间写入；MCP 服务会为工具调用读取数据库。

原生主机是唯一写入方。CLI 和 MCP 服务仅进行读取（审计日志除外，它是磁盘上仅追加的 JSONL 文件，不在数据库中）。

子路径导出

对于基于 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';

这些是 @peekdev/cli 包使用的子路径导出。API 接口范围虽小，但稳定。

版本控制与兼容性

遵循语义化版本控制。目前为 0.1.0-alpha.x——预发布版本；工具架构在设计上保持稳定，但补丁版本可能会新增工具。兼容性矩阵（MCP 协议版本、Chrome 稳定版渠道、Node 版本）请参阅 SUPPORTED.md。

各版本的变更记录在 CHANGELOG 中。

隐私

仅限本地运行。不连接任何网络目的地。不收集遥测数据。MCP 通过子进程管道使用 stdio 传输——你的 AI 客户端会启动 peek-mcp，通过 stdin/stdout 与其通信，并在完成后将其终止。该二进制程序不会在 ~/.peek/ 之外保留任何持久状态。

完整的数据处理政策：docs/peek/PRIVACY_POLICY.md。威胁模型：docs/peek/THREATMODEL.md。

分发（面向维护者）

本节介绍维护者在第 5 阶段发布时的提交工作流。 如果你是用户，则无需了解这些内容——只需运行 npx @peekdev/cli init。

peek 已列入（或正在排队等待列入）以下发现平台。 每个链接文件都是一个提交模板，其中预先填写的元数据已根据注册表截至 2026-05-30 的当前架构审核——并非面向用户的安装指南。

• 官方 MCP 注册表提交 — 用于通过 mcp-publisher CLI 提交到 registry.modelcontextprotocol.io 的 server.json。下游注册表（PulseMCP 等）会从这里获取数据。
• PulseMCP 提交 — 仅需提供 URL 的表单，并支持从 MCP 注册表自动获取数据。
• Smithery 提交 — 通过 smithery mcp publish 上传 MCPB 程序包。
• mcp.so 提交 — 网页表单提交，源内容已准备好，可直接粘贴。
• Claude Code skill 独立安装 — 为不想运行 peek init、但想使用 Claude Code skill 的用户提供的 curl 命令。

发布顺序记录在 docs/peek/distribution/README.md 中（先上架 CWS，再分发到各 MCP 注册表）。Chrome Web Store 上架申请已提交，且现已上线：chromewebstore.google.com/detail/peek/dmgpmkeneheenpdnfmpjjahnkknkaejb。

相关程序包

• @peekdev/cli — peek init 向导，用于将此 MCP 服务接入你的 AI 客户端并安装原生消息主机。从这里开始。
• @peekdev/extension — Chrome MV3 扩展，可记录经过脱敏的浏览器会话，并将其写入 ~/.peek/sessions.db。可从 Chrome Web Store 获取；贡献者也可以从 packages/peek-extension/chrome-mv3/ 加载未打包版本，以进行本地构建。npm 程序包保持为 private（不发布到 npm）。

许可证

Apache 2.0。捆绑的 rrweb 引擎仍采用 MIT 许可证；请参阅 NOTICE。

欢迎贡献，贡献内容须遵循 Developer Certificate of Origin (DCO)——请使用 git commit -s 为提交签名。另请参阅 CONTRIBUTING.md 和 SECURITY.md。