Droid MCP

М minimal MCP (Model Context Protocol) сервер для работы с Android ADB командами.

Описание

Этот сервер предоставляет инструменты для взаимодействия с Android устройствами через ADB. Сервер построен на официальном @modelcontextprotocol/sdk и использует Zod для валидации входных данных.

Требования

• Node.js 18+
• TypeScript 5+
• ADB установлен и доступен в PATH
• Подключенное Android устройство или эмулятор

Зависимости

Проект использует:

• @modelcontextprotocol/sdk - официальный SDK для MCP серверов
• zod - библиотека для валидации и типизации данных

Установка

npm install
npm run build

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

📖 Примеры использования: См. EXAMPLES.md для детальных сценариев отладки и промптов для Cursor/Windsurf.

Глобальная фильтрация по Package ID

Вы можете настроить автоматическую фильтрацию логов по package ID через переменную окружения ANDROID_APP_IDS. Это значительно уменьшит объем данных, которые получает LLM, исключив системные логи.

Формат: Список package ID через запятую или пробел:

# Одно приложение
export ANDROID_APP_IDS="com.example.myapp"

# Несколько приложений
export ANDROID_APP_IDS="com.example.app1,com.example.app2"
# или
export ANDROID_APP_IDS="com.example.app1 com.example.app2"

Когда ANDROID_APP_IDS установлена, все инструменты (get_logcat и capture_session) автоматически фильтруют логи только для запущенных процессов указанных приложений. Если приложение не запущено, выводится предупреждение, но работа продолжается без фильтра.

Запуск сервера

npm start

Или после сборки:

node dist/index.js

Доступные инструменты

inspect_app_identity

Сканирует директорию проекта и подключенное Android устройство для автоматического определения package ID (applicationId) для фильтрации логов. Ищет applicationId в файлах build.gradle и выводит список всех установленных сторонних приложений на устройстве. Показывает совпадения между проектом и устройством, помогая настроить переменную окружения ANDROID_APP_IDS. Параметры не требуются. Полезен для первоначальной настройки или при работе с несколькими приложениями.

Параметры: Нет (пустой объект)

Что делает:

• Сканирует build.gradle файлы проекта для поиска applicationId
• Получает список всех установленных сторонних приложений с устройства
• Показывает совпадения между проектом и устройством
• Предлагает примеры настройки ANDROID_APP_IDS

Пример:

{
  "name": "inspect_app_identity"
}

Пример вывода:

=== Package ID Inspection ===

[Project Source] Found in build.gradle: com.example.myapp
  ✓ Currently installed on device

[Device] Third-party packages installed (15 total):
  → com.example.myapp (matches gradle)
    com.google.android.youtube
    ru.yandex.taxi
  ... and 12 more packages

[Usage] Set ANDROID_APP_IDS environment variable to filter logs:
  Example: ANDROID_APP_IDS="com.example.myapp"

get_logcat

Получает историю логов logcat с опциональной фильтрацией по tag. Автоматически применяет фильтр по PID, если установлена переменная ANDROID_APP_IDS. Полезен для просмотра недавней истории логов или отладки прошлых событий.

Параметры:

• tag (string, optional): Фильтр по tag (например, "MyApp"). При указании возвращаются только логи с этим тегом.
• lines (number, optional): Количество строк логов для получения. По умолчанию: 200, максимум: 2000.

Примеры:

{
  "name": "get_logcat",
  "arguments": {
    "tag": "MyApp",
    "lines": 500
  }
}

Это выполнит команду: adb logcat -d -t 500 MyApp:*

{
  "name": "get_logcat",
  "arguments": {
    "lines": 200
  }
}

Это выполнит команду: adb logcat -d -t 200

Примечание: Если установлена переменная ANDROID_APP_IDS, команда автоматически добавит фильтры --pid=<PID> для каждого запущенного процесса указанных приложений.

capture_session

