npm package: @horuzhenko/mcp-guac
Description: MCP сервер для Guacamole
Latest version: 6.0.31

# @horuzhenko/mcp-guac — MCP сервер для Apache Guacamole (STDIO)

Минимальный STDIO MCP-сервер, который подключается к Apache Guacamole и предоставляет 11 инструментов:
- session.connect, session.disconnect
- screen.screenshot
- input.move, input.click, input.drag, input.scroll, input.keyCombo, input.typeText
- clipboard.set, clipboard.get

Требования:
- Запущенные Guacamole и observer (как в guac-testkit)
- Node.js 20+, pnpm

## Установка и сборка

- pnpm install
- pnpm -w build

## Запуск STDIO-сервера

- pnpm dlx @horuzhenko/mcp-guac@6.0.27 serve \
  --guac-url http://localhost:8080/guacamole \
  --username guacadmin --password guacadmin \
  --display "1366x768@96" --human-delay 75 --max-retries 3

Примечания:
- Логи — только debug через console.debug. В проде по умолчанию тихо.
- Типизация строгая, без any.

## Проверка работы (примерный сценарий)
Ниже — последовательность вызовов MCP-инструментов, которую можно выполнить любым MCP‑клиентом (см. examples/simple-client.ts и интеграционный тест tests/mvp.int.test.ts).

1) Подключение

Инструмент: session.connect
Аргументы:
```json
{
  "auth": { "baseUrl": "http://localhost:8080/guacamole", "username": "guacadmin", "password": "guacadmin" },
  "display": { "width": 1366, "height": 768, "dpi": 96 }
}
```
Ответ содержит sessionId.

2) Скриншот

Инструмент: screen.screenshot
Аргументы:
```json
{ "sessionId": "<SESSION_ID>", "format": "png", "downscaleLongEdge": 1200 }
```
Ответ:
```json
[
  {
    "type": "image",
    "mimeType": "image/png",
    "data": "<BASE64>"
  },
  {
    "type": "text",
    "text": "{\"id\":\"...\",\"width\":1200,\"height\":675}"
  }
]
```

Base64 содержит только символы `A-Za-z0-9+/=` — без префикса `data:image/...`.

3) Клик по координатам (левая кнопка)

Инструмент: input.click
Аргументы:
```json
{ "sessionId": "<SESSION_ID>", "x": 200, "y": 150, "button": "left", "count": 1 }
```
Ответ: ok

4) Двойной клик

Инструмент: input.click
Аргументы:
```json
{ "sessionId": "<SESSION_ID>", "x": 200, "y": 150, "button": "left", "count": 2 }
```
Ответ: ok

5) Перемещение курсора

Инструмент: input.move
Аргументы:
```json
{ "sessionId": "<SESSION_ID>", "x": 300, "y": 300 }
```
Ответ: ok

6) Завершение сессии

Инструмент: session.disconnect
Аргументы:
```json
{ "sessionId": "<SESSION_ID>" }
```
Ответ: ok

## Быстрая проверка тестами (на живом Guacamole)

- export RUN_GUAC_INT=1
- export GUAC_BASE_URL=http://localhost:8080/guacamole
- export GUAC_USERNAME=guacadmin
- export GUAC_PASSWORD=guacadmin
- pnpm --filter "@horuzhenko/mcp-guac" test -- --run

Сценарий теста покрывает: connect → screenshot → input (move/click/type/drag/scroll/keyCombo) → clipboard (set/get) → disconnect.


## Установка из npm (для пользователей)

- Глобально:
  - npm i -g @horuzhenko/mcp-guac
  - mcp-guac serve --guac-url http://localhost:8080/guacamole --username guacadmin --password guacadmin --display 1366x768@96

- Без установки (pnpm dlx):
  - pnpm dlx @horuzhenko/mcp-guac@6.0.27 serve --guac-url http://localhost:8080/guacamole --username guacadmin --password guacadmin --display 1366x768@96

Примечание: CLI поднимает STDIO-сервер и ждёт подключение MCP-клиента. Подключение/аутентификация к Guacamole выполняется инструментом session.connect на стороне клиента.

