docs(peek): correct MCP tool count (10 → 14) + permission model

[harry-harish]

What

The peek MCP server registers 14 tools, but the docs + a code comment still described the original 10-tool read-only surface ("writes are Phase 3d — not registered here"). This corrects every stale reference, found via a literal sweep plus a semantic check that caught tool tables/sections missing the newer tools.

The actual surface (verified against server.ts + levels.ts)

• Read (8): list_recent_sessions, get_session_summary, get_session_console_errors, get_session_network_errors, get_user_action_before_error, get_dom_snapshot, query_dom_history, generate_playwright_repro
• Act (2, Level 3+): request_authorization, execute_action
• Suggest (2, Level 2+): suggest_element, clear_highlight
• Control (2, Level 4): set_intent, request_user_input

Files fixed

• packages/peek-mcp/src/mcp/server.ts — header comment ("seven session/query tools… not registered here") + the createPeekMcpServer docstring ("all Level-1 read tools").
• packages/peek-mcp/README.md — tool table (added the 4 missing tools) + the stale "Level 2 highlight … queued" line (now shipped).
• packages/peek-cli/README.md — "exposes 10 tools" → 14 (+ mentions highlight & input handoff).
• packages/peek-cli/skills/peek-skill.md — count in 3 places; expanded the tool tables into Read/Act/Suggest/Control; and rewrote the permission model, which described a wrong 6-level (0–5) scheme with the wrong default (Level 0) and wrong storage path (~/.peek/permissions.json).
• docs/peek/distribution/{claude-code-skill,modelcontextprotocol-servers,mcp-so}.md — count + registry-listing tool lists (so future submissions are accurate).

Permission-model correction (ADR-0010 ground truth)

The skill now matches the code: 5 levels — 0 Off · 1 Read-only (default) · 2 Suggest-only · 3 Act-with-confirm · 4 YOLO this session. Levels live in chrome.storage.sync (peek:permissionLevels), not a JSON file. Read tools work at Level 1+ (the skill wrongly said 2+). The destructive-action blocklist is a cross-level override, not a "Level 5".

Verification

• All 17 edits applied via a self-asserting script (each anchor matched exactly once; dry-run before apply).
• Re-grepped: no residual "10 tools" / "Level 5" / wrong-storage references remain (the two surviving "Level 5" mentions are the intentional "there is no Level 5" clarifications).
• The frozen peek-mcp/CHANGELOG.md "exposes 10 tools" entry was left untouched (historical record).
• Docs/comment-only; workspace builds + pre-commit biome/typecheck pass.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Expanded documentation to clarify the full suite of 14 tools including read operations, actions, element suggestions, and control features
  • Enhanced permission model documentation with detailed explanation of the 5-level authorization system and per-origin permission controls
  • Updated safety guidelines with explicit details on destructive action safeguards and permission level requirements across all operations

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 47b6c1c3-5964-47ed-98b6-04e5e6451c9f

📥 Commits

Reviewing files that changed from the base of the PR and between db8d39b and d194237.

📒 Files selected for processing (8)

• .changeset/peek-tool-count-fixes.md
• docs/peek/distribution/claude-code-skill.md
• docs/peek/distribution/mcp-so.md
• docs/peek/distribution/modelcontextprotocol-servers.md
• packages/peek-cli/README.md
• packages/peek-cli/skills/peek-skill.md
• packages/peek-mcp/README.md
• packages/peek-mcp/src/mcp/server.ts

---

📝 Walkthrough

Walkthrough

Documentation-only update that corrects the stated MCP tool count from 10 to 14 across all READMEs, distribution docs, and server.ts JSDoc, adds the four new tools (suggest_element, clear_highlight, set_intent, request_user_input) to relevant tables, and rewrites the permission model description to match ADR-0010 (Levels 0–4, chrome.storage.sync, destructive-action blocklist). A patch changeset for @peekdev/cli and @peekdev/mcp is included.

Changes

MCP Tool Count and Permission Model Documentation Corrections

Layer / File(s)	Summary
Patch release changeset .changeset/peek-tool-count-fixes.md	Registers patch bumps for @peekdev/cli and @peekdev/mcp and documents what was corrected (tool count 10→14, permission model).
Canonical skill doc packages/peek-cli/skills/peek-skill.md	Updates intro and tool-count header to 14, replaces old "write tools" block with Act/Suggest/Control categories and their gating rules, rewrites the permission model section (Levels 0–4, chrome.storage.sync key peek:permissionLevels, no Level 5, destructive blocklist always prompts, control-shield gating), and updates the safety-floor statement.
Package READMEs packages/peek-mcp/README.md, packages/peek-cli/README.md	peek-mcp/README.md adds four new tool rows (suggest_element, clear_highlight, set_intent, request_user_input) to the tool table and updates the write-path narrative from "queued" to "implemented." peek-cli/README.md updates the tool count and capability description.
server.ts JSDoc packages/peek-mcp/src/mcp/server.ts	Top-of-file and createPeekMcpServer JSDoc updated to describe the full multi-tier tool surface (read, act, suggest, control) instead of only the prior Level-1 read-only description.
Distribution docs docs/peek/distribution/claude-code-skill.md, docs/peek/distribution/mcp-so.md, docs/peek/distribution/modelcontextprotocol-servers.md	Tool count updated to 14 in each doc's "What it does" section; mcp-so.md and modelcontextprotocol-servers.md also extend their tool tables/lists with the four new names.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• Cubenest/rrweb-stack#74: Introduced the suggest_element, set_intent, request_user_input tools and Level 4 control/input-handoff behavior that this PR's documentation now describes.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main changes: correcting MCP tool count (10 → 14) and the permission model, which are the two central themes across all updated files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/peek-tool-count

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}