---
name: snapshot-query
description: Query and analyze snapshot log files generated by cursor-ide-browser. Use when (1) Working with cursor-ide-browser snapshots, (2) Need to find element references (ref) for browser automation, (3) Analyzing page structure from accessibility snapshots, (4) Querying snapshot files for specific elements, (5) Integrating snapshot queries into browser automation workflows, (6) Using MCP tools to query snapshot files programmatically
metadata:
  short-description: Query cursor-ide-browser snapshot files
---

## Installation

Run without installation using `uvx`:
```bash
uvx snapshot-query <file_path> <command> [args]
```

Or install via pip:
```bash
pip install snapshot-query
```

## Core Concepts

### Snapshot Files

Snapshot files are YAML-formatted accessibility tree structures saved by cursor-ide-browser:
- **Location**: `C:\Users\{username}\.cursor\browser-logs\`
- **Format**: `snapshot-{ISO 8601 timestamp}.log`
- **Structure**: Tree of elements with `role`, `ref`, `name`, and `children`

### Element Properties

- **`role`**: Element type (button, link, textbox, etc.)
- **`ref`**: Unique reference identifier (used for browser interactions)
- **`name`**: Element text/label (optional)
- **`children`**: Child elements (optional)

## Quick Start

Find button reference for browser automation:
```bash
browser_snapshot()  # Get page snapshot
uvx snapshot-query snapshot.log find-name "search"  # Find element
# Extract ref from output, then use: browser_click(element="Search", ref="ref-xxxxx")
```

Find input field:
```bash
uvx snapshot-query snapshot.log find-role textbox
# Or: uvx snapshot-query snapshot.log find-name "username"
```

List all interactive elements:
```bash
uvx snapshot-query snapshot.log interactive
```

## Commands

**Basic queries:**
- `find-name "text"` - Fuzzy search by name
- `find-name-exact "text"` - Exact match
- `find-name-bm25 "text" [top_k]` - Relevance-ranked (BM25)
- `find-role button` - Find by role
- `find-ref ref-xxxxx` - Find by reference ID

**Advanced queries:**
- `find-grep "pattern" [field]` - Regular expression (field: name/role/ref)
- `find-selector "selector"` - CSS/jQuery selector (e.g., `button[name='search']`)
- `find-text "text"` - Text content search

**Utilities:**
- `interactive` - List interactive elements
- `count` - Count by type
- `path ref-xxxxx` - Show element path
- `all-refs` - List all refs

## Python API

```python
from snapshot_query import SnapshotQuery

query = SnapshotQuery("snapshot.log")
buttons = query.find_by_role("button")
element = query.find_by_ref("ref-xxxxx")

# Advanced: BM25, CSS selectors, regex
results = query.find_by_name_bm25("search", top_k=5)
results = query.find_by_selector("button[name='search']")
results = query.find_by_regex("^search$", field="name")
```

## MCP Integration

Configure in `~/.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "snapshot-query": {
      "command": "snapshot-query-mcp",
      "args": []
    }
  }
}
```

Available tools: `find_by_name`, `find_by_name_bm25`, `find_by_role`, `find_by_ref`, `find_by_text`, `find_by_regex`, `find_by_selector`, `find_interactive_elements`, `count_elements`, `get_element_path`, `extract_all_refs`

## Best Practices

- Prefer `find-name-bm25` over `find-name` for relevance ranking
- Use CSS selectors for flexible querying: `find-selector "button[name='search']"`
- Refs change with each snapshot - get a new snapshot before using refs
- Use `path` command to understand element hierarchy

## Common Patterns

Find and click button:
```bash
browser_snapshot()
uvx snapshot-query snapshot.log find-name "submit"
browser_click(element="Submit", ref="ref-from-output")
```

Fill form:
```bash
uvx snapshot-query snapshot.log find-name "username"  # Get ref-username
uvx snapshot-query snapshot.log find-name "password"  # Get ref-password
browser_type(element="Username", ref="ref-username", text="user")
browser_type(element="Password", ref="ref-password", text="pass")
```

## Troubleshooting

- Can't find element: Try `find-name-bm25` or check spelling
- Ref not working: Refs change with each snapshot - get a new snapshot
- Too many results: Use `find-name-bm25` with `top_k` or more specific selectors
