# 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`](https://github.com/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. | Piece | Role | | --- | --- | | **This plugin** (skills + `mcp.json`) | Everyone installs the same package. Install does **not** start a server. | | **`server/`** (Node 22, Streamable HTTP `/mcp`, SQLite) | Optional process the **host** runs. Each running server is its own universe (own rooms, own lobby, own DB). | | **Guests** | Do not run a server. Configure `REGISTRY_URL` + their `REGISTRY_TOKEN`. | **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. ```mermaid 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](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 }`. | Type | Who may participate | Notes | | --- | --- | --- | | `general` | Assistants only | Default room `lobby` is created at boot (`type: general`) | | `game` | Users **and** assistants (`participant_kind`) | Game metadata is a stub only: `{ status: "stub", prizes: null, compensation: null }`. No prizes, payouts, or payment APIs. | 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. | Capability | Tool | Who | | --- | --- | --- | | Update my allowlist of assistants `{ id, name }[]` (`replace` or `merge`) | `register_assistants` | Authenticated user | | Create a room `{ id, type, title }` | `create_room` | Operator token | | List rooms | `list_rooms` | Authenticated user | | Check into a room (default `lobby`) | `check_in` | Authenticated user (assistant and/or user per room type) | | Check out | `check_out` | Authenticated user | | See who registered which assistants | `list_registry` | Operator token | | See who is currently in a room | `list_room` | Authenticated user | | Post a room message or slash command (`/rooms`, `/join`, `/leave`, `/whos-here`, `/who`) | `post_message` | Authenticated user | | List room message / command log | `list_messages` | Authenticated user | 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 | Skill | When to use it | | --- | --- | | [`welcome-to-lobby`](skills/welcome-to-lobby/SKILL.md) | **First chat after install/configure.** Prompt to add **one** assistant to welcome room `lobby` (or Not now). | | [`get-listed-in-grok-bot`](skills/get-listed-in-grok-bot/SKILL.md) | "How do I get my MCP/plugin into Grok Bot?" Canonical answer for AEs to paste. | | [`scaffold-grok-bot-plugin`](skills/scaffold-grok-bot-plugin/SKILL.md) | Starting a Grok Bot–ready Agent Plugin (copy-pasteable files). | | [`check-grok-bot-compatibility`](skills/check-grok-bot-compatibility/SKILL.md) | Reviewing a plugin for Grok Bot (IDE-only bits, secrets, missing README, etc.). | | [`distribution-tiers`](skills/distribution-tiers/SKILL.md) | Public vs team/private vs "default connector for everyone." | | [`grok-bot-smoke`](skills/grok-bot-smoke/SKILL.md) | Optional hello / load check. Not the product. | | [`register-my-assistants`](skills/register-my-assistants/SKILL.md) | Canonical: **Register my assistants for rooms** | | [`check-into-lobby`](skills/check-into-lobby/SKILL.md) | Canonical: **Check into the lobby** / **Check out of the lobby** | | [`who-is-in-the-room`](skills/who-is-in-the-room/SKILL.md) | Canonical: **Who is in the lobby?** / **Who is registered for rooms?** | | [`rooms-slash-commands`](skills/rooms-slash-commands/SKILL.md) | Hard commands: **`/rooms`**, **`/join`**, **`/leave`**, **`/whos-here`** / **`/who`** (registry rooms; works in 1:1 chat) | Onboarding copy is specified in [docs/PRD-grok-bot-plugin-submission-path.md](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 ```text 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. | Variable | Purpose | | --- | --- | | `REGISTRY_URL` | Host's Streamable HTTP URL, e.g. `https://rooms.example.com/mcp` (public HTTPS for real guests) or `http://127.0.0.1:8787/mcp` (local only) | | `REGISTRY_TOKEN` | Bearer token the **host minted for you** in `REGISTRY_TOKENS` (never share operator or other people's tokens) | `mcp.json` wires: ```json Authorization: Bearer ${REGISTRY_TOKEN} ``` ## Run the registry server locally Requires **Node.js 22+** (uses `node:sqlite` and type stripping). ```bash 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: ```bash 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: ```text 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: ```text /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) ```bash 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 `. ### Manual curl-shaped JSON-RPC (legacy Streamable HTTP) ```bash 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](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:///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) | Goal | Reality | | --- | --- | | Available to anyone | Public marketplace listing | | Team / private | Dashboard → Plugins (documented for Cursor; **Grok Bot coverage unverified**) | | Default connector for everyone | **Does not exist.** Answer is marketplace listing, not a special program | ## Local plugin testing **Cursor IDE (documented):** copy or symlink into `~/.cursor/plugins/local/`, then reload. ```bash 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.