VI · English
RN Agent Observer 2.4.0 es un puente de observabilidad de runtime local para React Native/Expo. La herramienta usa un mismo núcleo TypeScript para CLI y MCP, controla Android a través de ADB/UIAutomator, recibe telemetría de la instrumentación de desarrollo, exporta perfiles de consola/excepciones/heap/CPU de JS mediante el Chrome DevTools Protocol de Metro, captura tráfico de red por petición sin instrumentación, genera comprensión de pantalla con estado/titular/acciones/hallazgos de UI para el agente, proporciona refs de snapshot estables por sesión + diff + replay de auto-grabación, graba vídeo de pantalla, guarda la sesión en SQLite y mantiene imágenes/trazas/árbol de UI como artefactos en disco.
La versión actual completa Android v1 en Windows: 45 herramientas MCP, CLI correspondiente, demo Expo con laboratorios deterministas, diagnóstico heurístico transparente y comparación de imágenes + estructura de UI.
Node.js 22.12 o superior
pnpm 9.6
Android Platform Tools (adb)
Emulador de Android o dispositivo físico con depuración USB habilitada
Compilación de desarrollo de Expo si se necesita telemetría específica de la aplicación
Related MCP server: React Native MCP Server
pnpm install
pnpm check
adb devices -l
pnpm rn-observe --help
pnpm mcp:checkApunta el observer a tu app de Expo/React Native:
$env:RN_OBSERVER_PROJECT_ROOT = 'C:\path\to\expo-app'
$env:RN_OBSERVER_DEVICE_ID = 'emulator-5554'
# Có thể bỏ qua nếu app.json chứa expo.android.package
$env:RN_OBSERVER_APP_ID = 'com.example.app'
pnpm rn-observe launch
pnpm rn-observe observe
pnpm rn-observe understand-screen
pnpm rn-observe ui-model
pnpm rn-observe tap --test-id buy-button
pnpm rn-observe performance
pnpm rn-observe diagnoseLos artefactos y los datos de SQLite se crean en <projectRoot>/.artifacts/; los binarios grandes nunca se incrustan en las respuestas de MCP.
pnpm --filter @rn-agent-observer/demo-expo android -- --device <device-name>La demo incluye PerformanceLab, NetworkLab, RenderLab, AnimationLab, ErrorLab y VisualLab. NetworkLab usa fixtures internos (0/500/2000ms y 503) por lo que no depende de servicios de Internet. PerformanceLab reporta con precisión su tarea JS larga de 100ms mediante instrumentación.
pnpm mcp:check
pnpm mcp:startEl servidor usa stdio. La configuración del cliente y la lista de las 45 herramientas están en docs/protocol.md.
Hay 3 formas para que un agente (OpenCode/Claude Code/Cursor/Codex...) use el observer:
1. Servidor MCP (recomendado — herramientas estructuradas)
{
"mcpServers": {
"rn-agent-observer": {
"command": "node",
"args": [
"C:\\abs\\rn-agent-observer\\packages\\mcp-server\\dist\\server.js"
],
"env": {
"RN_OBSERVER_PROJECT_ROOT": "C:\\path\\to\\expo-app",
"RN_OBSERVER_DEVICE_ID": "emulator-5554"
}
}
}
}2. Instalar como skill (enseña al agente el flujo de depuración mediante comandos)
npx skills add GinzaTech/rn-agent-observerLa skill está en skills/rn-agent-observer/SKILL.md — enseña al agente el ciclo observe -> understand-screen -> reproduce -> diagnose -> fix -> understand-screen -> compare, cómo leer las métricas con honestidad y manejar errores comunes. Después de instalarla, basta con decir "depurar la app X que va lenta" y el agente sabrá usar rn-observe.
3. AGENTS.md (si el agente trabaja directamente en este repo) — ya está en la raíz del repo; los agentes lo leen automáticamente.
Las 3 formas se pueden usar a la vez: la skill/AGENTS.md enseña el workflow, MCP proporciona herramientas llamables directamente.
Android/Windows es el único objetivo compatible de Observer 2.4.0.
ADB no tiene una señal de JS FPS confiable; el campo se devuelve como available: false — los valores nunca se adivinan.
El bloqueo de JS, la ruta, los renders de React y los metadatos de red requieren instrumentación de desarrollo dentro de la app.
Las funciones de DevTools vía CDP (devtools-export, devtools-profile) y el tráfico de red por petición (metro-network) requieren Metro en ejecución y la app conectada a Metro (adb reverse tcp:8081 tcp:8081); no se pueden usar mientras otra sesión de React Native DevTools mantenga la conexión.
reload --fast usa CDP Page.reload (solo JS); recurre automáticamente a force-stop cuando Metro no está disponible.
App sin instrumentación: usa metro-network (CDP), app-state (actividad en primer plano, PID) y device-network (contadores de bytes a nivel de dispositivo, no atribuidos a la app) como evidencia de respaldo.
record (screenrecord) está limitado a 180s por clip por Android.
El trazado de Perfetto está soportado en Android; el análisis profundo de trazas sigue en Perfetto UI/Android Studio.
Los comandos CDP se ponen en cola entre procesos; React Native DevTools externo debe cerrarse porque no usa el bloqueo del observer.
session stop genera automáticamente un replay; los refs de sesión sobreviven a reordenamientos/scroll; las sesiones faltantes producen EVIDENCE_NOT_RECORDED.
understand-screen/MCP understand_screen devuelve la ruta instrumentada cuando está disponible, el estado de pantalla, el titular, las referencias de texto/acciones, los hallazgos de UI y la evidencia de captura/árbol de UI; las llamadas repetidas detectan cargas sin cambios. La clasificación es heurística y los valores de los campos de texto siempre se redactan.
ui-model/MCP runtime_ui_model analiza TSX con el AST de TypeScript para obtener el componente + file:line, y luego lo correlaciona con la instrumentación y el árbol nativo. El resultado distingue rendered, visible/offscreen/hidden/unmounted/flattened-or-unobserved, enabled y canPress con su razón.
El plugin de Babel solo para desarrollo añade automáticamente un testID derivado del código fuente y envuelve onPress; session stop recopila interacciones start/success/error y promueve los taps con testID al replay. Los argumentos de handler, las props y los valores de entrada nunca se registran.
El observer no captura el cuerpo de la red por defecto. La opción de solo desarrollo usa listas blancas fail-closed y debe limitarse solo a fixtures de desarrollo.
RN Agent Observer 2.4.0 is a local runtime observability bridge for React Native/Expo. It uses one shared TypeScript core behind both a CLI and an MCP server, drives Android through ADB/UIAutomator, receives telemetry from development instrumentation, exports console/exceptions/heap/JS CPU profiles through Metro's Chrome DevTools Protocol, captures per-request network traffic without app instrumentation, produces structured screen understanding (state/headline/actions/UI findings) for agents, provides session-stable ref snapshots + diffs + automatically recorded replay scripts, records on-screen video, persists sessions in SQLite, and keeps screenshots/traces/UI trees as on-disk artifacts.
The current release completes Android v1 on Windows: 45 MCP tools, the matching CLI, an Expo demo app with deterministic labs, transparent heuristic diagnosis, and pixel + structural UI comparison.
Node.js 22.12 or newer
pnpm 9.6
Android Platform Tools (adb)
An Android emulator or physical device with USB debugging enabled
An Expo development build if you need app-specific telemetry
pnpm install
pnpm check
adb devices -l
pnpm rn-observe --help
pnpm mcp:checkPoint the observer at your Expo/React Native app:
$env:RN_OBSERVER_PROJECT_ROOT = 'C:\path\to\expo-app'
$env:RN_OBSERVER_DEVICE_ID = 'emulator-5554'
# Optional when app.json contains expo.android.package
$env:RN_OBSERVER_APP_ID = 'com.example.app'
pnpm rn-observe launch
pnpm rn-observe observe
pnpm rn-observe understand-screen
pnpm rn-observe ui-model
pnpm rn-observe tap --test-id buy-button
pnpm rn-observe performance
pnpm rn-observe diagnoseArtifacts and SQLite data are created under <projectRoot>/.artifacts/; large binaries are never embedded in MCP responses.
pnpm --filter @rn-agent-observer/demo-expo android -- --device <device-name>The demo ships PerformanceLab, NetworkLab, RenderLab, AnimationLab, ErrorLab, and VisualLab. NetworkLab uses internal fixtures (0/500/2000ms and HTTP 503) so it never depends on Internet services. PerformanceLab reports its intentional 100ms long JS task precisely through instrumentation.
pnpm mcp:check
pnpm mcp:startThe server speaks stdio. Client configuration and the full list of 45 tools are documented in docs/protocol.md.
Three ways for agents (OpenCode/Claude Code/Cursor/Codex...) to use the observer:
1. MCP server (recommended — structured tools)
{
"mcpServers": {
"rn-agent-observer": {
"command": "node",
"args": [
"C:\\abs\\rn-agent-observer\\packages\\mcp-server\\dist\\server.js"
],
"env": {
"RN_OBSERVER_PROJECT_ROOT": "C:\\path\\to\\expo-app",
"RN_OBSERVER_DEVICE_ID": "emulator-5554"
}
}
}
}2. Install as a skill (teaches the agent the debugging workflow via CLI)
npx skills add GinzaTech/rn-agent-observerThe skill lives at skills/rn-agent-observer/SKILL.md — it teaches the observe -> understand-screen -> reproduce -> diagnose -> fix -> understand-screen -> compare loop, how to read metrics honestly, and common failure recovery. After installing, just say "app X feels laggy" and the agent knows to reach for rn-observe.
3. AGENTS.md (when the agent works inside this repo) — already present at the repo root; agents read it automatically.
All three can be combined: the skill/AGENTS.md teach the workflow, MCP provides directly callable tools.
Android/Windows is the only supported target of Observer 2.4.0.
ADB has no trustworthy JS FPS signal; the field is returned as available: false — values are never guessed.
JS blocking, route, React renders, and network metadata require development instrumentation inside the app.
CDP features (devtools-export, devtools-profile, metro-network) need Metro running for the right app and the app connected to it (adb reverse tcp:8081 tcp:8081); they cannot attach while another React Native DevTools session holds the connection.
reload --fast uses CDP Page.reload (JS-only) and automatically falls back to force-stop when Metro is unavailable.
Observer CDP commands queue across processes; external React Native DevTools must still be closed because it does not participate in the observer lock.
session stop automatically writes a replay, session refs survive reorder/scroll, and missing sessions produce EVIDENCE_NOT_RECORDED.
understand-screen/MCP understand_screen returns the instrumented route when available, screen state, headline, text/action refs, UI findings, and screenshot/UI-tree evidence; repeated calls detect unchanged loading. Classification is heuristic and text-field values are always redacted.
ui-model/MCP runtime_ui_model parses TSX with the TypeScript AST for component + file:line, then correlates source with instrumentation and the native tree. It distinguishes rendered, visible/off-screen/hidden/unmounted/flattened-or-unobserved, enabled, and evidence-backed canPress states.
The development-only Babel plugin injects a source-derived testID and wraps onPress; session stop collects interaction start/success/error and promotes testID taps into replay. Handler arguments, props, and input values are never recorded.
Network body capture is off by default. Development-only opt-in uses fail-closed allowlists and should still be limited to fixtures.
Apps without instrumentation: use metro-network (CDP), app-state (foreground activity, PID), and device-network (device-level byte counters, not app-attributed) as fallback evidence.
record (screenrecord) is limited to 180s per clip by Android.
Perfetto tracing is supported on Android; deep trace analysis remains in Perfetto UI/Android Studio.
This server cannot be deployed
Remote MCP for Android CLI agent build gate, structured receipts, audit logs, and reviewer-ready evi
Capture, inspect & debug HTTPS traffic across iOS, Android, browsers & backends — 304 MCP tools.
Analytics and debugging for your MCP server — explore usage and sessions, then root-cause errors.
Developer utility MCP: screenshots, PDFs, OG, QR, link preview, JSON validate, ShipPack.
