@ddqd/droid-mcp 2.0.0

package/README.md

@@ -0,0 +1,354 @@
+# Droid MCP
+
+М minimal MCP (Model Context Protocol) сервер для работы с Android ADB командами.
+
+## Описание
+
+Этот сервер предоставляет инструменты для взаимодействия с Android устройствами через ADB. Сервер построен на официальном [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk) и использует Zod для валидации входных данных.
+
+## Требования
+
+- Node.js 18+
+- TypeScript 5+
+- ADB установлен и доступен в PATH
+- Подключенное Android устройство или эмулятор
+
+## Зависимости
+
+Проект использует:
+- `@modelcontextprotocol/sdk` - официальный SDK для MCP серверов
+- `zod` - библиотека для валидации и типизации данных
+
+## Установка
+
+```bash
+npm install
+npm run build
+```
+
+## Использование
+
+> **📖 Примеры использования:** См. [EXAMPLES.md](EXAMPLES.md) для детальных сценариев отладки и промптов для Cursor/Windsurf.
+
+### Глобальная фильтрация по Package ID
+
+Вы можете настроить автоматическую фильтрацию логов по package ID через переменную окружения `ANDROID_APP_IDS`. Это значительно уменьшит объем данных, которые получает LLM, исключив системные логи.
+
+**Формат:** Список package ID через запятую или пробел:
+```bash
+# Одно приложение
+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`) автоматически фильтруют логи только для запущенных процессов указанных приложений. Если приложение не запущено, выводится предупреждение, но работа продолжается без фильтра.
+
+### Запуск сервера
+
+```bash
+npm start
+```
+
+Или после сборки:
+
+```bash
+node dist/index.js
+```
+
+### Доступные инструменты
+
+#### `inspect_app_identity`
+
+Сканирует директорию проекта и подключенное Android устройство для автоматического определения package ID (applicationId) для фильтрации логов. Ищет applicationId в файлах build.gradle и выводит список всех установленных сторонних приложений на устройстве. Показывает совпадения между проектом и устройством, помогая настроить переменную окружения `ANDROID_APP_IDS`. Параметры не требуются. Полезен для первоначальной настройки или при работе с несколькими приложениями.
+
+**Параметры:** Нет (пустой объект)
+
+**Что делает:**
+- Сканирует `build.gradle` файлы проекта для поиска `applicationId`
+- Получает список всех установленных сторонних приложений с устройства
+- Показывает совпадения между проектом и устройством
+- Предлагает примеры настройки `ANDROID_APP_IDS`
+
+**Пример:**
+```json
+{
+  "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.
+
+**Примеры:**
+
+```json
+{
+  "name": "get_logcat",
+  "arguments": {
+    "tag": "MyApp",
+    "lines": 500
+  }
+}
+```
+
+Это выполнит команду: `adb logcat -d -t 500 MyApp:*`
+
+```json
+{
+  "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' (основной буфер).
+
+**Примеры:**
+
+```json
+{
+  "name": "capture_session",
+  "arguments": {
+    "stop_pattern": "FATAL|Exception",
+    "timeout_seconds": 60,
+    "clear_buffer": true,
+    "tag": "MyApp"
+  }
+}
+```
+
+Это запустит запись логов, очистит буфер, будет фильтровать по tag "MyApp" и остановится при появлении "FATAL" или "Exception" или через 60 секунд.
+
+```json
+{
+  "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".
+
+**Пример:**
+```json
+{
+  "name": "dump_view_hierarchy",
+  "arguments": {
+    "format": "compact",
+    "include_invisible": false
+  }
+}
+```
+
+#### `capture_screenshot`
+
+Получает снимок экрана Android устройства. По умолчанию сохраняет в файл и возвращает абсолютный путь. Поддерживает WebP формат (по умолчанию, AI-оптимизированный, меньший размер) и PNG (без потерь). Автоматически масштабирует для уменьшения размера при сохранении читаемости для AI. Идеален для визуальной отладки, проверки UI и документирования проблем.
+
+**Настройка output директории:**
+
+```bash
+# Через аргумент командной строки
+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, файл):
+```json
+{
+  "name": "capture_screenshot",
+  "arguments": {}
+}
+```
+
+Получить скриншот в PNG с полным разрешением:
+```json
+{
+  "name": "capture_screenshot",
+  "arguments": {
+    "format": "png",
+    "scale": 1.0
+  }
+}
+```
+
+Получить скриншот как base64 data URL:
+```json
+{
+  "name": "capture_screenshot",
+  "arguments": {
+    "output": "base64",
+    "format": "webp",
+    "scale": 0.5
+  }
+}
+```
+
+**Ответ (file mode):**
+```json
+{
+  "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 схемы для валидации параметров инструментов
+
+## Разработка
+
+```bash
+# Сборка
+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-логированием
+
+```bash
+# Windows PowerShell
+$env:DROID_MCP_DEBUG="true"; npm start
+
+# Linux/Mac
+DROID_MCP_DEBUG=true npm start
+```
+
+#### Node.js Debugger
+
+```bash
+# Запуск с debugger на порту 9229
+node --inspect dist/index.js
+
+# Затем откройте Chrome и перейдите на chrome://inspect
+```
+
+**Debug-логирование включает:**
+- Все вызовы инструментов MCP с параметрами
+- Все ADB команды с полными командами и результатами
+- Детали обработки ошибок
+- Время выполнения операций
+- Информацию о фильтрации по PID
+- Детали работы с view hierarchy dump
+
+## Тестирование
+
+Тесты проверяют базовую работоспособность MCP сервера: инициализацию, получение списка инструментов, валидацию параметров и обработку ошибок.
+
+**Запуск тестов:**
+
+```bash
+npm test
+```
+
+Команда автоматически выполнит сборку проекта и запустит интеграционные тесты. Тесты используют официальный MCP Client SDK для проверки взаимодействия с сервером.
+
+**Что проверяют тесты:**
+
+- Инициализация сервера с корректными параметрами протокола
+- Получение списка доступных инструментов (`get_logcat`, `capture_session`, `inspect_app_identity`)
+- Валидация параметров инструментов (Zod схемы)
+- Обработка ошибок (неизвестные инструменты, невалидные параметры)
+- Структура ответов MCP протокола
+
+**Примечание:** Тесты не требуют подключенного Android устройства, так как проверяют только протокол MCP и валидацию, а не выполнение ADB команд. Тесты, которые вызывают ADB, обрабатывают отсутствие устройства gracefully.
+
+## Лицензия
+
+MIT
+

