GrokBot ↔ Hermes ブリッジ

自己ホスト型のMCPゲートウェイ兼Agent Pluginテンプレートで、Grok Botを既存のHermes Agentと連携させることができます。Grok Botはチャットインターフェースのままで、Hermesがお使いのマシン上で実行され、回答を生成します。

このリポジトリはオペレーター非依存です。実在のエンドポイント、トークン、ホスト名、プライベートアドレス、ユーザーパス、アカウントハンドル、会話は一切含まれていません。

クイックスタート

LinuxまたはmacOSで、監査可能な1つのコマンドで実行できます:

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も使用せず、ゲートウェイを起動せず、指定しない限り実際の公開ホスト名を書き込みません。レビューとテスト用に非対話モードとドライラン（dry-run）モードが用意されています:

./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のインストール先の隣で実行され、hermes_askとhermes_statusの正確に2つのMCPツールを公開します。

2. HTTPSリバースプロキシまたはトンネルにより、/mcpがGrok Botから到達可能になります。

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エンドポイント1つとして説明しています。これは文字通りすべてのMCPサーバーというわけではなく、このリポジトリにバンドルされているわけでもありません。

2つの接続は分けて管理してください:

ここにある.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を参照してください。