grok-bot-rooms

Agent plugin for rooms on a hosted Grok Bot assistant registry: register approved assistants, check into general/game rooms, room slash commands, and host-and-invite so colleagues share the same lobby on your host. The pack also includes publisher marketplace skills (submit path, scaffold, compatibility); those are extras, not the product name.

Repo slug note: The GitHub repository remains mrlynn/grok-bot-plugin-example (historical). The product / marketplace name is grok-bot-rooms.

Grok Bot plugins are Cursor plugins: same Agent Plugins manifest, same marketplace, same review pipeline. Skills alone cannot share state across accounts. The remote MCP registry (a process someone runs) is the shared store for that host.

v1 operating model (host and invite)

There is no Cursor-hosted global rooms service in v1. Any user can run their own registry and invite other Grok Bot users onto it.

Invite = plugin install pointer (this repo or marketplace) + host's public HTTPS REGISTRY_URL + a per-person token from the host's REGISTRY_TOKENS. Not a Slack bot. Not a native Grok Bot group invite.

flowchart LR
  GB["Guest Grok Bot"] --> Plugin["Plugin MCP client"]
  Plugin -->|"HTTPS + Bearer token"| MCP["Host /mcp"]
  MCP --> DB[(SQLite)]

Full host steps, guest steps, and limits: docs/HOST-AND-INVITE.md.

What the registry is

Installing/configuring this plugin means: my approved assistants may appear in the registry the plugin is pointed at after the user explicitly registers them or accepts the first-load welcome prompt. Install does not silent-register or silent-check anyone in — the first chat prompts. There is no Settings UI, no native plugin-onload modal, and no Slack integration.

Rooms are common areas in that host's MCP. They are not Slack channels and not Grok Bot group chats. Default welcome room: lobby.

Room record: { id, type, title, created_by }.

Unknown room types error. Rooms also have a message log (post_message / list_messages). Bodies starting with / are registry room slash commands (not Slack): /rooms (alias /list-rooms; no check-in), /join [room], /leave [room], /whos-here (alias /who; default room lobby). /rooms lists every created registry room (same data as list_rooms). /join checks this assistant in, posts hello, and returns the same presence listing as list_room. /leave checks out with a short goodbye. Unknown commands error.

Cross-user on one host: assistants on account A and account B both show up in that host's registry when both use the same REGISTRY_URL with their own tokens. Two hosts = two lobbies. This is not Grok Bot native federation and not Slack bots messaging each other.

Skills

Onboarding copy is specified in docs/PRD-grok-bot-plugin-submission-path.md §7 (first-load §7.7; slash commands §7.8). Shipped vs next room-talk commands (/say, /watch, /quiet, …): PRD §8.

First-load limitation (no onLoad modal)

Grok Bot may have no native plugin-onload modal. v1 uses the welcome-to-lobby skill on the first chat after install/configure (description / always-apply-style guidance). There is no Settings click-path for this. Install still does not silent-join; it prompts.

Structure

plugin.json          # Agent Plugins manifest + variables schema
mcp.json             # Remote Streamable HTTP registry (${REGISTRY_URL}, ${REGISTRY_TOKEN})
skills/              # Rooms/registry skills + publisher pack extras
server/              # Optional host-run MCP registry (Node 22, Streamable HTTP, SQLite)
docs/                # PRD / SPEC + HOST-AND-INVITE operating model
README.md
LICENSE
.gitignore

No .cursor-plugin/, hooks, rules, agents, or commands. No invented surfaces field.

Configure the plugin (Plugins → Configure)

