droid-mcp 1.0.0

package/CLAUDE.md

@@ -0,0 +1,124 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Проект
+
+Droid MCP — это минимальный MCP (Model Context Protocol) сервер для взаимодействия с Android устройствами через ADB. Сервер позволяет AI-ассистентам получать логи logcat, захватывать логи в реальном времени и получать иерархию View из Android приложений.
+
+## Технологический стек
+
+- Node.js 18+ с ES2022 модулями
+- TypeScript 5+ со строгой типизацией
+- Официальный `@modelcontextprotocol/sdk` v1.24.3 для MCP протокола
+- Zod v4 для валидации параметров инструментов
+- Cross-platform поддержка (Windows, Linux, macOS)
+
+## Команды для разработки
+
+```bash
+npm install          # Установка зависимостей
+npm run build        # Компиляция TypeScript в dist/
+npm start            # Запуск скомпилированного сервера
+npm test             # Сборка и запуск интеграционных тестов
+npm run test:old     # Запуск устаревшего набора тестов
+```
+
+### Отладка
+
+Режим отладки включается через переменную окружения:
+
+```bash
+# Windows PowerShell
+$env:DROID_MCP_DEBUG="true"; npm start
+
+# Linux/Mac
+DROID_MCP_DEBUG=true npm start
+```
+
+Также можно использовать VS Code debugger с конфигурацией из `.vscode/launch.json`.
+
+## Архитектура
+
+### Структура исходного кода
+
+```
+src/
+├── index.ts    # MCP сервер: регистрация инструментов, обработка запросов
+├── adb.ts      # ADB абстракция: выполнение команд, работа с процессами
+└── types.ts    # Zod схемы для валидации параметров инструментов
+```
+
+### Слой MCP сервера (`src/index.ts`)
+
+Основной файл, который:
+- Создаёт MCP сервер через `@modelcontextprotocol/sdk`
+- Регистрирует инструменты через `server.registerTool()`
+- Обрабатывает переменную окружения `ANDROID_APP_IDS` для глобальной фильтрации по PID
+- Предоставляет debug-логирование через `debugLog()`
+
+### Слой ADB абстракции (`src/adb.ts`)
+
+Содержит всю логику взаимодействия с ADB:
+- `execAdb()` — выполнение ADB команд с промисами
+- `captureLogcatUntil()` — захват логов в реальном времени с остановкой по паттерну
+- `getPidForPackage()` / `getPidsForPackages()` — получение PID процессов по package ID
+- `listThirdPartyPackages()` — список установленных сторонних приложений
+- `scanGradleForPackageId()` — поиск applicationId в build.gradle файлах
+
+Кастомный класс `AdbError` расширяет Error и содержит `code` и `stderr`.
+
+### Слой типизации (`src/types.ts`)
+
+Zod схемы для валидации параметров всех инструментов:
+- `GetLogcatSchema` — параметры для `get_logcat`
+- `CaptureSessionSchema` — параметры для `capture_session`
+- `InspectAppSchema` — параметры для `inspect_app_identity` (пустой объект)
+
+Типы параметров inference'ся из схем через `z.infer<>`.
+
+## Доступные MCP инструменты
+
+### `get_logcat`
+Получает историю логов logcat. Поддерживает фильтрацию по tag и количеству строк. Автоматически фильтрует по PID если установлена `ANDROID_APP_IDS`.
+
+### `capture_session`
+Захватывает логи в реальном времени до появления стоп-паттерна (regex) или истечения таймаута. Поддерживает фильтрацию по tag, priority, buffer и PID.
+
+### `inspect_app_identity`
+Сканирует проект и устройство для определения package ID. Ищет applicationId в build.gradle и показывает установленные приложения.
+
+## Глобальная фильтрация по Package ID
+
+Переменная окружения `ANDROID_APP_IDS` содержит список package ID через запятую или пробел:
+```bash
+export ANDROID_APP_IDS="com.example.app1,com.example.app2"
+```
+
+Когда установлена, все инструменты автоматически фильтруют логи по PID указанных приложений. Это значительно уменьшает объём данных, получаемых LLM.
+
+## Конвенции и паттерны
+
+1. **Debug-логирование**: Используйте `debugLog(message, data)` для отладочного вывода в stderr. Включается через `DROID_MCP_DEBUG`.
+
+2. **Обработка ошибок**: Все ADB ошибки должны быть типа `AdbError` с полями `code` и `stderr`. В工具 handlers оборачивайте ошибки и пробрасывайте с описательным сообщением.
+
+3. **Валидация**: Параметры всех инструментов валидируются через Zod схемы. Добавляйте новые схемы в `types.ts`.
+
+4. **PID-фильтрация**: При работе с логами всегда применяйте глобальную фильтрацию через `getPidsForPackages(globalPackageIds)`.
+
+5. **Process management**: В `captureLogcatUntil` используется `spawn()` для реального времени. Не забывайте про cleanup и timeout.
+
+6. **Таймауты**: Устанавливайте разумные лимиты для всех операций с ADB (logcat capture, view hierarchy dump).
+
+## Тестирование
+
+Тесты находятся в `tests/integration.test.js` и используют официальный MCP Client SDK. Тесты:
+- Не требуют подключенного Android устройства
+- Проверяют MCP протокол и валидацию параметров
+- Обрабатывают отсутствие ADB gracefully
+
+Для добавления нового инструмента:
+1. Добавьте Zod схему в `src/types.ts`
+2. Зарегистрируйте инструмент в `src/index.ts` через `server.registerTool()`
+3. Добавьте тесты в `tests/integration.test.js`

