# Desktop Target Specification for claude-in-mobile
## Overview
Добавление desktop-таргета через Kotlin Multiplatform (Compose Desktop) для автоматизированного тестирования UI приложений на десктопных платформах.
## Целевые платформы
| Платформа | Приоритет | Accessibility API |
|-----------|-----------|-------------------|
| macOS | 1 (первый) | AXUIElement |
| Windows | 2 | UI Automation (UIA) |
| Linux | 3 | AT-SPI2 |
## Архитектура
### Взаимодействие компонентов
```
┌─────────────────┐ stdin/stdout ┌──────────────────────┐
│ MCP Server │ ◄──────────────────► │ Desktop App │
│ (Node.js) │ JSON-RPC │ (Compose Desktop) │
└────────┬────────┘ └──────────────────────┘
│
│ set_target('desktop')
│
┌────────▼────────┐
│ ADB Client │ (для Android, параллельно)
└─────────────────┘
```
### Запуск Desktop-приложения
MCP-сервер запускает desktop-app как child process через Gradle:
- Команда: `./gradlew :desktopApp:run` или `:composeApp:desktopRun`
- Автодетект подходящего таска в проекте
- Поддержка кастомных JVM-аргументов и переменных окружения
## MCP Tools API
### Управление таргетами
```typescript
// Переключение активного таргета
set_target(target: 'desktop' | 'android'): void
// Получение текущего таргета
get_target(): { target: string, status: 'running' | 'stopped' }
```
### Запуск приложения
```typescript
launch_desktop_app(params: {
projectPath: string; // Путь к Gradle-проекту
task?: string; // Gradle-таск (автодетект если не указан)
jvmArgs?: string[]; // JVM аргументы
env?: Record<string, string>; // Переменные окружения
}): { success: boolean, pid: number }
```
### Input-операции
```typescript
// Тап/клик по координатам
tap(x: number, y: number): void
// Свайп/drag
swipe(startX: number, startY: number, endX: number, endY: number, durationMs?: number): void
// Ввод текста
type_text(text: string): void
// Нажатие клавиш
key_event(key: string, modifiers?: string[]): void
// Примеры: key_event('Enter'), key_event('a', ['ctrl'])
```
### UI Hierarchy
```typescript
get_ui_hierarchy(): {
windows: Window[];
}
interface Window {
id: string;
title: string;
bounds: Bounds;
focused: boolean;
elements: UIElement[];
}
interface UIElement {
// Унифицированный формат (совпадает с Android)
id?: string;
text?: string;
contentDescription?: string;
className: string;
bounds: Bounds;
clickable: boolean;
enabled: boolean;
focused: boolean;
children: UIElement[];
}
interface Bounds {
x: number;
y: number;
width: number;
height: number;
}
```
### Скриншоты
```typescript
screenshot(params?: {
windowId?: string; // Конкретное окно (по умолчанию: focused)
quality?: number; // JPEG quality 0-100 (по умолчанию: 80)
}): {
base64: string; // JPEG в base64
width: number;
height: number;
scaleFactor: number; // HiDPI scale factor
}
```
### Информация об окнах
```typescript
get_window_info(): {
windows: Array<{
id: string;
title: string;
bounds: Bounds;
focused: boolean;
minimized: boolean;
fullscreen: boolean;
}>;
activeWindowId: string;
}
resize_window(params: {
windowId?: string;
width: number;
height: number;
}): void
focus_window(windowId: string): void
```
### Clipboard
```typescript
get_clipboard(): { text: string }
set_clipboard(text: string): void
```
### File Dialogs
```typescript
// Отслеживание открытия file dialog
on_file_dialog(): Promise<{ type: 'open' | 'save', path?: string }>
// Автоматический выбор файла в диалоге
select_file(path: string): void
```
### Логи
```typescript
get_logs(params?: {
type?: 'stdout' | 'stderr' | 'compose' | 'crash' | 'all';
since?: number; // timestamp
limit?: number;
}): {
logs: Array<{
timestamp: number;
type: string;
message: string;
}>;
}
get_performance_metrics(): {
fps: number;
memoryUsageMb: number;
cpuPercent: number;
}
```
## Технические детали
### Input Injection
- **java.awt.Robot** для синтетического input (клики, клавиатура)
- **OS Accessibility API** для получения UI-дерева:
- macOS: AXUIElement через JNI/JNA
- Windows: UI Automation через JNA
- Linux: AT-SPI2 через D-Bus
### Fallback стратегия
Если элемент не найден через Accessibility API:
1. Использовать координатный клик
2. Сообщить в ответе что элемент найден по координатам, не по semantics
### HiDPI/Retina поддержка
- Автодетект scale factor через `GraphicsEnvironment`
- Все координаты в API — логические (1x)
- Внутренняя конвертация в физические координаты
- Скриншоты возвращают `scaleFactor` для информации
### Permissions (macOS)
При отсутствии Accessibility permissions:
1. Показать инструкцию пользователю
2. Автоматически открыть System Preferences > Security & Privacy > Accessibility
3. Вернуть ошибку с подробным описанием
```typescript
{
error: 'ACCESSIBILITY_PERMISSION_REQUIRED',
message: 'Accessibility permission required. Opening System Preferences...',
instructions: [
'1. Click the lock to make changes',
'2. Enable access for Terminal/IDE',
'3. Restart the MCP server'
]
}
```
### Crash Handling
При падении desktop-app:
1. Сохранить crash stacktrace
2. Автоматически перезапустить приложение
3. Вернуть информацию о crash через `get_logs(type: 'crash')`
### Multi-window поддержка
- Список всех окон процесса через `get_window_info()`
- Фокус на конкретное окно через `focus_window()`
- Работа с диалогами и popup как с отдельными окнами
- `screenshot(windowId)` для скриншота конкретного окна
## Performance Requirements
| Операция | Target Latency |
|----------|----------------|
| screenshot | < 300ms |
| get_ui_hierarchy | < 500ms |
| tap/click | < 50ms |
| type_text | < 100ms |
## Фичи на будущее (v2+)
- [ ] Запись видео/GIF действий
- [ ] Drag-and-drop эмуляция
- [ ] System tray взаимодействие
- [ ] Запуск из JAR (без Gradle)
- [ ] Native меню поддержка
## Зависимости
### Kotlin/JVM
- Compose Desktop 1.5+
- JNA (для OS APIs)
- kotlinx.serialization (JSON-RPC)
### Node.js (MCP Server)
- Существующий код из claude-in-mobile
- child_process для управления desktop-app
## Структура файлов
```
claude-in-mobile/
├── src/
│ ├── desktop/
│ │ ├── client.ts # Desktop client (аналог adb/client.ts)
│ │ ├── accessibility/
│ │ │ ├── macos.ts # AXUIElement bindings
│ │ │ ├── windows.ts # UI Automation bindings
│ │ │ └── linux.ts # AT-SPI2 bindings
│ │ ├── input.ts # Robot-based input
│ │ └── gradle.ts # Gradle task detection & launch
│ └── tools/
│ └── desktop-tools.ts # MCP tool definitions
└── docs/
└── SPEC_DESKTOP.md # This file
```
## Open Questions
1. **Compose Semantics экспорт**: Насколько полно Compose Desktop экспортирует Semantics в OS Accessibility API? Требуется исследование.
2. **Linux поддержка**: AT-SPI2 может работать нестабильно в некоторых дистрибутивах. Возможно потребуется fallback на Robot-only режим.
3. **Native диалоги**: File dialogs на каждой ОС выглядят по-разному и могут не экспортировать accessibility. Возможно потребуется platform-specific код.
---
*Спецификация создана: 2026-01-12*
*Версия: 1.0*