## Интеграция с редакторами (MCP)

### Cursor IDE
1) Settings → Features → Model Context Protocol (MCP) → Add Server
2) Вариант через pnpm dlx:
   - Command: pnpm
   - Args:
     dlx, @horuzhenko/mcp-guac@6.0.27, serve, --guac-url, http://localhost:8080/guacamole, --username, guacadmin, --password, guacadmin, --display, 1366x768@96
3) Вариант при глобальной установке:
   - Command: mcp-guac
   - Args:
     serve, --guac-url, http://localhost:8080/guacamole, --username, guacadmin, --password, guacadmin, --display, 1366x768@96

Пример конфигурации (settings.json):

```
"mcpServers": {
  "guac": {
    "command": "pnpm",
    "args": ["dlx", "@horuzhenko/mcp-guac@6.0.27", "serve", "--guac-url", "http://localhost:8080/guacamole", "--username", "guacadmin", "--password", "guacadmin", "--display", "1366x768@96"]
  }
}
```

### Claude Desktop
1) Settings → Integrations → Model Context Protocol → Add Local MCP Server
2) Вариант через pnpm dlx (рекомендуется):
   - Command: pnpm
   - Args: dlx, @horuzhenko/mcp-guac@6.0.27, serve, --guac-url, http://localhost:8080/guacamole, --username, guacadmin, --password, guacadmin, --display, 1366x768@96
3) Вариант при глобальной установке: Command: mcp-guac, Args: serve, ...

После добавления сервера Claude сможет вызывать инструменты: session.connect → screen.screenshot → input.* → clipboard.* → session.disconnect.

### VS Code — Cline
1) Установите расширение Cline
2) Откройте Settings (JSON) и добавьте:

```
"cline.mcpServers": {
  "guac": {
    "command": "pnpm",
    "args": ["dlx", "@horuzhenko/mcp-guac@6.0.27", "serve", "--guac-url", "http://localhost:8080/guacamole", "--username", "guacadmin", "--password", "guacadmin", "--display", "1366x768@96"]
  }
}
```

### Windsurf (Codeium)
1) Settings → MCP → Add Server
2) Укажите команду/аргументы аналогично Cursor/Claude (npx или глобальный бинарь).

## Дополнительные примеры
- Клик левой кнопкой 1x:
```
{ "sessionId": "<SESSION_ID>", "x": 200, "y": 150, "button": "left", "count": 1 }
```
- Двойной клик:
```
{ "sessionId": "<SESSION_ID>", "x": 200, "y": 150, "button": "left", "count": 2 }
```
- Буфер обмена (get/set):
```
{ "sessionId": "<SESSION_ID>" }
{ "sessionId": "<SESSION_ID>", "text": "Hello", "mime": "text/plain" }
```

## Troubleshooting
- Запуск через npx может конфликтовать с pnpm-глобалом:
  - Рекомендуем: pnpm dlx @horuzhenko/mcp-guac@6.0.27 serve
- Node.js < 20:
  - Обновите Node до 20+ (пакет требует современную поддержку ESM)
- Node.js 22 + canvas:
  - Если запускаете опубликованную версию 6.0.8 и видите ошибку про canvas.node, временно используйте Node 20.x LTS (nvm use 20). В ближайшем релизе переведём рендер на @napi-rs/canvas без системных зависимостей.
- Сервер "ничего не делает":
  - Это нормально: STDIO-сервер ждёт MCP-клиента. Проверьте конфигурацию клиента/редактора.
- Аутентификация Guacamole не происходит на старте:
  - Верно: авторизация выполняется инструментом session.connect из клиента. Передайте baseUrl/username/password в вызове инструмента.
- Проблема с кавычками в --display:
  - Допустимы оба варианта: 1366x768@96 или "1366x768@96". На Windows используйте двойные кавычки.
- Ошибки доступа/Permission denied:
  - Для глобальной установки используйте npm i -g, затем запускайте mcp-guac. Для npx проблем быть не должно.