expo-mcp

MCP-сервер для автоматизации приложений Expo/React Native с интеграцией Maestro.

Возможности

• Архитектура на основе сессий: start_session запускает Expo, привязывает устройство и получает аренду — никакого ручного управления ID устройства

• Аренда устройства с TTL: 2-минутная аренда автоматически продлевается при каждом вызове инструмента устройства; истекает после периода бездействия, чтобы другие экземпляры могли использовать устройство

• Координация между экземплярами: Несколько экземпляров MCP могут работать одновременно без конфликтов устройств

• Управление сервером разработки Expo: Запуск/остановка/перезагрузка сервера разработки Expo

• Интеграция с Maestro: Полноценные инструменты автоматизации UI (нажатие, ввод, скриншот и т.д.)

Установка

Как плагин Claude Code (рекомендуется)

Две команды, затем перезапуск:

# 1. Install the plugin. Just dismiss the "Expo App Directory" prompt
#    (or leave it empty) — the next step configures it for you.
/plugin marketplace add DaveDev42/expo-mcp
/plugin install expo-mcp --scope project

# 2. One-shot installer. Runs environment checks, auto-detects the Expo
#    app directory, and writes the userConfig directly into
#    .claude/settings.json. No /plugin UI round-trip needed.
/expo-mcp:install                     # auto-detect
/expo-mcp:install apps/mobile         # monorepo: pass the path explicitly

Затем перезапустите Claude Code, и все инструменты, агенты и навыки будут готовы.

Флаги установщика:

/expo-mcp:install apps/mobile --global        # write to ~/.claude/settings.json
/expo-mcp:install --scaffold-maestro          # also create a starter maestro/
/expo-mcp:install --skip-doctor               # skip prerequisite checks

Установщик запускает встроенные скрипты Node (doctor.mjs, detect-app-dir.mjs, scaffold-maestro.mjs) из директории плагина. Claude Code предложит вам подтвердить каждый из них при первом запуске — подтвердите их, чтобы продолжить.

Если вы предпочитаете предварительно подтвердить скрипты (без запросов), добавьте это в .claude/settings.local.json в вашем проекте, заменив <PATH> на абсолютный путь, показанный Claude Code при первом запуске каждого скрипта:

{
  "permissions": {
    "allow": [
      "Bash(node <PATH>/doctor.mjs:*)",
      "Bash(node <PATH>/detect-app-dir.mjs:*)",
      "Bash(node <PATH>/scaffold-maestro.mjs:*)"
    ]
  }
}

Установка плагина автоматически настраивает:

• MCP-сервер expo (ручной .mcp.json не требуется)

• QA-агент (qa) для автоматизированного тестирования мобильных приложений

• Агент написания сценариев (flow-writer) для создания тестовых сценариев Maestro в формате YAML

• Руководство по использованию (/expo-guide) со справочником инструментов и лучшими практиками

• Хук валидации, который предупреждает о вердиктах QA PASS без доказательств выполнения

Только как MCP-сервер

Этот проект распространяется только через GitHub (имя expo-mcp в npm принадлежит другому, не связанному пакету — не используйте его). Запустите его через ссылку на GitHub:

npx -y github:DaveDev42/expo-mcp

Использование с Claude Code

Ручная настройка MCP

Если вы не используете плагин, добавьте в свой .mcp.json:

{
  "mcpServers": {
    "expo": {
      "command": "npx",
      "args": ["-y", "github:DaveDev42/expo-mcp"]
    }
  }
}

Настройка в монорепозитории

Используйте позиционный аргумент для указания директории приложения:

{
  "mcpServers": {
    "expo": {
      "command": "npx",
      "args": ["-y", "github:DaveDev42/expo-mcp", "apps/mobile"]
    }
  }
}

Конкретное устройство

Закрепите определенный симулятор или эмулятор с помощью --device-id:

{
  "mcpServers": {
    "expo": {
      "command": "npx",
      "args": ["-y", "github:DaveDev42/expo-mcp", "--device-id=6D192F60-1234-5678-ABCD-000000000000"]
    }
  }
}

Фильтрация инструментов

Исключите определенные инструменты с помощью --exclude-tools:

{
  "mcpServers": {
    "expo": {
      "command": "npx",
      "args": ["-y", "github:DaveDev42/expo-mcp", "apps/mobile", "--exclude-tools=list_devices"]
    }
  }
}

Или откройте только определенные инструменты с помощью --tools:

{
  "mcpServers": {
    "expo": {
      "command": "npx",
      "args": ["-y", "github:DaveDev42/expo-mcp", "--tools=start_session,stop_session,take_screenshot"]
    }
  }
}

Справочник CLI

Usage: expo-mcp [app-dir] [options]

Arguments:
  app-dir                      Path to Expo app directory (default: cwd)

