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.goindex 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.jsonindex 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.goindex 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.gonew file mode 100644index 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.gonew file mode 100644index 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 "))+ }+ }+}