Add token-optimized a11y snapshot mode (like Playwright MCP)

[MathiasPaulenko]

Add token-optimized a11y snapshot mode (like Playwright MCP)

Context

Playwright MCP's accessibility snapshots are optimized for LLM token consumption (~200-400 tokens per snapshot). WaveXisMCP's wavexis_a11y_snapshot already filters InlineTextBox and LineBreak nodes and uses compact refs (el-1, el-2), but it's not as aggressive as it could be.

Adding a compact mode would reduce token usage by 40-60%, making it cheaper to use with LLMs that charge per token.

What needs to happen

In wavexis-mcp

1. Add profile parameter to A11ySnapshotInput:

   • "full" (default) — current behavior, includes all nodes
   • "balanced" — skip invisible elements, truncate long names, strip node_id/backend_node_id
   • "light" — only interactive elements (buttons, links, inputs, comboboxes), strip all metadata except role + name + ref

2. Add max_depth parameter (default: unlimited, suggested: 10 for balanced, 5 for light)

3. Add truncate_names_at parameter (default: unlimited, suggested: 50 chars)

Implementation in wavexis_mcp/tools/a11y.py

• Extend _format_a11y_tree() to accept profile/depth/truncate parameters
• For "light" profile: skip nodes with roles like text, generic, paragraph, heading (unless they have children that are interactive)
• For "balanced" profile: skip nodes with display:none or visibility:hidden (check via node.get("ignored") if available from CDP)
• Truncate name field to truncate_names_at chars with ... suffix
• Strip node_id and backend_node_id from output in balanced/light modes

Expected token savings

Profile	Nodes (typical page)	Est. tokens	vs current
full	~200	~2000	baseline
balanced	~120	~800	-60%
light	~40	~200	-90%

Example

# Full (current default)
wavexis_a11y_snapshot(session_id="abc")
-> {"snapshot": [{"ref": "el-1", "role": "webarea", "name": "Example", "level": 0, "node_id": 42, "backend_node_id": 1001, "children": [...]}]}

# Light (new)
wavexis_a11y_snapshot(session_id="abc", profile="light")
-> {"snapshot": [{"ref": "el-3", "role": "button", "name": "Login", "level": 2}, {"ref": "el-5", "role": "link", "name": "Sign up", "level": 2}]}

Getting started

1. Read wavexis_mcp/tools/a11y.py to understand the current implementation
2. Read wavexis_mcp/models.py to find A11ySnapshotInput
3. Add the new fields to the model
4. Extend _format_a11y_tree() with the filtering logic
5. Add tests in tests/unit/test_a11y.py (or equivalent)
6. Update docs/tools/a11y.md with the new parameters

References

• Playwright MCP a11y snapshot approach
• mcp-playwright-browser capture profiles
• Our a11y tool docs