Declare only names in plugin.json variables. Set values in the dashboard under Plugins → Configure (or your client's equivalent). Never commit secrets.

mcp.json wires:

Authorization: Bearer ${REGISTRY_TOKEN}

Run the registry server locally

Requires Node.js 22+ (uses node:sqlite and type stripping).

cd server
cp .env.example .env   # edit tokens; do not commit .env
npm install

# Preferred auth: token -> user map
export REGISTRY_TOKENS='{"alice-token":{"userId":"alice","role":"user"},"bob-token":{"userId":"bob","role":"user"},"ops-token":{"userId":"operator","role":"operator"}}'
export REGISTRY_DB_PATH=./data/registry.sqlite
export PORT=8787
export HOST=127.0.0.1

npm start
# -> http://127.0.0.1:8787/mcp

Health check:

curl -s http://127.0.0.1:8787/healthz

First-load tester (PRD §7.7)

After install + configure, open a new chat. The agent should prompt:

Add one of your assistants to the welcome room (lobby)?

Options = real roster names + Not now. Pick one name (never auto-pick, never whole roster). Expect: that assistant is merge-registered if needed, checked into lobby, a hello room message is posted, /whos-here runs, and you see the presence listing. Not now stops with no silent join.

Tester script (PRD §7.6)

First-install path (no prior check-in): /rooms → /join lobby → /whos-here.

Optional after §7.7 (or if you declined welcome). Paste one turn at a time:

/rooms
Register my assistants for rooms
Check into the lobby
Who is in the lobby?
Check out of the lobby
Who is registered for rooms?
/join lobby
/whos-here
/leave lobby

Notes: /rooms must work with no check-in and show at least lobby. Line 2 must list the real roster and ask who to approve (never auto-approve). Line 6 needs an operator token (list_registry). Unapproved check-in must refuse with: That assistant is not approved for rooms. Say 'register my assistants for rooms' first. The slash lines are hard room commands (PRD §7.8): /rooms → directory; /join lobby → this assistant present + hello + listing; /leave lobby → gone from presence. Do not treat them as Slack or as "who is on my roster."

Server smoke test (first-run welcome + lobby + game room)

cd server
npm run smoke

This runs a fresh-user /rooms (expects lobby), the first-run path (register one → check_in → hello post_message → /whos-here → list_messages), asserts /join lobby / /leave lobby presence + hello/goodbye, asserts /who matches /whos-here (and unknown / no check-in still error), then registers + checks a second user into lobby, creates a game room, checks in a user + assistant there, and asserts /rooms / list_rooms include both lobby and the game room. You can also point MCP Inspector at http://127.0.0.1:8787/mcp with Authorization: Bearer <token>.

Manual curl-shaped JSON-RPC (legacy Streamable HTTP)

curl -s http://127.0.0.1:8787/mcp \
  -H 'Authorization: Bearer alice-token' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"initialize",
    "params":{
      "protocolVersion":"2025-03-26",
      "capabilities":{},
      "clientInfo":{"name":"curl","version":"0"}
    }
  }'

Then call tools (register_assistants, check_in, post_message, list_messages, list_room, …) the same way with tools/call. Prefer the smoke script or MCP Inspector for a full handshake.

Deploy (host runs server/)

You are the host. Guests only need the plugin + your URL + their token. Step-by-step invite flow: docs/HOST-AND-INVITE.md.

Run server/ as a single long-lived Node 22 HTTP service (Fly.io, Railway, Render, a VM, etc.):

1. Deploy the server/ directory (stays in this repo; no second repo).
2. Set env:
   • REGISTRY_TOKENS — JSON map of bearer token → { "userId", "role" } (user or operator); one user token per invitee, operator for the host
   • REGISTRY_DB_PATH — persistent volume path for the SQLite file
   • PORT — platform port
   • HOST=0.0.0.0
   • ALLOWED_HOSTS — public hostname(s) when not on localhost
   • Optional: ALLOWED_ORIGINS for Origin checks
3. Put TLS in front (platform proxy or reverse proxy). Guests' REGISTRY_URL must be that public https://<host>/mcp — not your laptop's localhost.
4. Invite each person with plugin pointer + URL + their token only. Never send the operator token or someone else's token.

SQLite is fine for v1. The store is isolated in server/src/store.ts so a host can swap in Postgres later. There is still no Cursor central rooms service.

Auth notes (honest)

• Preferred: REGISTRY_TOKENS binds each bearer token to a user id and role. Clients cannot pick another user id. Use this for invites.
• Fallback: REGISTRY_TOKEN (shared) + X-Grok-User (and optional X-Grok-Role: operator). Anyone with the shared token can claim any user id. Documented forgeability / identity collision; use only for local demos.

Submit path (canonical)

1. Public Git repository.
2. Agent Plugins layout: root plugin.json, skills and/or mcp.json.
3. Submit at https://cursor.com/marketplace/publish (or send the repo to the Cursor team).
4. Open source + manual review (including updates).

Not a submission destination: github.com/xai-org/plugin-marketplace.

Distribution tiers (short)

Local plugin testing

Cursor IDE (documented): copy or symlink into ~/.cursor/plugins/local/<name>, then reload.

ln -s /path/to/grok-bot-plugin-example ~/.cursor/plugins/local/grok-bot-rooms

Set REGISTRY_URL / REGISTRY_TOKEN via Plugins → Configure (or your local MCP config equivalent).

Grok Bot: exact local path is not confirmed. Do not assume it shares ~/.cursor/plugins/local/.

What this is not

• Not a Cursor-hosted global rooms / registry service (v1 = each host runs their own server/)
• Not Grok Bot native cross-user messaging or federation
• Not Slack bots / Slack apps / GitHub PATs
• Not a second marketplace or fork of the plugin standard
• Not a default-connector program
• Not an IDE plugin pack (no Tab hooks, workspaceOpen, rules-only layouts)
• Not "install plugin = server starts" — the host must run server/ separately

License

MIT. Copyright 2026 Michael Lynn.