package/dist/adb.d.ts

@@ -0,0 +1,110 @@
+export interface AdbResult {
+    stdout: string;
+    stderr: string;
+}
+export declare class AdbError extends Error {
+    code: number | null;
+    stderr: string;
+    constructor(message: string, code: number | null, stderr: string);
+}
+/**
+ * Execute an ADB command
+ * @param command - Array of command arguments (e.g., ["logcat", "-d", "-t", "200"])
+ * @returns Promise with stdout and stderr
+ * @throws AdbError if command fails
+ */
+export declare function execAdb(command: string[]): Promise<AdbResult>;
+export interface CaptureLogcatOptions {
+    stopPattern: string;
+    timeoutMs: number;
+    clearBuffer?: boolean;
+    tag?: string;
+    priority?: string;
+    buffer?: string;
+    pids?: string[];
+}
+/**
+ * Получает PID процесса по package ID
+ * @param packageId - Package ID приложения (например, "com.example.app")
+ * @returns PID процесса или null, если приложение не запущено
+ */
+export declare function getPidForPackage(packageId: string): Promise<string | null>;
+/**
+ * Получает PID для списка package ID
+ * @param packageIds - Массив package ID
+ * @returns Массив PID для запущенных процессов (только те, что найдены)
+ */
+export declare function getPidsForPackages(packageIds: string[]): Promise<string[]>;
+/**
+ * Получает список установленных сторонних приложений (User installed)
+ * @returns Массив package ID установленных приложений
+ */
+export declare function listThirdPartyPackages(): Promise<string[]>;
+/**
+ * Пытается найти applicationId в build.gradle файлах проекта
+ * @param rootDir - Корневая директория проекта (по умолчанию process.cwd())
+ * @returns Найденный applicationId или null
+ */
+export declare function scanGradleForPackageId(rootDir?: string): Promise<string | null>;
+/**
+ * Запускает logcat и слушает вывод до появления stopPattern или истечения таймаута
+ * @param options - Параметры захвата логов
+ * @returns Promise с накопленными логами
+ * @throws AdbError если команда не может быть выполнена
+ */
+export declare function captureLogcatUntil(options: CaptureLogcatOptions): Promise<string>;
+/**
+ * Оптимизированный узел view для AI-агента
+ */
+export interface ParsedViewNode {
+    class: string;
+    bounds?: string;
+    id?: string;
+    text?: string;
+    desc?: string;
+    clickable?: boolean;
+    children?: ParsedViewNode[];
+}
+/**
+ * Опции для парсинга view hierarchy
+ */
+export interface ParseViewHierarchyOptions {
+    includeInvisible: boolean;
+    compact: boolean;
+}
+/**
+ * Выполняет uiautomator dump и возвращает XML
+ * @returns XML строка с иерархией View
+ * @throws AdbError если команда не может быть выполнена
+ */
+export declare function dumpViewHierarchy(): Promise<string>;
+/**
+ * Парсит XML иерархии View в оптимизированное для AI дерево
+ * @param xml - XML строка от uiautomator dump
+ * @param options - Опции парсинга
+ * @returns Оптимизированное дерево View
+ */
+export declare function parseViewHierarchyXml(xml: string, options: ParseViewHierarchyOptions): ParsedViewNode;
+export declare function setOutputDir(dir: string): void;
+export declare function getOutputDir(): string;
+export interface CaptureScreenshotOptions {
+    format: "webp" | "png";
+    scale: number;
+    quality: number;
+    output: "file" | "base64";
+}
+export interface ScreenshotResult {
+    filePath?: string;
+    relativePath?: string;
+    data?: string;
+    format: string;
+    size: number;
+    sizeKb: number;
+    width: number;
+    height: number;
+    originalWidth: number;
+    originalHeight: number;
+    scaled: boolean;
+}
+export declare function captureScreenshot(options: CaptureScreenshotOptions): Promise<ScreenshotResult>;
+//# sourceMappingURL=adb.d.ts.map

package/dist/adb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adb.d.ts","sourceRoot":"","sources":["../src/adb.ts"],"names":[],"mappings":"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"}