Записывает логи logcat в реальном времени, ожидая появления стоп-слова (regex pattern) или истечения таймаута. Автоматически применяет фильтр по PID, если установлена переменная ANDROID_APP_IDS. Поддерживает фильтрацию по tag, уровню приоритета и буферу логов. Идеально для интерактивной отладки при воспроизведении конкретных пользовательских сценариев. По умолчанию таймаут: 30 секунд (максимум: 300). Можно опционально очистить буфер перед началом для захвата только свежих логов.

Параметры:

• stop_pattern (string, required): Regex pattern или строка, при появлении которой запись остановится. Когда этот паттерн появляется в логах, захват останавливается немедленно.
• timeout_seconds (number, optional): Максимальное время ожидания stop_pattern в секундах. По умолчанию: 30, максимум: 300. Захват остановится при достижении таймаута, даже если stop_pattern не найден.
• clear_buffer (boolean, optional): Очистить буфер logcat перед началом захвата. По умолчанию: false. Полезно для начала со свежими логами.
• tag (string, optional): Фильтр по tag (например, "MyApp"). При указании захватываются только логи с этим тегом.
• priority (string, optional): Минимальный уровень приоритета логов: V (Verbose), D (Debug), I (Info), W (Warning), E (Error), F (Fatal). Захватываются только логи на этом уровне и выше.
• buffer (string, optional): Буфер логов для чтения: 'main' (логи приложений по умолчанию), 'system' (системные логи), 'crash' (логи крашей), 'radio' (логи радио), 'events' (логи событий), 'all' (все буферы), 'default' (основной буфер).

Примеры:

{
  "name": "capture_session",
  "arguments": {
    "stop_pattern": "FATAL|Exception",
    "timeout_seconds": 60,
    "clear_buffer": true,
    "tag": "MyApp"
  }
}

Это запустит запись логов, очистит буфер, будет фильтровать по tag "MyApp" и остановится при появлении "FATAL" или "Exception" или через 60 секунд.

{
  "name": "capture_session",
  "arguments": {
    "stop_pattern": "SCENARIO_FINISHED",
    "timeout_seconds": 120,
    "priority": "E"
  }
}

Это будет записывать только ошибки (priority E и выше) до появления "SCENARIO_FINISHED" или таймаута.

Примечание: Если установлена переменная ANDROID_APP_IDS, команда автоматически добавит фильтры --pid=<PID> для каждого запущенного процесса указанных приложений, что значительно уменьшает объем записываемых логов.

dump_view_hierarchy

Получает иерархию View с экрана Android устройства, используя uiautomator. Возвращает структуру View с bounds, text, resource-id, content-desc и clickable атрибутами. Оптимизирован для AI-анализа с компактным JSON форматом (по умолчанию), который фильтрует пустые контейнеры для экономии токенов. Поддерживает вывод в сыром XML для отладки. Полезен для понимания UI, тестовой автоматизации и AI-агентам, которые взаимодействуют с Android приложениями.

Параметры:

• format (string, optional): Формат вывода — "xml" (сырой uiautomator XML), "json" (полное дерево), "compact" (AI-оптимизированный JSON, по умолчанию — фильтрует пустые контейнеры).
• include_invisible (boolean, optional): Включать non-clickable view без text/content-desc. По умолчанию: false (фильтрует пустые контейнеры). Применяется только к форматам "json" и "compact".

Пример:

{
  "name": "dump_view_hierarchy",
  "arguments": {
    "format": "compact",
    "include_invisible": false
  }
}

capture_screenshot

Получает снимок экрана Android устройства. По умолчанию сохраняет в файл и возвращает абсолютный путь. Поддерживает WebP формат (по умолчанию, AI-оптимизированный, меньший размер) и PNG (без потерь). Автоматически масштабирует для уменьшения размера при сохранении читаемости для AI. Идеален для визуальной отладки, проверки UI и документирования проблем.

Настройка output директории:

# Через аргумент командной строки
node dist/index.js --output-dir /path/to/screenshots

# Через переменную окружения
export DROID_MCP_OUTPUT_DIR=/path/to/screenshots
node dist/index.js

