npm package: @horuzhenko/mcp-guacamole
Description: MCP-сервер для управления Apache Guacamole через LLM
Latest version: 6.0.7

# @horuzhenko/mcp-guacamole

MCP-сервер для управления Apache Guacamole через LLM. Предоставляет набор инструментов (tools) для подключения к удаленным рабочим столам, управления вводом и получения скриншотов.

## Возможности

- 🔐 **Автоматическая аутентификация**: Получение токена по логину/паролю
- 🖥️ **Управление сессиями**: Подключение и отключение от удаленных рабочих столов
- 🖱️ **Ввод**: Перемещение мыши, клики, ввод текста, комбинации клавиш, прокрутка
- 📸 **Скриншоты**: Получение снимков экрана в PNG/WebP формате
- ⚡ **InputSequencer**: Последовательное выполнение операций с задержками
- 🔄 **JSON-RPC**: Стандартный протокол MCP для взаимодействия с LLM
- 🚀 **run_sequence**: Batch-инструмент для выполнения множества действий в одном вызове
- ⚙️ **Конфигурация**: Профили подключения с дефолтными настройками
- 🌍 **Переменные окружения**: Настройка через переменные окружения
- 💓 **Keep-Alive**: Автоматическое поддержание активности соединений
- ⏰ **TTL**: Автоматическое отключение неактивных сессий

## Установка

```bash
pnpm add @horuzhenko/mcp-guacamole
```

Или для глобальной установки:

```bash
npm install -g @horuzhenko/mcp-guacamole
```

## Конфигурация через переменные окружения

Сервер поддерживает настройку через переменные окружения, что упрощает развертывание в различных средах:

| Переменная | Описание | Значение по умолчанию |
|------------|----------|----------------------|
| `MCP_GUAC_BASE_URL` | URL сервера Guacamole | `http://localhost:8080/guacamole` |
| `MCP_GUAC_USERNAME` | Имя пользователя | `guacadmin` |
| `MCP_GUAC_PASSWORD` | Пароль | `guacadmin` |
| `MCP_GUAC_WIDTH` | Ширина экрана | `1280` |
| `MCP_GUAC_HEIGHT` | Высота экрана | `800` |
| `MCP_GUAC_DPI` | DPI экрана | `96` |
| `MCP_GUAC_CONNECTION_ID` | ID соединения | `vnc-ubuntu` |
| `MCP_GUAC_DATASOURCE` | Источник данных | (не задан) |

### Пример использования с переменными окружения

```bash
# Настройка переменных окружения
export MCP_GUAC_BASE_URL="http://my-guacamole:8080/guacamole"
export MCP_GUAC_USERNAME="admin"
export MCP_GUAC_PASSWORD="mypassword"
export MCP_GUAC_WIDTH="1920"
export MCP_GUAC_HEIGHT="1080"
export MCP_GUAC_CONNECTION_ID="my-vnc-connection"

# Запуск сервера
npx @horuzhenko/mcp-guacamole
```

При использовании переменных окружения можно подключаться с минимальными параметрами:

```json
{
  "name": "connect",
  "arguments": {
    "auth": {}
  }
}
```

Переменные окружения имеют приоритет над значениями по умолчанию, но могут быть переопределены параметрами в запросе или конфигурационными файлами.

## Режимы работы

### 🚀 Демон (рекомендуется)
Постоянно работающий сервер для эффективного взаимодействия с LLM:

```bash
# Запуск демона
npx @horuzhenko/mcp-guacamole daemon start

# Остановка демона
npx @horuzhenko/mcp-guacamole daemon stop

# Статус демона
npx @horuzhenko/mcp-guacamole daemon status
```

**Преимущества демона:**
- ✅ Сохранение сессий между запросами
- ✅ Быстрый отклик (~10-50ms vs ~500-2000ms)
- ✅ Один процесс вместо множества
- ✅ Упрощенная интеграция с LLM
- ✅ Keep-Alive и TTL управление сессиями

Подробнее: [DAEMON.md](./DAEMON.md)

### 📡 Stdio режим (совместимость)
Традиционный режим для совместимости с существующими интеграциями:

```bash
# Как исполняемый файл
npx @horuzhenko/mcp-guacamole

# Или через Node.js
node node_modules/@horuzhenko/mcp-guacamole/dist/server.js
```

## CLI инструмент

Для удобного тестирования и взаимодействия с сервером используйте отдельный CLI пакет:

```bash
# Установка CLI
pnpm add @horuzhenko/mcp-guac

# Использование
npx mcp-guac list-tools
npx mcp-guac connect --base-url http://localhost:8080/guacamole --username admin --password secret
```

