Grok → dot event bridge

MCP event bridge with D1 persistence, authenticated owner console, signed event subscriptions, a limited Grok MCP endpoint, and an asynchronous reply outbox.

This is a sanitized source snapshot of the deployed v17 application. The complete tracked source tree is included, with deployment examples substituted for private configuration. Deployment identifiers, production URLs, real test identifiers, credentials, messages, runtime databases, build outputs, and original Git history are excluded. All example hosts and deterministic test credentials are fixtures.

Development

Requires Node.js 22.13 or later (with node:sqlite support).

npm ci
node --test tests/*.test.mjs
npm run dev
npm run build

The frontend uses React/Vinext and Cloudflare Workers. D1 schema migrations are in drizzle/; do not edit already applied migrations. The DB binding is required.

Related MCP server: Agent Wire

Deployment

The included Sites integration expects ChatGPT Sites hosting and its trusted authenticated-user headers. An ordinary Worker deployment needs an equivalent trusted identity integration; never trust a user-supplied owner header.

1. Register a new Site or use your own existing Site. Replace YOUR_SITE_PROJECT_ID in .openai/hosting.json and the connection page/prompt with that Site's identifier. Replace https://bridge.example.com in source and tests with your own base URL.

2. Provision D1 and apply the checked-in migrations. Preserve the DB binding and the nodejs_compat and global_fetch_strictly_public compatibility flags in vite.config.ts.

3. Configure BRIDGE_OWNER_ID to the owner's Site-scoped user ID. Keep external ingress and Grok delivery disabled until configuration is complete.

4. Configure runtime secrets through the hosting provider, never in Git. The implementation reads BRIDGE_MCP_AUTHORIZATION, BRIDGE_INGRESS_SECRET, BRIDGE_GROK_BEARER_KEY, and other BRIDGE_* settings; inspect their validation in lib/ before enabling an integration. The MCP authorization value includes its Bearer prefix. The optional owner credential-copy flow must have an explicit expiration (BRIDGE_HANDOFF_EXPIRES_AT).

5. Set the Grok channel and approved webhook destination using BRIDGE_GROK_CHANNEL and BRIDGE_GROK_WEBHOOK_URL, then enable only the required ingress/delivery flags. Never copy a production webhook key into documentation or client code.

6. Use the official Sites site-workflow.mjs helper to build/package and publish to your own Site. Pass source credentials through stdin. This GitHub repository does not deploy to or modify the original Site.

Interfaces and behavior

• /: authenticated owner console; /connect/grok: protected credential handoff/configuration page.

• /mcp: owner tools and MCP event subscriptions.

• /mcp/grok: limited Grok submission/result/reply tools using a separate authorization header.

• lib/bridge-service.mjs: persistence, ownership checks and dispatch.

• lib/bridge-protocol.mjs: strict payload validation, HMAC signatures and callback validation.

• lib/grok-outbox.mjs: bounded retries and delivery state; HTTP 200 confirms acceptance, not completion.

Messages are deduplicated by stable ID. A Grok reply receipt terminates the roundtrip with hop=2. External message text is data, never permission to run commands or disclose private information. The owner test endpoint can advance queued deliveries; tests against a real deployment have side effects and need explicit authorization.

License

Project-authored code is MIT licensed. Bundled third-party notices are retained; see THIRD_PARTY_NOTICES.md. Dependency packages retain their own licenses.