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

@peekdev/mcp

実際のブラウザーで起きたことを、AI コーディングエージェントがデバッグできるようにします。peek は、ローカルに記録されたセッション（DOM の履歴、コンソールとネットワークのエラー、失敗の直前に行われた操作）を MCP 経由で読み取り、実行可能な Playwright の再現コードに変換します。ローカルファーストです。peek がデータをアップロードすることはありません。データをどう扱うかは、MCP クライアントに委ねられます。

ドキュメント：https://peek.cubenest.in

@peekdev/mcp は、1 つのバイナリーで 2 つの役割を担います。

1. AI コーディングエージェント（Claude Code、Cursor、Cline、Windsurf、Continue、Zed）が、記録されたブラウザーセッションを照会する際に接続する stdio MCP サーバー。
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（~/.peek/host.sock を介した LocalSocketHostBridge ↔ HostSocketServer）は、現在接続されています。レベル 3 では、すべての操作の実行前にサイドパネルの確認バナーが表示されます。実際のブラウザーでの MAIN world ディスパッチとバナーの 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はアルファ版のため、@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 エージェントでできること

ツール	アクション	認可
list_recent_sessions	最近記録されたセッションを新しい順に一覧表示します（id、origin、ts、イベント数）	なし
search_sessions	タイトル／URL／origin 内のテキストと、絞り込み条件（origin、日付範囲、ステータス、コンソール／ネットワークエラー）でセッションを検索します。読み取り専用です。list_recent_sessions と同じ行を返します。	なし
get_session_summary	セッションの LLM が読み取れるナラティブ形式の要約	なし
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	2 つのモードがあります。セレクターモード — 1 つのノードに対する属性／テキスト変更のタイムライン（従来どおり）。ウィンドウモード（ts と任意の windowMs を指定し、セレクターは指定しない） — target のヒントを含む、時間ウィンドウ内のすべての DOM 変更。	なし
get_page_view	ライブでマスク済みの、ref タグ付きインタラクティブ要素一覧です。書き込みアクションでは CSS セレクターの代わりに ref を指定します（get_dom_snapshot より低コストで決定論的です）。	origin ごとに Level 1 以上
get_element_detail	get_page_view の単一 ref に関する完全なマスク済み詳細です（role、name、すべての aria-*、state、value、href、position、近くの見出し、ref 付きの直接のインタラクティブな子要素）。判別や操作が必要な要素だけを詳しく確認できます。	origin ごとに Level 1 以上
request_authorization	書き込みアクションのサイドパネルでの同意（Level 3）	アクションごとのユーザープロンプト
execute_action	UI アクションを実行します（権限レベルと破壊的操作ブロックリストによる制御）。状態を変更するアクション（click／type／scroll／enter／dblclick／navigate／…）で observe: true を指定すると、get_page_view を再度呼び出す代わりに、1 回のラウンドトリップで変更内容（追加／削除／変更された ref）を示す details.viewDelta も返します。	権限レベルと破壊的操作ブロックリスト
suggest_element	非破壊的なオーバーレイで要素をハイライトします	origin ごとに Level 2 以上
clear_highlight	ハイライトオーバーレイを削除します	origin ごとに Level 2 以上
set_intent	コントロールシールドのステータスバナーを設定します	origin ごとに Level 4
request_user_input	一時停止してフィールドをユーザーに引き渡し、その後再開します	origin ごとに 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 段階）

オリジンごとに 5 段階（0～4）です。デフォルトは レベル 1 — 読み取り専用 です。より高いレベルは、オリジンごとにオプトインします。

レベル	名前	許可される操作	デフォルト
0	オフ	記録を抑制し、そのオリジンのツールを無効にします
1	読み取り専用	記録されたセッションを読み取ります。アクションは実行できません	有効
2	提案のみ	読み取りに加え、オーバーレイで DOM をハイライトします。DOM は変更しません
3	確認して実行	読み取りに加え、アクションを実行します。実行ごとに「今回のみ許可」／「このサイトでは常に許可」／「拒否」を確認します
4	このセッションで YOLO	読み取りに加え、非破壊的なアクションを確認なしで実行します（タブを閉じるか 60 分経過すると自動的に期限切れになります）

レベル 3 では、以前の request_authorization で発行されたワンショットの confirmToken を渡さない限り、execute_action を呼び出すたびにサイドパネルのバナーでユーザーに確認します。レベル 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 を実行すると、チェーンを再計算して完全性を確認できます。このログは改ざんを検知できますが、改ざんを防止するものではありません。破損、切り詰め、並べ替えは検出できますが、チェーンを再計算する執拗な攻撃者は検出できません。鍵も外部アンカーもなく、データの外部送信もありません。

書き込み経路はエンドツーエンドで接続されています： 5 段階のモデル、破壊的アクションのブロックリスト、監査ログライターは peek-mcp 内で適用されており（~/.peek/audit.log で確認できます）。また、execute_action がブラウザーでクリックを実行できるようにするプロセス間 IPC も動作します。これは ~/.peek/host.sock 経由の LocalSocketHostBridge（MCP プロセス）↔ 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 はこの DB を主に読み取り専用で開き、ネイティブホストは拡張機能のキャプチャ中に書き込み、MCP サーバーはツール呼び出しのために読み取ります。

ネイティブホストだけが書き込みを行います。CLI と MCP サーバーは読み取りのみを行います（ただし、ディスク上で追記専用の JSONL として保存される監査ログは DB 内にありません）。

サブパスエクスポート

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。

配布（メンテナー向け）

このセクションは、Phase 5 のローンチにおけるメンテナーの登録ワークフローを対象としています。 ユーザーの場合、これらは必要ありません。npx @peekdev/cli init を実行するだけです。

peek は、以下の検索サービスに掲載済み、または掲載待ちです。 各リンク先のファイルは、レジストリの現行スキーマに照らして監査済みで、2026-05-30 時点のメタデータが事前入力された登録用テンプレートです。ユーザー向けのインストールガイドではありません。

• Official MCP Registry への登録 — mcp-publisher CLI を使って registry.modelcontextprotocol.io に登録するための server.json です。下流のレジストリ（PulseMCP など）は、ここからデータを取り込みます。
• PulseMCP への登録 — URL のみを入力するフォームと、MCP Registry からの自動取り込みに対応しています。
• Smithery への登録 — smithery mcp publish を使って MCPB バンドルをアップロードします。
• mcp.so への登録 — ソースコンテンツをそのまま貼り付けられるウェブフォームから登録します。
• Claude Code スキルの単独インストール — peek init を実行せずに Claude Code スキルを使いたいユーザー向けの curl コマンド例です。

ローンチの順序は docs/peek/distribution/README.md に記載されています（まず CWS、その後 MCP Registry へ一括登録します）。Chrome ウェブストアへの掲載申請は完了しており、現在公開中です：chromewebstore.google.com/detail/peek/dmgpmkeneheenpdnfmpjjahnkknkaejb。

関連パッケージ

• @peekdev/cli — この MCP サーバーを AI クライアントに接続し、ネイティブメッセージングホストをインストールする peek init ウィザードです。まずはこちらから。
• @peekdev/extension — マスク処理されたブラウザーセッションを記録し、~/.peek/sessions.db に保存する Chrome MV3 拡張機能です。Chrome ウェブストアから入手できます。コントリビューターは、ローカルビルド用に 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 も参照してください。