#Element Query

React Native 컴포넌트 트리에서 요소를 찾고, 앱 또는 WebView 컨텍스트에서 JavaScript를 실행하는 도구입니다.

#query_selector

React Fiber 트리에서 셀렉터와 일치하는 첫 번째 요소를 찾습니다. compact 텍스트로 UID, 타입, 위치, 크기를 반환합니다.

#Parameters

#Example

// testID로 찾기
{ "tool": "query_selector", "arguments": { "selector": "#submit-btn" } }

// 텍스트 내용으로 찾기
{ "tool": "query_selector", "arguments": { "selector": ":text(\"Login\")" } }

// 계층 구조로 찾기
{ "tool": "query_selector", "arguments": { "selector": "ScrollView > View > Text" } }

// 응답 (compact 텍스트)
View #submit-btn pageX=120 pageY=580 width=200 height=48

#Tips

• 대부분의 인터랙션 워크플로우의 시작점입니다: query_selector → 좌표 획득 → tap.
• 요소 중앙을 탭하려면: x = pageX + width/2, y = pageY + height/2.
• UID는 사전에 알 수 없으므로, 항상 query_selector를 먼저 호출하여 확인해야 합니다.
• compact 출력: JSON 대비 토큰을 대폭 절감합니다. 각 속성은 key=value 형식으로 명시적으로 표시됩니다.

#query_selector_all

셀렉터와 일치하는 모든 요소를 찾습니다. 측정값이 포함된 배열을 반환합니다.

#Parameters

#Example

// 모든 리스트 항목 찾기
{ "tool": "query_selector_all", "arguments": { "selector": "#list-item" } }

// 응답 (compact 텍스트)
# 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

• 요소 하나만 필요할 때는 query_selector를 사용하세요.
• 리스트 순회, 화면에 보이는 항목 개수 확인, 여러 일치 항목 반복 처리 등에 활용합니다.

#evaluate_script

앱의 런타임 컨텍스트에서 JavaScript를 실행합니다. measureView(uid)를 사용하여 탭/스와이프 좌표를 얻을 수 있습니다.

#Parameters

#Example

// UID로 뷰 측정
{
  "tool": "evaluate_script",
  "arguments": {
    "function": "(uid) => measureView(uid)",
    "args": ["submit-btn"]
  }
}

// 등록된 WebView ID 조회
{
  "tool": "evaluate_script",
  "arguments": {
    "function": "() => getRegisteredWebViewIds()"
  }
}

// 앱 전역 변수 접근
{
  "tool": "evaluate_script",
  "arguments": {
    "function": "() => ({ width: globalThis.screen?.width, height: globalThis.screen?.height })"
  }
}

#Tips

• measureView(uid)는 { pageX, pageY, width, height }를 반환하며, 탭 좌표 계산에 유용합니다.
• require()는 사용할 수 없습니다. 전역 변수와 내장 MCP 헬퍼만 접근 가능합니다.
• 함수는 try-catch로 감싸져 WebSocket을 통해 실행됩니다.

#webview_evaluate_script

앱 내 WebView에서 JavaScript를 실행합니다. DOM 조작, 폼 입력, 웹 콘텐츠 읽기 등에 유용합니다.

#Parameters

#Example

// 먼저 WebView ID 조회
{
  "tool": "evaluate_script",
  "arguments": { "function": "() => getRegisteredWebViewIds()" }
}
// 응답: ["webview-0"]

// WebView 내부의 버튼 클릭
{
  "tool": "webview_evaluate_script",
  "arguments": {
    "webViewId": "webview-0",
    "script": "document.querySelector('#login-btn').click(); 'clicked'"
  }
}

#Tips

• WebView DOM 인터랙션에는 tap보다 이 도구를 사용하세요 -- 더 빠르고 안정적입니다.
• WebView는 babel 플러그인에 의해 자동 등록됩니다. getRegisteredWebViewIds()로 사용 가능한 ID를 확인하세요.
• 결과를 반환하려면 스크립트가 값으로 평가되어야 합니다. 문자열이나 표현식으로 끝내세요.

#get_component_source

셀렉터 또는 take_snapshot의 uid로 컴포넌트를 지정하면, React의 _debugStack과 Metro 소스맵으로 원본 파일·라인·컬럼을 반환합니다. "이 컴포넌트를 에디터에서 열기"나 토큰 절약을 위한 코드 탐색에 유용합니다.

#Parameters

#Example

// 셀렉터로 조회
{
  "tool": "get_component_source",
  "arguments": { "selector": "#SubmitButton" }
}

// 스냅샷 uid로 조회
{
  "tool": "get_component_source",
  "arguments": { "uid": "header>Text:0" }
}

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

#Tips

• 앱 소스가 우선됩니다. 앱 파일이 있으면 node_modules/react, node_modules/react-native, 런타임 프레임은 건너뜁니다.
• AI나 사용자가 "이 컴포넌트 수정해줘"라고 할 때 코드베이스 검색 없이 해당 파일·라인으로 이동할 수 있습니다.