Live DOM Queries

Gasoline is an open-source MCP server with a query_dom tool that lets AI coding assistants query the live DOM using CSS selectors — without you copying HTML or taking screenshots.

The Problem

When your AI asks “what does the button say?” or “is the modal visible?”, you have to inspect the page manually and describe what you see. Screenshots help but don’t give your AI structured data it can reason about.

With DOM queries, your AI just asks the browser directly.

How It Works

1. Your AI calls query_dom with a CSS selector
2. MCP server forwards the query to the extension
3. Extension runs the selector against the live page
4. Results returned: tag, attributes, text, children

// AI asks: "What's in the error banner?"
{
  "selector": ".error-banner"
}

// Response:
{
  "elements": [{
    "tag": "div",
    "className": "error-banner visible",
    "textContent": "Invalid email address",
    "attributes": {
      "role": "alert",
      "aria-live": "polite"
    }
  }]
}

Example Queries

• query_dom("nav") — navigation structure
• query_dom(".error-message") — visible error messages
• query_dom("[data-testid='user-menu']") — test-id elements
• query_dom("form input[type='email']") — form fields
• query_dom(".spinner") — check if loading is visible

What Gets Returned

For each matching element:

Field	Description
Tag name	div, button, input, etc.
Class list	Current CSS classes
Text content	Visible text
Attributes	id, role, aria-, data-, type, value
Computed state	Visibility, disabled status
Children	Child elements (limited depth)

get_page_info

Get high-level page context without a selector:

{
  "url": "http://localhost:3000/dashboard",
  "title": "Dashboard - MyApp",
  "viewport": { "width": 1440, "height": 900 }
}

Use Cases

Verifying UI State

“Is the loading spinner showing?”

Your AI queries .spinner and knows instantly — no screenshot needed.

Debugging Form Issues

“Why won’t the form submit?”

Your AI queries the submit button to check if it’s disabled, and the form inputs for validation states.

Checking Rendered Data

“What items are in the list?”

Your AI queries .list-item and sees all rendered items with their content.

Confirming Fixes

After applying a fix, your AI queries the relevant element to verify the change took effect without you refreshing and checking manually.

Error Message Inspection

“What error is the user seeing?”

Your AI queries [role="alert"] or .error-message and reads the exact text — then correlates with console errors and network failures to diagnose the root cause.