# Если не настроено — используется .droid-mcp/screenshots в проекте

Параметры:

• output (string, optional): "file" (по умолчанию, сохраняет в output директорию) или "base64" (встраивает в ответ как data URL).
• format (string, optional): "webp" (по умолчанию, AI-оптимизированный) или "png" (без потерь).
• scale (number, optional): Масштаб 0.25-1.0. По умолчанию: 0.5 (половина разрешения, ~300KB).
• quality (number, optional): Качество WebP 1-100. По умолчанию: 85.

Примеры:

Получить скриншот с настройками по умолчанию (WebP, 50% scale, файл):

{
  "name": "capture_screenshot",
  "arguments": {}
}

Получить скриншот в PNG с полным разрешением:

{
  "name": "capture_screenshot",
  "arguments": {
    "format": "png",
    "scale": 1.0
  }
}

Получить скриншот как base64 data URL:

{
  "name": "capture_screenshot",
  "arguments": {
    "output": "base64",
    "format": "webp",
    "scale": 0.5
  }
}

Ответ (file mode):

{
  "filePath": "/absolute/path/to/screenshot_2025-01-17_14-30-25.webp",
  "relativePath": "screenshot_2025-01-17_14-30-25.webp",
  "format": "webp",
  "sizeKb": 305,
  "width": 540,
  "height": 960,
  "originalWidth": 1080,
  "originalHeight": 1920,
  "scaled": true,
  "message": "Screenshot saved to /absolute/path/to/screenshot_2025-01-17_14-30-25.webp"
}

Архитектура

• src/index.ts - Основной MCP сервер, использующий официальный SDK
• src/adb.ts - Обертка для выполнения ADB команд
• src/types.ts - Zod схемы для валидации параметров инструментов

Разработка

# Сборка
npm run build

# Запуск
npm start

Отладка (Debug Mode)

Для отладки сервера доступно несколько вариантов:

VS Code Debugger (Рекомендуется)

1. Откройте проект в VS Code
2. Перейдите в раздел "Run and Debug" (F5)
3. Выберите конфигурацию "Debug droid-mcp" или "Debug droid-mcp (with ANDROID_APP_IDS)"
4. Нажмите F5 для запуска

Конфигурация автоматически:

• Соберет проект перед запуском
• Включит детальное логирование через переменную DROID_MCP_DEBUG
• Настроит source maps для отладки TypeScript кода
• Позволит ставить breakpoints и инспектировать переменные

Ручной запуск с debug-логированием

# Windows PowerShell
$env:DROID_MCP_DEBUG="true"; npm start

# Linux/Mac
DROID_MCP_DEBUG=true npm start

Node.js Debugger

# Запуск с debugger на порту 9229
node --inspect dist/index.js

# Затем откройте Chrome и перейдите на chrome://inspect

Debug-логирование включает:

• Все вызовы инструментов MCP с параметрами
• Все ADB команды с полными командами и результатами
• Детали обработки ошибок
• Время выполнения операций
• Информацию о фильтрации по PID
• Детали работы с view hierarchy dump

Тестирование

Тесты проверяют базовую работоспособность MCP сервера: инициализацию, получение списка инструментов, валидацию параметров и обработку ошибок.

Запуск тестов:

npm test

Команда автоматически выполнит сборку проекта и запустит интеграционные тесты. Тесты используют официальный MCP Client SDK для проверки взаимодействия с сервером.

Что проверяют тесты:

• Инициализация сервера с корректными параметрами протокола
• Получение списка доступных инструментов (get_logcat, capture_session, inspect_app_identity)
• Валидация параметров инструментов (Zod схемы)
• Обработка ошибок (неизвестные инструменты, невалидные параметры)
• Структура ответов MCP протокола

Примечание: Тесты не требуют подключенного Android устройства, так как проверяют только протокол MCP и валидацию, а не выполнение ADB команд. Тесты, которые вызывают ADB, обрабатывают отсутствие устройства gracefully.

Лицензия

MIT