High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
feat(mcp): add pinchtab_console and pinchtab_errors tools and document the console/errors channels in the shipped skills, so an agent can see why a page failed (PIN-294)
Luigi Agosti466d2a3ecd59
diff --git a/docs/mcp.md b/docs/mcp.mdindex cb241e8b..858299d1 100644--- a/docs/mcp.md+++ b/docs/mcp.md@@ -114,7 +114,7 @@ PINCHTAB_TOKEN=<that-host-token> pinchtab --server http://remote:9867 mcp## Available Tools-PinchTab currently exposes 36 tools:+PinchTab currently exposes 38 tools:- Navigation: 9- Interaction: 8@@ -125,6 +125,7 @@ PinchTab currently exposes 36 tools:- Tab management: 5- Wait utilities: 1- Network: 5+- Diagnostics: 2- Dialog: 1### Navigation@@ -189,6 +190,11 @@ PinchTab currently exposes 36 tools:- `pinchtab_network_route`- `pinchtab_network_unroute`+### Diagnostics++- `pinchtab_console` — read (or `clear`) the tab's browser console logs+- `pinchtab_errors` — read (or `clear`) the tab's uncaught JavaScript exceptions; check this when a snapshot looks healthy but actions do nothing+### Dialog- `pinchtab_dialog`diff --git a/internal/mcp/handlers.go b/internal/mcp/handlers.goindex 211924f4..a06c3c68 100644--- a/internal/mcp/handlers.go+++ b/internal/mcp/handlers.go@@ -63,6 +63,9 @@ func rawHandlerMap(c *Client) map[string]func(context.Context, mcp.CallToolReque"pinchtab_network_route": handleNetworkRoute(c),"pinchtab_network_unroute": handleNetworkUnroute(c),+ "pinchtab_console": handleConsole(c),+ "pinchtab_errors": handleErrors(c),+"pinchtab_record": handleRecord(c),"pinchtab_dialog": handleDialog(c),diff --git a/internal/mcp/handlers_diagnostics.go b/internal/mcp/handlers_diagnostics.gonew file mode 100644index 00000000..665b7a78--- /dev/null+++ b/internal/mcp/handlers_diagnostics.go@@ -0,0 +1,43 @@+package mcp++import (+ "context"+ "net/url"++ "github.com/mark3labs/mcp-go/mcp"+)++// handleConsole and handleErrors mirror the CLI's `pinchtab console [--clear]` and+// `pinchtab errors [--clear]`: a GET reads the channel, and the optional clear+// boolean routes to the POST clear endpoint instead. resultFromBytes is the shared+// funnel — /console and /errors are channels whose payload IS failures, and neither+// carries a top-level counting shape, so an error-laden body reaches the agent as a+// successful result rather than being misread as a failed call.+func handleConsole(c *Client) func(context.Context, mcp.CallToolRequest) (*mcp.CallToolResult, error) {+ return diagnosticsHandler(c, "/console")+}++func handleErrors(c *Client) func(context.Context, mcp.CallToolRequest) (*mcp.CallToolResult, error) {+ return diagnosticsHandler(c, "/errors")+}++func diagnosticsHandler(c *Client, path string) func(context.Context, mcp.CallToolRequest) (*mcp.CallToolResult, error) {+ return func(ctx context.Context, r mcp.CallToolRequest) (*mcp.CallToolResult, error) {+ q := url.Values{}+ if tabID := optString(r, "tabId"); tabID != "" {+ q.Set("tabId", tabID)+ }+ if clear, ok := optBool(r, "clear"); ok && clear {+ body, code, err := c.Post(ctx, path+"/clear?"+q.Encode(), nil)+ if err != nil {+ return mcp.NewToolResultError(err.Error()), nil+ }+ return resultFromBytes(body, code)+ }+ body, code, err := c.Get(ctx, path, q)+ if err != nil {+ return mcp.NewToolResultError(err.Error()), nil+ }+ return resultFromBytes(body, code)+ }+}diff --git a/internal/mcp/handlers_diagnostics_test.go b/internal/mcp/handlers_diagnostics_test.gonew file mode 100644index 00000000..070efc97--- /dev/null+++ b/internal/mcp/handlers_diagnostics_test.go@@ -0,0 +1,92 @@+package mcp++import (+ "encoding/json"+ "net/http"+ "net/http/httptest"+ "strings"+ "testing"+)++// The two tools must be advertised in tools/list AND have a handler, or the MCP+// surface and the route catalogue drift apart on exactly the pair this card adds.+func TestConsoleAndErrorToolsAreRegistered(t *testing.T) {+ declared := map[string]bool{}+ for _, tool := range allTools() {+ declared[tool.Name] = true+ }+ handlers := rawHandlerMap(NewClient("http://example.invalid", ""))++ for _, name := range []string{"pinchtab_console", "pinchtab_errors"} {+ if !declared[name] {+ t.Errorf("%s is not in allTools(), so tools/list does not advertise it", name)+ }+ if _, ok := handlers[name]; !ok {+ t.Errorf("%s has no handler, so NewServer panics on it", name)+ }+ }+}++// A page that throws produces an /errors payload that is ALL failures. /errors is a+// channel whose content is failures, so the MCP call must report success whenever the+// HTTP call succeeded — never keying failure off the error entries in the body. If the+// funnel misread this, the one channel that says why the page died would reach the agent+// as an error, and the agent would learn nothing.+func TestErrorsToolReturnsSuccessCarryingTheErrorText(t *testing.T) {+ const thrown = "Uncaught TypeError: Cannot read properties of null (reading 'x')"+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ if r.URL.Path != "/errors" || r.Method != http.MethodGet {+ t.Errorf("unexpected request: %s %s", r.Method, r.URL.Path)+ }+ w.Header().Set("Content-Type", "application/json")+ _ = json.NewEncoder(w).Encode(map[string]any{+ "tabId": "tab1",+ "errors": []map[string]any{+ {"timestamp": "2026-09-03T08:46:59Z", "message": thrown, "url": "http://localhost:18777/", "line": 8, "column": 59},+ },+ })+ }))+ defer srv.Close()++ result := callTool(t, "pinchtab_errors", map[string]any{"tabId": "tab1"}, srv)++ if result.IsError {+ t.Fatalf("a payload full of errors was reported as a failed call; /errors content IS failures and the call succeeded: %s", resultText(t, result))+ }+ if text := resultText(t, result); !strings.Contains(text, thrown) {+ t.Fatalf("successful result does not carry the error text the agent needs: %q", text)+ }+}++// The same contract for /console, and the clear flag must route to the POST clear+// endpoint rather than the GET read — the CLI's `pinchtab console --clear` shape.+func TestConsoleToolReadsAndClears(t *testing.T) {+ var seen []string+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ seen = append(seen, r.Method+" "+r.URL.Path)+ w.Header().Set("Content-Type", "application/json")+ if strings.HasSuffix(r.URL.Path, "/clear") {+ _ = json.NewEncoder(w).Encode(map[string]any{"cleared": true})+ return+ }+ _ = json.NewEncoder(w).Encode(map[string]any{+ "tabId": "tab1",+ "console": []map[string]any{{"timestamp": "2026-09-03T08:46:59Z", "level": "error", "message": "boom"}},+ })+ }))+ defer srv.Close()++ read := callTool(t, "pinchtab_console", map[string]any{"tabId": "tab1"}, srv)+ if read.IsError || !strings.Contains(resultText(t, read), "boom") {+ t.Fatalf("console read did not succeed carrying the log: %s", resultText(t, read))+ }++ cleared := callTool(t, "pinchtab_console", map[string]any{"tabId": "tab1", "clear": true}, srv)+ if cleared.IsError {+ t.Fatalf("console clear reported failure: %s", resultText(t, cleared))+ }++ if len(seen) != 2 || seen[0] != "GET /console" || seen[1] != "POST /console/clear" {+ t.Fatalf("clear did not route to the POST clear endpoint: %v", seen)+ }+}diff --git a/internal/mcp/server_test.go b/internal/mcp/server_test.goindex d54c0097..36ff1e9f 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) != 36 {- t.Errorf("expected 36 tools, got %d — if a tool was added or removed, update this count and the totals in docs/mcp.md", len(tools))+ if len(tools) != 38 {+ t.Errorf("expected 38 tools, got %d — if a tool was added or removed, update this count and the totals in docs/mcp.md", len(tools))}}diff --git a/internal/mcp/testdata/preamble_budget.json b/internal/mcp/testdata/preamble_budget.jsonindex f97974f1..74a65ba6 100644--- a/internal/mcp/testdata/preamble_budget.json+++ b/internal/mcp/testdata/preamble_budget.json@@ -2,22 +2,22 @@{"surface": "mcp:allTools","minBytes": 18092,- "maxBytes": 36185,- "takenOn": "2026-08-22",- "commit": "15af50c1"+ "maxBytes": 37504,+ "takenOn": "2026-09-03",+ "commit": "8a12cd4a"},{"surface": "skills/pinchtab-mcp/SKILL.md","minBytes": 6789,- "maxBytes": 14109,+ "maxBytes": 14581,"takenOn": "2026-09-03",- "commit": "a0884888"+ "commit": "8a12cd4a"},{"surface": "skills/pinchtab/SKILL.md","minBytes": 10176,- "maxBytes": 20688,+ "maxBytes": 21238,"takenOn": "2026-09-03",- "commit": "a0884888"+ "commit": "8a12cd4a"}]diff --git a/internal/mcp/tools.go b/internal/mcp/tools.goindex 96321cfb..e4b35190 100644--- a/internal/mcp/tools.go+++ b/internal/mcp/tools.go@@ -306,6 +306,17 @@ func allTools() []mcp.Tool {mcp.WithString("pattern", mcp.Description("Pattern to remove (omit to clear all rules)")),),+ mcp.NewTool("pinchtab_console",+ mcp.WithDescription("Read the tab's captured browser console logs (console.log/warn/error and friends). Check this when a page looks healthy in the snapshot but does not respond to actions — the log often says why. A payload full of error-level logs is still a successful call."),+ tabIDParam(),+ mcp.WithBoolean("clear", mcp.Description("Clear the tab's console log buffer instead of reading it")),+ ),+ mcp.NewTool("pinchtab_errors",+ mcp.WithDescription("Read the tab's uncaught JavaScript errors (exceptions the page threw). Check this when a snapshot looks right but clicks do nothing: a script that died on load leaves the DOM present and the handlers unwired. A payload full of errors is still a successful call."),+ tabIDParam(),+ mcp.WithBoolean("clear", mcp.Description("Clear the tab's error buffer instead of reading it")),+ ),+mcp.NewTool("pinchtab_record",mcp.WithDescription("Record browser activity; 'action' picks which. action='start': start recording — requires security.allowScreencast, and GIF works without ffmpeg while WebM/MP4 need ffmpeg. action='stop': stop recording and save the encoded file; encoding may take a while for long recordings. action='status': check active recording status (format, fps, duration, frame count)."),mcp.WithString("action", mcp.Required(), mcp.Enum("start", "stop", "status"), mcp.Description("Recording action to take")),diff --git a/plugins/grok/skills/pinchtab-mcp/SKILL.md b/plugins/grok/skills/pinchtab-mcp/SKILL.mdindex 4af81551..364050af 100644--- a/plugins/grok/skills/pinchtab-mcp/SKILL.md+++ b/plugins/grok/skills/pinchtab-mcp/SKILL.md@@ -363,3 +363,6 @@ For these, use the pinchtab CLI or HTTP API directly.| `invalid URL` | Missing scheme | Include `http://` or `https://` || Element not found | Page not loaded | Use `pinchtab_wait(for="selector", value=…)` || Action seems ignored | Page changed mid-action | Re-snapshot, use fresh refs |+| Snapshot looks right but clicks do nothing | A script threw on load, leaving the DOM present and handlers unwired | Call `pinchtab_errors()` (and `pinchtab_console()`) — they report why the page died |++`pinchtab_console(clear=…)` and `pinchtab_errors(clear=…)` read the tab's console logs and uncaught JS exceptions. A result full of errors is a **successful** call — that payload is the diagnosis, not a tool failure — so read it rather than retrying blind.diff --git a/plugins/grok/skills/pinchtab/SKILL.md b/plugins/grok/skills/pinchtab/SKILL.mdindex a230d46a..66c2f1f0 100644--- a/plugins/grok/skills/pinchtab/SKILL.md+++ b/plugins/grok/skills/pinchtab/SKILL.md@@ -248,8 +248,12 @@ pinchtab pdf [-o path.pdf] [--landscape]pinchtab record start out.gif [--fps 5] [--scale 1.0] # .gif/.webm/.mp4; requires security.allowScreencast; .gif works without ffmpeg, .webm/.mp4 need ffmpegpinchtab record stop # stop, encode, and save to path given at startpinchtab record status # check active recording+pinchtab console [--clear] # browser console logs for the tab+pinchtab errors [--clear] # uncaught JS exceptions the page threw```+**When a snapshot looks right but the page does not respond to actions, check `pinchtab errors` (and `pinchtab console`) before retrying.** A script that threw on load leaves the DOM present and the handlers unwired, so clicks land on nothing; the error log is the only channel that says so. A buffer full of errors is the useful answer, not a failed command.+### Site review```bashdiff --git a/plugins/grok/skills/pinchtab/references/commands.md b/plugins/grok/skills/pinchtab/references/commands.mdindex 119b7187..bb5dbd16 100644--- a/plugins/grok/skills/pinchtab/references/commands.md+++ b/plugins/grok/skills/pinchtab/references/commands.md@@ -253,6 +253,25 @@ pinchtab network <requestId> --body> **Sensitive data:** Request bodies and exports may contain cookies, tokens, or personal data. Obtain explicit approval before inspecting bodies or exporting data, keep redaction enabled, and delete artifacts after use.+### `pinchtab console`+Read the tab's captured browser console logs (`console.log`/`warn`/`error`). Check this when a page looks healthy in the snapshot but does not respond to actions — the log often says why.++```bash+pinchtab console+pinchtab console --limit 20+pinchtab console --clear # empty the buffer instead of reading it+```++### `pinchtab errors`+Read the tab's **uncaught JavaScript errors** — exceptions the page threw. A script that dies on load leaves the DOM present and the click handlers unwired, so the snapshot looks right while nothing works.++```bash+pinchtab errors+pinchtab errors --clear # empty the buffer instead of reading it+```++A buffer full of errors is the normal, useful case — it is what tells you the page failed, not an error in the command itself.+---## State Commandsdiff --git a/skills/pinchtab-mcp/SKILL.md b/skills/pinchtab-mcp/SKILL.mdindex 4af81551..364050af 100644--- a/skills/pinchtab-mcp/SKILL.md+++ b/skills/pinchtab-mcp/SKILL.md@@ -363,3 +363,6 @@ For these, use the pinchtab CLI or HTTP API directly.| `invalid URL` | Missing scheme | Include `http://` or `https://` || Element not found | Page not loaded | Use `pinchtab_wait(for="selector", value=…)` || Action seems ignored | Page changed mid-action | Re-snapshot, use fresh refs |+| Snapshot looks right but clicks do nothing | A script threw on load, leaving the DOM present and handlers unwired | Call `pinchtab_errors()` (and `pinchtab_console()`) — they report why the page died |++`pinchtab_console(clear=…)` and `pinchtab_errors(clear=…)` read the tab's console logs and uncaught JS exceptions. A result full of errors is a **successful** call — that payload is the diagnosis, not a tool failure — so read it rather than retrying blind.diff --git a/skills/pinchtab/SKILL.md b/skills/pinchtab/SKILL.mdindex a230d46a..66c2f1f0 100644--- a/skills/pinchtab/SKILL.md+++ b/skills/pinchtab/SKILL.md@@ -248,8 +248,12 @@ pinchtab pdf [-o path.pdf] [--landscape]pinchtab record start out.gif [--fps 5] [--scale 1.0] # .gif/.webm/.mp4; requires security.allowScreencast; .gif works without ffmpeg, .webm/.mp4 need ffmpegpinchtab record stop # stop, encode, and save to path given at startpinchtab record status # check active recording+pinchtab console [--clear] # browser console logs for the tab+pinchtab errors [--clear] # uncaught JS exceptions the page threw```+**When a snapshot looks right but the page does not respond to actions, check `pinchtab errors` (and `pinchtab console`) before retrying.** A script that threw on load leaves the DOM present and the handlers unwired, so clicks land on nothing; the error log is the only channel that says so. A buffer full of errors is the useful answer, not a failed command.+### Site review```bashdiff --git a/skills/pinchtab/references/commands.md b/skills/pinchtab/references/commands.mdindex 119b7187..bb5dbd16 100644--- a/skills/pinchtab/references/commands.md+++ b/skills/pinchtab/references/commands.md@@ -253,6 +253,25 @@ pinchtab network <requestId> --body> **Sensitive data:** Request bodies and exports may contain cookies, tokens, or personal data. Obtain explicit approval before inspecting bodies or exporting data, keep redaction enabled, and delete artifacts after use.+### `pinchtab console`+Read the tab's captured browser console logs (`console.log`/`warn`/`error`). Check this when a page looks healthy in the snapshot but does not respond to actions — the log often says why.++```bash+pinchtab console+pinchtab console --limit 20+pinchtab console --clear # empty the buffer instead of reading it+```++### `pinchtab errors`+Read the tab's **uncaught JavaScript errors** — exceptions the page threw. A script that dies on load leaves the DOM present and the click handlers unwired, so the snapshot looks right while nothing works.++```bash+pinchtab errors+pinchtab errors --clear # empty the buffer instead of reading it+```++A buffer full of errors is the normal, useful case — it is what tells you the page failed, not an error in the command itself.+---## State Commands