Skip to content

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.go
index 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.go
index 186e6428..6618daf8 100644
--- a/internal/mcp/handlers_content.go
+++ b/internal/mcp/handlers_content.go
@@ -2,8 +2,10 @@ package mcp
import (
"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.Call
if 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.go
index 02405227..4d27f909 100644
--- a/internal/mcp/handlers_content_test.go
+++ b/internal/mcp/handlers_content_test.go
@@ -1,8 +1,14 @@
package mcp
import (
+ "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.go
index 87a7dc55..6d580f41 100644
--- a/internal/mcp/handlers_helpers.go
+++ b/internal/mcp/handlers_helpers.go
@@ -3,8 +3,11 @@ package mcp
import (
"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))), nil
diff --git a/internal/mcp/handlers_interaction.go b/internal/mcp/handlers_interaction.go
index f33e9456..c52a7702 100644
--- a/internal/mcp/handlers_interaction.go
+++ b/internal/mcp/handlers_interaction.go
@@ -3,6 +3,7 @@ package mcp
import (
"context"
"fmt"
+ "strings"
"github.com/mark3labs/mcp-go/mcp"
)
@@ -15,37 +16,63 @@ func handleAction(c *Client, kind string) func(context.Context, mcp.CallToolRequ
payload["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.CallToolRequ
payload["key"] = key
case "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"] = value
case "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.go
index 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.go
index 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.go
index 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")),
),