GrokBot ↔ Hermes Bridge

Самостоятельно размещаемый MCP-шлюз и шаблон плагина агента, который позволяет Grok Bot общаться с вашим существующим агентом Hermes. Grok Bot остаётся интерфейсом чата; Hermes работает на вашей машине и формирует ответ.

Репозиторий не зависит от оператора: он не содержит живых конечных точек, токенов, имен хостов, частных адресов, пользовательских путей, учетных записей или переписок.

Быстрый старт

Linux или macOS, одной проверяемой командой:

git clone https://github.com/iamsupersocks/grokbot-hermes-bridge.git && cd grokbot-hermes-bridge && ./scripts/install.sh

Уже клонировано:

./scripts/install.sh
python3 scripts/doctor.py

Установщик локальный и проверяемый. Он не загружает удаленную оболочку, не использует sudo, не запускает шлюз и не записывает реальное публичное имя хоста, если вы его не передадите. Для проверки и тестов доступны неинтерактивный режим и режим пробного запуска:

./scripts/install.sh --dry-run --non-interactive
./scripts/install.sh --non-interactive --endpoint https://mcp.example.com/mcp

Затем заполните оставшиеся локальные пути в .env.local (режим 600, никогда не коммитьте его). Код владельца генерируется на диске; не вставляйте его в чат. См. docs/TUTORIAL.md для иллюстрированного руководства. Doctor намеренно остаётся красным, пока пример имени хоста или пути Hermes всё ещё являются заглушками.

Related MCP server: lighthouse-mcp-oauth

Как это работает

1. Шлюз работает рядом с вашей установкой Hermes и предоставляет ровно два MCP-инструмента: hermes_ask и hermes_status.

2. HTTPS-обратный прокси или туннель делает /mcp доступным из Grok Bot.

3. Grok Bot обнаруживает OAuth-поток шлюза. Вы одобряете подключение в браузере с помощью приватного кода владельца, хранящегося только в окружении сервера.

4. Плагин отправляет запросы пользователя в Hermes и возвращает ограниченный ответ.

Здесь нет SSH-конечной точки, универсального инструмента оболочки, дампа окружения или закоммиченных учетных данных. Код владельца не принимается в качестве MCP-токена носителя.

Требования

• Python 3.11+

• Рабочий CLI hermes и домашний каталог Hermes на машине шлюза

• Публичное HTTPS-имя хоста или туннель, перенаправляющий на 127.0.0.1:8099

• Grok Bot, Codex, Cursor или другой Streamable HTTP MCP-клиент с OAuth

Запуск шлюза

После установщика (или эквивалентной локальной настройки venv + .env.local):

. .venv/bin/activate
set -a
. ./.env.local
set +a
python -m hermes_gateway.mcp --host 127.0.0.1 --port 8099

Как минимум .env.local должен содержать:

HERMES_BRIDGE_SECRET=<64-random-hex-characters>
HERMES_BRIDGE_PUBLIC_BASE_URL=https://mcp.example.com
HERMES_BRIDGE_ALLOWED_HOSTS=localhost,127.0.0.1,mcp.example.com
HERMES_BRIDGE_HERMES_BIN=/absolute/path/to/hermes
HERMES_BRIDGE_HERMES_HOME=/absolute/path/to/hermes-home

GET /health должен возвращать {"status":"ok"}. Поместите HTTPS перед сервисом; не открывайте порт 8099 напрямую. См. deploy/ для общих примеров.

Настройка плагина

Установщик вызывает scripts/configure_plugin.py за вас. Чтобы повторить:

python scripts/configure_plugin.py https://mcp.example.com/mcp

Сгенерированный конфиг содержит только URL. Не добавляйте заголовок Authorization: Grok Bot использует обнаружение OAuth и PKCE для получения собственного токена доступа.

Установите или упакуйте эту папку как плагин, перезапустите Grok Bot, затем включите коннектор. Первое подключение открывает страницу одобрения. Введите тот же код владельца, который хранится в HERMES_BRIDGE_SECRET.

Добавление Composio рядом с этим мостом

Совет Corey Ganim по Grok Bot использует Composio Connect, чтобы выйти за пределы встроенного каталога коннекторов клиента. Composio описывает Connect как одну размещённую MCP-конечную точку для 1000+ приложений через 7 мета-инструментов. Это не буквально каждый MCP-сервер, и он не входит в этот репозиторий.

Держите два подключения раздельно:

Манифесты .grok-plugin, .cursor-plugin и .codex-plugin здесь устанавливают только мост Hermes. Трафик Composio не проходит через Hermes, и Composio не заменяет этот мост. См. руководство для полной модели настройки и границ безопасности.

Ограничение видимого сообщения Grok Bot

Grok Bot в настоящее время выводит короткое видимое сообщение перед каждым вызовом инструмента, например «Я передам это Hermes». Плагин не может скрыть или удалить этот шаг на уровне хоста. Встроенный навык делает его кратким и предотвращает выдачу Grok Bot за Hermes.

Модель безопасности

• фиксированный исполняемый файл Hermes; без вызова оболочки

• ограниченные промпт, вывод, количество ходов, таймаут, полезная нагрузка, частота и параллелизм

• минимальное окружение дочерних процессов

• обнаружение OAuth, динамическая регистрация клиентов, код авторизации + PKCE, подписанные токены доступа и токены обновления

• требуется одобрение владельца; код владельца никогда не работает как токен носителя

• проверки хоста/источника, защита от DNS-ребinding, привязка только к localhost, редактирование журналов и фильтрованный вывод статуса

• отказ при запуске, если конечная точка, код владельца, бинарник Hermes или домашний каталог Hermes недействительны

Провайдер OAuth намеренно однопользовательский. Зарегистрированные клиенты сохраняются локально в JSON-файле с режимом 0600; ожидающие одобрения и коды авторизации находятся в памяти. Ротация HERMES_BRIDGE_SECRET аннулирует выданные токены.

Тестирование и аудит

python -m pip install -e '.[dev]'
python -m unittest discover -s tests -v
python src/privacy_scan.py --root .
python scripts/audit_git_history.py
python3 scripts/doctor.py

Также прочтите SECURITY.md перед открытием конечной точки. Этот репозиторий начался с новой публичной истории Git; он не наследует историю приватной реализации.

Лицензия

MIT. См. LICENSE.