Options:
  --device-id=<id>             Specific device to use (iOS simulator UUID or Android serial)
  --exclude-tools=tool1,tool2  Exclude specific tools from the MCP server
  --tools=tool1,tool2          Only expose specific tools
  -h, --help                   Show help message
  -v, --version                Show version number

Быстрый старт

# 1. Start session (launches Expo + binds device + acquires lease)
start_session({ target: "ios-simulator" })

# 2. Use tools directly (no device_id needed!)
take_screenshot()
tap_on({ text: "Login" })
input_text({ text: "hello@example.com" })
press_key({ key: "Enter" })
scroll({ direction: "down" })
swipe({ direction: "left" })

# 3. Run Maestro flows
run_maestro_flow({ flow_yaml: "- assertVisible: Welcome" })
check_maestro_flow_syntax({ flow_yaml: "- tap: Login" })

# 4. Reload app after code changes
reload_app()

# 5. Check logs if needed
get_logs({ level: "error" })

# 6. Stop session when done
stop_session()

Возможности плагина

При установке в качестве плагина Claude Code вы получаете следующие дополнительные возможности:

QA-агент

Делегируйте мобильное QA-тестирование агенту qa. Он систематически тестирует ваше приложение на симуляторе/эмуляторе со строгими требованиями к доказательствам — никаких вердиктов только на основе проверки кода.

# In Claude Code, delegate to the QA agent:
"Test the login flow on iOS simulator"  →  delegates to qa agent

Агент следует структурированной методологии: запуск приложения → проверка UI → взаимодействие → верификация → отчет с вердиктом PASS/FAIL/INCONCLUSIVE.

Агент написания сценариев (Flow Writer)

Агент flow-writer проверяет работающее приложение и создает тестовые сценарии Maestro в формате YAML:

# Ask the flow writer to create a test flow:
"Write a Maestro flow for the onboarding sequence"  →  delegates to flow-writer agent

Он проверяет синтаксис, выполняет сценарий для подтверждения его работоспособности и записывает файл .yaml в ваш проект.

Руководство по использованию

Получите доступ к справочнику инструментов и лучшим практикам через /expo-guide:

/expo-guide                    # Full guide
/expo-guide session            # Session lifecycle
/expo-guide debugging          # Debugging tips

Инструменты

Инструменты жизненного цикла

Опции start_session

Инструменты Maestro

Все инструменты Maestro работают автоматически, как только сессия активна — device_id внедряется из сессии:

Примечание: Инструменты устройства требуют активной сессии. Сначала вызовите start_session. list_devices и check_maestro_flow_syntax можно вызывать в любое время.

Система аренды устройств

Аренда устройства предотвращает ситуацию, когда один экземпляр MCP удерживает устройство бесконечно:

1. Получение: start_session получает 2-минутную аренду устройства

2. Автопродление: Каждый вызов инструмента устройства (take_screenshot, tap_on и т.д.) сбрасывает 2-минутный таймер

3. Истечение: Если в течение 2 минут не вызывается ни один инструмент устройства, аренда истекает, и устройство становится доступным

4. Повторное получение: Вызовите start_session снова, чтобы повторно получить аренду (сервер продолжает работать, перезапуск не требуется)

5. Проверка: get_session_status показывает оставшееся время аренды

Несколько экземпляров MCP координируются через файловый реестр (/tmp/expo-mcp/instances/), поэтому два экземпляра не могут претендовать на одно и то же устройство одновременно.

Переменные окружения

Как это работает

1. Запуск сессии: start_session запускает сервер разработки Expo, ожидает подключения устройства и получает аренду

2. Привязка устройства: ID подключенного устройства сохраняется в сессии с TTL 2 минуты

3. Автоматическое внедрение: Все инструменты устройства Maestro автоматически используют ID устройства из сессии

4. Продление аренды: Каждый вызов инструмента устройства сбрасывает таймер аренды

5. Завершение сессии: stop_session очищает все, или аренда истекает после бездействия

Неинтерактивные среды (CI/CD, AI-агенты)

Этот MCP-сервер автоматически включает режим --offline при запуске в средах CI (CI=1). Это позволяет приложению работать без необходимости наличия EXPO_TOKEN.

Что делает автономный режим

• Пропускает обмен данными с сервером Expo (подпись манифеста)

• НЕ влияет на сетевые функции вашего приложения (API-запросы, fetch и т.д.)

• Режим туннеля (--tunnel) недоступен в автономном режиме

Если вам нужны функции учетной записи Expo

Для функций, требующих аутентификации Expo, отключите автономный режим и предоставьте EXPO_TOKEN:

{
  "mcpServers": {
    "expo": {
      "env": {
        "EXPO_TOKEN": "your-token-here"
      }
    }
  }
}

Затем вызовите start_session с offline: false:

start_session({ target: "ios-simulator", offline: false })

Требования

• Node.js >= 18

• Xcode (для симулятора iOS)

• Android Studio (для эмулятора Android)

• Maestro CLI (для автоматизации UI)

Лицензия

MIT