GrokBot ↔ Hermes 브리지

Grok Bot이 기존 Hermes Agent와 통신할 수 있게 해주는 자체 호스팅 MCP 게이트웨이 및 Agent Plugin 템플릿입니다. 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를 참조하십시오. 예제 호스트 이름 또는 Hermes 경로가 여전히 자리 표시자인 동안 Doctor는 의도적으로 빨간색으로 유지됩니다.

Related MCP server: lighthouse-mcp-oauth

작동 방식

1. 게이트웨이는 Hermes 설치 옆에서 실행되며 정확히 두 개의 MCP 도구(hermes_ask 및 hermes_status)를 노출합니다.

2. HTTPS 리버스 프록시 또는 터널이 Grok Bot에서 /mcp에 도달할 수 있게 합니다.

3. Grok Bot이 게이트웨이의 OAuth 흐름을 발견합니다. 서버 환경에만 저장된 비공개 소유자 코드로 브라우저에서 연결을 승인합니다.

4. 플러그인은 사용자 요청을 Hermes로 보내고 제한된 응답을 반환합니다.

SSH 엔드포인트, 일반 셸 도구, 환경 덤프 또는 커밋된 자격 증명이 없습니다. 소유자 코드는 MCP 베어러 토큰으로 허용되지 않습니다.

요구 사항

• Python 3.11+

• 게이트웨이 머신에서 작동하는 hermes CLI 및 Hermes 홈 디렉터리

• 127.0.0.1:8099로 전달되는 공개 HTTPS 호스트 이름 또는 터널

• OAuth를 지원하는 Grok Bot, Codex, Cursor 또는 기타 Streamable HTTP MCP 클라이언트

게이트웨이 실행

설치 프로그램(또는 동등한 로컬 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를 7개의 메타 도구를 통해 1000개 이상의 앱을 위한 하나의 호스팅 MCP 엔드포인트로 설명합니다. 말 그대로 모든 MCP 서버는 아니며, 이 저장소에 번들로 포함되어 있지 않습니다.

두 연결을 분리하여 유지하십시오:

여기의 .grok-plugin, .cursor-plugin 및 .codex-plugin 매니페스트는 Hermes 브리지만 설치합니다. Composio 트래픽은 Hermes를 통과하지 않으며 Composio가 이 브리지를 대체하지 않습니다. 전체 설정 모델 및 안전 경계는 튜토리얼을 참조하십시오.

Grok Bot의 표시 메시지 제한

Grok Bot은 현재 모든 도구 호출 전에 "Hermes로 전달하겠습니다."와 같은 짧은 표시 메시지를 출력합니다. 플러그인은 이 호스트 수준 단계를 숨기거나 제거할 수 없습니다. 번들된 스킬은 이를 간결하게 유지하고 Grok Bot이 Hermes를 사칭하지 못하게 합니다.

보안 모델

• 고정 Hermes 실행 파일, 셸 호출 없음

• 제한된 프롬프트, 출력, 턴, 타임아웃, 페이로드, 속도 및 동시성

• 최소 하위 프로세스 환경

• OAuth 검색, 동적 클라이언트 등록, 인증 코드 + PKCE, 서명된 액세스 토큰 및 리프레시 토큰

• 소유자 승인 필요, 소유자 코드는 베어러 토큰으로 작동하지 않음

• 호스트/오리진 검사, DNS 리바인딩 보호, localhost 전용 바인딩, 로그 편집 및 필터링된 상태 출력

• 엔드포인트, 소유자 코드, Hermes 바이너리 또는 Hermes 홈이 유효하지 않은 경우 실패 시 종료

OAuth 공급자는 의도적으로 단일 소유자입니다. 등록된 클라이언트는 모드 0600 JSON 파일에 로컬로 유지됩니다. 보류 중인 승인 및 인증 코드는 메모리에 있습니다. 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를 참조하십시오.