High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
mcp: improve selector aliases, dialog click args, and find hints
Djain912f7962c9a61a4
diff --git a/internal/mcp/handlers.go b/internal/mcp/handlers.goindex fcfeb72c..91b96e14 100644--- a/internal/mcp/handlers.go+++ b/internal/mcp/handlers.go@@ -20,14 +20,15 @@ func handlerMap(c *Client) map[string]func(context.Context, mcp.CallToolRequest)"pinchtab_get_text": handleGetText(c),// Interaction- "pinchtab_click": handleAction(c, "click"),- "pinchtab_type": handleAction(c, "type"),- "pinchtab_press": handleAction(c, "press"),- "pinchtab_hover": handleAction(c, "hover"),- "pinchtab_focus": handleAction(c, "focus"),- "pinchtab_select": handleAction(c, "select"),- "pinchtab_scroll": handleAction(c, "scroll"),- "pinchtab_fill": handleAction(c, "fill"),+ "pinchtab_click": handleAction(c, "click"),+ "pinchtab_type": handleAction(c, "type"),+ "pinchtab_press": handleAction(c, "press"),+ "pinchtab_hover": handleAction(c, "hover"),+ "pinchtab_focus": handleAction(c, "focus"),+ "pinchtab_select": handleAction(c, "select"),+ "pinchtab_scroll": handleAction(c, "scroll"),+ "pinchtab_scroll_into_view": handleAction(c, "scrollintoview"),+ "pinchtab_fill": handleAction(c, "fill"),// Keyboard (no selector)"pinchtab_keyboard_type": handleKeyboardText(c, "keyboard-type"),diff --git a/internal/mcp/handlers_content.go b/internal/mcp/handlers_content.goindex 186e6428..6618daf8 100644--- a/internal/mcp/handlers_content.go+++ b/internal/mcp/handlers_content.go@@ -2,8 +2,10 @@ package mcpimport ("context"+ "encoding/json""fmt""net/url"+ "strings""github.com/mark3labs/mcp-go/mcp")@@ -63,6 +65,25 @@ func handleFind(c *Client) func(context.Context, mcp.CallToolRequest) (*mcp.Callif err != nil {return mcp.NewToolResultError(err.Error()), nil}- return resultFromBytes(body, code)+ if code >= 400 {+ return resultFromBytes(body, code)+ }++ var resp map[string]any+ if err := json.Unmarshal(body, &resp); err != nil {+ return resultFromBytes(body, code)+ }++ bestRef, _ := resp["best_ref"].(string)+ bestRef = strings.TrimSpace(bestRef)+ if bestRef != "" {+ resp["bestRef"] = bestRef+ resp["selector"] = bestRef+ resp["nextActionHint"] = fmt.Sprintf("Use selector %q in pinchtab_click/type/fill/hover. Reuse this ref until page changes; refresh snapshot only after navigation or stale-ref errors.", bestRef)+ } else {+ resp["nextActionHint"] = "No high-confidence ref found. Consider pinchtab_snapshot compact mode once, then retry pinchtab_find with a more specific query."+ }++ return jsonResult(resp)}}diff --git a/internal/mcp/handlers_content_test.go b/internal/mcp/handlers_content_test.goindex 02405227..4d27f909 100644--- a/internal/mcp/handlers_content_test.go+++ b/internal/mcp/handlers_content_test.go@@ -1,8 +1,14 @@package mcpimport (+ "context"+ "encoding/json"+ "net/http"+ "net/http/httptest""strings""testing"++ "github.com/mark3labs/mcp-go/mcp")func TestHandleEval(t *testing.T) {@@ -58,3 +64,39 @@ func TestHandleFind(t *testing.T) {t.Errorf("expected /find, got %s", text)}}++func TestHandleFindAddsSelectorHints(t *testing.T) {+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ if r.URL.Path != "/find" {+ http.Error(w, "unexpected path", http.StatusNotFound)+ return+ }+ _ = json.NewEncoder(w).Encode(map[string]any{+ "best_ref": "e7",+ "score": 0.91,+ })+ }))+ defer srv.Close()++ c := NewClient(srv.URL, "")+ h := handleFind(c)+ req := mcp.CallToolRequest{}+ req.Params.Name = "pinchtab_find"+ req.Params.Arguments = map[string]any{"query": "search button"}++ result, err := h(context.Background(), req)+ if err != nil {+ t.Fatalf("handler error: %v", err)+ }++ resp := resultJSON(t, result)+ if got, _ := resp["bestRef"].(string); got != "e7" {+ t.Fatalf("bestRef = %q, want e7", got)+ }+ if got, _ := resp["selector"].(string); got != "e7" {+ t.Fatalf("selector = %q, want e7", got)+ }+ if _, ok := resp["nextActionHint"].(string); !ok {+ t.Fatal("expected nextActionHint in response")+ }+}diff --git a/internal/mcp/handlers_helpers.go b/internal/mcp/handlers_helpers.goindex 87a7dc55..6d580f41 100644--- a/internal/mcp/handlers_helpers.go+++ b/internal/mcp/handlers_helpers.go@@ -3,8 +3,11 @@ package mcpimport ("encoding/json""fmt"+ "strconv"+ "strings""github.com/mark3labs/mcp-go/mcp"+ "github.com/pinchtab/pinchtab/internal/selector")func optString(r mcp.CallToolRequest, key string) string {@@ -12,11 +15,27 @@ func optString(r mcp.CallToolRequest, key string) string {return v}+func optTrimmedString(r mcp.CallToolRequest, key string) string {+ return strings.TrimSpace(optString(r, key))+}+func optFloat(r mcp.CallToolRequest, key string) (float64, bool) {v, ok := r.GetArguments()[key].(float64)return v, ok}+func optInt(r mcp.CallToolRequest, key string) (int, bool) {+ if v, ok := optFloat(r, key); ok {+ return int(v), true+ }+ if raw := optTrimmedString(r, key); raw != "" {+ if n, err := strconv.Atoi(raw); err == nil {+ return n, true+ }+ }+ return 0, false+}+func optBool(r mcp.CallToolRequest, key string) (bool, bool) {v, ok := r.GetArguments()[key].(bool)return v, ok@@ -31,6 +50,82 @@ func formatInt(v float64) string {return fmt.Sprintf("%d", int(v))}+func firstNonEmptyString(r mcp.CallToolRequest, keys ...string) string {+ for _, key := range keys {+ if v := optTrimmedString(r, key); v != "" {+ return v+ }+ }+ return ""+}++func hasKnownSelectorPrefix(v string) bool {+ lower := strings.ToLower(strings.TrimSpace(v))+ return strings.HasPrefix(lower, "css:") ||+ strings.HasPrefix(lower, "xpath:") ||+ strings.HasPrefix(lower, "text:") ||+ strings.HasPrefix(lower, "find:") ||+ strings.HasPrefix(lower, "ref:")+}++func looksLikeStructuredSelector(v string) bool {+ v = strings.TrimSpace(v)+ if v == "" {+ return false+ }+ if strings.HasPrefix(v, "#") || strings.HasPrefix(v, ".") || strings.HasPrefix(v, "[") {+ return true+ }+ if strings.HasPrefix(v, "//") || strings.HasPrefix(v, "(//") {+ return true+ }+ if strings.ContainsAny(v, "[]#:>+~") || strings.Contains(v, "=") {+ return true+ }+ // Treat dot notation as CSS only when it looks like tag/class syntax,+ // not plain text like numeric values (e.g. "50.50").+ if strings.Contains(v, ".") && hasASCIIAlpha(v) && !strings.ContainsAny(v, " \t\r\n") {+ return true+ }+ return false+}++func hasASCIIAlpha(v string) bool {+ for i := 0; i < len(v); i++ {+ c := v[i]+ if (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') {+ return true+ }+ }+ return false+}++// actionSelectorArg resolves common selector aliases used by MCP clients.+// If only "query" is provided, natural language input is normalized to+// semantic selector form (find:...).+func actionSelectorArg(r mcp.CallToolRequest) string {+ if sel := firstNonEmptyString(r, "selector", "ref", "element", "target"); sel != "" {+ return sel+ }+ query := optTrimmedString(r, "query")+ if query == "" {+ return ""+ }+ if hasKnownSelectorPrefix(query) || selector.IsRef(query) || looksLikeStructuredSelector(query) {+ return query+ }+ return "find:" + query+}++func resolveXY(r mcp.CallToolRequest) (float64, float64, bool) {+ x, okX := optFloat(r, "x")+ y, okY := optFloat(r, "y")+ if okX && okY {+ return x, y, true+ }+ return 0, 0, false+}+func resultFromBytes(body []byte, code int) (*mcp.CallToolResult, error) {if code >= 400 {return mcp.NewToolResultError(fmt.Sprintf("HTTP %d: %s", code, string(body))), nildiff --git a/internal/mcp/handlers_interaction.go b/internal/mcp/handlers_interaction.goindex f33e9456..c52a7702 100644--- a/internal/mcp/handlers_interaction.go+++ b/internal/mcp/handlers_interaction.go@@ -3,6 +3,7 @@ package mcpimport ("context""fmt"+ "strings""github.com/mark3labs/mcp-go/mcp")@@ -15,37 +16,63 @@ func handleAction(c *Client, kind string) func(context.Context, mcp.CallToolRequpayload["tabId"] = tabID}- resolveSelector := func(required bool) error {- sel := optString(r, "selector")- ref := optString(r, "ref")+ x, y, hasXY := resolveXY(r)+ if hasXY {+ payload["x"] = x+ payload["y"] = y+ payload["hasXY"] = true+ }++ hasNodeID := false+ if nodeID, ok := optInt(r, "nodeId"); ok && nodeID > 0 {+ hasNodeID = true+ payload["nodeId"] = nodeID+ }++ resolveSelector := func(required bool) (bool, error) {+ sel := actionSelectorArg(r)if sel != "" {payload["selector"] = sel- } else if ref != "" {- payload["selector"] = ref- } else if required {- return fmt.Errorf("required parameter 'selector' is missing")+ return true, nil}- return nil+ if required {+ return false, fmt.Errorf("required parameter 'selector' is missing")+ }+ return false, nil}switch kind {case "click", "hover", "focus":- if err := resolveSelector(true); err != nil {+ requiresSelector := !hasNodeID+ if kind == "click" || kind == "hover" {+ requiresSelector = requiresSelector && !hasXY+ }+ if _, err := resolveSelector(requiresSelector); err != nil {return mcp.NewToolResultError(err.Error()), nil}if kind == "click" {if waitNav, ok := optBool(r, "waitNav"); ok && waitNav {payload["waitNav"] = true}+ dialogAction := strings.ToLower(firstNonEmptyString(r, "dialogAction", "onDialog"))+ if dialogAction != "" {+ if dialogAction != "accept" && dialogAction != "dismiss" {+ return mcp.NewToolResultError("dialogAction must be 'accept' or 'dismiss'"), nil+ }+ payload["dialogAction"] = dialogAction+ if dialogText := firstNonEmptyString(r, "dialogText", "promptText"); dialogText != "" {+ payload["dialogText"] = dialogText+ }+ }}case "type":- if err := resolveSelector(true); err != nil {+ if _, err := resolveSelector(true); err != nil {return mcp.NewToolResultError(err.Error()), nil}- text, err := r.RequireString("text")- if err != nil {- return mcp.NewToolResultError(err.Error()), nil+ text := firstNonEmptyString(r, "text", "value")+ if text == "" {+ return mcp.NewToolResultError("required parameter 'text' is missing"), nil}payload["text"] = text@@ -57,29 +84,78 @@ func handleAction(c *Client, kind string) func(context.Context, mcp.CallToolRequpayload["key"] = keycase "select":- if err := resolveSelector(true); err != nil {+ if _, err := resolveSelector(true); err != nil {return mcp.NewToolResultError(err.Error()), nil}- value, err := r.RequireString("value")- if err != nil {- return mcp.NewToolResultError(err.Error()), nil+ value := firstNonEmptyString(r, "value", "option")+ if value == "" {+ return mcp.NewToolResultError("required parameter 'value' is missing"), nil}payload["value"] = valuecase "scroll":- _ = resolveSelector(false)- if px, ok := optFloat(r, "pixels"); ok {- payload["scrollY"] = int(px)+ hasSelector, err := resolveSelector(false)+ if err != nil {+ return mcp.NewToolResultError(err.Error()), nil}+ pixels, hasPixels := optInt(r, "pixels")+ deltaX, hasDeltaX := optInt(r, "deltaX")+ deltaY, hasDeltaY := optInt(r, "deltaY")- case "fill":- if err := resolveSelector(true); err != nil {+ direction := strings.ToLower(optTrimmedString(r, "direction"))+ steps, hasSteps := optInt(r, "steps")+ if !hasSteps || steps < 1 {+ steps = 1+ }++ if direction != "" && !hasDeltaY {+ magnitude := 120+ if hasPixels && pixels != 0 {+ magnitude = pixels+ if magnitude < 0 {+ magnitude = -magnitude+ }+ }+ magnitude *= steps+ switch direction {+ case "down":+ deltaY = magnitude+ case "up":+ deltaY = -magnitude+ default:+ return mcp.NewToolResultError("direction must be 'up' or 'down'"), nil+ }+ hasDeltaY = true+ }++ useWheel := hasXY || hasDeltaX || hasDeltaY || (hasSelector && hasPixels)+ if useWheel {+ payload["kind"] = "mouse-wheel"+ if hasDeltaX {+ payload["deltaX"] = deltaX+ }+ if hasDeltaY {+ payload["deltaY"] = deltaY+ } else if hasPixels {+ payload["deltaY"] = pixels+ }+ } else if hasPixels {+ payload["scrollY"] = pixels+ }++ case "scrollintoview":+ if _, err := resolveSelector(true); err != nil {return mcp.NewToolResultError(err.Error()), nil}- value, err := r.RequireString("value")- if err != nil {++ case "fill":+ if _, err := resolveSelector(true); err != nil {return mcp.NewToolResultError(err.Error()), nil}+ value := firstNonEmptyString(r, "value", "text")+ if value == "" {+ return mcp.NewToolResultError("required parameter 'value' is missing"), nil+ }payload["value"] = value}diff --git a/internal/mcp/handlers_interaction_test.go b/internal/mcp/handlers_interaction_test.goindex 9f153bc5..bd30e4f1 100644--- a/internal/mcp/handlers_interaction_test.go+++ b/internal/mcp/handlers_interaction_test.go@@ -44,6 +44,92 @@ func TestHandleClickMissingRef(t *testing.T) {}}+func TestHandleClickCoordinates(t *testing.T) {+ srv := mockPinchTab()+ defer srv.Close()++ r := callTool(t, "pinchtab_click", map[string]any{+ "x": float64(120),+ "y": float64(340),+ }, srv)++ resp := resultJSON(t, r)+ body, _ := resp["body"].(map[string]any)+ if got, ok := body["hasXY"].(bool); !ok || !got {+ t.Fatalf("expected hasXY=true, got %#v", body["hasXY"])+ }+ if got, _ := body["x"].(float64); got != 120 {+ t.Fatalf("x = %v, want 120", got)+ }+ if got, _ := body["y"].(float64); got != 340 {+ t.Fatalf("y = %v, want 340", got)+ }+}++func TestHandleClickQueryAliasUsesSemanticSelector(t *testing.T) {+ srv := mockPinchTab()+ defer srv.Close()++ r := callTool(t, "pinchtab_click", map[string]any{+ "query": "login button",+ }, srv)++ resp := resultJSON(t, r)+ body, _ := resp["body"].(map[string]any)+ if got, _ := body["selector"].(string); got != "find:login button" {+ t.Fatalf("selector = %q, want %q", got, "find:login button")+ }+}++func TestHandleClickQueryAliasNumericTextUsesSemanticSelector(t *testing.T) {+ srv := mockPinchTab()+ defer srv.Close()++ r := callTool(t, "pinchtab_click", map[string]any{+ "query": "50.50",+ }, srv)++ resp := resultJSON(t, r)+ body, _ := resp["body"].(map[string]any)+ if got, _ := body["selector"].(string); got != "find:50.50" {+ t.Fatalf("selector = %q, want %q", got, "find:50.50")+ }+}++func TestHandleClickDialogActionPassThrough(t *testing.T) {+ srv := mockPinchTab()+ defer srv.Close()++ r := callTool(t, "pinchtab_click", map[string]any{+ "ref": "e5",+ "dialogAction": "accept",+ "dialogText": "pinchtab",+ }, srv)++ resp := resultJSON(t, r)+ body, _ := resp["body"].(map[string]any)+ if got, _ := body["dialogAction"].(string); got != "accept" {+ t.Fatalf("dialogAction = %q, want accept", got)+ }+ if got, _ := body["dialogText"].(string); got != "pinchtab" {+ t.Fatalf("dialogText = %q, want pinchtab", got)+ }+}++func TestHandleClickDialogActionRejectsInvalidValue(t *testing.T) {+ srv := mockPinchTab()+ defer srv.Close()++ r := callTool(t, "pinchtab_click", map[string]any{+ "ref": "e5",+ "dialogAction": "maybe",+ }, srv)++ if !r.IsError {+ t.Fatal("expected error for invalid dialogAction")+ }+}+func TestHandleType(t *testing.T) {srv := mockPinchTab()defer srv.Close()@@ -105,6 +191,62 @@ func TestHandleScroll(t *testing.T) {}}+func TestHandleScrollDirectionUsesMouseWheel(t *testing.T) {+ srv := mockPinchTab()+ defer srv.Close()++ r := callTool(t, "pinchtab_scroll", map[string]any{+ "direction": "down",+ "steps": float64(2),+ }, srv)++ resp := resultJSON(t, r)+ body, _ := resp["body"].(map[string]any)+ if got, _ := body["kind"].(string); got != "mouse-wheel" {+ t.Fatalf("kind = %q, want mouse-wheel", got)+ }+ if got, _ := body["deltaY"].(float64); got != 240 {+ t.Fatalf("deltaY = %v, want 240", got)+ }+}++func TestHandleScrollSelectorPixelsUsesMouseWheel(t *testing.T) {+ srv := mockPinchTab()+ defer srv.Close()++ r := callTool(t, "pinchtab_scroll", map[string]any{+ "selector": "#list",+ "pixels": float64(300),+ }, srv)++ resp := resultJSON(t, r)+ body, _ := resp["body"].(map[string]any)+ if got, _ := body["kind"].(string); got != "mouse-wheel" {+ t.Fatalf("kind = %q, want mouse-wheel", got)+ }+ if got, _ := body["deltaY"].(float64); got != 300 {+ t.Fatalf("deltaY = %v, want 300", got)+ }+}++func TestHandleScrollIntoView(t *testing.T) {+ srv := mockPinchTab()+ defer srv.Close()++ r := callTool(t, "pinchtab_scroll_into_view", map[string]any{+ "ref": "e9",+ }, srv)++ resp := resultJSON(t, r)+ body, _ := resp["body"].(map[string]any)+ if got, _ := body["kind"].(string); got != "scrollintoview" {+ t.Fatalf("kind = %q, want scrollintoview", got)+ }+ if got, _ := body["selector"].(string); got != "e9" {+ t.Fatalf("selector = %q, want e9", got)+ }+}+func TestHandleFill(t *testing.T) {srv := mockPinchTab()defer srv.Close()diff --git a/internal/mcp/server_test.go b/internal/mcp/server_test.goindex 2046dd8a..ecffc0b7 100644--- a/internal/mcp/server_test.go+++ b/internal/mcp/server_test.go@@ -18,8 +18,8 @@ func TestNewServerRegistersAllTools(t *testing.T) {// The server should have registered all tools.// We verify by checking that NewServer doesn't panic — the panic// in NewServer fires if any tool lacks a handler.- if len(tools) != 35 {- t.Errorf("expected 35 tools, got %d", len(tools))+ if len(tools) != 36 {+ t.Errorf("expected 36 tools, got %d", len(tools))}}diff --git a/internal/mcp/tools.go b/internal/mcp/tools.goindex 2dd17e1c..bd88aab9 100644--- a/internal/mcp/tools.go+++ b/internal/mcp/tools.go@@ -12,7 +12,7 @@ func allTools() []mcp.Tool {mcp.WithString("tabId", mcp.Description("Target tab ID (optional, uses current tab if empty)")),),mcp.NewTool("pinchtab_snapshot",- mcp.WithDescription("Get an accessibility tree snapshot of the current page"),+ 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")),mcp.WithBoolean("interactive", mcp.Description("Only interactive elements (buttons, links, inputs)")),mcp.WithBoolean("compact", mcp.Description("Compact format (most token-efficient)")),@@ -44,16 +44,23 @@ func allTools() []mcp.Tool {// ── Interaction ─────────────────────────────────────────────mcp.NewTool("pinchtab_click",- mcp.WithDescription("Click an element by selector (ref from snapshot e.g. 'e5', CSS e.g. 'css:#btn', XPath e.g. 'xpath://button', text e.g. 'text:Submit', or semantic e.g. 'find:login button')"),- mcp.WithString("selector", mcp.Required(), mcp.Description("Unified selector: ref (e.g. 'e5'), CSS ('css:#btn' or '#btn'), XPath ('xpath://button'), text ('text:Submit'), or semantic ('find:login button'). Non-ref selectors resolve in the current frame scope.")),+ 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 ('css:#btn' or '#btn'), XPath ('xpath://button'), text ('text:Submit'), or semantic ('find:login button'). 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 (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")),mcp.WithBoolean("waitNav", mcp.Description("Wait for navigation after the click when the element triggers a page change")),mcp.WithString("tabId", mcp.Description("Target tab ID")),),mcp.NewTool("pinchtab_type",mcp.WithDescription("Type text into an input element"),- mcp.WithString("selector", mcp.Required(), mcp.Description("Unified selector: ref (e.g. 'e5'), CSS, XPath, text, or semantic. Non-ref selectors resolve in the current frame scope.")),+ 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.WithString("tabId", mcp.Description("Target tab ID")),),@@ -64,34 +71,56 @@ func allTools() []mcp.Tool {),mcp.NewTool("pinchtab_hover",mcp.WithDescription("Hover over an element"),- mcp.WithString("selector", mcp.Required(), mcp.Description("Unified selector: ref (e.g. 'e5'), CSS, XPath, text, or semantic. Non-ref selectors resolve in the current frame scope.")),+ 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("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.WithString("tabId", mcp.Description("Target tab ID")),),mcp.NewTool("pinchtab_focus",mcp.WithDescription("Focus an element"),- mcp.WithString("selector", mcp.Required(), mcp.Description("Unified selector: ref (e.g. 'e5'), CSS, XPath, text, or semantic. Non-ref selectors resolve in the current frame scope.")),+ 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.NewTool("pinchtab_select",mcp.WithDescription("Select a dropdown option by value or visible text"),- mcp.WithString("selector", mcp.Required(), mcp.Description("Unified selector for the select element. Non-ref selectors resolve in the current frame scope.")),+ 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")),mcp.WithString("value", mcp.Required(), mcp.Description("Option value or visible text to select")),mcp.WithString("tabId", mcp.Description("Target tab ID")),),mcp.NewTool("pinchtab_scroll",- mcp.WithDescription("Scroll the page or an element"),+ 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")),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")),+ mcp.WithString("direction", mcp.Description("Convenience direction: 'up' or 'down'")),+ mcp.WithNumber("steps", mcp.Description("Multiplier for direction-based scrolling (default 1)")),+ mcp.WithNumber("x", mcp.Description("Optional X coordinate for wheel target")),+ mcp.WithNumber("y", mcp.Description("Optional Y coordinate for wheel target")),+ mcp.WithString("tabId", mcp.Description("Target tab ID")),+ ),+ 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.WithString("tabId", mcp.Description("Target tab ID")),),mcp.NewTool("pinchtab_fill",mcp.WithDescription("Fill an input field directly via JavaScript dispatch"),- mcp.WithString("selector", mcp.Required(), mcp.Description("Unified selector: ref (e.g. 'e5'), CSS, XPath, text, or semantic. Non-ref selectors resolve in the current frame scope.")),+ 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.WithString("value", mcp.Required(), mcp.Description("Value to fill")),mcp.WithString("tabId", mcp.Description("Target tab ID")),),@@ -132,7 +161,7 @@ func allTools() []mcp.Tool {mcp.WithString("pageRanges", mcp.Description("Pages to export (e.g., '1-3,5')")),),mcp.NewTool("pinchtab_find",- mcp.WithDescription("Find elements by text content or CSS selector"),+ 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")),),