Skip to content

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

fix: MCP sends browser in the body where the router only reads the query (PIN-069)

Luigi Agostide3a3836e10b
diff --git a/internal/mcp/handlers_interaction.go b/internal/mcp/handlers_interaction.go
index ae960739..2bdaee11 100644
--- a/internal/mcp/handlers_interaction.go
+++ b/internal/mcp/handlers_interaction.go
@@ -16,9 +16,6 @@ func handleAction(c *Client, kind string) func(context.Context, mcp.CallToolRequ
if tabID := optString(r, "tabId"); tabID != "" {
payload["tabId"] = tabID
}
- if browser := optString(r, "browser"); browser != "" {
- payload["browser"] = browser
- }
x, y, hasXY := resolveXY(r)
if hasXY {
@@ -172,7 +169,7 @@ func handleAction(c *Client, kind string) func(context.Context, mcp.CallToolRequ
payload["value"] = value
}
- body, code, err := c.Post(ctx, "/action", payload)
+ body, code, err := c.Post(ctx, routedPathWithBody(r, "/action", payload), payload)
if err != nil {
return mcp.NewToolResultError(err.Error()), nil
}
@@ -210,10 +207,7 @@ func handleKeyboardText(c *Client, kind string) func(context.Context, mcp.CallTo
if tabID := optString(r, "tabId"); tabID != "" {
payload["tabId"] = tabID
}
- if browser := optString(r, "browser"); browser != "" {
- payload["browser"] = browser
- }
- body, code, err := c.Post(ctx, "/action", payload)
+ body, code, err := c.Post(ctx, routedPathWithBody(r, "/action", payload), payload)
if err != nil {
return mcp.NewToolResultError(err.Error()), nil
}
@@ -231,10 +225,7 @@ func handleKeyboardKey(c *Client, kind string) func(context.Context, mcp.CallToo
if tabID := optString(r, "tabId"); tabID != "" {
payload["tabId"] = tabID
}
- if browser := optString(r, "browser"); browser != "" {
- payload["browser"] = browser
- }
- body, code, err := c.Post(ctx, "/action", payload)
+ body, code, err := c.Post(ctx, routedPathWithBody(r, "/action", payload), payload)
if err != nil {
return mcp.NewToolResultError(err.Error()), nil
}
diff --git a/internal/mcp/handlers_navigation.go b/internal/mcp/handlers_navigation.go
index 641733f3..dbd5e45a 100644
--- a/internal/mcp/handlers_navigation.go
+++ b/internal/mcp/handlers_navigation.go
@@ -27,10 +27,7 @@ func handleNavigate(c *Client) func(context.Context, mcp.CallToolRequest) (*mcp.
if tabID != "" {
payload["tabId"] = tabID
}
- if browser := optString(r, "browser"); browser != "" {
- payload["browser"] = browser
- }
- body, code, err := c.Post(ctx, "/navigate", payload)
+ body, code, err := c.Post(ctx, routedPathWithBody(r, "/navigate", payload), payload)
if err != nil {
return mcp.NewToolResultError(err.Error()), nil
}
@@ -100,10 +97,7 @@ func handleSnapshot(c *Client) func(context.Context, mcp.CallToolRequest) (*mcp.
if v, ok := optBool(r, "noAnimations"); ok && v {
q.Set("noAnimations", "true")
}
- if browser := optString(r, "browser"); browser != "" {
- q.Set("browser", browser)
- }
- body, code, err := c.Get(ctx, "/snapshot", q)
+ body, code, err := c.Get(ctx, "/snapshot", routedQuery(r, q))
if err != nil {
return mcp.NewToolResultError(err.Error()), nil
}
@@ -115,16 +109,12 @@ func handleFrame(c *Client) func(context.Context, mcp.CallToolRequest) (*mcp.Cal
return func(ctx context.Context, r mcp.CallToolRequest) (*mcp.CallToolResult, error) {
tabID := optString(r, "tabId")
target := optString(r, "target")
- browser := optString(r, "browser")
if strings.TrimSpace(target) == "" {
q := url.Values{}
if tabID != "" {
q.Set("tabId", tabID)
}
- if browser != "" {
- q.Set("browser", browser)
- }
- body, code, err := c.Get(ctx, "/frame", q)
+ body, code, err := c.Get(ctx, "/frame", routedQuery(r, q))
if err != nil {
return mcp.NewToolResultError(err.Error()), nil
}
@@ -135,10 +125,7 @@ func handleFrame(c *Client) func(context.Context, mcp.CallToolRequest) (*mcp.Cal
if tabID != "" {
payload["tabId"] = tabID
}
- if browser != "" {
- payload["browser"] = browser
- }
- body, code, err := c.Post(ctx, "/frame", payload)
+ body, code, err := c.Post(ctx, routedPath(r, "/frame"), payload)
if err != nil {
return mcp.NewToolResultError(err.Error()), nil
}
@@ -182,13 +169,10 @@ func handleScreenshot(c *Client) func(context.Context, mcp.CallToolRequest) (*mc
if quality, ok := optFloat(r, "quality"); ok {
q.Set("quality", fmt.Sprintf("%d", int(quality)))
}
- if browser := optString(r, "browser"); browser != "" {
- q.Set("browser", browser)
- }
// Always request the inline base64 envelope screenshotResult parses,
// rather than relying on the server's default output mode.
q.Set("output", "inline")
- body, code, err := c.Get(ctx, "/screenshot", q)
+ body, code, err := c.Get(ctx, "/screenshot", routedQuery(r, q))
if err != nil {
return mcp.NewToolResultError(err.Error()), nil
}
@@ -285,11 +269,7 @@ func handleCapture(c *Client) func(context.Context, mcp.CallToolRequest) (*mcp.C
if v, ok := optBool(r, "noAnimations"); ok && v {
q.Set("noAnimations", "true")
}
- if browser := optString(r, "browser"); browser != "" {
- q.Set("browser", browser)
- }
-
- body, code, err := c.Get(ctx, "/capture", q)
+ body, code, err := c.Get(ctx, "/capture", routedQuery(r, q))
if err != nil {
return mcp.NewToolResultError(err.Error()), nil
}
@@ -379,10 +359,7 @@ func handleGetText(c *Client) func(context.Context, mcp.CallToolRequest) (*mcp.C
if v, ok := optInt(r, "maxChars"); ok && v > 0 {
q.Set("maxChars", strconv.Itoa(v))
}
- if browser := optString(r, "browser"); browser != "" {
- q.Set("browser", browser)
- }
- body, code, err := c.Get(ctx, "/text", q)
+ body, code, err := c.Get(ctx, "/text", routedQuery(r, q))
if err != nil {
return mcp.NewToolResultError(err.Error()), nil
}
diff --git a/internal/mcp/handlers_scrape.go b/internal/mcp/handlers_scrape.go
index 39acc782..6055319b 100644
--- a/internal/mcp/handlers_scrape.go
+++ b/internal/mcp/handlers_scrape.go
@@ -50,12 +50,9 @@ func handleScrape(c *Client) func(context.Context, mcp.CallToolRequest) (*mcp.Ca
if list := splitCommaList(optString(r, "exclude")); len(list) > 0 {
payload["excludePatterns"] = list
}
- if browser := optString(r, "browser"); browser != "" {
- payload["browser"] = browser
- }
// A multi-page scrape legitimately runs for minutes; the default MCP
// client timeout is far too short for it.
- body, code, err := c.withTimeout(scrapeMCPTimeout).Post(ctx, "/scrape", payload)
+ body, code, err := c.withTimeout(scrapeMCPTimeout).Post(ctx, routedPathWithBody(r, "/scrape", payload), payload)
if err != nil {
return mcp.NewToolResultError(err.Error()), nil
}
diff --git a/internal/mcp/handlers_wait.go b/internal/mcp/handlers_wait.go
index e2aa3ab1..5515cf78 100644
--- a/internal/mcp/handlers_wait.go
+++ b/internal/mcp/handlers_wait.go
@@ -3,7 +3,6 @@ package mcp
import (
"context"
"fmt"
- "net/url"
"time"
"github.com/mark3labs/mcp-go/mcp"
@@ -90,14 +89,7 @@ func callWaitEndpoint(ctx context.Context, c *Client, r mcp.CallToolRequest, pay
if tabID := optString(r, "tabId"); tabID != "" {
payload["tabId"] = tabID
}
- // Browser routing is query-based (orchestrator.ExtractRequestedBrowser reads
- // r.URL.Query()), so forward `browser` in the query, not the body — a body
- // value would be silently dropped by the router.
- path := "/wait"
- if browser := optString(r, "browser"); browser != "" {
- path += "?browser=" + url.QueryEscape(browser)
- }
- body, code, err := c.Post(ctx, path, payload)
+ body, code, err := c.Post(ctx, routedPath(r, "/wait"), payload)
if err != nil {
return mcp.NewToolResultError(err.Error()), nil
}
diff --git a/internal/mcp/routing.go b/internal/mcp/routing.go
new file mode 100644
index 00000000..49642972
--- /dev/null
+++ b/internal/mcp/routing.go
@@ -0,0 +1,57 @@
+package mcp
+
+import (
+ "net/url"
+ "strings"
+
+ "github.com/mark3labs/mcp-go/mcp"
+)
+
+// Routing parameters decide WHICH PinchTab instance serves a call, and the layer
+// that decides reads the query string only: orchestrator.ExtractRequestedBrowser
+// looks at r.URL.Query() and nothing else. A browser sent solely in the JSON
+// body is therefore served by whichever instance the router defaults to —
+// measured on a two-instance setup, a body-form call landed on the chrome
+// instance while the same value in the query reached the cloak one.
+//
+// These three helpers are the only place that choice is made. A handler asks for
+// its path or its query to be routed and never spells out "browser" itself, so a
+// new tool cannot pick the form that silently mis-routes.
+
+// routedQuery applies the routing parameters to a GET handler's query values.
+func routedQuery(r mcp.CallToolRequest, q url.Values) url.Values {
+ if browser := routingBrowser(r); browser != "" {
+ q.Set("browser", browser)
+ }
+ return q
+}
+
+// routedPath applies the routing parameters to a POST path. Use it for
+// endpoints that do not decode a body browser of their own.
+func routedPath(r mcp.CallToolRequest, path string) string {
+ browser := routingBrowser(r)
+ if browser == "" {
+ return path
+ }
+ sep := "?"
+ if strings.Contains(path, "?") {
+ sep = "&"
+ }
+ return path + sep + "browser=" + url.QueryEscape(browser)
+}
+
+// routedPathWithBody routes the path and also records the browser in the
+// payload, for the endpoints whose own handler decodes a `browser` field and
+// resolves the browser one layer below routing (/navigate, /action, /scrape).
+// Both are needed: the query is what the router reads, and the body is what
+// those endpoints read on a single-instance server, where there is no router.
+func routedPathWithBody(r mcp.CallToolRequest, path string, payload map[string]any) string {
+ if browser := routingBrowser(r); browser != "" {
+ payload["browser"] = browser
+ }
+ return routedPath(r, path)
+}
+
+func routingBrowser(r mcp.CallToolRequest) string {
+ return optString(r, "browser")
+}
diff --git a/internal/mcp/routing_test.go b/internal/mcp/routing_test.go
new file mode 100644
index 00000000..47b08451
--- /dev/null
+++ b/internal/mcp/routing_test.go
@@ -0,0 +1,140 @@
+package mcp
+
+import (
+ "encoding/json"
+ "io"
+ "net/http"
+ "net/http/httptest"
+ "net/url"
+ "testing"
+)
+
+// requiredArgs supplies the minimum each browser-taking tool needs to reach the
+// HTTP call. It doubles as the membership list: a new tool that exposes
+// `browser` fails TestEveryBrowserToolForwardsInTheQuery until it is added here,
+// which is what stops the next tool from picking the body form.
+var browserToolArgs = map[string]map[string]any{
+ "pinchtab_navigate": {"url": "https://example.com"},
+ "pinchtab_snapshot": {},
+ "pinchtab_frame": {"target": "#payment"},
+ "pinchtab_screenshot": {},
+ "pinchtab_capture": {},
+ "pinchtab_get_text": {},
+ "pinchtab_click": {"selector": "#go"},
+ "pinchtab_type": {"selector": "#q", "text": "hello"},
+ "pinchtab_press": {"key": "Enter"},
+ "pinchtab_hover": {"selector": "#go"},
+ "pinchtab_focus": {"selector": "#q"},
+ "pinchtab_select": {"selector": "#s", "value": "one"},
+ "pinchtab_scroll": {},
+ "pinchtab_scroll_into_view": {"selector": "#go"},
+ "pinchtab_fill": {"selector": "#q", "value": "hello"},
+ "pinchtab_keyboard_type": {"text": "hello"},
+ "pinchtab_keyboard_inserttext": {"text": "hello"},
+ "pinchtab_keydown": {"key": "a"},
+ "pinchtab_keyup": {"key": "a"},
+ "pinchtab_wait_for_url": {"url": "https://example.com/done"},
+ "pinchtab_wait_for_load": {"load": "content-loaded"},
+ "pinchtab_wait_for_function": {"fn": "1"},
+ "pinchtab_scrape": {"url": "https://example.com"},
+}
+
+// bodyBrowserEndpoints are the endpoints whose own handler decodes a `browser`
+// field and resolves the browser below the routing layer. On a single-instance
+// server there is no router reading the query, so the body value must stay.
+var bodyBrowserEndpoints = map[string]bool{
+ "/navigate": true,
+ "/action": true,
+ "/scrape": true,
+}
+
+type recordedRequest struct {
+ path string
+ query url.Values
+ body map[string]any
+}
+
+func recordingPinchTab(t *testing.T, seen *recordedRequest) *httptest.Server {
+ t.Helper()
+ return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ seen.path = r.URL.Path
+ seen.query = r.URL.Query()
+ seen.body = nil
+ if raw, err := io.ReadAll(r.Body); err == nil && len(raw) > 0 {
+ var parsed map[string]any
+ if json.Unmarshal(raw, &parsed) == nil {
+ seen.body = parsed
+ }
+ }
+ w.Header().Set("Content-Type", "application/json")
+ _, _ = w.Write([]byte(`{"ok":true}`))
+ }))
+}
+
+// The routing layer reads r.URL.Query() only, so a browser sent in the body is
+// served by whichever instance the router defaults to. Every tool exposing
+// `browser` has to put it in the query; the handlers whose endpoint also reads a
+// body browser send both.
+func TestEveryBrowserToolForwardsInTheQuery(t *testing.T) {
+ tools := 0
+ for _, tool := range allTools() {
+ if _, ok := tool.InputSchema.Properties["browser"]; !ok {
+ continue
+ }
+ tools++
+ args, known := browserToolArgs[tool.Name]
+ if !known {
+ t.Errorf("%s exposes a browser argument but is not covered here; add it to browserToolArgs so its forwarding is pinned", tool.Name)
+ continue
+ }
+
+ t.Run(tool.Name, func(t *testing.T) {
+ var seen recordedRequest
+ srv := recordingPinchTab(t, &seen)
+ defer srv.Close()
+
+ call := map[string]any{"browser": "cloak"}
+ for k, v := range args {
+ call[k] = v
+ }
+ callTool(t, tool.Name, call, srv)
+
+ if seen.path == "" {
+ t.Fatalf("%s never reached the server", tool.Name)
+ }
+ if got := seen.query.Get("browser"); got != "cloak" {
+ t.Errorf("%s sent browser=%q in the query for %s; the router reads the query only, so this call would be served by the default instance (body=%v)",
+ tool.Name, got, seen.path, seen.body)
+ }
+ if bodyBrowserEndpoints[seen.path] {
+ if got, _ := seen.body["browser"].(string); got != "cloak" {
+ t.Errorf("%s dropped the body browser for %s (got %q); that endpoint resolves it itself, and a single-instance server has no router reading the query",
+ tool.Name, seen.path, got)
+ }
+ }
+ })
+ }
+ if tools == 0 {
+ t.Fatal("no tool exposes a browser argument — this test is checking nothing")
+ }
+}
+
+// Without a browser argument nothing is appended, so a single-browser
+// deployment sends exactly the request it sent before.
+func TestRoutingHelpersAreNoOpsWithoutABrowser(t *testing.T) {
+ var seen recordedRequest
+ srv := recordingPinchTab(t, &seen)
+ defer srv.Close()
+
+ callTool(t, "pinchtab_navigate", map[string]any{"url": "https://example.com"}, srv)
+
+ if seen.query.Has("browser") {
+ t.Errorf("navigate sent a browser query parameter with no browser argument: %v", seen.query)
+ }
+ if _, present := seen.body["browser"]; present {
+ t.Errorf("navigate sent a browser body field with no browser argument: %v", seen.body)
+ }
+ if got, _ := seen.body["url"].(string); got != "https://example.com" {
+ t.Errorf("navigate payload lost its url: %v", seen.body)
+ }
+}