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"`. - 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 peekaboo-local --stdio "$PEEKABOO_BIN mcp serve" --schema --timeout 30 ``` 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 peekaboo-local.permissions --stdio "$PEEKABOO_BIN mcp serve" --timeout 15 ``` Expect Screen Recording ✅ (hard requirement) and Accessibility ⚠️/✅. If Screen Recording is missing, fix it before continuing. 3) **Server status via list tool** ``` $MCPORTER call peekaboo-local.list \ item_type:server_status \ --stdio "$PEEKABOO_BIN mcp serve" --timeout 20 ``` Expect version string (3.x), active provider names, and a healthy status line. 4) **Window inventory** ``` $MCPORTER call peekaboo-local.list \ item_type:application_windows \ app:"Finder" \ include_window_details:'["bounds","ids"]' \ --stdio "$PEEKABOO_BIN mcp serve" --timeout 20 ``` 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 peekaboo-local.image \ path:/tmp/peekaboo-mcp/frontmost.png \ format:png \ app_target:frontmost \ capture_focus:auto \ --stdio "$PEEKABOO_BIN mcp serve" --timeout 25 ``` 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 peekaboo-local.image \ path:/tmp/peekaboo-mcp/frontmost-analysis.png \ format:png \ app_target:frontmost \ capture_focus:auto \ question:"What window is in focus?" \ --stdio "$PEEKABOO_BIN mcp serve" --timeout 60 ``` 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 peekaboo-local --stdio "$PEEKABOO_BIN mcp serve" --timeout 15 ``` 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` 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*`.