package/EXAMPLES.md

@@ -0,0 +1,471 @@
+# Примеры использования droid-mcp
+
+Этот документ содержит практические примеры использования инструментов `get_logcat` и `capture_session` для отладки Android приложений через Cursor/Windsurf.
+
+## Содержание
+
+- [Настройка MCP сервера в Cursor](#настройка-mcp-сервера-в-cursor)
+- [Сценарий 1: Отладка краша при авторизации](#сценарий-1-отладка-краша-при-авторизации)
+- [Сценарий 2: Отслеживание успешного сценария](#сценарий-2-отслеживание-успешного-сценария)
+- [Сценарий 3: Поиск проблемы с производительностью](#сценарий-3-поиск-проблемы-с-производительностью)
+- [Сценарий 4: Универсальный отладчик](#сценарий-4-универсальный-отладчик)
+- [Сценарий 5: Анализ сетевых запросов](#сценарий-5-анализ-сетевых-запросов)
+- [Сценарий 6: Отладка ANR (Application Not Responding)](#сценарий-6-отладка-anr-application-not-responding)
+- [Сценарий 7: Инспекция иерархии View](#сценарий-7-инспекция-иерархии-view)
+
+---
+
+## Настройка MCP сервера в Cursor
+
+### Шаг 1: Сборка проекта
+
+```bash
+cd e:\droid-mcp
+npm install
+npm run build
+```
+
+### Шаг 2: Добавление в конфигурацию Cursor
+
+Найдите файл конфигурации MCP в Cursor (обычно `~/.cursor/mcp.json` или через настройки Cursor) и добавьте:
+
+```json
+{
+  "mcpServers": {
+    "droid-mcp": {
+      "command": "node",
+      "args": ["E:/droid-mcp/dist/index.js"],
+      "env": {}
+    }
+  }
+}
+```
+
+**Важно:** Замените путь `E:/droid-mcp/dist/index.js` на абсолютный путь к вашему проекту.
+
+### Шаг 3: Перезапуск Cursor
+
+Перезапустите Cursor, чтобы подхватить новый MCP сервер.
+
+### Шаг 4: Проверка подключения
+
+В Cursor должны быть доступны инструменты:
+- `get_logcat` - получение истории логов
+- `capture_session` - запись логов в реальном времени
+
+---
+
+## Сценарий 1: Отладка краша при авторизации
+
+**Проблема:** Приложение падает при попытке входа пользователя.
+
+**Промпт для Cursor:**
+
+```
+Я хочу отладить проблему с крашем приложения при авторизации. 
+
+Используй инструмент capture_session из droid-mcp для записи логов в реальном времени. 
+
+Параметры:
+- Очисти буфер перед началом (clear_buffer: true), чтобы получить чистую сессию
+- Фильтруй логи по tag моего приложения (замени "MyApp" на реальный tag, если знаешь)
+- Остановись при появлении "FATAL", "Exception", "AndroidRuntime" или "crash"
+- Таймаут: 60 секунд
+- Приоритет: только ошибки и выше (priority: "E")
+
+После того как я скажу "готово", я воспроизведу проблему на устройстве - попытаюсь войти в приложение. Как только увидишь краш в логах, проанализируй стек трейс и предложи решение.
+```
+
+**Что происходит:**
+1. Cursor запускает `capture_session` с указанными параметрами
+2. Вы воспроизводите проблему на устройстве (пытаетесь войти)
+3. При появлении краша запись останавливается
+4. Cursor анализирует логи и предлагает решение
+
+**Пример результата:**
+```
+[Анализ логов]
+Найдена ошибка в строке 42 файла LoginActivity.kt:
+NullPointerException при обращении к userRepository
+
+Рекомендация: Добавить проверку на null перед вызовом userRepository.getUser()
+```
+
+---
+
+## Сценарий 2: Отслеживание успешного сценария
+
+**Задача:** Проверить, что определенный флоу работает корректно и зафиксировать все логи этого процесса.
+
+**Промпт для Cursor:**
+
+```
+Мне нужно протестировать сценарий "добавление товара в корзину". 
+
+Используй capture_session для записи логов этого процесса:
+- Очисти буфер (clear_buffer: true)
+- Фильтруй по tag "MyApp" (или другому, если знаешь)
+- Остановись при появлении "CHECKOUT_COMPLETE" или "SCENARIO_FINISHED" (я добавлю этот лог в код)
+- Таймаут: 120 секунд
+- Приоритет: все логи (не фильтровать по priority)
+
+Я скажу "начали", когда буду готов. После завершения сценария я добавлю в код Log.i("MyApp", "SCENARIO_FINISHED"), и запись остановится. Затем проанализируй логи и скажи, есть ли проблемы или всё работает корректно.
+```
+
+**Подготовка кода:**
+
+Перед началом добавьте в код точку завершения:
+
+```kotlin
+// В конце успешного выполнения сценария
+Log.i("MyApp", "SCENARIO_FINISHED")
+```
+
+**Что происходит:**
+1. Cursor начинает запись логов
+2. Вы выполняете сценарий (добавляете товар в корзину)
+3. При появлении лога "SCENARIO_FINISHED" запись останавливается
+4. Cursor анализирует весь флоу и сообщает о проблемах
+
+---
+
+## Сценарий 3: Поиск проблемы с производительностью
+
+**Проблема:** Приложение тормозит при открытии галереи изображений.
+
+**Промпт для Cursor:**
+
+```
+Приложение тормозит при открытии галереи изображений. Нужно найти причину.
+
+Используй capture_session:
+- Очисти буфер (clear_buffer: true)
+- Фильтруй по tag "MyApp" и "ImageLoader" (если есть)
+- Остановись при появлении "GALLERY_LOADED" или таймауте 90 секунд
+- Приоритет: все логи (verbose и выше)
+
+Я скажу "старт", открою галерею, и когда она загрузится, добавлю лог "GALLERY_LOADED". Проанализируй логи на предмет:
+1. Медленных операций (большие задержки между логами)
+2. Повторяющихся операций (возможные утечки или неоптимальные циклы)
+3. Ошибок или предупреждений
+```
+
+**Подготовка кода:**
+
+```kotlin
+// В методе, который вызывается после загрузки галереи
+Log.d("MyApp", "GALLERY_LOADED")
+```
+
+**Что происходит:**
+1. Cursor записывает все логи процесса загрузки
+2. Вы открываете галерею
+3. При появлении "GALLERY_LOADED" запись останавливается
+4. Cursor анализирует временные метки и находит узкие места
+
+**Пример результата:**
+```
+[Анализ производительности]
+Найдена проблема: между логами "Loading images" и "Images loaded" прошло 3.2 секунды.
+
+Анализ показал:
+- 500+ запросов к базе данных в цикле (должно быть батчинг)
+- Отсутствие кеширования изображений
+- Синхронная загрузка вместо асинхронной
+
+Рекомендации:
+1. Использовать batch запросы к БД
+2. Добавить кеш для изображений
+3. Перевести загрузку на корутины
+```
+
+---
+
+## Сценарий 4: Универсальный отладчик
+
+**Задача:** Быстрое тестирование любого сценария без специфических настроек.
+
+**Промпт для Cursor:**
+
+```
+Я хочу записать сессию logcat для отладки. Используй capture_session со следующими параметрами:
+
+- stop_pattern: "DEBUG_SESSION_END" (я добавлю этот лог в код когда закончу)
+- timeout_seconds: 180
+- clear_buffer: true
+- priority: "D" (debug и выше, чтобы видеть достаточно информации)
+
+Я скажу "запись начата", когда буду готов воспроизвести проблему. После того как закончу, добавлю Log.d("MyApp", "DEBUG_SESSION_END") в код, и запись остановится. Затем проанализируй логи и помоги найти проблему.
+```
+
+**Подготовка кода:**
+
+```kotlin
+// В любом месте кода, когда закончите тестирование
+Log.d("MyApp", "DEBUG_SESSION_END")
+```
+
+**Преимущества:**
+- Универсальный подход для любой задачи
+- Гибкий таймаут (3 минуты)
+- Достаточно детальные логи (debug уровень)
+
+---
+
+## Сценарий 5: Анализ сетевых запросов
+
+**Проблема:** Нужно отследить все сетевые запросы и ответы при определенном действии.
+
+**Промпт для Cursor:**
+
+```
+Мне нужно проанализировать сетевые запросы при синхронизации данных. 
+
+Используй capture_session:
+- clear_buffer: true
+- tag: "OkHttp" или "Retrofit" (в зависимости от библиотеки)
+- stop_pattern: "SYNC_COMPLETE"
+- timeout_seconds: 120
+- priority: "I" (info и выше)
+
+Я скажу "начали синхронизацию", запущу синхронизацию в приложении, и когда она завершится, добавлю лог "SYNC_COMPLETE". Проанализируй все HTTP запросы, ответы, ошибки и тайминги.
+```
+
+**Подготовка кода:**
+
+```kotlin
+// После завершения синхронизации
+Log.i("MyApp", "SYNC_COMPLETE")
+```
+
+**Что происходит:**
+1. Cursor записывает все сетевые логи
+2. Вы запускаете синхронизацию
+3. При завершении запись останавливается
+4. Cursor анализирует запросы и находит проблемы
+
+**Пример результата:**
+```
+[Анализ сетевых запросов]
+Найдено 15 HTTP запросов за 8 секунд.
+
+Проблемы:
+- 3 запроса возвращают 500 ошибку (серверная проблема)
+- 2 запроса занимают >2 секунды (медленный ответ)
+- Повторяющиеся запросы к одному endpoint (отсутствие кеширования)
+
+Рекомендации:
+1. Добавить retry логику для 500 ошибок
+2. Увеличить таймауты или оптимизировать запросы
+3. Реализовать кеширование для повторяющихся запросов
+```
+
+---
+
+## Сценарий 6: Отладка ANR (Application Not Responding)
+
+**Проблема:** Приложение зависает и показывает "Приложение не отвечает".
+
+**Промпт для Cursor:**
+
+```
+Приложение зависает при выполнении определенного действия. Нужно найти причину ANR.
+
+Используй capture_session:
+- clear_buffer: true
+- buffer: "events" (буфер событий системы)
+- stop_pattern: "ANR|Application Not Responding|FATAL"
+- timeout_seconds: 60
+- priority: "E" (только ошибки)
+
+Я скажу "начали", воспроизведу проблему, и когда появится ANR, запись остановится. Проанализируй логи и найди, какой процесс блокирует главный поток.
+```
+
+**Что происходит:**
+1. Cursor записывает системные события
+2. Вы воспроизводите проблему
+3. При появлении ANR запись останавливается
+4. Cursor анализирует системные логи и находит блокирующий процесс
+
+**Пример результата:**
+```
+[Анализ ANR]
+Найдена причина: главный поток заблокирован операцией чтения из базы данных.
+
+Детали:
+- Операция выполняется синхронно на главном потоке
+- Запрос к БД занимает 8+ секунд
+- Блокировка происходит в методе UserRepository.getUser()
+
+Рекомендация: Перевести операцию на фоновый поток (coroutine или AsyncTask)
+```
+
+---
+
+## Сценарий 7: Инспекция иерархии View
+
+**Задача:** Получить полную структуру UI компонентов для анализа layout или поиска проблем с отображением.
+
+**Промпт для Cursor:**
+
+```
+Мне нужно получить иерархию View текущего экрана приложения. Используй инструмент get_view_hierarchy из droid-mcp.
+
+Параметры:
+- package_id: "com.example.app" (или используй автоопределение)
+- timeout_ms: 5000
+
+После получения JSON проанализируй структуру и скажи:
+1. Какие основные компоненты есть на экране
+2. Есть ли вложенные ViewGroup, которые можно оптимизировать
+3. Какие View имеют одинаковые ID (если есть)
+4. Предложи улучшения структуры, если видишь проблемы
+```
+
+**Что происходит:**
+1. Cursor вызывает `get_view_hierarchy` и получает JSON с полной иерархией View
+2. Анализирует структуру и предоставляет рекомендации
+
+**Пример результата:**
+```
+[Анализ иерархии View]
+Найдено 45 View элементов на экране.
+
+Структура:
+- Root: FrameLayout
+  - LinearLayout (main_container)
+    - RecyclerView (list_items) - 20 элементов
+    - Button (action_button)
+  - FloatingActionButton
+
+Проблемы:
+- Глубокая вложенность: 6 уровней (можно оптимизировать до 4)
+- Дублирование ID: "item_view" используется 20 раз (нормально для RecyclerView)
+
+Рекомендации:
+1. Рассмотреть ConstraintLayout вместо вложенных LinearLayout
+2. Проверить производительность RecyclerView (возможно нужен ViewPool)
+```
+
+### Получить иерархию конкретного View
+
+**Промпт:**
+```
+Получи иерархию только для View с ID "com.example:id/main_container" используя get_view_hierarchy.
+```
+
+**Пример:**
+```json
+{
+  "name": "get_view_hierarchy",
+  "arguments": {
+    "view_id": "com.example:id/main_container"
+  }
+}
+```
+
+### Получить иерархию конкретного Fragment
+
+**Промпт:**
+```
+Получи иерархию View для Fragment "ProductDetailFragment" используя get_view_hierarchy.
+```
+
+**Пример:**
+```json
+{
+  "name": "get_view_hierarchy",
+  "arguments": {
+    "fragment_class": "ProductDetailFragment"
+  }
+}
+```
+
+**Примечание:** Для работы `get_view_hierarchy` необходимо реализовать BroadcastReceiver в вашем Android приложении. См. пример в `docs/android_view_dump_receiver_example.kt`.
+
+---
+
+## Быстрые команды для get_logcat
+
+### Получить последние ошибки
+
+**Промпт:**
+```
+Получи последние 500 строк логов с приоритетом Error и выше, используя get_logcat.
+```
+
+### Получить логи конкретного тега
+
+**Промпт:**
+```
+Получи последние 1000 строк логов с тегом "MyApp" используя get_logcat.
+```
+
+### Получить логи за последние минуты
+
+**Промпт:**
+```
+Получи максимальное количество логов (2000 строк) используя get_logcat, чтобы увидеть что происходило в последнее время.
+```
+
+---
+
+## Советы и рекомендации
+
+### Перед началом сессии
+
+1. **Проверьте подключение устройства:**
+   ```bash
+   adb devices
+   ```
+
+2. **Узнайте tag вашего приложения:**
+   - Посмотрите в `AndroidManifest.xml`
+   - Или используйте `get_logcat` без фильтров и найдите свой tag
+
+3. **Очистите старые логи (опционально):**
+   ```bash
+   adb logcat -c
+   ```
+
+### Во время сессии
+
+1. **Не закрывайте Cursor** во время записи
+2. **Добавьте стоп-слово в код** заранее, если используете кастомное
+3. **Следите за таймаутом** - если сессия долгая, увеличьте `timeout_seconds`
+
+### После получения логов
+
+1. **Задавайте уточняющие вопросы** о конкретных строках
+2. **Просите объяснить стек трейсы** если видите ошибки
+3. **Спрашивайте рекомендации** по оптимизации
+
+### Оптимизация производительности
+
+- Используйте фильтры (`tag`, `priority`) чтобы уменьшить объем логов
+- Очищайте буфер (`clear_buffer: true`) для "чистых" сессий
+- Выбирайте правильный буфер (`buffer`) в зависимости от задачи:
+  - `main` - логи приложений
+  - `system` - системные логи
+  - `crash` - краши
+  - `events` - системные события (для ANR)
+
+---
+
+## Часто задаваемые вопросы
+
+**Q: Как узнать tag моего приложения?**
+A: Используйте `get_logcat` без фильтров, запустите приложение и найдите строки с вашим package name или классом.
+
+**Q: Что делать если запись не останавливается?**
+A: Проверьте, что стоп-слово действительно появляется в логах. Можно использовать более общий паттерн или увеличить таймаут.
+
+**Q: Можно ли использовать несколько стоп-слов?**
+A: Да, используйте regex: `"FATAL|Exception|ERROR"` - запись остановится при появлении любого из них.
+
+**Q: Как записать логи из конкретного буфера?**
+A: Используйте параметр `buffer`: `"crash"` для крашей, `"events"` для системных событий, `"radio"` для сетевых логов.
+
+**Q: Что делать если логи слишком большие?**
+A: Используйте фильтры (`tag`, `priority`) или уменьшите таймаут. Также можно использовать `get_logcat` с ограничением по строкам для предварительного анализа.
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 droid-mcp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.