Отказ от ответственности: Это независимый проект, созданный сообществом, и он не связан с KegLand или RAPT.io, не одобрен ими и не поддерживается ими. RAPT, RaptPill и KegLand являются товарными знаками их соответствующих владельцев и упоминаются здесь исключительно для описания совместимости. Программное обеспечение предоставляется как есть, без каких-либо гарантий — см. LICENSE, где приведены полные условия, включая дополнительное пояснение простым языком, касающееся использования данным проектом неподдерживаемого стороннего API.

RAPT.io MCP Server

MCP-сервер (Model Context Protocol) для мониторинга и управления устройствами KegLand RAPT — ферментационными камерами и гидрометрами RaptPill — через RAPT.io API.

⚠️ По умолчанию — только чтение. RAPT.io API не поддерживается и не документирован для большинства изменяющих операций (см. Примечания по безопасности и использованию API ниже). Этот сервер отклоняет все POST-запросы к RAPT.io API, если оператор явно не установит RAPTIO_MCP_READ_ONLY=false.

Возможности

Ферментационная камера

• Получить список всех ферментационных камер

• Получить статус (температура, нагрев/охлаждение, PID, время работы)

• Получить историю телеметрии

• (при RAPTIO_MCP_READ_ONLY=false) Установить целевую температуру, включить/отключить PID, настроить параметры PID

RaptPill (гидрометр)

• Получить список всех гидрометров RaptPill

• Получить статус (плотность, температура, уровень заряда батареи)

• Получить историю телеметрии

Общее

• Получить список всех сопряжённых устройств

• Управлять профилями ферментации и просматривать их

Некоторые ранее доступные управляющие инструменты (переключение нагрева/охлаждения/вентилятора/освещения, гистерезис, задержка компрессора/смены режима) были удалены в ожидании проверки соответствующего API endpoint. См. Удалённые инструменты ниже.

Related MCP server: RAPT.io MCP Server

Установка

Требования

• Python 3.11+

• uv (рекомендуется) или pip

Установка через uv

uv sync --frozen

Установка через pip

pip install -e .

Аутентификация

Этот сервер аутентифицируется в RAPT.io API с помощью вашего имени пользователя RAPT.io и API Secret (не пароля от учётной записи).

1. Войдите в RAPT Portal.

2. Перейдите в раздел My Account → API Secrets (https://app.rapt.io/account/apisecrets).

3. Нажмите Add API Secret и сразу же сохраните значение — оно хэшируется на стороне сервера, и позже получить его будет невозможно.

Не используйте ваш настоящий пароль от учётной записи в качестве RAPT_API_SECRET. API Secret — это отдельные, независимо отзываемые учётные данные: даже если они утекут, вы можете пересоздать их через портал, не затрагивая ваш основной вход в учётную запись.

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

Задайте следующие переменные окружения:

Использование

Запуск напрямую (Streamable HTTP)

RAPT_USERNAME="you@example.com" \
RAPT_API_SECRET="your-api-secret" \
RAPTIO_MCP_AUTH_TOKEN="$(openssl rand -hex 32)" \
  uv run raptio-mcp

Сервер прослушивает адрес http://<RAPTIO_MCP_HOST>:<RAPTIO_MCP_PORT>/mcp (транспорт Streamable HTTP, без состояния, ответы в JSON). Все запросы к /mcp требуют указанный выше bearer-токен. /healthz не требует аутентификации и предназначен для liveness/readiness-проверок со стороны оркестратора.

Подключение MCP-клиента

Настройте ваш MCP-клиент на использование транспорта Streamable HTTP, например:

claude mcp add --transport http raptio http://localhost:8000/mcp \
  --header "Authorization: Bearer <your RAPTIO_MCP_AUTH_TOKEN>"

В более ранних версиях этот сервер использовал транспорт stdio (для локального запуска в качестве дочернего процесса в Claude Desktop / Claude Code). Начиная с 0.2.0 сервер работает исключительно через Streamable HTTP, что требует указанного выше bearer-токена. Неявной доверительной границы на основе владельца процесса больше не существует, поэтому аутентификация обязательна.

Доступные инструменты

Пока значение RAPTIO_MCP_READ_ONLY=true (по умолчанию), три изменяющих инструмента по-прежнему присутствуют в списке (чтобы их схемы оставались обнаруживаемыми), но каждый вызов возвращает явную ошибку вместо обращения к RAPT.io API.

Удалённые инструменты

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

• set_fermentation_chamber_heating_enabled

• set_fermentation_chamber_cooling_enabled

• set_fermentation_chamber_fan_enabled

• set_fermentation_chamber_light_enabled

• set_fermentation_chamber_cooling_hysteresis

• set_fermentation_chamber_heating_hysteresis

• set_fermentation_chamber_compressor_delay

• set_fermentation_chamber_mode_switch_delay

Все они полагались на POST /api/FermentationChambers/UpdateFermentationChamber — конечную точку, которая не встречается в опубликованной спецификации RAPT.io API (https://api.rapt.io/swagger/v1/swagger.json) и не имеет задокументированного поведения при конкурентных запросах. Они будут возвращены только после того, как существование и безопасность этой конечной точки будут подтверждены на реальном аккаунте. (set_fermentation_chamber_light_enabled также раньше отправлял неверные значения enum — On/Off/Auto вместо правильных AlwaysOn/AlwaysOff/Automatic — и до повторного добавления потребуется применить и это исправление.)

Безопасность и примечания по использованию API

Публичный RAPT.io API явно позиционируется KegLand как неподдерживаемый:

«Доступ к API не поддерживается. Это означает, что вы не получите помощи от KegLand по любым вопросам, с которыми вы можете столкнуться при использовании API... если вы повредите устройство в результате неправильного использования API, гарантия аннулируется... API (endpoints, параметры, модели ответов и т.д.) может изменяться без предварительного уведомления». — https://docs.rapt.io/integrations/api-secrets

Исходя из этого, сервер по умолчанию придерживается консервативной политики:

• По умолчанию — только чтение (RAPTIO_MCP_READ_ONLY=true) — ни один запрос, изменяющий состояние устройства, не отправляется, если это не было явно включено.

• Используются только официально задокументированные конечные точки — SetTargetTemperature, SetPIDEnabled, SetPID; все они подтверждены в опубликованной Swagger-спецификации RAPT.io.

• Не документированные конечные точки не используются — см. Удалённые инструменты.

• Аутентификация обязательна на HTTP-транспорте (RAPTIO_MCP_AUTH_TOKEN), поскольку Streamable HTTP убирает неявную границу доверия, которую прежняя модель stdio-подпроцесса предоставляла бесплатно.

• Все вызовы изменяющих инструментов записываются в журнал аудита (имя инструмента, аргументы, результат) в структурированные журналы сервера.

Если вы указываете RAPTIO_MCP_READ_ONLY=false, вы сознательно соглашаетесь отправлять команды на физическое пивоваренное/ферментационное оборудование через API, которое KegLand может изменить или ограничить без уведомления. Любой ущерб или ограничение учётной записи, возникшие в результате такого использования, остаются на вашей ответственности в соответствии с положениями KegLand, приведёнными выше.

Детали процесса аутентификации

Внутри сервера ваши RAPT_USERNAME и RAPT_API_SECRET обмениваются на кратковременный bearer-токен через OAuth2 Resource Owner Password Credentials, обращаясь к https://id.rapt.io/connect/token, в соответствии с документированным процессом RAPT.io. Токены кэшируются в памяти и автоматически обновляются за ~30 секунд до истечения срока действия.

Лицензия

MIT