Skip to content

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

feat(a11y): add pinchtab_a11y_audit MCP tool wired to /a11y/audit (PIN-397)

Luigi Agosti6d82db269d0f
diff --git a/docs/mcp.md b/docs/mcp.md
index b29b6858..d1e06c42 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 42 tools:
+PinchTab currently exposes 43 tools:
- Navigation: 9
- Interaction: 8
@@ -126,7 +126,7 @@ PinchTab currently exposes 42 tools:
- Human handoff: 3
- Wait utilities: 1
- Network: 5
-- Diagnostics: 2
+- Diagnostics: 3
- Dialog: 1
### Navigation
@@ -202,6 +202,7 @@ PinchTab currently exposes 42 tools:
- `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
+- `pinchtab_a11y_audit` — accessibility audit; `engine=axe` runs vendored axe-core in the isolated world and returns ref-mapped violations with WCAG tags and help URLs
### Dialog
diff --git a/internal/mcp/handlers.go b/internal/mcp/handlers.go
index b78857e9..7d95ac94 100644
--- a/internal/mcp/handlers.go
+++ b/internal/mcp/handlers.go
@@ -32,6 +32,7 @@ func rawHandlerMap(c *Client) map[string]func(context.Context, mcp.CallToolReque
"pinchtab_screenshot": handleScreenshot(c),
"pinchtab_capture": handleCapture(c),
"pinchtab_get_text": handleGetText(c),
+ "pinchtab_a11y_audit": handleA11yAudit(c),
"pinchtab_click": handleAction(c, "click"),
"pinchtab_type": handleAction(c, "type"),
diff --git a/internal/mcp/routing_test.go b/internal/mcp/routing_test.go
index a3707afc..1c030071 100644
--- a/internal/mcp/routing_test.go
+++ b/internal/mcp/routing_test.go
@@ -23,6 +23,7 @@ var browserToolArgs = map[string]map[string]any{
"pinchtab_screenshot": {},
"pinchtab_capture": {},
"pinchtab_get_text": {},
+ "pinchtab_a11y_audit": {},
"pinchtab_click": {"selector": "#go"},
"pinchtab_type": {"selector": "#q", "text": "hello"},
"pinchtab_hover": {"selector": "#go"},
diff --git a/internal/mcp/server_test.go b/internal/mcp/server_test.go
index 2b81e19b..c60079f9 100644
--- a/internal/mcp/server_test.go
+++ b/internal/mcp/server_test.go
@@ -19,8 +19,8 @@ func TestNewServer(t *testing.T) {
func TestNewServerRegistersAllTools(t *testing.T) {
_ = NewServer("http://localhost:9867", "")
tools := allTools()
- if len(tools) != 42 {
- t.Errorf("expected 42 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) != 43 {
+ t.Errorf("expected 43 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 43d9880f..d9feec1e 100644
--- a/internal/mcp/testdata/preamble_budget.json
+++ b/internal/mcp/testdata/preamble_budget.json
@@ -2,9 +2,9 @@
{
"surface": "mcp:allTools",
"minBytes": 18092,
- "maxBytes": 40500,
+ "maxBytes": 42200,
"takenOn": "2026-09-12",
- "commit": "1ae3bf87"
+ "commit": "cee8a04b"
},
{
"surface": "skills/pinchtab-mcp/SKILL.md",
diff --git a/internal/mcp/tools.go b/internal/mcp/tools.go
index d5d0836f..dd99ce87 100644
--- a/internal/mcp/tools.go
+++ b/internal/mcp/tools.go
@@ -369,5 +369,6 @@ func allTools() []mcp.Tool {
mcp.WithNumber("timeoutSeconds", mcp.Description("Overall HTTP crawl timeout in seconds (default 60)")),
browserParam(),
),
+ a11yAuditTool(),
}
}
diff --git a/internal/mcp/tools_a11y.go b/internal/mcp/tools_a11y.go
new file mode 100644
index 00000000..f4617391
--- /dev/null
+++ b/internal/mcp/tools_a11y.go
@@ -0,0 +1,45 @@
+package mcp
+
+import (
+ "context"
+ "net/url"
+
+ "github.com/mark3labs/mcp-go/mcp"
+)
+
+// a11yAuditTool declares the pinchtab_a11y_audit tool: an accessibility audit of
+// the current page, native by default or axe-core with engine=axe.
+func a11yAuditTool() mcp.Tool {
+ return mcp.NewTool("pinchtab_a11y_audit",
+ mcp.WithDescription("Audit the current page for accessibility issues. Default 'native' engine scores the accessibility snapshot. engine='axe' runs vendored axe-core in the page's isolated world and returns industry rule ids (image-alt, label, color-contrast, …) with WCAG tags, help URLs, a comparable score, and a snapshot 'ref' for each failing element so you can act on it with pinchtab_click/fill."),
+ tabIDParam(),
+ mcp.WithString("engine", mcp.Description("Audit engine: 'native' (default) or 'axe'. Any other value is a 400.")),
+ mcp.WithString("tags", mcp.Description("axe: comma list of WCAG tags to run, e.g. 'wcag2a,wcag2aa,best-practice'. best-practice runs only when named.")),
+ mcp.WithString("rules", mcp.Description("axe: comma allowlist of rule ids to run; wins over tags.")),
+ mcp.WithBoolean("includeIncomplete", mcp.Description("axe: include rules axe could not decide (the incomplete set)")),
+ browserParam(),
+ )
+}
+
+// handleA11yAudit maps the tool arguments onto GET /a11y/audit query params.
+func handleA11yAudit(c *Client) 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 engine := optString(r, "engine"); engine != "" {
+ q.Set("engine", engine)
+ }
+ if tags := optString(r, "tags"); tags != "" {
+ q.Set("tags", tags)
+ }
+ if rules := optString(r, "rules"); rules != "" {
+ q.Set("rules", rules)
+ }
+ if v, ok := optBool(r, "includeIncomplete"); ok && v {
+ q.Set("includeIncomplete", "true")
+ }
+ return toolResult(c.Get(ctx, "/a11y/audit", routedQuery(r, q)))
+ }
+}