#Element Query

Tools for finding elements in the React Native component tree and executing JavaScript in the app or WebView context.

#query_selector

Find the first element matching a selector in the React Fiber tree. Returns compact text with UID, type, and position (pageX, pageY, width, height).

#Parameters

#Example

// Find by testID
{ "tool": "query_selector", "arguments": { "selector": "#submit-btn" } }

// Find by text content
{ "tool": "query_selector", "arguments": { "selector": ":text(\"Login\")" } }

// Find by hierarchy
{ "tool": "query_selector", "arguments": { "selector": "ScrollView > View > Text" } }

// Response (compact text)
View #submit-btn pageX=120 pageY=580 width=200 height=48

#Tips

• This is the entry point for most interaction workflows: query_selector → get coordinates → tap.
• Tap the center of an element: x = pageX + width/2, y = pageY + height/2.
• UIDs are not known ahead of time — always call query_selector first to discover them.
• Compact output: Significant token savings compared to JSON. Each attribute uses explicit key=value format.

#query_selector_all

Find all elements matching a selector. Returns an array with measurements.

#Parameters

#Example

// Find all list items
{ "tool": "query_selector_all", "arguments": { "selector": "#list-item" } }

// Response (compact text)
# 2 matches
- View #list-item-0 pageX=0 pageY=100 width=375 height=60
- View #list-item-1 pageX=0 pageY=160 width=375 height=60

#Tips

• Prefer query_selector when you only need one element.
• Use this to enumerate lists, count visible items, or iterate over multiple matches.

#evaluate_script

Run JavaScript in the app's runtime context. Use measureView(uid) to get tap/swipe coordinates.

#Parameters

#Example

// Measure a view by UID
{
  "tool": "evaluate_script",
  "arguments": {
    "function": "(uid) => measureView(uid)",
    "args": ["submit-btn"]
  }
}

// Get registered WebView IDs
{
  "tool": "evaluate_script",
  "arguments": {
    "function": "() => getRegisteredWebViewIds()"
  }
}

// Access app globals
{
  "tool": "evaluate_script",
  "arguments": {
    "function": "() => ({ width: globalThis.screen?.width, height: globalThis.screen?.height })"
  }
}

#Tips

• measureView(uid) returns { pageX, pageY, width, height } — useful for computing tap targets.
• require() is not available. Only access globals and the built-in MCP helpers.
• The function is wrapped in a try-catch and executed via WebSocket.

#webview_evaluate_script

Run JavaScript inside an in-app WebView. Useful for DOM manipulation, form filling, or reading web content.

#Parameters

#Example

// Get WebView IDs first
{
  "tool": "evaluate_script",
  "arguments": { "function": "() => getRegisteredWebViewIds()" }
}
// Response: ["webview-0"]

// Click a button inside the WebView
{
  "tool": "webview_evaluate_script",
  "arguments": {
    "webViewId": "webview-0",
    "script": "document.querySelector('#login-btn').click(); 'clicked'"
  }
}

#Tips

• Prefer this over tap for WebView DOM interactions — it's faster and more reliable.
• WebViews are auto-registered by the babel plugin. Use getRegisteredWebViewIds() to discover available IDs.
• The script must evaluate to a value to return a result. End with a string or expression.

#get_component_source

Resolve a component to its source location (file path, line, column) using React's _debugStack and the Metro source map. Use a selector or a uid from take_snapshot. Useful for "open this component in the editor" or token-efficient code navigation.

#Parameters

#Example

// By selector
{
  "tool": "get_component_source",
  "arguments": { "selector": "#SubmitButton" }
}

// By uid from snapshot
{
  "tool": "get_component_source",
  "arguments": { "uid": "header>Text:0" }
}

// Response
{
  "filePath": "/app/src/components/SubmitButton.tsx",
  "lineNumber": 42,
  "columnNumber": 10
}

#Tips

• App source is preferred: frames from node_modules/react, node_modules/react-native, or the runtime are skipped when an app file is available.
• Use this to jump to the right file and line when an AI or user asks to "edit this component" without searching the codebase.