Discover available taps. Default (no args) returns a compact site-grouped summary for orientation. Pass {query:'...'} for substring search across site/name/description (ranked by relevance). Pass {site} for full schema (columns, args) of one site; {site, name} for a single tap. If a matching tap exists, use tap.run — it executes with zero AI, faster and more stable than manual tap operations. NEVER bypass a tap by using manual tap.* calls to replicate what a tap already does.

Run a pre-built tap. Preferred over tap.* tools — deterministic, zero AI at runtime. Returns {columns, rows, count, timing, cache_hit}. Read-intent taps are memoized for 5 minutes per process; identical calls return cached data with cache_hit:true. Pass {fresh:true} to bypass cache. Write-intent taps are never cached. If rows contain login/error page content or are empty on a site that requires login → call tap.runtime(runtime:'chrome') first, then retry. If rows is empty on a public site, use tap.doctor(site, name) for structured diagnosis. On transient failure (timeout, connection), RETRY tap.run — do not fall back to manual tap.* operations.

Check tap runtime environment: binary version, TAP_HOME directory, installed skills count, Playwright availability, daemon status, and OS info. Zero side effects — no browser needed. Use for initial troubleshooting or CI health gates.

Health check for taps. Runs each tap's examples against its health contract. Returns {ok, annotations[], issues[], suggestions[]}. Each annotation is a W3C Web Annotation (motivation:'assessing') with body.tap:verdict in {healthy, broken, stale, layer-mismatch}. Use when tap.run returns empty/error rows, or after forge.save to validate. ALWAYS specify site+name — unscoped checks scan all user taps and are expensive. PIPE TAPS: annotations include recursive sub-tap diagnosis via body.children[]. Use tap.explain for static analysis without running.

Diagnose and repair a broken tap. Runs tap.doctor first, then collects page-level diagnostics (current DOM vs expected selectors, auth wall detection, redirect analysis). Returns the same shape as tap.doctor plus repair-specific fields: {diagnostics:{currentSnapshot, expectedSelectors, authWall, suggestions[]}, patches[]}. Free tier gets diagnostics only; Pro tier gets AI-generated fix proposals. Use when tap.doctor returns verdict=broken.

Switch browser runtime mid-session. Default is headless (no login). Use 'chrome' when you need the user's real browser with login sessions (Xiaohongshu, Zhihu, etc.) or for write operations (publish, comment). Use 'headless' to switch back. (Unrelated to tap mcp connect, which registers the Tap MCP server with an AI host.)

Analyze a page for tap forging: detects framework, SSR state, APIs, and generates extraction strategies. Also use this to re-forge a broken tap — inspect the page again to find what changed. Pass probe_writes:true to discover write actions without triggering them (zero side effects).

AUTHORING PRINCIPLE: Prefer API > SSR > DOM. handle.fetch (cookie-aware) and handle.ssrState beat handle.eval(querySelectorAll); handle.find / handle.copyAll beat hand-rolled selectors. Read existing_taps first — if one already covers part of the need, compose with it inside handle.pipe rather than re-extracting.

Load a tap into memory and optionally verify it live. Accepts a structured plan (TapAnnotation — preferred; verify runs it via the plan runtime) or legacy code (.tap.js source). When url is provided, auto-runs verification and returns {score, rows}. Without url, just stashes the draft.

Save the tap to disk as .tap.json and auto-commit to git. Accepts either a structured plan (W3C Annotation wrapping an ExecutionPlan body — preferred) or code (legacy .tap.js source, migrated to a plan on write). Falls back to code from the active forge.draft session when neither is passed. After saving, tap.run can execute it forever with zero AI.

Optional verify_examples runs the just-saved tap against the supplied examples and asserts row-shape contracts (min_rows, non_empty, max_elapsed_ms). When all examples pass, the response includes doctor (verdict from running tap.doctor on the saved tap). When any example fails, the response includes regenerated_inspect — a fresh forge.inspect on the same URL — so the agent can re-forge in one round-trip instead of three. When omitted, behavior is unchanged and the response carries doctor: "indeterminate".

Inspect the current page. Use target to choose what to inspect: page (url/title/meta), dom (HTML structure), a11y (accessibility tree), element (single element detail, requires selector), network (captured traffic — auto-starts capture on first call, dumps on subsequent). Default: page.

Expand this session's MCP tool set. Call when the default Layer-1 set (run/list/doctor/fix/forge.*/inspect) is insufficient — e.g. need manual browser actions (click/type/fill/scroll), write-tap operations, or diagnostic probes that aren't exposed yet. Levels: 2 = creative (forge supplements + diagnostics), 3 = manual (raw browser control: tap.click, tap.type, tap.eval, tap.find, tap.upload, tap.nav, tap.wait, tap.cookies, tap.pressKey). After calling, the server sends notifications/tools/list_changed; clients that honor it will re-query tools/list automatically. Higher-level calls subsume lower ones — calling with level:3 exposes both Layer 2 and Layer 3.