Skip to content

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.md
index 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.go
index 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.go
new file mode 100644
index 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.go
new file mode 100644
index 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.go
index 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.json
index 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.go
index 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.md
index 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.md
index 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 ffmpeg
pinchtab record stop # stop, encode, and save to path given at start
pinchtab 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
```bash
diff --git a/plugins/grok/skills/pinchtab/references/commands.md b/plugins/grok/skills/pinchtab/references/commands.md
index 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 Commands
diff --git a/skills/pinchtab-mcp/SKILL.md b/skills/pinchtab-mcp/SKILL.md
index 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.md
index 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 ffmpeg
pinchtab record stop # stop, encode, and save to path given at start
pinchtab 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
```bash
diff --git a/skills/pinchtab/references/commands.md b/skills/pinchtab/references/commands.md
index 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