execbro-sdk

Навіщо цей SDK?

ExecBro працює без жодних змін у застосунку, але встановлення execbro-sdk найбільше розширює можливості вашого агента. Він під’єднує важливі частини застосунку (сховища стану, навігацію та будь-який інший переданий об’єкт) просто в досяжність агента, тож той досліджує й керує справжнім станом застосунку, а не вгадує ззовні.

Він також закриває прогалини стандартного підключення MCP-сервера. Сервер спілкується із застосунком через Chrome DevTools Protocol (CDP), що чудово працює для більшості функцій, але на новіших архітектурах React Native (Expo SDK 52+, Bridgeless) CDP має обмеження:

SDK патчить fetch і console під час імпорту й зберігає все в буфері всередині застосунку. MCP-сервер автоматично виявляє SDK і читає з нього, додаткова конфігурація не потрібна.

Встановлення

Встановлюйте цей пакет усередині свого React Native застосунку: це SDK для застосунку, а не CLI і не плагін для редактора. Він має бути в залежностях того React Native / Expo застосунку, який ви хочете налагоджувати, і імпортуватися з його вхідного файлу. Встановлення будь-де інде (глобально, у бекенді чи поруч із MCP-сервером) нічого не дає.

Запустіть це в корені свого React Native / Expo застосунку:

npm install execbro-sdk

Стара назва пакета

Раніше цей SDK публікувався як react-native-ai-devtools-sdk. Під старою назвою й далі виходять ідентичні збірки через дзеркальну публікацію, тож наявні встановлення працюють. Для нових встановлень використовуйте execbro-sdk.

Налаштування

Додайте у вхідний файл застосунку (index.js, App.tsx або app/_layout.tsx для Expo Router), це має бути перший імпорт:

import { init } from 'execbro-sdk';
if (__DEV__) {
  init();
}

// ... rest of your imports

От і все. Інструменти MCP (get_network_requests, get_logs тощо) автоматично використовуватимуть дані SDK, коли вони доступні.

Примітка щодо мокання відповідей

network_mock, network_condition і network_replay працюють однаково з SDK і без нього. Мокання живе у вбудованому перехоплювачі MCP-сервера, а не в цьому SDK, тож встановлення SDK його не вмикає і не вимикає.

Одна відмінність у відображенні: зі встановленим SDK дані надходять із власного буфера SDK під його власними id запитів, тому окремі рядки не позначаються [MOCK m1]. Банер активних правил у кожному читанні мережі та лічильники спрацювань для кожного правила в network_mock({action:"list"}) однаково повідомляють, що трафік змінюється.

Зі сховищами стану

Передайте посилання на свої сховища стану для прямого доступу AI:

import { init } from 'execbro-sdk';
import { store } from './store'; // Redux store
import { queryClient } from './queryClient'; // TanStack Query

if (__DEV__) {
  init({
    stores: {
      redux: store,
      queryClient: queryClient,
    },
  });
}

Після цього AI-асистент може досліджувати стан сховища напряму:

execute_in_app with expression="globalThis.__RN_AI_DEVTOOLS__.stores.redux.getState()"

З навігацією

Передайте посилання на навігацію, щоб AI міг досліджувати навігацію:

import { init } from 'execbro-sdk';
import { navigationRef } from './navigation';

if (__DEV__) {
  init({
    navigation: navigationRef,
  });
}

З власними посиланнями

Використовуйте custom, щоб дати агенту пряме керування всім, що не належить до сховищ чи навігації: AsyncStorage, MMKV, клієнт аналітики, сервіс feature-флагів, ваші власні синглтони. Будь-який переданий об’єкт агент може читати й діяти через нього напряму:

import { init } from 'execbro-sdk';
import AsyncStorage from '@react-native-async-storage/async-storage';
import { storage } from './mmkv';

if (__DEV__) {
  init({
    custom: {
      asyncStorage: AsyncStorage,
      mmkv: storage,
    },
  });
}

Параметри конфігурації

init({
  // Max network entries to buffer (default: 500)
  maxNetworkEntries: 500,

  // Max console entries to buffer (default: 500)
  maxConsoleEntries: 500,

  // State store references for AI access
  stores: {
    redux: reduxStore,
    queryClient: queryClient,
    userStore: useUserStore,
  },

  // Navigation reference
  navigation: navigationRef,

  // Any additional references for AI access
  custom: {
    asyncStorage: AsyncStorage,
    mmkv: storage,
  },
});

Як це працює

Архітектура

React Native App
  |
  |  1. import { init } from 'execbro-sdk'
  |     -> patches globalThis.fetch (captures all network requests)
  |     -> patches console.log/warn/error/info/debug (captures all logs)
  |     -> stores references to state management stores
  |     -> exposes globalThis.__RN_AI_DEVTOOLS__ with query methods
  |
  |  2. App runs normally - all fetch() calls and console output
  |     are intercepted, stored in circular buffers, and passed
  |     through to their original implementations unchanged
  |
  v
