Skip to content

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

fix: nodeId is read for all nine action tools but declared on three, so six lose discovery and validation (PIN-144)

Luigi Agostibe0f68c4b604
diff --git a/docs/reference/mcp-tools.md b/docs/reference/mcp-tools.md
index 864d58c0..7f4fd0d7 100644
--- a/docs/reference/mcp-tools.md
+++ b/docs/reference/mcp-tools.md
@@ -32,19 +32,19 @@ Structured semantic locators are matched by the semantic engine; CSS, XPath, ref
## Interaction
-All element-action tools accept the unified `selector` and the legacy aliases `ref` (deprecated) and `query` (semantic shorthand).
+All element-action tools accept the unified `selector` and the legacy aliases `ref` (deprecated) and `query` (semantic shorthand). Every one of them also accepts `nodeId` (a backend node ID from a snapshot) as an alternative target. Coordinates (`x`/`y`) are accepted only by `pinchtab_click`, `pinchtab_hover` and `pinchtab_scroll` — the other kinds have no coordinate behaviour.
| Tool | Key Parameters | Notes |
| --- | --- | --- |
| `pinchtab_click` | `selector`, `ref`, `query`, `tabId`, `x`, `y`, `nodeId`, `dialogAction`, `dialogText`, `waitNav`, `mode`, `snap` | Click element by selector or coordinate; `mode` accepts `dom` or `dispatch` as a broad low-level escape hatch for click delivery; `mode` and `humanize` are mutually exclusive; `dialogAction` handles a dialog opened by the click; `waitNav=true` waits for navigation; `snap=true` returns a snapshot |
-| `pinchtab_type` | `selector`, `ref`, `query`, `text` required, `tabId` | Sends key events at the targeted input |
-| `pinchtab_press` | `key` required, `tabId` | Press a key such as `Enter` |
+| `pinchtab_type` | `selector`, `ref`, `query`, `nodeId`, `text` required, `tabId` | Sends key events at the targeted input; target with `selector` or `nodeId` |
+| `pinchtab_press` | `key` required, `nodeId`, `tabId` | Press a key such as `Enter`; `nodeId` focuses that node first, otherwise the key goes to the focused element |
| `pinchtab_hover` | `selector`, `ref`, `query`, `tabId`, `x`, `y`, `nodeId` | Hover an element or coordinate |
| `pinchtab_focus` | `selector`, `ref`, `query`, `tabId`, `nodeId` | Focus element |
-| `pinchtab_select` | `selector`, `ref`, `query`, `value` required, `tabId`, `snap` | Select `<option>` by value or visible text |
-| `pinchtab_scroll` | `selector`, `ref`, `query`, `pixels`, `deltaX`, `deltaY`, `direction`, `steps`, `x`, `y`, `tabId` | Omit `selector` to scroll the page; element + `pixels` uses wheel semantics; `direction` accepts `up`/`down` |
-| `pinchtab_scroll_into_view` | `selector`, `ref`, `query`, `tabId` | Scrolls the target into view and returns geometry for stable follow-up actions |
-| `pinchtab_fill` | `selector`, `ref`, `query`, `value` required, `tabId`, `snap` | Direct fill via JS dispatch instead of keystrokes |
+| `pinchtab_select` | `selector`, `ref`, `query`, `nodeId`, `value` required, `tabId`, `snap` | Select `<option>` by value or visible text; target with `selector` or `nodeId` |
+| `pinchtab_scroll` | `selector`, `ref`, `query`, `nodeId`, `pixels`, `deltaX`, `deltaY`, `direction`, `steps`, `x`, `y`, `tabId` | Omit every target to scroll the page; element + `pixels` uses wheel semantics; `direction` accepts `up`/`down` |
+| `pinchtab_scroll_into_view` | `selector`, `ref`, `query`, `nodeId`, `tabId` | Scrolls the target into view and returns geometry for stable follow-up actions; target with `selector` or `nodeId` |
+| `pinchtab_fill` | `selector`, `ref`, `query`, `nodeId`, `value` required, `tabId`, `snap` | Direct fill via JS dispatch instead of keystrokes; target with `selector` or `nodeId` |
## Keyboard
diff --git a/internal/mcp/argcheck_test.go b/internal/mcp/argcheck_test.go
index 02b0ea1b..4a4a729c 100644
--- a/internal/mcp/argcheck_test.go
+++ b/internal/mcp/argcheck_test.go
@@ -224,10 +224,13 @@ func TestEveryHandlerHasASchemaAndEverySchemaAHandler(t *testing.T) {
// see it either — it derives from the schemas, so an undeclared argument keeps the
// silent-coercion-drop this package otherwise rejects.
//
-// Name-level, not per-tool, and deliberately so: a per-tool assertion needs a
-// tool-to-handler-source mapping that is declared nowhere and would be brittle
-// enough to invite deletion. Name-level needs no mapping and still catches the
-// class.
+// NAME-LEVEL, not per-tool: an argument passes as soon as ONE tool declares it,
+// so this census cannot see an argument read for a kind whose own tool omits it —
+// which is how nodeId and x/y were each read for all nine action tools while
+// three declared them. TestNoActionToolIsSentATypedArgumentItDoesNotDeclare covers
+// that per-tool half behaviourally, for the action family. The two are not one
+// check: this one spans every handler in the package and catches a name declared
+// nowhere at all; that one is narrower in scope and stricter within it.
//
// optString is deliberately NOT scanned. A string argument read without a
// declaration is undiscoverable but not a correctness hazard: there is no
@@ -378,3 +381,92 @@ func TestOnlyPointerToolsDeclareHumanize(t *testing.T) {
}
}
}
+
+// The per-tool half the name-level census above cannot see. A typed argument read
+// for a kind whose tool does not declare it is undiscoverable AND unvalidated,
+// because validateTypedArgs keys its type map per tool — the name being declared
+// somewhere else does not help the tool being called. handleAction reads its
+// arguments before switching on kind, so this is where that goes wrong.
+//
+// Behavioural rather than structural: reachability is observed as an effect on the
+// wire (the argument, or anything derived from it, in the outbound body) or as an
+// extra upstream request. That needs no tool-to-handler-source mapping and cannot
+// go stale as the handler moves code around. Its blind spot is an undeclared read
+// with no observable effect at all, which by construction changes nothing.
+func TestNoActionToolIsSentATypedArgumentItDoesNotDeclare(t *testing.T) {
+ // Arguments the handler only reads as a set; sending one alone proves nothing.
+ groups := [][]string{{"x", "y"}}
+ grouped := map[string]bool{}
+ for _, group := range groups {
+ for _, name := range group {
+ grouped[name] = true
+ }
+ }
+ for _, tc := range actionToolTargets {
+ for name := range schemaArgTypesOnce()[tc.tool] {
+ if !grouped[name] {
+ groups = append(groups, []string{name})
+ grouped[name] = true
+ }
+ }
+ }
+
+ // The declared type of each name, taken from whichever action tool declares it,
+ // so the probe value is one the accessor would actually read.
+ typeOf := map[string]string{}
+ for _, tc := range actionToolTargets {
+ for name, kind := range schemaArgTypesOnce()[tc.tool] {
+ typeOf[name] = kind
+ }
+ }
+
+ const sentinel = 424242.0
+ checked := 0
+ for _, tc := range actionToolTargets {
+ declared := schemaArgTypesOnce()[tc.tool]
+ for _, group := range groups {
+ kinds := map[string]int{}
+ for _, name := range group {
+ kinds[declared[name]]++
+ }
+ if len(kinds) != 1 {
+ t.Errorf("%s declares %v inconsistently (%v); the group must be all-or-nothing", tc.tool, group, kinds)
+ continue
+ }
+ if _, isDeclared := declared[group[0]]; isDeclared {
+ continue
+ }
+
+ args := actionArgs(tc.tool, map[string]any{"selector": "#a"})
+ for _, name := range group {
+ if typeOf[name] == "boolean" {
+ args[name] = true
+ continue
+ }
+ args[name] = sentinel
+ }
+ checked++
+
+ srv, paths := upstreamRecorder(t)
+ result := callTool(t, tc.tool, args, srv)
+ if result.IsError {
+ t.Fatalf("%s rejected undeclared %v outright (%s); this guard expects it to be ignored", tc.tool, group, resultText(t, result))
+ }
+ body, _ := resultJSON(t, result)["body"].(map[string]any)
+ for field, value := range body {
+ if value == sentinel || value == true || field == "hasXY" {
+ t.Errorf("pinchtab_%s: %v is reachable for kind %q but the tool does not declare it — outbound body carries %s=%v, so it is undiscoverable and validateTypedArgs cannot type-check it",
+ strings.TrimPrefix(tc.tool, "pinchtab_"), group, tc.tool, field, value)
+ break
+ }
+ }
+ if len(*paths) != 1 {
+ t.Errorf("%s made %v upstream requests with undeclared %v; the argument changed behaviour it cannot be validated for", tc.tool, *paths, group)
+ }
+ }
+ }
+ if checked == 0 {
+ t.Fatal("no undeclared (tool, argument) pair exercised — this guard is checking nothing")
+ }
+ t.Logf("checked %d undeclared (tool, typed argument) pairs across %d action tools", checked, len(actionToolTargets))
+}
diff --git a/internal/mcp/handlers_interaction.go b/internal/mcp/handlers_interaction.go
index 32c4d7e3..aa40594b 100644
--- a/internal/mcp/handlers_interaction.go
+++ b/internal/mcp/handlers_interaction.go
@@ -15,6 +15,12 @@ import (
// also has mode, so only click can hit the mutual-exclusion rule.
var humanizeAction = map[string]bool{"click": true, "hover": true}
+// xyAction is the set of kinds that can be targeted by coordinate, mirroring the
+// tools that declare x/y. The bridge honours x/y only for these kinds — the text
+// and form actions target by nodeId or selector — so reading it for every kind
+// forwarded an inert, undiscoverable and unvalidated pair, hasXY included.
+var xyAction = map[string]bool{"click": true, "hover": true, "scroll": true}
+
func handleAction(c *Client, kind string) func(context.Context, mcp.CallToolRequest) (*mcp.CallToolResult, error) {
return func(ctx context.Context, r mcp.CallToolRequest) (*mcp.CallToolResult, error) {
payload := map[string]any{"kind": kind}
@@ -23,7 +29,10 @@ func handleAction(c *Client, kind string) func(context.Context, mcp.CallToolRequ
payload["tabId"] = tabID
}
- x, y, hasXY := resolveXY(r)
+ x, y, hasXY := 0.0, 0.0, false
+ if xyAction[kind] {
+ x, y, hasXY = resolveXY(r)
+ }
if hasXY {
payload["x"] = x
payload["y"] = y
@@ -94,7 +103,7 @@ func handleAction(c *Client, kind string) func(context.Context, mcp.CallToolRequ
}
case "type":
- if _, err := resolveSelector(true); err != nil {
+ if _, err := resolveSelector(!hasNodeID); err != nil {
return mcp.NewToolResultError(err.Error()), nil
}
text := firstNonEmptyString(r, "text", "value")
@@ -111,7 +120,7 @@ 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(!hasNodeID); err != nil {
return mcp.NewToolResultError(err.Error()), nil
}
value := firstNonEmptyString(r, "value", "option")
@@ -171,12 +180,12 @@ func handleAction(c *Client, kind string) func(context.Context, mcp.CallToolRequ
}
case "scrollintoview":
- if _, err := resolveSelector(true); err != nil {
+ if _, err := resolveSelector(!hasNodeID); err != nil {
return mcp.NewToolResultError(err.Error()), nil
}
case "fill":
- if _, err := resolveSelector(true); err != nil {
+ if _, err := resolveSelector(!hasNodeID); err != nil {
return mcp.NewToolResultError(err.Error()), nil
}
value := firstNonEmptyString(r, "value", "text")
diff --git a/internal/mcp/handlers_interaction_test.go b/internal/mcp/handlers_interaction_test.go
index 14052b61..84f550df 100644
--- a/internal/mcp/handlers_interaction_test.go
+++ b/internal/mcp/handlers_interaction_test.go
@@ -341,3 +341,128 @@ func TestHandleFocus(t *testing.T) {
t.Errorf("expected focus, got %s", text)
}
}
+
+// actionToolTargets is the per-tool matrix this card decided: every action tool
+// declares nodeId, because the bridge honours req.NodeID for every one of the nine
+// kinds. requiredArgs are the tool's own non-target requirements, and
+// selectorOptionalWithNodeID marks the tools whose MCP layer used to demand a
+// selector even though the bridge does not.
+var actionToolTargets = []struct {
+ tool string
+ requiredArgs map[string]any
+ selectorOptionalWithNodeID bool
+}{
+ {tool: "pinchtab_click", selectorOptionalWithNodeID: true},
+ {tool: "pinchtab_hover", selectorOptionalWithNodeID: true},
+ {tool: "pinchtab_focus", selectorOptionalWithNodeID: true},
+ {tool: "pinchtab_type", requiredArgs: map[string]any{"text": "hi"}, selectorOptionalWithNodeID: true},
+ {tool: "pinchtab_fill", requiredArgs: map[string]any{"value": "v"}, selectorOptionalWithNodeID: true},
+ {tool: "pinchtab_select", requiredArgs: map[string]any{"value": "v"}, selectorOptionalWithNodeID: true},
+ {tool: "pinchtab_scroll_into_view", selectorOptionalWithNodeID: true},
+ {tool: "pinchtab_scroll"},
+ {tool: "pinchtab_press", requiredArgs: map[string]any{"key": "Enter"}},
+}
+
+func actionArgs(tool string, extra map[string]any) map[string]any {
+ args := map[string]any{}
+ for _, entry := range actionToolTargets {
+ if entry.tool != tool {
+ continue
+ }
+ for name, value := range entry.requiredArgs {
+ args[name] = value
+ }
+ }
+ for name, value := range extra {
+ args[name] = value
+ }
+ return args
+}
+
+// nodeId was read before the switch on kind, so all nine tools forwarded it, but
+// only click, hover and focus declared it. On the other six that meant no
+// discovery and — because validateTypedArgs keys its type map per tool — no
+// validation either, so a malformed value was dropped in silence.
+func TestEveryActionToolAcceptsAndValidatesNodeID(t *testing.T) {
+ for _, tc := range actionToolTargets {
+ t.Run(tc.tool, func(t *testing.T) {
+ srv, _ := upstreamRecorder(t)
+ result := callTool(t, tc.tool, actionArgs(tc.tool, map[string]any{"selector": "#a", "nodeId": float64(42)}), srv)
+ if result.IsError {
+ t.Fatalf("a valid nodeId was rejected: %s", resultText(t, result))
+ }
+ body, _ := resultJSON(t, result)["body"].(map[string]any)
+ if got, ok := body["nodeId"]; !ok || got != float64(42) {
+ t.Errorf("outbound nodeId = %v (present: %v), want 42 — the bridge honours it for this kind", got, ok)
+ }
+
+ srv2, paths := upstreamRecorder(t)
+ malformed := callTool(t, tc.tool, actionArgs(tc.tool, map[string]any{"selector": "#a", "nodeId": "abc"}), srv2)
+ if !malformed.IsError {
+ t.Fatalf("nodeId \"abc\" was accepted and silently dropped; upstream saw %v", *paths)
+ }
+ if text := resultText(t, malformed); !strings.Contains(text, "nodeId") {
+ t.Errorf("rejection %q does not name nodeId, so the caller cannot correct it", text)
+ }
+ if len(*paths) != 0 {
+ t.Errorf("upstream was called %v despite the malformed argument", *paths)
+ }
+ })
+ }
+}
+
+// The MCP layer required a selector on type, fill, select and scroll_into_view
+// even though the bridge resolves those kinds from NodeID alone. Declaring nodeId
+// there without relaxing this would advertise an argument that cannot be used.
+func TestNodeIDAloneSatisfiesTheTargetRequirement(t *testing.T) {
+ for _, tc := range actionToolTargets {
+ if !tc.selectorOptionalWithNodeID {
+ continue
+ }
+ t.Run(tc.tool, func(t *testing.T) {
+ srv, _ := upstreamRecorder(t)
+ result := callTool(t, tc.tool, actionArgs(tc.tool, map[string]any{"nodeId": float64(42)}), srv)
+ if result.IsError {
+ t.Fatalf("nodeId alone was rejected: %s", resultText(t, result))
+ }
+ body, _ := resultJSON(t, result)["body"].(map[string]any)
+ if _, ok := body["selector"]; ok {
+ t.Errorf("outbound body carries a selector the caller never sent: %v", body)
+ }
+ if got := body["nodeId"]; got != float64(42) {
+ t.Errorf("outbound nodeId = %v, want 42", got)
+ }
+
+ srv2, paths := upstreamRecorder(t)
+ neither := callTool(t, tc.tool, actionArgs(tc.tool, nil), srv2)
+ if !neither.IsError {
+ t.Fatalf("a call with no target at all was accepted; upstream saw %v", *paths)
+ }
+ if text := resultText(t, neither); !strings.Contains(text, "selector") {
+ t.Errorf("the no-target rejection %q should still name selector", text)
+ }
+ })
+ }
+}
+
+// x/y had the same shape as nodeId — read before the switch, so forwarded for all
+// nine kinds with hasXY set — but the opposite correct answer: the bridge honours
+// coordinates only for the pointer kinds, so the fix is to stop reading it
+// elsewhere rather than to declare it everywhere.
+func TestCoordinatesReachTheWireOnlyForTheToolsThatDeclareThem(t *testing.T) {
+ for _, tc := range actionToolTargets {
+ t.Run(tc.tool, func(t *testing.T) {
+ _, declared := schemaArgTypesOnce()[tc.tool]["x"]
+ srv, _ := upstreamRecorder(t)
+ result := callTool(t, tc.tool, actionArgs(tc.tool, map[string]any{"selector": "#a", "x": float64(11), "y": float64(22)}), srv)
+ if result.IsError {
+ t.Fatalf("coordinates were rejected: %s", resultText(t, result))
+ }
+ body, _ := resultJSON(t, result)["body"].(map[string]any)
+ _, forwarded := body["hasXY"]
+ if declared != forwarded {
+ t.Errorf("%s declares x/y = %v but forwards them = %v (body %v)", tc.tool, declared, forwarded, body)
+ }
+ })
+ }
+}
diff --git a/internal/mcp/tools.go b/internal/mcp/tools.go
index 12dc55a2..2210c93e 100644
--- a/internal/mcp/tools.go
+++ b/internal/mcp/tools.go
@@ -118,6 +118,7 @@ func allTools() []mcp.Tool {
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).")),
@@ -125,6 +126,7 @@ func allTools() []mcp.Tool {
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).")),
@@ -158,6 +160,7 @@ func allTools() []mcp.Tool {
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.WithNumber("nodeId", mcp.Description("Optional backend node ID to target directly")),
mcp.WithString("tabId", mcp.Description("Target tab ID")),
mcp.WithBoolean("snap", mcp.Description("Return interactive compact snapshot after select (saves a round-trip)")),
mcp.WithString("browser",
@@ -175,6 +178,7 @@ func allTools() []mcp.Tool {
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.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).")),
@@ -184,6 +188,7 @@ func allTools() []mcp.Tool {
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).")),
@@ -194,6 +199,7 @@ func allTools() []mcp.Tool {
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.WithNumber("nodeId", mcp.Description("Optional backend node ID to target directly")),
mcp.WithString("tabId", mcp.Description("Target tab ID")),
mcp.WithBoolean("snap", mcp.Description("Return interactive compact snapshot after fill (saves a round-trip)")),
mcp.WithString("browser",