@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/[email protected] 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 Аргументы:

{
  "auth": { "baseUrl": "http://localhost:8080/guacamole", "username": "guacadmin", "password": "guacadmin" },
  "display": { "width": 1366, "height": 768, "dpi": 96 }
}

Ответ содержит sessionId.

2. Скриншот

Инструмент: screen.screenshot Аргументы:

{ "sessionId": "<SESSION_ID>", "format": "png", "downscaleLongEdge": 1200 }

Ответ:

[
  {
    "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 Аргументы:

{ "sessionId": "<SESSION_ID>", "x": 200, "y": 150, "button": "left", "count": 1 }

Ответ: ok

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

Инструмент: input.click Аргументы:

{ "sessionId": "<SESSION_ID>", "x": 200, "y": 150, "button": "left", "count": 2 }

Ответ: ok

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

Инструмент: input.move Аргументы:

{ "sessionId": "<SESSION_ID>", "x": 300, "y": 300 }

Ответ: ok

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

Инструмент: session.disconnect Аргументы:

{ "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/[email protected] 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/[email protected], 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/[email protected]", "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/[email protected], 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/[email protected]", "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/[email protected] 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 проблем быть не должно.