GrokBot ↔ Hermes Bridge

Un gateway MCP autoalojado y una plantilla de plugin de agente que permite que Grok Bot hable con tu agente Hermes existente. Grok Bot sigue siendo la interfaz de chat; Hermes se ejecuta en tu máquina y produce la respuesta.

El repositorio es independiente del operador: no contiene ningún endpoint en vivo, token, nombre de host, dirección privada, ruta de usuario, identificador de cuenta ni conversación.

Inicio rápido

Linux o macOS, en un solo comando auditable:

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

Ya clonado:

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

El instalador es local y auditable. No descarga un shell remoto, no usa sudo, no inicia el gateway y no escribe un nombre de host público real a menos que lo pases. Los modos no interactivo y de prueba en seco están disponibles para revisión y pruebas:

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

Luego completa las rutas locales restantes en .env.local (modo 600, nunca lo confirmes). El código de propietario se genera en disco; no lo pegues en el chat. Consulta docs/TUTORIAL.md para ver el tutorial ilustrado. Doctor permanece deliberadamente en rojo mientras el nombre de host de ejemplo o las rutas de Hermes sigan siendo marcadores de posición.

Related MCP server: lighthouse-mcp-oauth

Cómo funciona

1. El gateway se ejecuta junto a tu instalación de Hermes y expone exactamente dos herramientas MCP: hermes_ask y hermes_status.

2. Un proxy inverso HTTPS o túnel hace que /mcp sea accesible desde Grok Bot.

3. Grok Bot descubre el flujo OAuth del gateway. Apruebas la conexión en un navegador con un código de propietario privado almacenado solo en el entorno del servidor.

4. El plugin envía las solicitudes del usuario a Hermes y devuelve la respuesta limitada.

No hay endpoint SSH, herramienta de shell genérica, volcado de entorno ni credencial confirmada. El código de propietario no se acepta como token portador MCP.

Requisitos

• Python 3.11+

• Un CLI hermes funcional y un directorio de inicio de Hermes en la máquina del gateway

• Un nombre de host HTTPS público o túnel que reenvíe a 127.0.0.1:8099

• Grok Bot, Codex, Cursor u otro cliente MCP Streamable HTTP con OAuth

Ejecutar el gateway

Después del instalador (o la configuración local equivalente de venv + .env.local):

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

Como mínimo, .env.local debe contener:

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 debería devolver {"status":"ok"}. Pon HTTPS delante del servicio; no expongas el puerto 8099 directamente. Consulta deploy/ para ver ejemplos genéricos.

Configurar el plugin

El instalador llama a scripts/configure_plugin.py por ti. Para repetirlo:

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

La configuración generada contiene solo la URL. No agregues un encabezado Authorization: Grok Bot usa descubrimiento OAuth y PKCE para obtener su propio token de acceso.

Instala o empaqueta esta carpeta como plugin, reinicia Grok Bot y luego habilita el conector. La primera conexión abre la página de aprobación. Ingresa el mismo código de propietario almacenado en HERMES_BRIDGE_SECRET.

Añadir Composio junto a este puente

El consejo de Corey Ganim sobre Grok Bot usa Composio Connect para ir más allá del catálogo de conectores nativos de un cliente. Composio describe Connect como un endpoint MCP alojado para más de 1000 aplicaciones a través de 7 meta-herramientas. No es literalmente cada servidor MCP, y no está incluido en este repositorio.

Mantén las dos conexiones separadas:

Los manifiestos .grok-plugin, .cursor-plugin y .codex-plugin aquí instalan solo el puente de Hermes. El tráfico de Composio no pasa por Hermes y Composio no reemplaza este puente. Consulta el tutorial para ver el modelo de configuración completo y los límites de seguridad.

Limitación del mensaje visible de Grok Bot

Grok Bot actualmente emite un mensaje visible corto antes de cada llamada a herramienta, como "Lo pasaré a Hermes". El plugin no puede ocultar ni eliminar ese paso a nivel de host. La habilidad incluida lo mantiene breve y evita que Grok Bot se haga pasar por Hermes.

Modelo de seguridad

• ejecutable de Hermes fijo; sin invocación de shell

• prompt, salida, turnos, tiempo de espera, carga útil, tasa y concurrencia limitados

• entorno de proceso hijo mínimo

• descubrimiento OAuth, registro dinámico de clientes, código de autorización + PKCE, tokens de acceso firmados y tokens de actualización

• aprobación del propietario requerida; el código de propietario nunca funciona como token portador

• comprobaciones de host/origen, protección contra rebinding de DNS, enlace solo a localhost, redacción de registros y salida de estado filtrada

• inicio con fallo cerrado si el endpoint, el código de propietario, el binario de Hermes o el directorio de inicio de Hermes no son válidos

El proveedor OAuth es intencionalmente de un solo propietario. Los clientes registrados persisten localmente en un archivo JSON con modo 0600; las aprobaciones pendientes y los códigos de autorización están en memoria. Rotar HERMES_BRIDGE_SECRET invalida los tokens emitidos.

Pruebas y auditoría

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

También lee SECURITY.md antes de exponer el endpoint. Este repositorio comenzó con un historial de Git público nuevo; no hereda el historial de implementación privado.

Licencia

MIT. Ver LICENSE.