Peekaboo MCP

--- summary: 'Manual MCP smoke tests via mcporter for Peekaboo' read_when: - 'verifying Peekaboo MCP server changes or regressions' - 'running hand-driven MCP smokes before releases' --- # Manual MCP Testing (mcporter) Use this checklist to exercise the Swift MCP server with mcporter. It mirrors the Oracle smokes but targets the Peekaboo CLI (`peekaboo mcp serve`) so we can validate stdio transport, tool schemas, and basic automation without relying on Claude/Cursor. ## Quick setup - Build the CLI: `pnpm run build:cli` (or `pnpm run build:swift` for release binaries). - Export the binary path for reuse: `export PEEKABOO_BIN="$(swift build --show-bin-path --package-path Apps/CLI)/peekaboo"` - Pick a mcporter entry point (set once): `export MCPORTER="${MCPORTER:-npx mcporter}"` If you have the local repo, prefer `MCPORTER="pnpm --dir ~/Projects/mcporter exec tsx ~/Projects/mcporter/src/cli.ts"`. - mcporter timeouts are **milliseconds**. Use `--timeout 15000` (15s), not `--timeout 15`. - Permissions: run `$PEEKABOO_BIN permissions status` once to confirm Screen Recording + Accessibility are granted; the `permissions` tool will fail if screen capture is blocked. - AI analysis (optional steps below) needs providers set in `~/.peekaboo/config.json` and env keys (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.). ## Test cases (run in order) 1) **Discover + schema check** ``` $MCPORTER list --stdio "$PEEKABOO_BIN mcp serve" --name peekaboo-local --schema --timeout 30000 ``` Expect: tool catalog prints Peekaboo-native tools (image, see, list, permissions, click, type, drag, window, menu, dock, space, swipe, hotkey, clipboard, shell, agent, capture, sleep). Any transport/auth errors here block the rest of the suite. 2) **Permissions sanity** ``` $MCPORTER call --stdio "$PEEKABOO_BIN mcp serve" --name peekaboo-local permissions --timeout 15000 ``` Expect Screen Recording ✅ (hard requirement) and Accessibility ⚠️/✅. If Screen Recording is missing, fix it before continuing. 3) **Server status via list tool** ``` $MCPORTER call --stdio "$PEEKABOO_BIN mcp serve" --name peekaboo-local \ list item_type:server_status --timeout 20000 ``` Expect version string (3.x), active provider names, and a healthy status line. 4) **Window inventory** ``` $MCPORTER call --stdio "$PEEKABOO_BIN mcp serve" --name peekaboo-local \ list item_type:application_windows app:"Finder" \ include_window_details:'["bounds","ids"]' --timeout 20000 ``` Expect numbered windows with titles; bounds/IDs present when Finder has open windows. Swap `app:` to any running target if Finder is closed. 5) **Screenshot smoke (frontmost)** ``` $MCPORTER call --stdio "$PEEKABOO_BIN mcp serve" --name peekaboo-local \ image path:/tmp/peekaboo-mcp/frontmost.png format:png \ app_target:frontmost capture_focus:auto --timeout 25000 ``` Expect `📸 Captured …` text plus a saved file path. Open the PNG to confirm the active window is captured without the shadow frame. 6) **Image + analysis (optional, needs AI keys)** ``` $MCPORTER call --stdio "$PEEKABOO_BIN mcp serve" --name peekaboo-local \ image path:/tmp/peekaboo-mcp/frontmost-analysis.png format:png \ app_target:frontmost capture_focus:auto \ question:"What window is in focus?" --timeout 60000 ``` Expect an analysis paragraph plus `savedFiles` metadata; failures here usually mean provider config or permissions issues. Note: OpenAI Responses (GPT‑5.x) requires `image_url` to be a string (URL or data URL). Peekaboo normalizes legacy `{ url, detail }` objects internally, but upstream tools should prefer the string form to avoid 400s. 7) **List cached tools after reuse (daemon/keep-alive sanity)** ``` $MCPORTER list --stdio "$PEEKABOO_BIN mcp serve" --name peekaboo-local --timeout 15000 ``` Expect a fast re-list with no lingering stderr; if it hangs, run `$MCPORTER daemon stop` and retry to rule out stuck keep-alive state. ## Notes - These smokes use ad-hoc stdio (`--stdio "$PEEKABOO_BIN mcp serve"`), so no project config file is required. If you prefer persistence, add `--persist ~/.mcporter/mcporter.json --name peekaboo-local --yes` on the first `list` call. - Record pass/fail plus notable log snippets or file paths in PR descriptions so reviewers can audit the real runs. - If any step fails because the server stays busy, re-run with `DEBUG=mcp` to surface raw MCP traffic, then check for crash logs under `~/Library/Logs/DiagnosticReports/peekaboo*`.