Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

refactor(mcp): declare shared tool params once and route the two wait tools on browser

Luigi Agosti552ea6f97668
diff --git a/internal/mcp/routing_test.go b/internal/mcp/routing_test.go
index 5e893e99..657f2558 100644
--- a/internal/mcp/routing_test.go
+++ b/internal/mcp/routing_test.go
@@ -36,6 +36,8 @@ var browserToolArgs = map[string]map[string]any{
"pinchtab_keyboard_inserttext": {"text": "hello"},
"pinchtab_keydown": {"key": "a"},
"pinchtab_keyup": {"key": "a"},
+ "pinchtab_wait_for_selector": {"selector": ".loaded"},
+ "pinchtab_wait_for_text": {"text": "done"},
"pinchtab_wait_for_url": {"url": "https://example.com/done"},
"pinchtab_wait_for_load": {"load": "content-loaded"},
"pinchtab_wait_for_function": {"fn": "1"},
diff --git a/internal/mcp/testdata/preamble_budget.json b/internal/mcp/testdata/preamble_budget.json
index 7d7eb4a2..2728a750 100644
--- a/internal/mcp/testdata/preamble_budget.json
+++ b/internal/mcp/testdata/preamble_budget.json
@@ -1,10 +1,10 @@
[
{
"surface": "mcp:allTools",
- "minBytes": 19333,
- "maxBytes": 38666,
+ "minBytes": 20044,
+ "maxBytes": 40088,
"takenOn": "2026-08-22",
- "commit": "9cb14d50"
+ "commit": "2ab9a73f"
},
{
"surface": "skills/pinchtab-mcp/SKILL.md",
diff --git a/internal/mcp/tools.go b/internal/mcp/tools.go
index ae38561b..1e951467 100644
--- a/internal/mcp/tools.go
+++ b/internal/mcp/tools.go
@@ -21,35 +21,31 @@ func allTools() []mcp.Tool {
mcp.NewTool("pinchtab_navigate",
mcp.WithDescription("Navigate to a URL in the browser"),
mcp.WithString("url", mcp.Required(), mcp.Description("The URL to navigate to")),
- mcp.WithString("tabId", mcp.Description("Target tab ID (optional, uses current tab if empty)")),
+ tabIDParam(),
mcp.WithBoolean("snap", mcp.Description("Return interactive compact snapshot after navigation (saves a round-trip)")),
- mcp.WithString("browser",
- mcp.Description("Browser to use for this request (e.g. chrome, cloak, ghost-chrome).")),
+ browserParam(),
),
mcp.NewTool("pinchtab_back",
mcp.WithDescription("Go back one entry in the tab's session history. Returns the tab ID and the URL the tab landed on, so a redirect or bfcache restore is visible without a snapshot."),
- mcp.WithString("tabId", mcp.Description("Target tab ID (optional, uses current tab if empty)")),
- mcp.WithBoolean("snap", mcp.Description("Return interactive compact snapshot after the navigation (saves a round-trip)")),
- mcp.WithString("browser",
- mcp.Description("Browser to use for this request (e.g. chrome, cloak, ghost-chrome).")),
+ tabIDParam(),
+ snapParam(),
+ browserParam(),
),
mcp.NewTool("pinchtab_forward",
mcp.WithDescription("Go forward one entry in the tab's session history. Returns the tab ID and the URL the tab landed on."),
- mcp.WithString("tabId", mcp.Description("Target tab ID (optional, uses current tab if empty)")),
- mcp.WithBoolean("snap", mcp.Description("Return interactive compact snapshot after the navigation (saves a round-trip)")),
- mcp.WithString("browser",
- mcp.Description("Browser to use for this request (e.g. chrome, cloak, ghost-chrome).")),
+ tabIDParam(),
+ snapParam(),
+ browserParam(),
),
mcp.NewTool("pinchtab_reload",
mcp.WithDescription("Reload the current page. Returns the tab ID and the URL the tab landed on."),
- mcp.WithString("tabId", mcp.Description("Target tab ID (optional, uses current tab if empty)")),
- mcp.WithBoolean("snap", mcp.Description("Return interactive compact snapshot after the navigation (saves a round-trip)")),
- mcp.WithString("browser",
- mcp.Description("Browser to use for this request (e.g. chrome, cloak, ghost-chrome).")),
+ tabIDParam(),
+ snapParam(),
+ browserParam(),
),
mcp.NewTool("pinchtab_snapshot",
mcp.WithDescription("Get an accessibility tree snapshot of the current page. Use this sparingly: prefer pinchtab_find + action selectors for faster loops."),
- mcp.WithString("tabId", mcp.Description("Target tab ID")),
+ tabIDParam(),
mcp.WithBoolean("interactive", mcp.Description("Only interactive elements (buttons, links, inputs)")),
mcp.WithBoolean("compact", mcp.Description("Compact format (most token-efficient)")),
mcp.WithString("format", mcp.Description("Output format: 'compact' or 'text'")),
@@ -58,34 +54,31 @@ func allTools() []mcp.Tool {
mcp.WithNumber("maxTokens", mcp.Description("Maximum estimated tokens in response (e.g. 300)")),
mcp.WithNumber("depth", mcp.Description("Maximum tree depth (e.g. 3)")),
mcp.WithBoolean("noAnimations", mcp.Description("Disable animations before capturing the snapshot")),
- mcp.WithString("browser",
- mcp.Description("Browser to use for this request (e.g. chrome, cloak, ghost-chrome).")),
+ browserParam(),
),
mcp.NewTool("pinchtab_frame",
mcp.WithDescription("Get or set the current frame scope for selector-based actions and snapshots"),
- mcp.WithString("tabId", mcp.Description("Target tab ID")),
+ tabIDParam(),
mcp.WithString("target", mcp.Description("Frame target: 'main', a snapshot ref, a selector for an iframe element, or a frame name/URL")),
- mcp.WithString("browser",
- mcp.Description("Browser to use for this request (e.g. chrome, cloak, ghost-chrome).")),
+ browserParam(),
),
mcp.NewTool("pinchtab_screenshot",
mcp.WithDescription("Take a screenshot of the current page. The result is delivered as an MCP image content block (image/jpeg by default, image/png with format='png') so clients render it directly. The accompanying text block is always a JSON envelope `{\"format\": \"jpeg\"|\"png\", \"annotations\": [...]}` — `annotations` is an empty array by default. With `annotate=true`, the picture has numbered overlay boxes on interactive elements and `annotations` is populated with `[{\"ref\": \"e5\", \"role\": \"button\", \"name\": \"Submit\", \"tag\": \"button\", \"box\": {\"x\": <number>, \"y\": <number>, \"w\": <number>, \"h\": <number>}}, ...]`; the `ref` values reuse the same selectors as pinchtab_click/fill/etc. Set `beyondViewport=true` to capture the entire scrollable document instead of the visible viewport."),
- mcp.WithString("tabId", mcp.Description("Target tab ID")),
+ tabIDParam(),
mcp.WithString("selector", mcp.Description("Unified selector. Without annotate it clips the screenshot to the element. With annotate=true it narrows which elements receive overlay boxes (default: all interactive elements).")),
- mcp.WithString("format", mcp.Description("Image format: 'jpeg' (default) or 'png'")),
+ imageFormatParam(),
mcp.WithNumber("quality", mcp.Description("JPEG quality 0-100 (only for JPEG format)")),
mcp.WithNumber("scale", mcp.Description("Rescale the output image bitmap. Default 1 (native). 0.5 halves each axis (quarter of the pixels).")),
mcp.WithBoolean("annotate", mcp.Description("Overlay numbered ref boxes on interactive elements (or on selector matches). Returns the image plus a structured list of {ref, role, name, box}.")),
mcp.WithBoolean("beyondViewport", mcp.Description("Capture the entire scrollable document, not just the visible viewport. Box coordinates in the annotations envelope are document-relative when this is true. Ignored when selector is set.")),
- mcp.WithString("browser",
- mcp.Description("Browser to use for this request (e.g. chrome, cloak, ghost-chrome).")),
+ browserParam(),
),
mcp.NewTool("pinchtab_capture",
mcp.WithDescription("Paired screenshot + accessibility snapshot from the same DOM epoch. Returns an image content block plus a JSON envelope `{url, title, epoch:{frameId,loaderId,domEpoch}, pairing:{navigated,captureDurationMs}, image:{format,bytes,coordinateSpace,devicePixelRatio,viewport,clip}, snapshot:{filter,nodeCount,nodes}}`. Each node in `snapshot.nodes` may carry a `boundingBox:{x,y,w,h}` and `visible:bool` so a vision-capable model can overlay refs on pixels. Coordinate space is 'viewport' by default, 'document' when beyondViewport=true, and 'clip' when selector is set. Prefer this over a separate snapshot+screenshot pair whenever the model needs both image and refs."),
- mcp.WithString("tabId", mcp.Description("Target tab ID")),
+ tabIDParam(),
mcp.WithString("selector", mcp.Description("Scope: clips screenshot and filters snapshot subtree to the same element. Wins over beyondViewport.")),
mcp.WithString("filter", mcp.Description("Snapshot filter: 'interactive' (default) or 'all'")),
- mcp.WithString("format", mcp.Description("Image format: 'jpeg' (default) or 'png'")),
+ imageFormatParam(),
mcp.WithNumber("quality", mcp.Description("JPEG quality 0-100 (JPEG only)")),
mcp.WithNumber("depth", mcp.Description("Snapshot tree depth limit (e.g. 3)")),
mcp.WithNumber("scale", mcp.Description("Rescale the output image bitmap. Default 1 (native). 0.5 halves each axis.")),
@@ -99,91 +92,84 @@ func allTools() []mcp.Tool {
),
mcp.NewTool("pinchtab_get_text",
mcp.WithDescription("Extract readable text content from the current page. Inherits the current frame scope for the tab unless no frame is selected."),
- mcp.WithString("tabId", mcp.Description("Target tab ID")),
+ tabIDParam(),
mcp.WithBoolean("raw", mcp.Description("Return raw text without formatting")),
mcp.WithString("format", mcp.Description("Response format: 'text'/'plain' for plain text, default JSON envelope")),
mcp.WithNumber("maxChars", mcp.Description("Maximum characters in response (e.g. 3000)")),
- mcp.WithString("browser",
- mcp.Description("Browser to use for this request (e.g. chrome, cloak, ghost-chrome).")),
+ browserParam(),
),
mcp.NewTool("pinchtab_click",
mcp.WithDescription("Click an element. Prefer selector from pinchtab_find.best_ref (e.g. 'e5') to avoid extra snapshots."),
mcp.WithString("selector", mcp.Description("Unified selector: ref (e.g. 'e5'), CSS, XPath, text, find, role, label, placeholder, alt, title, testid, or first/last/nth. Non-ref selectors resolve in the current frame scope."+positionalWrapperGrammar)),
- mcp.WithString("ref", mcp.Description("(deprecated) Element ref from snapshot — use 'selector' instead")),
+ refParam(),
mcp.WithString("query", mcp.Description("Alias for semantic targeting when selector is omitted (example: 'login button' -> find:login button)")),
mcp.WithString("dialogAction", mcp.Description("Optional one-shot dialog handling for this click: 'accept' or 'dismiss'")),
mcp.WithString("dialogText", mcp.Description("Optional prompt text used with dialogAction='accept'")),
mcp.WithNumber("x", mcp.Description("Optional X coordinate for coordinate click")),
mcp.WithNumber("y", mcp.Description("Optional Y coordinate for coordinate click")),
- mcp.WithNumber("nodeId", mcp.Description("Optional backend node ID to target directly")),
+ nodeIDParam(),
mcp.WithBoolean("waitNav", mcp.Description("Wait for navigation after the click when the element triggers a page change")),
mcp.WithString("mode", mcp.Description("Optional click delivery override: 'dom' for element.click() or 'dispatch' for synthetic click events on the target")),
- mcp.WithBoolean("humanize", mcp.Description("Use the humanized input path for this request — bezier pointer path, per-step jitter, pre-press delays. Overrides the instance default; omit to inherit it.")),
+ humanizeParam(),
mcp.WithBoolean("snap", mcp.Description("Return interactive compact snapshot after click (saves a round-trip)")),
- mcp.WithString("tabId", mcp.Description("Target tab ID")),
- mcp.WithString("browser",
- mcp.Description("Browser to use for this request (e.g. chrome, cloak, ghost-chrome).")),
+ tabIDParam(),
+ browserParam(),
),
mcp.NewTool("pinchtab_type",
mcp.WithDescription("Type text into an input element"),
- mcp.WithString("selector", mcp.Description("Unified selector: ref (e.g. 'e5'), CSS, XPath, text, or semantic. Non-ref selectors resolve in the current frame scope.")),
- mcp.WithString("ref", mcp.Description("(deprecated) Element ref from snapshot — use 'selector' instead")),
- mcp.WithString("query", mcp.Description("Alias for semantic targeting when selector is omitted")),
- mcp.WithString("text", mcp.Required(), mcp.Description("Text to type")),
- mcp.WithNumber("nodeId", mcp.Description("Optional backend node ID to target directly")),
- mcp.WithString("tabId", mcp.Description("Target tab ID")),
- mcp.WithString("browser",
- mcp.Description("Browser to use for this request (e.g. chrome, cloak, ghost-chrome).")),
+ selectorParam(),
+ refParam(),
+ queryParam(),
+ textToTypeParam(),
+ nodeIDParam(),
+ tabIDParam(),
+ browserParam(),
),
mcp.NewTool("pinchtab_press",
mcp.WithDescription("Press a keyboard key (Enter, Tab, Escape, etc.)"),
mcp.WithString("key", mcp.Required(), mcp.Description("Key to press (e.g., 'Enter', 'Tab', 'Escape')")),
- mcp.WithNumber("nodeId", mcp.Description("Optional backend node ID to target directly")),
- mcp.WithString("tabId", mcp.Description("Target tab ID")),
- mcp.WithString("browser",
- mcp.Description("Browser to use for this request (e.g. chrome, cloak, ghost-chrome).")),
+ nodeIDParam(),
+ tabIDParam(),
+ browserParam(),
),
mcp.NewTool("pinchtab_hover",
mcp.WithDescription("Hover over an element"),
- mcp.WithString("selector", mcp.Description("Unified selector: ref (e.g. 'e5'), CSS, XPath, text, or semantic. Non-ref selectors resolve in the current frame scope.")),
- mcp.WithString("ref", mcp.Description("(deprecated) Element ref from snapshot — use 'selector' instead")),
- mcp.WithString("query", mcp.Description("Alias for semantic targeting when selector is omitted")),
+ selectorParam(),
+ refParam(),
+ queryParam(),
mcp.WithNumber("x", mcp.Description("Optional X coordinate for coordinate hover")),
mcp.WithNumber("y", mcp.Description("Optional Y coordinate for coordinate hover")),
- mcp.WithNumber("nodeId", mcp.Description("Optional backend node ID to target directly")),
- mcp.WithBoolean("humanize", mcp.Description("Use the humanized input path for this request — bezier pointer path, per-step jitter, pre-press delays. Overrides the instance default; omit to inherit it.")),
- mcp.WithString("tabId", mcp.Description("Target tab ID")),
- mcp.WithString("browser",
- mcp.Description("Browser to use for this request (e.g. chrome, cloak, ghost-chrome).")),
+ nodeIDParam(),
+ humanizeParam(),
+ tabIDParam(),
+ browserParam(),
),
mcp.NewTool("pinchtab_focus",
mcp.WithDescription("Focus an element"),
- mcp.WithString("selector", mcp.Description("Unified selector: ref (e.g. 'e5'), CSS, XPath, text, or semantic. Non-ref selectors resolve in the current frame scope.")),
- mcp.WithString("ref", mcp.Description("(deprecated) Element ref from snapshot — use 'selector' instead")),
- mcp.WithString("query", mcp.Description("Alias for semantic targeting when selector is omitted")),
- mcp.WithNumber("nodeId", mcp.Description("Optional backend node ID to target directly")),
- mcp.WithString("tabId", mcp.Description("Target tab ID")),
- mcp.WithString("browser",
- mcp.Description("Browser to use for this request (e.g. chrome, cloak, ghost-chrome).")),
+ selectorParam(),
+ refParam(),
+ queryParam(),
+ nodeIDParam(),
+ tabIDParam(),
+ browserParam(),
),
mcp.NewTool("pinchtab_select",
mcp.WithDescription("Select a dropdown option by value or visible text"),
mcp.WithString("selector", mcp.Description("Unified selector for the select element. Non-ref selectors resolve in the current frame scope.")),
- mcp.WithString("ref", mcp.Description("(deprecated) Element ref from snapshot — use 'selector' instead")),
- mcp.WithString("query", mcp.Description("Alias for semantic targeting when selector is omitted")),
+ refParam(),
+ queryParam(),
mcp.WithString("value", mcp.Required(), mcp.Description("Option value or visible text to select")),
- mcp.WithNumber("nodeId", mcp.Description("Optional backend node ID to target directly")),
- mcp.WithString("tabId", mcp.Description("Target tab ID")),
+ nodeIDParam(),
+ tabIDParam(),
mcp.WithBoolean("snap", mcp.Description("Return interactive compact snapshot after select (saves a round-trip)")),
- mcp.WithString("browser",
- mcp.Description("Browser to use for this request (e.g. chrome, cloak, ghost-chrome).")),
+ browserParam(),
),
mcp.NewTool("pinchtab_scroll",
mcp.WithDescription("Scroll the page or an element. For element targeting + pixel deltas, this automatically uses wheel semantics for smoother behavior."),
mcp.WithString("selector", mcp.Description("Unified selector for element to scroll (omit for page scroll). Non-ref selectors resolve in the current frame scope.")),
- mcp.WithString("ref", mcp.Description("(deprecated) Element ref to scroll — use 'selector' instead")),
- mcp.WithString("query", mcp.Description("Alias for semantic targeting when selector is omitted")),
+ refParam(),
+ queryParam(),
mcp.WithNumber("pixels", mcp.Description("Number of pixels to scroll (positive=down, negative=up)")),
mcp.WithNumber("deltaX", mcp.Description("Horizontal wheel delta for precise scrolling")),
mcp.WithNumber("deltaY", mcp.Description("Vertical wheel delta for precise scrolling")),
@@ -195,71 +181,64 @@ func allTools() []mcp.Tool {
mcp.WithNumber("steps", mcp.Description("Multiplier for direction-based scrolling (default 1), so steps=2 moves twice "+scrollStepDescription)),
mcp.WithNumber("x", mcp.Description("Optional X coordinate for wheel target")),
mcp.WithNumber("y", mcp.Description("Optional Y coordinate for wheel target")),
- mcp.WithNumber("nodeId", mcp.Description("Optional backend node ID to target directly")),
- mcp.WithString("tabId", mcp.Description("Target tab ID")),
- mcp.WithString("browser",
- mcp.Description("Browser to use for this request (e.g. chrome, cloak, ghost-chrome).")),
+ nodeIDParam(),
+ tabIDParam(),
+ browserParam(),
),
mcp.NewTool("pinchtab_scroll_into_view",
mcp.WithDescription("Scroll a target element into view and return geometry details for stable follow-up actions."),
- mcp.WithString("selector", mcp.Description("Unified selector: ref (e.g. 'e5'), CSS, XPath, text, or semantic. Non-ref selectors resolve in the current frame scope.")),
- mcp.WithString("ref", mcp.Description("(deprecated) Element ref — use 'selector' instead")),
- mcp.WithString("query", mcp.Description("Alias for semantic targeting when selector is omitted")),
- mcp.WithNumber("nodeId", mcp.Description("Optional backend node ID to target directly")),
- mcp.WithString("tabId", mcp.Description("Target tab ID")),
- mcp.WithString("browser",
- mcp.Description("Browser to use for this request (e.g. chrome, cloak, ghost-chrome).")),
+ selectorParam(),
+ refParam(),
+ queryParam(),
+ nodeIDParam(),
+ tabIDParam(),
+ browserParam(),
),
mcp.NewTool("pinchtab_fill",
mcp.WithDescription("Fill an input field directly via JavaScript dispatch"),
- mcp.WithString("selector", mcp.Description("Unified selector: ref (e.g. 'e5'), CSS, XPath, text, or semantic. Non-ref selectors resolve in the current frame scope.")),
- mcp.WithString("ref", mcp.Description("(deprecated) Element ref — use 'selector' instead")),
- mcp.WithString("query", mcp.Description("Alias for semantic targeting when selector is omitted")),
+ selectorParam(),
+ refParam(),
+ queryParam(),
mcp.WithString("value", mcp.Required(), mcp.Description("Value to fill; send an empty string to clear the field")),
- mcp.WithNumber("nodeId", mcp.Description("Optional backend node ID to target directly")),
- mcp.WithString("tabId", mcp.Description("Target tab ID")),
+ nodeIDParam(),
+ tabIDParam(),
mcp.WithBoolean("snap", mcp.Description("Return interactive compact snapshot after fill (saves a round-trip)")),
- mcp.WithString("browser",
- mcp.Description("Browser to use for this request (e.g. chrome, cloak, ghost-chrome).")),
+ browserParam(),
),
mcp.NewTool("pinchtab_keyboard_type",
mcp.WithDescription("Type text at the currently focused element via keystroke events (keyDown + keyUp per character)"),
- mcp.WithString("text", mcp.Required(), mcp.Description("Text to type")),
- mcp.WithString("tabId", mcp.Description("Target tab ID")),
- mcp.WithString("browser",
- mcp.Description("Browser to use for this request (e.g. chrome, cloak, ghost-chrome).")),
+ textToTypeParam(),
+ tabIDParam(),
+ browserParam(),
),
mcp.NewTool("pinchtab_keyboard_inserttext",
mcp.WithDescription("Insert text at the currently focused element without key events (paste-like)"),
mcp.WithString("text", mcp.Required(), mcp.Description("Text to insert")),
- mcp.WithString("tabId", mcp.Description("Target tab ID")),
- mcp.WithString("browser",
- mcp.Description("Browser to use for this request (e.g. chrome, cloak, ghost-chrome).")),
+ tabIDParam(),
+ browserParam(),
),
mcp.NewTool("pinchtab_keydown",
mcp.WithDescription("Hold a key down (e.g. modifier keys like Control, Shift, Alt)"),
mcp.WithString("key", mcp.Required(), mcp.Description("Key to hold down (e.g. 'Control', 'Shift', 'Alt', 'a')")),
- mcp.WithString("tabId", mcp.Description("Target tab ID")),
- mcp.WithString("browser",
- mcp.Description("Browser to use for this request (e.g. chrome, cloak, ghost-chrome).")),
+ tabIDParam(),
+ browserParam(),
),
mcp.NewTool("pinchtab_keyup",
mcp.WithDescription("Release a held key"),
mcp.WithString("key", mcp.Required(), mcp.Description("Key to release (e.g. 'Control', 'Shift', 'Alt', 'a')")),
- mcp.WithString("tabId", mcp.Description("Target tab ID")),
- mcp.WithString("browser",
- mcp.Description("Browser to use for this request (e.g. chrome, cloak, ghost-chrome).")),
+ tabIDParam(),
+ browserParam(),
),
mcp.NewTool("pinchtab_eval",
mcp.WithDescription("Execute JavaScript in the browser and return the result. This is not frame-scoped; current pinchtab_frame state does not change evaluation context."),
- mcp.WithString("expression", mcp.Required(), mcp.Description("JavaScript expression to evaluate")),
- mcp.WithString("tabId", mcp.Description("Target tab ID")),
+ expressionParam("expression"),
+ tabIDParam(),
),
mcp.NewTool("pinchtab_pdf",
mcp.WithDescription("Export the current page as a PDF (returns base64-encoded PDF)"),
- mcp.WithString("tabId", mcp.Description("Target tab ID")),
+ tabIDParam(),
mcp.WithBoolean("landscape", mcp.Description("Landscape orientation")),
mcp.WithNumber("scale", mcp.Description("Print scale 0.1-2.0 (default: 1.0)")),
mcp.WithString("pageRanges", mcp.Description("Pages to export (e.g., '1-3,5')")),
@@ -267,7 +246,7 @@ func allTools() []mcp.Tool {
mcp.NewTool("pinchtab_find",
mcp.WithDescription("Find elements by natural-language query. Returns best_ref and selector hints that should be reused in action tools."),
mcp.WithString("query", mcp.Required(), mcp.Description("Text or CSS selector to search for")),
- mcp.WithString("tabId", mcp.Description("Target tab ID")),
+ tabIDParam(),
),
mcp.NewTool("pinchtab_list_tabs",
@@ -275,14 +254,14 @@ func allTools() []mcp.Tool {
),
mcp.NewTool("pinchtab_close_tab",
mcp.WithDescription("Close a browser tab"),
- mcp.WithString("tabId", mcp.Description("ID of the tab to close; uses the current/default tab when omitted")),
+ tabIDParam(),
),
mcp.NewTool("pinchtab_health",
mcp.WithDescription("Check PinchTab server health status"),
),
mcp.NewTool("pinchtab_cookies",
mcp.WithDescription("Get cookies for the current page"),
- mcp.WithString("tabId", mcp.Description("Target tab ID")),
+ tabIDParam(),
),
mcp.NewTool("pinchtab_cookies_set",
mcp.WithDescription("Set one cookie on the current page, for reusing an authenticated session. An empty value blanks the cookie without deleting it."),
@@ -295,7 +274,7 @@ func allTools() []mcp.Tool {
mcp.WithBoolean("secure", mcp.Description("Mark the cookie Secure")),
mcp.WithBoolean("httpOnly", mcp.Description("Mark the cookie HttpOnly")),
mcp.WithNumber("expires", mcp.Description("Expiry as a Unix timestamp in seconds; omit for a session cookie")),
- mcp.WithString("tabId", mcp.Description("Target tab ID")),
+ tabIDParam(),
),
mcp.NewTool("pinchtab_connect_profile",
mcp.WithDescription("Get the user-facing connect URL and instance status for a profile"),
@@ -309,44 +288,43 @@ func allTools() []mcp.Tool {
mcp.NewTool("pinchtab_wait_for_selector",
mcp.WithDescription("Wait for an element matching a selector to appear or disappear on the page"),
mcp.WithString("selector", mcp.Required(), mcp.Description("Unified selector to wait for (CSS, XPath, text, or ref)")),
- mcp.WithNumber("timeout", mcp.Description("Timeout in milliseconds (default: 10000, max: 30000)")),
+ timeoutParam(),
mcp.WithString("state", mcp.Description("Element state to wait for: 'visible' (default) or 'hidden'")),
- mcp.WithString("tabId", mcp.Description("Target tab ID")),
+ tabIDParam(),
+ browserParam(),
),
mcp.NewTool("pinchtab_wait_for_text",
mcp.WithDescription("Wait for specific text to appear on the page"),
mcp.WithString("text", mcp.Required(), mcp.Description("Text to wait for")),
- mcp.WithNumber("timeout", mcp.Description("Timeout in milliseconds (default: 10000, max: 30000)")),
- mcp.WithString("tabId", mcp.Description("Target tab ID")),
+ timeoutParam(),
+ tabIDParam(),
+ browserParam(),
),
mcp.NewTool("pinchtab_wait_for_url",
mcp.WithDescription("Wait for the page URL to match a glob pattern"),
mcp.WithString("url", mcp.Required(), mcp.Description("URL glob pattern to match (e.g. '**/dashboard')")),
- mcp.WithNumber("timeout", mcp.Description("Timeout in milliseconds (default: 10000, max: 30000)")),
- mcp.WithString("tabId", mcp.Description("Target tab ID")),
- mcp.WithString("browser",
- mcp.Description("Browser to use for this request (e.g. chrome, cloak, ghost-chrome).")),
+ timeoutParam(),
+ tabIDParam(),
+ browserParam(),
),
mcp.NewTool("pinchtab_wait_for_load",
mcp.WithDescription("Wait for a page load state"),
mcp.WithString("load", mcp.Required(), mcp.Description("Load state: 'ready-state' (readyState=complete), 'content-loaded' (readyState in {interactive, complete}), or 'network-idle' (0 in-flight requests for 500ms)")),
- mcp.WithNumber("timeout", mcp.Description("Timeout in milliseconds (default: 10000, max: 30000)")),
- mcp.WithString("tabId", mcp.Description("Target tab ID")),
- mcp.WithString("browser",
- mcp.Description("Browser to use for this request (e.g. chrome, cloak, ghost-chrome).")),
+ timeoutParam(),
+ tabIDParam(),
+ browserParam(),
),
mcp.NewTool("pinchtab_wait_for_function",
mcp.WithDescription("Wait for a JavaScript expression to return a truthy value"),
- mcp.WithString("fn", mcp.Required(), mcp.Description("JavaScript expression to evaluate")),
- mcp.WithNumber("timeout", mcp.Description("Timeout in milliseconds (default: 10000, max: 30000)")),
- mcp.WithString("tabId", mcp.Description("Target tab ID")),
- mcp.WithString("browser",
- mcp.Description("Browser to use for this request (e.g. chrome, cloak, ghost-chrome).")),
+ expressionParam("fn"),
+ timeoutParam(),
+ tabIDParam(),
+ browserParam(),
),
mcp.NewTool("pinchtab_network",
mcp.WithDescription("List recent network requests captured from the browser. Returns method, status, URL, type, size, and timing for each request."),
- mcp.WithString("tabId", mcp.Description("Target tab ID (optional, uses current tab if empty)")),
+ tabIDParam(),
mcp.WithString("filter", mcp.Description("URL pattern filter (substring match)")),
mcp.WithString("method", mcp.Description("HTTP method filter (GET, POST, etc)")),
mcp.WithString("status", mcp.Description("Status code range filter (e.g. '4xx', '5xx', '200')")),
@@ -357,7 +335,7 @@ func allTools() []mcp.Tool {
mcp.NewTool("pinchtab_network_detail",
mcp.WithDescription("Get full details of a specific network request including headers, timing, and optionally the response body"),
mcp.WithString("requestId", mcp.Required(), mcp.Description("The request ID from pinchtab_network results")),
- mcp.WithString("tabId", mcp.Description("Target tab ID")),
+ tabIDParam(),
mcp.WithBoolean("body", mcp.Description("Include response body (can be large)")),
),
mcp.NewTool("pinchtab_network_clear",
@@ -366,7 +344,7 @@ func allTools() []mcp.Tool {
),
mcp.NewTool("pinchtab_network_route",
mcp.WithDescription("Install a request interception rule on a tab. Action 'abort' blocks matching requests, 'fulfill' returns a mocked response body, 'continue' passes through. Fulfill is BLOCKED on hosts in security.allowedDomains (the operator's authorized/sensitive surfaces) and ALLOWED on other hosts; matched fulfill rules on allowlisted hosts fall through to a real network fetch."),
- mcp.WithString("tabId", mcp.Required(), mcp.Description("Target tab ID")),
+ requiredTabIDParam(),
mcp.WithString("pattern", mcp.Required(), mcp.Description("URL pattern: substring (no wildcards) or glob ('*', '?')")),
mcp.WithString("action", mcp.Description("'continue' (default), 'abort', or 'fulfill'")),
mcp.WithString("body", mcp.Description("Response body (with action=fulfill). Sent verbatim; not auto-encoded.")),
@@ -377,7 +355,7 @@ func allTools() []mcp.Tool {
),
mcp.NewTool("pinchtab_network_unroute",
mcp.WithDescription("Remove a tab's interception rule by pattern, or all rules if pattern is omitted"),
- mcp.WithString("tabId", mcp.Required(), mcp.Description("Target tab ID")),
+ requiredTabIDParam(),
mcp.WithString("pattern", mcp.Description("Pattern to remove (omit to clear all rules)")),
),
@@ -387,7 +365,7 @@ func allTools() []mcp.Tool {
mcp.WithNumber("fps", mcp.Description("Frames per second 1-30 (default: 5)")),
mcp.WithNumber("quality", mcp.Description("JPEG capture quality 1-100 (default: 80)")),
mcp.WithNumber("scale", mcp.Description("Resolution scale 0-1.0 (default: 1.0)")),
- mcp.WithString("tabId", mcp.Description("Target tab ID")),
+ tabIDParam(),
),
mcp.NewTool("pinchtab_record_stop",
mcp.WithDescription("Stop recording and save the encoded file. Encoding may take a while for long recordings."),
@@ -401,7 +379,7 @@ func allTools() []mcp.Tool {
mcp.WithDescription("Handle a JavaScript dialog (alert, confirm, prompt). Accept or dismiss the currently open dialog."),
mcp.WithString("action", mcp.Required(), mcp.Description("Action to take: 'accept' or 'dismiss'")),
mcp.WithString("text", mcp.Description("Text to enter for prompt dialogs (only used with accept)")),
- mcp.WithString("tabId", mcp.Description("Target tab ID")),
+ tabIDParam(),
),
mcp.NewTool("pinchtab_scrape",
@@ -417,8 +395,7 @@ func allTools() []mcp.Tool {
mcp.WithBoolean("enrichAll", mcp.Description("Browser-render every reachable page, ignoring routing")),
mcp.WithBoolean("noBrowser", mcp.Description("HTTP crawl only; record routing verdicts without browser rendering")),
mcp.WithNumber("timeoutSeconds", mcp.Description("Overall HTTP crawl timeout in seconds (default 60)")),
- mcp.WithString("browser",
- mcp.Description("Browser to use for enrichment (e.g. chrome, cloak, ghost-chrome).")),
+ browserParam(),
),
}
}
diff --git a/internal/mcp/tools_params.go b/internal/mcp/tools_params.go
new file mode 100644
index 00000000..e7fef8df
--- /dev/null
+++ b/internal/mcp/tools_params.go
@@ -0,0 +1,62 @@
+package mcp
+
+import "github.com/mark3labs/mcp-go/mcp"
+
+// Parameters that more than one tool declares live here, so a reword is one
+// edit with a uniform effect on every tool that carries it. A wording that
+// describes genuinely different behaviour for the same parameter name — a tabId
+// whose empty value clears every tab rather than selecting the current one —
+// stays spelled out at its tool and is deliberately not folded in here.
+
+func browserParam() mcp.ToolOption {
+ return mcp.WithString("browser",
+ mcp.Description("Browser to use for this request (e.g. chrome, cloak, ghost-chrome)."))
+}
+
+func tabIDParam() mcp.ToolOption {
+ return mcp.WithString("tabId", mcp.Description("Target tab ID (optional, uses current tab if empty)"))
+}
+
+func requiredTabIDParam() mcp.ToolOption {
+ return mcp.WithString("tabId", mcp.Required(), mcp.Description("Target tab ID"))
+}
+
+func selectorParam() mcp.ToolOption {
+ return mcp.WithString("selector", mcp.Description("Unified selector: ref (e.g. 'e5'), CSS, XPath, text, or semantic. Non-ref selectors resolve in the current frame scope."))
+}
+
+func refParam() mcp.ToolOption {
+ return mcp.WithString("ref", mcp.Description("(deprecated) Element ref from snapshot — use 'selector' instead"))
+}
+
+func nodeIDParam() mcp.ToolOption {
+ return mcp.WithNumber("nodeId", mcp.Description("Optional backend node ID to target directly"))
+}
+
+func queryParam() mcp.ToolOption {
+ return mcp.WithString("query", mcp.Description("Alias for semantic targeting when selector is omitted"))
+}
+
+func timeoutParam() mcp.ToolOption {
+ return mcp.WithNumber("timeout", mcp.Description("Timeout in milliseconds (default: 10000, max: 30000)"))
+}
+
+func snapParam() mcp.ToolOption {
+ return mcp.WithBoolean("snap", mcp.Description("Return interactive compact snapshot after the navigation (saves a round-trip)"))
+}
+
+func humanizeParam() mcp.ToolOption {
+ return mcp.WithBoolean("humanize", mcp.Description("Use the humanized input path for this request — bezier pointer path, per-step jitter, pre-press delays. Overrides the instance default; omit to inherit it."))
+}
+
+func textToTypeParam() mcp.ToolOption {
+ return mcp.WithString("text", mcp.Required(), mcp.Description("Text to type"))
+}
+
+func expressionParam(name string) mcp.ToolOption {
+ return mcp.WithString(name, mcp.Required(), mcp.Description("JavaScript expression to evaluate"))
+}
+
+func imageFormatParam() mcp.ToolOption {
+ return mcp.WithString("format", mcp.Description("Image format: 'jpeg' (default) or 'png'"))
+}
diff --git a/internal/mcp/tools_params_test.go b/internal/mcp/tools_params_test.go
new file mode 100644
index 00000000..99ceaee0
--- /dev/null
+++ b/internal/mcp/tools_params_test.go
@@ -0,0 +1,254 @@
+package mcp
+
+import (
+ "go/ast"
+ "go/parser"
+ "go/token"
+ "os"
+ "sort"
+ "strconv"
+ "strings"
+ "testing"
+)
+
+var routingHelpers = map[string]bool{
+ "routedPath": true,
+ "routedPathWithBody": true,
+ "routedQuery": true,
+}
+
+// packageCallGraph maps every package-local function to the package-local
+// functions it calls, closures included, so reachability can be asked of a
+// handler that routes through a shared helper rather than calling the routing
+// helper itself.
+func packageCallGraph(t *testing.T) map[string]map[string]bool {
+ t.Helper()
+ fset := token.NewFileSet()
+ entries, err := os.ReadDir(".")
+ if err != nil {
+ t.Fatalf("cannot list the mcp package, so this guard checks nothing: %v", err)
+ }
+
+ calls := map[string]map[string]bool{}
+ for _, entry := range entries {
+ name := entry.Name()
+ if entry.IsDir() || !strings.HasSuffix(name, ".go") || strings.HasSuffix(name, "_test.go") {
+ continue
+ }
+ file, parseErr := parser.ParseFile(fset, name, nil, 0)
+ if parseErr != nil {
+ t.Fatalf("cannot parse %s: %v", name, parseErr)
+ }
+ for _, decl := range file.Decls {
+ fn, ok := decl.(*ast.FuncDecl)
+ if !ok || fn.Body == nil {
+ continue
+ }
+ callee := map[string]bool{}
+ ast.Inspect(fn.Body, func(n ast.Node) bool {
+ call, ok := n.(*ast.CallExpr)
+ if !ok {
+ return true
+ }
+ if ident, ok := call.Fun.(*ast.Ident); ok {
+ callee[ident.Name] = true
+ }
+ return true
+ })
+ calls[fn.Name.Name] = callee
+ }
+ }
+ if len(calls) == 0 {
+ t.Fatal("call graph is empty; the parse matched no functions and this guard would pass vacuously")
+ }
+ return calls
+}
+
+func reachesRouting(calls map[string]map[string]bool, start string) bool {
+ seen := map[string]bool{}
+ var walk func(string) bool
+ walk = func(fn string) bool {
+ if seen[fn] {
+ return false
+ }
+ seen[fn] = true
+ for callee := range calls[fn] {
+ if routingHelpers[callee] || walk(callee) {
+ return true
+ }
+ }
+ return false
+ }
+ return walk(start)
+}
+
+// toolHandlers reads the tool→handler pairs off rawHandlerMap's source, so the
+// guard cannot drift from the dispatch table it is asking about.
+func toolHandlers(t *testing.T) map[string]string {
+ t.Helper()
+ fset := token.NewFileSet()
+ file, err := parser.ParseFile(fset, "handlers.go", nil, 0)
+ if err != nil {
+ t.Fatalf("cannot parse handlers.go: %v", err)
+ }
+
+ pairs := map[string]string{}
+ ast.Inspect(file, func(n ast.Node) bool {
+ fn, ok := n.(*ast.FuncDecl)
+ if !ok || fn.Name.Name != "rawHandlerMap" {
+ return true
+ }
+ ast.Inspect(fn.Body, func(n ast.Node) bool {
+ kv, ok := n.(*ast.KeyValueExpr)
+ if !ok {
+ return true
+ }
+ key, ok := kv.Key.(*ast.BasicLit)
+ if !ok || key.Kind != token.STRING {
+ return true
+ }
+ name, err := strconv.Unquote(key.Value)
+ if err != nil {
+ return true
+ }
+ call, ok := kv.Value.(*ast.CallExpr)
+ if !ok {
+ return true
+ }
+ if ident, ok := call.Fun.(*ast.Ident); ok {
+ pairs[name] = ident.Name
+ }
+ return true
+ })
+ return false
+ })
+
+ if len(pairs) == 0 {
+ t.Fatal("found no tool→handler pairs in rawHandlerMap; a rename has made this guard vacuous")
+ }
+ return pairs
+}
+
+func toolsDeclaringBrowser(t *testing.T) map[string]bool {
+ t.Helper()
+ declared := map[string]bool{}
+ for _, tool := range allTools() {
+ if _, ok := tool.InputSchema.Properties["browser"]; ok {
+ declared[tool.Name] = true
+ }
+ }
+ return declared
+}
+
+func TestEveryToolWhoseHandlerRoutesDeclaresBrowser(t *testing.T) {
+ calls := packageCallGraph(t)
+ handlers := toolHandlers(t)
+ declared := toolsDeclaringBrowser(t)
+
+ var routed, missing []string
+ for tool, handler := range handlers {
+ if !reachesRouting(calls, handler) {
+ continue
+ }
+ routed = append(routed, tool)
+ if !declared[tool] {
+ missing = append(missing, tool+" (via "+handler+")")
+ }
+ }
+ sort.Strings(routed)
+ sort.Strings(missing)
+
+ if len(routed) < 10 {
+ t.Fatalf("only %d tools reach a routing helper (%v); the reachability walk has stopped following the call graph and this guard would pass while checking almost nothing", len(routed), routed)
+ }
+ if len(missing) > 0 {
+ t.Errorf("%d tool(s) route on browser but never declare it, so an agent on a multi-browser server cannot aim them anywhere but the default and gets no signal why:\n %s",
+ len(missing), strings.Join(missing, "\n "))
+ }
+}
+
+func TestNoParameterDescriptionIsWrittenTwice(t *testing.T) {
+ fset := token.NewFileSet()
+ file, err := parser.ParseFile(fset, "tools.go", nil, 0)
+ if err != nil {
+ t.Fatalf("cannot parse tools.go: %v", err)
+ }
+
+ seen := map[string]int{}
+ ast.Inspect(file, func(n ast.Node) bool {
+ call, ok := n.(*ast.CallExpr)
+ if !ok {
+ return true
+ }
+ sel, ok := call.Fun.(*ast.SelectorExpr)
+ if !ok || sel.Sel.Name != "Description" || len(call.Args) != 1 {
+ return true
+ }
+ lit, ok := call.Args[0].(*ast.BasicLit)
+ if !ok || lit.Kind != token.STRING {
+ return true
+ }
+ text, err := strconv.Unquote(lit.Value)
+ if err != nil {
+ return true
+ }
+ seen[text]++
+ return true
+ })
+
+ if len(seen) == 0 {
+ t.Fatal("found no description literals in tools.go; the scan matched nothing and this guard is vacuous")
+ }
+
+ var repeated []string
+ for text, count := range seen {
+ if count > 1 {
+ repeated = append(repeated, strconv.Itoa(count)+"x "+strconv.Quote(text))
+ }
+ }
+ sort.Strings(repeated)
+ if len(repeated) > 0 {
+ t.Errorf("%d description string(s) are written more than once in tools.go; give each a shared constructor in tools_params.go so a reword is one edit with a uniform effect:\n %s",
+ len(repeated), strings.Join(repeated, "\n "))
+ }
+}
+
+func TestSharedParamsHaveOneWordingPerConcept(t *testing.T) {
+ wordings := map[string]map[string]bool{}
+ for _, tool := range allTools() {
+ for name, value := range tool.InputSchema.Properties {
+ fields, ok := value.(map[string]any)
+ if !ok {
+ continue
+ }
+ text, _ := fields["description"].(string)
+ if wordings[name] == nil {
+ wordings[name] = map[string]bool{}
+ }
+ wordings[name][text] = true
+ }
+ }
+
+ // tabId keeps a second, required wording (network route/unroute target one
+ // tab by contract) and a third for the clear-all semantics, so it is asked
+ // for the count it should have rather than for one.
+ for _, tc := range []struct {
+ param string
+ want int
+ }{
+ {"ref", 1},
+ {"selector", 8},
+ {"browser", 2},
+ {"tabId", 3},
+ } {
+ if got := len(wordings[tc.param]); got != tc.want {
+ var texts []string
+ for text := range wordings[tc.param] {
+ texts = append(texts, strconv.Quote(text))
+ }
+ sort.Strings(texts)
+ t.Errorf("%q has %d distinct wordings across the tool set, want %d; an agent reading the tool list gets inconsistent guidance for one concept:\n %s",
+ tc.param, got, tc.want, strings.Join(texts, "\n "))
+ }
+ }
+}