Подробнее: [@horuzhenko/mcp-guac](https://www.npmjs.com/package/@horuzhenko/mcp-guac)

## Доступные инструменты (Tools)

### connect
Подключение к удаленному рабочему столу

**Параметры:**
```json
{
  "auth": {
    "baseUrl": "http://guacamole-server:8080/guacamole",
    "username": "admin",
    "password": "password",
    "token": "optional-existing-token"
  },
  "display": {
    "width": 1024,
    "height": 768,
    "dpi": 96
  },
  "connectionId": "optional-connection-id",
  "datasource": "mysql"
}
```

**Результат:**
```json
{
  "sessionId": "uuid",
  "connectionId": "1",
  "remoteDisplay": { "width": 1024, "height": 768, "dpi": 96 },
  "capabilities": { "absolutePointer": true, "clipboard": true },
  "state": "READY"
}
```

### disconnect
Отключение от сессии

**Параметры:**
```json
{
  "sessionId": "session-uuid"
}
```

### mouse_move
Перемещение курсора мыши

**Параметры:**
```json
{
  "sessionId": "session-uuid",
  "x": 100,
  "y": 200
}
```

### mouse_click
Клик мыши (поддерживает двойной клик)

**Параметры:**
```json
{
  "sessionId": "session-uuid",
  "x": 100,
  "y": 200,
  "button": "left",
  "count": 1
}
```

### scroll
Прокрутка

**Параметры:**
```json
{
  "sessionId": "session-uuid",
  "x": 300,
  "y": 300,
  "deltaY": -120
}
```

### key_combo
Комбинация клавиш

**Параметры:**
```json
{
  "sessionId": "session-uuid",
  "keys": ["Ctrl", "c"]
}
```

### type_text
Ввод текста

**Параметры:**
```json
{
  "sessionId": "session-uuid",
  "text": "Hello, World!"
}
```

### screenshot
Получение скриншота

**Параметры:**
```json
{
  "sessionId": "session-uuid",
  "format": "png",
  "quality": 90
}
```

**Результат:**
```json
{
  "format": "png",
  "width": 1024,
  "height": 768,
  "imageBase64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "ts": 1234567890
}
```

### run_sequence
Выполнение последовательности действий в одном вызове

**Параметры:**
```json
{
  "sessionId": "session-uuid",
  "steps": [
    { "move": { "x": 100, "y": 100 } },
    { "wait": 500 },
    { "click": { "x": 100, "y": 100, "button": "left" } },
    { "type": { "text": "Hello!" } },
    { "key": { "keys": ["Enter"] } },
    { "screenshot": { "format": "webp", "quality": 80 } }
  ]
}
```

Подробнее: [RUN_SEQUENCE.md](./RUN_SEQUENCE.md)

## Пример использования

```typescript
import { spawn } from 'child_process';

// Запуск MCP-сервера
const server = spawn('node', ['packages/mcp-guacamole/dist/server.js'], {
  stdio: ['pipe', 'pipe', 'inherit']
});

// JSON-RPC запрос на подключение
const connectRequest = {
  jsonrpc: '2.0',
  id: 1,
  method: 'tools/call',
  params: {
    name: 'connect',
    arguments: {
      auth: {
        baseUrl: 'http://192.168.1.100:8080/guacamole',
        username: 'guacadmin',
        password: 'guacadmin'
      },
      display: { width: 1024, height: 768 }
    }
  }
};

server.stdin.write(JSON.stringify(connectRequest) + '\n');

server.stdout.on('data', (data) => {
  const response = JSON.parse(data.toString());
  console.log('Ответ сервера:', response);
});
```

## Архитектура

```
┌─────────────────┐    JSON-RPC    ┌─────────────────┐
│       LLM       │ ◄─────────────► │  MCP-сервер     │
└─────────────────┘                └─────────────────┘
                                            │
                                            ▼
                                   ┌─────────────────┐
                                   │ InputSequencer  │
                                   └─────────────────┘
                                            │
                                            ▼
                                   ┌─────────────────┐
                                   │   GuacAdapter   │
                                   └─────────────────┘
                                            │
                                            ▼
                                   ┌─────────────────┐
                                   │ Apache Guacamole│
                                   └─────────────────┘
```

## Особенности

### InputSequencer
Все операции ввода (кроме скриншотов) выполняются через InputSequencer, который:
- Гарантирует последовательное выполнение операций
- Добавляет реалистичные задержки между действиями
- Разбивает сложные операции (например, клик = move → mousedown → mouseup)
- Предотвращает гонку состояний

### Автоматическая аутентификация
Сервер автоматически:
- Получает токен аутентификации по логину/паролю
- Обнаруживает доступные соединения
- Выбирает подходящее соединение (по ID или первое доступное)

### Обработка ошибок
- Валидация всех входных параметров через Zod схемы
- Корректная обработка ошибок WebSocket соединения
- Автоматическая очистка ресурсов при отключении

## Разработка

```bash
# Сборка
pnpm build

# Разработка с автоматической пересборкой
pnpm dev

# Тестирование
pnpm test

# Запуск демо-клиента
cd examples && pnpm mcp-client-demo
```

## Конфигурация

MCP Guacamole поддерживает конфигурационные файлы для настройки профилей подключения, keep-alive и TTL параметров.

Подробнее: [CONFIGURATION.md](./CONFIGURATION.md)

## Требования

- Node.js 18+
- Apache Guacamole сервер
- Доступ к Guacamole API

## Лицензия

MIT