ExecBro MCP Server (npm: execbro)
  |
  |  3. Connects to app via CDP (Chrome DevTools Protocol)
  |     Detects SDK: typeof globalThis.__RN_AI_DEVTOOLS__?.getNetworkEntries === "function"
  |
  |  4. MCP tools read SDK data via Runtime.evaluate:
  |     get_network_requests -> globalThis.__RN_AI_DEVTOOLS__.getNetworkEntries()
  |     get_logs             -> globalThis.__RN_AI_DEVTOOLS__.getConsoleEntries()
  |
  v
AI Assistant (Claude Code, Cursor, VS Code Copilot, etc.)

Що перехоплюється

Мережеві запити: перехоплюється кожен виклик fetch(). SDK зберігає метод, URL, status, statusText, тривалість, повні заголовки й тіла запиту та відповіді (через response.clone().text(), оригінальна відповідь лишається недоторканою), а також помилки й таймінги.

Вивід консолі: кожен виклик console.log/warn/error/info/debug зберігається з рівнем логу, часовою міткою та відформатованим повідомленням. Оригінальні методи консолі працюють як і раніше, логи звично з’являються в Xcode/Metro/DevTools.

Сховища стану: посилання, передані через параметр stores, відкриваються глобально, щоб MCP-сервер міг звертатися до них на вимогу.

Чому це має бути перший імпорт

SDK патчить globalThis.fetch і console під час виклику init(). Якщо інший код (ваш застосунок, бібліотеки на кшталт Apollo/Axios) викличе fetch до того, як SDK його пропатчить, ці запити не буде перехоплено. Перший імпорт гарантує, що SDK перехоплює все з самого початку: оновлення OAuth-токена під час запуску, перші виклики GraphQL/REST API, завантаження конфігурації та feature-флагів і ранній вивід консолі під час ініціалізації.

Безпека в продакшні

У продакшн-збірках SDK нічого не робить: перевірка if (__DEV__) у вашому коді не дає викликати init(); навіть якщо викликати його без перевірки, init() сам перевіряє __DEV__ як запобіжник; а tree-shaking прибирає код SDK із продакшн-бандлів, коли його обгорнуто в if (__DEV__).

Кільцеві буфери

Мережеві дані й дані консолі зберігаються в кільцевих буферах (за замовчуванням по 500 записів). Коли буфер заповнюється, найстаріші записи витісняються. Так використання пам’яті обмежене, хоч скільки запитів чи логів створює застосунок.

Відкритий глобальний API

SDK відкриває globalThis.__RN_AI_DEVTOOLS__ з такими методами. Викликати їх напряму не потрібно, інструменти MCP використовують їх автоматично.

globalThis.__RN_AI_DEVTOOLS__ = {
  version: '0.5.1',

  // Capabilities - tells MCP server what's available
  capabilities: {
    network: true,
    console: true,
    stores: true,      // true if stores were passed
    navigation: true,  // true if navigation was passed
    render: false,      // future: render profiling
  },

  // State store references
  stores: { redux: store, queryClient: qc, ... },

  // Navigation reference
  navigation: navigationRef,

  // Custom references (AsyncStorage, MMKV, etc.)
  custom: { asyncStorage: AsyncStorage, mmkv: storage, ... },

  // Network
  getNetworkEntries(),  // all buffered network entries (incl. headers + bodies)
  clearNetwork(),       // returns number of entries cleared

  // Console
  getConsoleEntries(),  // all buffered console entries
  clearConsole(),       // returns number of entries cleared
}

Сумісність

SDK не має нативних залежностей: це чистий JavaScript, що патчить стандартні глобальні об’єкти (fetch, console). Він працює на будь-якій версії React Native, що їх підтримує.

Зв’язок з ExecBro

Цей SDK необов’язковий, але рекомендований. MCP-сервер працює і без нього: він підключається через CDP і одразу надає логи консолі, інспекцію компонентів, взаємодію з UI та базове відстеження мережі.

Встановлення SDK значно посилює агента: він під’єднує ваші сховища стану, навігацію та будь-які передані власні посилання просто в досяжність агента, перетворюючи інспекцію лише для читання на пряме керування тими частинами застосунку, які ви вирішите відкрити, і закриває прогалини CDP (архітектура Bridgeless, перехоплення запитів під час старту, тіла відповідей). Коли MCP-сервер виявляє SDK, він автоматично надає перевагу його даним; коли SDK немає, використовує CDP.

• SDK НЕ потрібен для: перегляду логів консолі, інспекції дерева компонентів, взаємодії з UI, виконання JavaScript, перезавантаження застосунку, виявлення помилок бандла чи керування пристроями.
• SDK додає: перехоплення мережевих запитів (особливо запитів під час старту й тіл відповідей), перехоплення логів консолі (стартові логи, які CDP може пропустити) і пряме керування сховищами стану, навігацією та будь-якими власними посиланнями, які ви під’єднаєте.