RKDash Adapter for Hermes Agent

Адаптер для Hermes Agent, который подключает агента, живущего на своём сервере, к платформе ресторанной аналитики RKDash.

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

Что даёт адаптер

• Инструменты платформы — MCP-сервер rkdash с 26 инструментами: заведения, меню и фудкост, чеки и продажи, официанты, склад, дашборды, интеграции, доска задач, вопросы к AI-агенту. Инструменты — те же операции, что доступны человеку в панели: прав у агента не больше, чем у ключа.

• Навык платформы — регламент работы: какой инструмент под какую задачу, формат ответа, что запрещено.

• Работа по задачам с доски — задача, назначенная агенту, доходит до него прогоном; отчёт агент оставляет комментарием в карточке.

• Забор задач самим агентом — если платформа не может достучаться до сервера агента (агент за NAT), он забирает назначенное сам запросом GET /api/v1/agent-tasks.

Related MCP server: Toast MCP Server

Архитектура

Hermes-агент (свой сервер)
      │  инструменты / MCP                     агент → RKDash
      ▼
RKDash: /api/mcp  +  /api/v1 (ключ агента, права, идемпотентность, журнал)
      ▲
      │  прогон по задаче с доски              RKDash → агент
      └── POST /v1/runs + поток событий по SSE (служба агента, API_SERVER_ENABLED=true)

Установка

Быстро: дайте агенту ссылку на этот репозиторий

Агент прочитает AGENTS.md, задаст вам два вопроса (ключ платформы и режим работы) и настроит себя сам. Ключ берётся в панели RKDash: Цифровые сотрудники → карточка исполнителя → «Комплект для установки».

Вручную

Требуется Hermes Agent и Python 3.10+.

git clone https://github.com/geniok1980/hermes-rkdash-adapter.git
RKDASH_KEY=rk_live_… sh hermes-rkdash-adapter/install.sh

Либо одной строкой, без клонирования (установщик скачает навык сам):

curl -fsSL https://raw.githubusercontent.com/geniok1980/hermes-rkdash-adapter/main/install.sh \
  | RKDASH_KEY=rk_live_… sh

Установщик:

1. ставит навык платформы в навыки нужного профиля;

2. прописывает MCP-сервер rkdash в config.yaml этого профиля, не трогая чужие серверы;

3. проверяет связь (hermes mcp test rkdash) и показывает, сколько инструментов найдено;

4. добавляет в окружение профиля блок службы, к которой обращается платформа.

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

Переменные установщика

Что остаётся человеку

1. Включить службу агента, чтобы платформа могла звать его прогоном:

   API_SERVER_ENABLED=true
   API_SERVER_HOST=0.0.0.0
   API_SERVER_PORT=9131
   API_SERVER_KEY=<свой секрет>

   Адрес снаружи — только по https; это отдельная служба со своим ключом, не равная ключу платформы.

2. Завести агента в панели: «Цифровые сотрудники → Подключить агента», транспорт «Внешний агент по API server», адрес агента и его API_SERVER_KEY. Кнопка «Проверить» идёт тем же транспортом, что и задача.

3. Включить MCP-сервер в «Настройки → API». Пока он выключен, агент подключён, но инструментов не видит.

Проверка

sh verify.sh                 # навык, конфиг, связь, служба агента
hermes mcp test rkdash       # связь с платформой и список инструментов

В панели: карточка исполнителя показывает, когда агент отвечал последний раз, сколько прогонов прошло и сколько из них с ошибкой.

Безопасность

• Ключ платформы — это права агента: создавайте его под конкретного исполнителя и давайте только нужные области доступа. Инструменты изменения (цены, склад) требуют явного разрешения в карточке исполнителя.

• Ключ агента (API_SERVER_KEY) на стороне платформы хранится зашифрованным и наружу не отдаётся.

• Навык и установщик секретов не содержат: ключ передаётся при запуске и в репозиторий не попадает.

Документация

• Живая документация и песочница API: https://rkdash.com/docs/api

• Адаптер со стороны платформы описан в репозитории платформы: docs/hermes-adapter.md.

Лицензия

MIT — см. LICENSE.