Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
docs(grok-bot): add the Grok Bot connector reference with runnable samples and a fix for every probe failure
nirholasae20babcd917
diff --git a/STRUCTURE.md b/STRUCTURE.mdindex 8eb7d7f57..df287c8c7 100644--- a/STRUCTURE.md+++ b/STRUCTURE.md@@ -231,6 +231,7 @@ bottom.| Escrowed knocks (pay-per-reply) | [contracts/knock-escrow/](contracts/knock-escrow) | In-repo | Anchor program making a knock's payment conditional instead of final: `knock` parks the price in a vault owned by the knock's own PDA, and only three things can happen to it. `answer` pays the owner minus a fee capped at 10% in the program itself, `refuse` refunds the sender in full and takes no fee, and `reclaim` refunds the sender once the reply window closes and can be called by anyone. Each `KnockRecord` snapshots the fee that was in force when it was made, so an authority cannot reprice money already in escrow, and it stores only the SHA-256 of the message and the reply, never their text. The trust-me version of this settles straight to the owner at [api/knock/](api/knock) (row above); this is the version that works between strangers. Both sides are reachable from a browser: senders escrow and crank their own refund from the door page, owners open their on-chain door, answer for payment or refuse for a refund from [/knock](pages/knock.html), all signed by their own wallet ([src/knock/escrow-checkout.js](src/knock/escrow-checkout.js)). Docs: [contracts/knock-escrow/README.md](contracts/knock-escrow/README.md), [docs/knock.md](docs/knock.md). Tests: [tests/knock-escrow-program.test.js](tests/knock-escrow-program.test.js), [tests/knock-escrow-pda.test.js](tests/knock-escrow-pda.test.js), [tests/api-knock-escrowed.test.js](tests/api-knock-escrowed.test.js), [tests/api-knock-escrow-sync.test.js](tests/api-knock-escrow-sync.test.js) || Cross-chain SDKs | [sdk/](sdk), [solana-agent-sdk/](solana-agent-sdk), [agent-payments-sdk/](agent-payments-sdk), [agent-protocol-sdk/](agent-protocol-sdk) | Published | Cross-chain agent SDKs || MCP integration | [mcp-server/](mcp-server), [mcp-bridge/](mcp-bridge), [packages/*-mcp/](packages) | 43 npm servers + 8 hosted remote (51 total, incl. the free `/api/mcp-studio` 3D Studio, whose ChatGPT plugin surface [api/mcp-chatgpt.js](api/mcp-chatgpt.js) `→ /api/mcp-chatgpt` serves the eight 3D tools and the model viewer without the persona tools or any `frameDomains`, and whose Grok surface [api/mcp-grok.js](api/mcp-grok.js) `→ /api/mcp-grok` serves every studio tool with no widget templates plus, for a caller signed in with OAuth 2.1 or a connector key, the account's agent tools from the core server ([api/_mcp-studio/account-tools.js](api/_mcp-studio/account-tools.js), never a value-moving tool; docs [docs/grok.md](docs/grok.md), test [tests/mcp-grok-accounts.test.js](tests/mcp-grok-accounts.test.js)); all three doors share [api/_mcp-studio/handler.js](api/_mcp-studio/handler.js), and `SURFACES` in [api/_mcp-studio/dispatch.js](api/_mcp-studio/dispatch.js) defines what each advertises), all in the [MCP registry](https://registry.modelcontextprotocol.io/?q=io.github.nirholas). Canonical metadata: [prompts/store-submissions/_generated/mcp-listing-source.json](prompts/store-submissions/_generated/mcp-listing-source.json), generated from the manifests by [scripts/build-mcp-listing-source.mjs](scripts/build-mcp-listing-source.mjs) (`npm run audit:mcp-listing` fails when it drifts) | Model Context Protocol surface, full server list in [docs/mcp.md](docs/mcp.md). One-click client setup: [pages/connect.html](pages/connect.html) `→ /connect` (Claude, Cursor and VS Code install links plus ChatGPT, Grok Bot, Claude Code and generic steps; the Grok Bot tab is the shared connector card [src/grok-connector.js](src/grok-connector.js), also mounted on the Grok landing page [pages/grok.html](pages/grok.html) `→ /grok` ([src/grok-page.js](src/grok-page.js): capabilities, a live strip of recent gallery creations, an in-page MCP demo against `/api/mcp-grok`, three scheduled recipes, the skill file); /connect is built live from [public/.well-known/mcp.json](public/.well-known/mcp.json) with tool counts from the catalog; config names match the CLI's `slugForPath`). CLI: [packages/three-ws-cli/](packages/three-ws-cli) (`npx three-ws setup`), docs [docs/cli.md](docs/cli.md) `→ /docs/cli`. Searchable index of every tool: [pages/mcp-tools.html](pages/mcp-tools.html) `→ /mcp-tools`, rendered from the generated [public/mcp-catalog.json](public/mcp-catalog.json) ([scripts/build-mcp-catalog.mjs](scripts/build-mcp-catalog.mjs), `npm run build:mcp-catalog`, staleness gated by `npm run audit:mcp-catalog`). Tool safety annotations are verified against each handler by [scripts/audit-mcp-safety.mjs](scripts/audit-mcp-safety.mjs) (`npm run audit:mcp-safety`, rules in [scripts/lib/mcp-safety-check.mjs](scripts/lib/mcp-safety-check.mjs), guarded-file list shared with the golden snapshot via [scripts/lib/mcp-tool-sources.mjs](scripts/lib/mcp-tool-sources.mjs)); docs [docs/mcp-safety.md](docs/mcp-safety.md) `→ /docs/mcp-safety`. Trust policy: [api/mcp-policy.js](api/mcp-policy.js) `-> GET /api/mcp-policy` turns those verified labels into a ready-to-paste client allowlist (profiles strict/balanced/open x formats claude/vscode/json), surfaced by the builder panel on `/mcp-tools`. Connector-review readiness (every paid stdio tool answers a clean x402 challenge, and the reviewer entitlement lifts it): [scripts/audit-mcp-reviewer-path.mjs](scripts/audit-mcp-reviewer-path.mjs), `npm run audit:mcp-reviewer`. Tests: [tests/mcp-safety-audit.test.js](tests/mcp-safety-audit.test.js), [tests/mcp-catalog.test.js](tests/mcp-catalog.test.js), [tests/api/mcp-policy.test.js](tests/api/mcp-policy.test.js) |+| Grok Bot integration (custom MCP connector) | Connector [api/mcp-grok.js](api/mcp-grok.js) `→ /api/mcp-grok` over [api/_mcp-studio/handler.js](api/_mcp-studio/handler.js) (signed-in account tools [api/_mcp-studio/account-tools.js](api/_mcp-studio/account-tools.js), job tools [api/_mcp-studio/job-tools.js](api/_mcp-studio/job-tools.js)), install tokens [api/mcp-studio/install.js](api/mcp-studio/install.js) `→ /api/mcp-studio/install`, guided prompts [api/_mcp/prompts.js](api/_mcp/prompts.js), landing [pages/grok.html](pages/grok.html) `→ /grok`, connector card [src/grok-connector.js](src/grok-connector.js) (also on `/connect`), skill file [data/grok-skill-md.template.md](data/grok-skill-md.template.md) `→ /grok-skill.md`, connector probe [scripts/mcp-client-probe.mjs](scripts/mcp-client-probe.mjs) (`npm run probe:mcp-clients`) | In-repo (live with the next deploy) | Grok Bot adds `https://three.ws/api/mcp-grok` as a custom MCP connector: the free studio anonymously, plus the account's agent tools with a connector key or OAuth 2.1 (`?auth=oauth`), never a value-moving tool. Developer reference [docs/grok-bot.md](docs/grok-bot.md) (setup per auth mode, server choice, links contract, jobs and idempotency, limits, spend rule, prompts, probe troubleshooting; samples run by [scripts/run-doc-samples.mjs](scripts/run-doc-samples.mjs), drift test [tests/grok-bot-doc.test.js](tests/grok-bot-doc.test.js)); overview [docs/grok.md](docs/grok.md) || Awesome 3D Agents (curated list) | Source [data/awesome.json](data/awesome.json), generator [scripts/build-awesome.mjs](scripts/build-awesome.mjs) (`npm run build:awesome`, drift-gated by `npm run check:awesome`, publishable mirror via `npm run awesome:standalone`), outputs [awesome/README.md](awesome/README.md) + [public/awesome.json](public/awesome.json), page [pages/awesome.html](pages/awesome.html) `-> /awesome`, link checker [scripts/check-awesome-links.mjs](scripts/check-awesome-links.mjs) (`npm run awesome:links`) | Live | An awesome-list of everything needed to give an AI agent a body: text-to-3D, capture and splatting, avatars, rigging, motion, lipsync and voice, web renderers, asset pipelines, physics and networking, agent frameworks, datasets, free assets, learning. One JSON source produces both the GitHub-facing list and the searchable page, so they cannot disagree. Every url is fetched and classified (ok / moved / bot-filtered / broken) before it ships; the checker stays out of the deploy path so a third-party outage cannot redden someone else's build. The README is written to pass `npx awesome-lint`: badge on the heading line, no License section, no Contributing entry in the contents, and every description capitalised and ended with a period, all enforced by the generator and by [tests/awesome-list.test.js](tests/awesome-list.test.js). Its last two lint rules read GitHub repository topics, which a list inside a product repo cannot satisfy, so `--standalone` emits a ready-to-publish mirror repo (readme, contributing, code of conduct, license) outside this checkout. Contributing: [awesome/CONTRIBUTING.md](awesome/CONTRIBUTING.md) || Agent Skills pack | [.agents/skills/](.agents/skills) (canonical) → manifest [.agents/skills/SKILLS.md](.agents/skills/SKILLS.md), [.agents/skills/skills-pack.json](.agents/skills/skills-pack.json); published 3D subset [public/skills/3d-studio/](public/skills/3d-studio) `→ /skills/3d-studio/` | In-repo; bundled in the `three-ws-core` [plugin](.claude-plugin/marketplace.json); 3D subset live on the site | Portable `SKILL.md` folders (Agent Skills open standard) for any Claude surface, in five categories: 3d/creative (cross-platform-safe), platform/agents (create an agent, author and sell its skills, hire other agents, connect a client to the MCP servers), wallet/payments, intel/trading, ops/production. Counts live in the generated manifest, never here. The 3d/creative ones are also published as a public, downloadable bundle at `/skills/3d-studio/` (`three-ws-3d-skills.zip`), which is what an OpenAI Plugin Directory submission uploads on its Skills tab; a skill referencing a tool [api/_mcp-studio/](api/_mcp-studio) does not declare is dropped rather than shipped as a dead path. The same build renders the two entry-point skills from shared facts ([scripts/lib/skill-md-facts.mjs](scripts/lib/skill-md-facts.mjs)): [public/skill.md](public/skill.md) `→ /skill.md` from [data/skill-md.template.md](data/skill-md.template.md), and the Grok variant [public/grok-skill.md](public/grok-skill.md) `→ /grok-skill.md` from [data/grok-skill-md.template.md](data/grok-skill-md.template.md) (links and example calls checked by [tests/grok-skill-file.test.js](tests/grok-skill-file.test.js)). Regenerate manifest: `npm run build:skills-pack` (drift gate `npm run check:skills-pack`); regenerate the published bundle: `npm run build:openai-skills` (drift gate `npm run check:openai-skills`, wired into `npm run gate`). Docs: [docs/agent-skills.md](docs/agent-skills.md) || Standalone skill repos | [scripts/build-standalone-skill-repos.mjs](scripts/build-standalone-skill-repos.mjs) → `.data/standalone-repos/<repo>/` (gitignored) | Generated on demand; publishing is owner-gated | Assembles the three.ws-origin skills into small, publishable repos so an external user installs with one `/plugin marketplace add nirholas/<repo>` instead of cloning this monorepo: `three-ws-skills` (everything), `three-ws-3d-skills` (the crypto-free 3d/creative subset), `three-ws-agent-economy-skills` (wallet/payments + platform/agents). Each output is a complete one-plugin marketplace (`.claude-plugin/{marketplace,plugin}.json`, `skills/`, generated `README.md` with every trigger, `LICENSE`). Built from the same `collectSkills()` the manifest uses, so a copy cannot drift; nothing is committed here. `npm run build:skill-repos`, validate with `npm run check:skill-repos` (wired into `npm run gate`). Docs: [docs/agent-skills.md](docs/agent-skills.md) |diff --git a/data/pages.json b/data/pages.jsonindex c1cade065..2f14b9ab4 100644--- a/data/pages.json+++ b/data/pages.json@@ -4022,6 +4022,14 @@"changefreq": "monthly","added": "2026-10-08"},+ {+ "path": "/docs/grok-bot",+ "title": "Docs · Grok Bot connector reference",+ "description": "Connect Grok Bot to three.ws as a custom MCP connector: exact fields for each sign-in mode, which server to pick, the links every result carries, jobs and safe retries, free limits and install tokens, why a connector key can never spend, guided prompts, and a fix for every connection failure.",+ "priority": 0.6,+ "changefreq": "monthly",+ "added": "2026-10-09"+ },{"path": "/docs/mcp-solana-memo-media","title": "Docs · Solana Memo Media MCP",diff --git a/docs/grok-bot.md b/docs/grok-bot.mdnew file mode 100644index 000000000..ba6f87b63--- /dev/null+++ b/docs/grok-bot.md@@ -0,0 +1,542 @@+# Grok Bot connector reference++Grok Bot, xAI's always-on computer-use agent, takes custom MCP servers as+connectors. This page is the developer reference for connecting it to three.ws:+the exact connector settings for each authentication mode, which hosted server+to pick, the contract every tool result follows, how long jobs and retries+behave, the limits, what a key held by a cloud agent can and cannot do, the+guided prompts, and a fix for every failure a connector can hit.++For the product overview (what Grok gets, example asks, the xAI Responses API+and the skill file), read [three.ws for Grok](./grok.md). For the live page and+an in-browser demo, open [three.ws/grok](/grok).++| | |+|---|---|+| **Server URL** | `https://three.ws/api/mcp-grok` |+| **Transport** | Streamable HTTP (JSON-RPC over `POST`; `GET` answers `405` with `Allow: POST, OPTIONS`) |+| **Authentication** | None, an API key (connector key), or OAuth 2.1 at `https://three.ws/api/mcp-grok?auth=oauth` |+| **Protocol** | MCP `2025-06-18`, whatever version the client opens with |+| **Session** | `initialize` issues an `Mcp-Session-Id` (`grk_…`); echo it on every later request |+| **Tools** | 15 free studio tools anonymously; signed in, plus the account tools your scopes allow |+| **Prompts** | 4 anonymously, 5 signed in |+| **Handler** | [`api/mcp-grok.js`](../api/mcp-grok.js) over [`api/_mcp-studio/handler.js`](../api/_mcp-studio/handler.js) |++## Connector setup++Grok Bot connects from xAI's cloud, so the URL must be public: a `localhost`+server never works. Add the server either by telling Grok Bot in chat+("Add a custom MCP server called three-ws-grok at https://three.ws/api/mcp-grok")+or through its connector form. The form takes four fields, and+[three.ws/connect?client=grok](/connect?client=grok) shows them with a copy+button for every hosted server. Use the name `three-ws-grok` so the guided+prompts, the [skill file](https://three.ws/grok-skill.md) and the `/grok` page+all refer to the connector by the same name.++### None (free, no account)++| Field | Value |+|---|---|+| Name | `three-ws-grok` |+| Transport | Streamable HTTP |+| Server URL | `https://three.ws/api/mcp-grok` |+| Authentication | None |++You get the free studio: text to 3D, image to 3D, rigging, refinement, the+catalog of ready-made assets, and personas. The generation caps key on the MCP+session, so they last one connection.++### None, with an install token (free, a quota that survives reconnects)++A scheduled Grok Bot task opens a new connection, and so a new session, on+every run. To keep one budget across all of them, mint a free install token and+put it in the URL. No account and no key:++```bash+curl -s -X POST https://three.ws/api/mcp-studio/install | jq -r .connector_urls.grok+```++```text+https://three.ws/api/mcp-grok?install=tws_tmm6fp_dce3ce5583a6bd9f66889a1ef74e6a6e553ef39620867a6374fe75b9f6f039a1+```++| Field | Value |+|---|---|+| Server URL | the `connector_urls.grok` value above |+| Authentication | None |++The token never expires and unlocks no account, tool or payment; it is only a+rate-limit identity, and request logs redact it. Anyone holding the URL spends+its budget, so keep it in the connector rather than in a shared prompt. On+[/connect](/connect?server=three-ws-studio), **Generate my connector URL** mints+the same thing in the browser. Details:+[install tokens](./mcp-studio.md#connector-url-for-cloud-agents-install-tokens).++### API key (your agents, memory and skills)++1. At [three.ws/dashboard/api](/dashboard/api) choose **New key**, then+ **For an AI agent (Grok Bot, schedules, CI)**, name it, and copy the key it+ shows once.+2. Add the connector:++| Field | Value |+|---|---|+| Server URL | `https://three.ws/api/mcp-grok` |+| Authentication | API key |+| Header (if asked) | `Authorization` |+| Value | `Bearer sk_live_…`, stored as a Bot secret |++Check the key before you hand it to Grok Bot. Signed in, `tools/list` grows from+15 to the studio plus every account tool your scopes allow:++```bash+curl -s https://three.ws/api/mcp-grok \+ -H "Authorization: Bearer $THREE_WS_API_KEY" \+ -H 'Content-Type: application/json' \+ -H 'Accept: application/json, text/event-stream' \+ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools | length'+```++A connector key is capped on every request: it can read, generate and edit+agent data and can never spend (see [Scoped keys and the spend rule](#scoped-keys-and-the-spend-rule)).++### OAuth 2.1 (sign in once, revoke any time)++| Field | Value |+|---|---|+| Server URL | `https://three.ws/api/mcp-grok?auth=oauth` |+| Authentication | OAuth 2.1 |+| Client ID | leave empty: the connector registers itself |++The `?auth=oauth` form is what makes sign-in start. An MCP client only begins+OAuth when the server answers `401`, and the plain URL serves anonymous callers,+so it never would. With the parameter, an anonymous `initialize` answers:++```bash+curl -s -i 'https://three.ws/api/mcp-grok?auth=oauth' \+ -H 'Content-Type: application/json' \+ -H 'Accept: application/json, text/event-stream' \+ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}' \+ | grep -iE '^HTTP|^www-authenticate'+```++```text+HTTP/1.1 401 Unauthorized+www-authenticate: Bearer resource_metadata="https://three.ws/.well-known/oauth-protected-resource/api/mcp-grok", resource="https://three.ws/api/mcp-grok"+```++From there the client reads the protected-resource document, finds the+authorization server, registers itself (RFC 7591 dynamic client registration),+and sends you to a consent screen that names the app, the host of its+`client_uri`, the host the code goes back to, and every permission in plain+language. PKCE `S256` is required. Access tokens last an hour and refresh on+their own; revoking the app in [Connected apps](/dashboard/settings#connected-apps)+refuses its very next call. More:+[Cloud connectors and revocation](./mcp.md#cloud-connectors-and-revocation).++## Which server to pick++Every hosted server speaks Streamable HTTP and is listed with its auth model in+[`/.well-known/mcp.json`](https://three.ws/.well-known/mcp.json). For Grok Bot:++| You want Grok Bot to | Connect | Auth |+|---|---|---|+| Make 3D models, avatars and personas, find ready-made assets | `https://three.ws/api/mcp-grok` | None (add an install token for scheduled tasks) |+| Do that and also run your agents, memory, skills and avatars | `https://three.ws/api/mcp-grok` | Connector key, or OAuth 2.1 at `?auth=oauth` |+| Use the full core server (validation, market data, a connected home) | `https://three.ws/api/mcp` | Connector key or OAuth 2.1 |+| Use paid generation, retexture and optimization | `https://three.ws/api/mcp-3d` | Connector key or OAuth 2.1 |+| Discover paid agent services | `https://three.ws/api/mcp-bazaar` | Connector key or OAuth 2.1 |++`/api/mcp-grok` is the right default. It is the free studio with no ChatGPT+widget templates (nothing renders inline in Grok, so every result hands back+plain links instead), it never lets a call hang, and it keys the free quota on+the MCP session rather than on xAI's shared egress IPs. The agent wallet server+(`/api/mcp-agent`) is not a good fit for an unattended connector: a connector key+there can browse and quote but every payment answers with a link back to+three.ws, by design. x402 pay-per-call is not a connector mode at all, because+each paid call needs a signed payment a connector cannot make for you.++## Links in every result++Grok Bot sees only JSON and text, so every result that carries a model also+carries four absolute links under fixed names, both in `structuredContent` and+as the first lines of the text content:++| Field | What it is |+|---|---|+| `viewer_url` | The interactive 3D viewer, opens in any browser |+| `glb_url` | The model file, to download, re-host, or pass to `rig_mesh` or `look_at_model` |+| `poster_png_url` | A rendered 1024 px PNG (`/api/render/glb`, CDN-cached a day) to attach to a reply or a card |+| `embed_html` | A paste-ready `<agent-3d>` or `<model-viewer>` snippet, script pinned with an integrity hash |++The generators, `get_job` and `check_job` once done, `look_at_model`, the three+catalog tools, and the three persona tools all carry them. A catalog search puts+them on each item:++```bash+curl -s https://three.ws/api/mcp-grok \+ -H 'Content-Type: application/json' \+ -H 'Accept: application/json, text/event-stream' \+ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_catalog","arguments":{"q":"chair","limit":1}}}' \+ | jq '.result.structuredContent.items[0] | {id, viewer_url, glb_url, poster_png_url}'+```++```json+{+ "id": "object:ArmChair_01",+ "viewer_url": "https://three.ws/viewer?src=https%3A%2F%2Fpub-2534e921bf9c4314addcd4d8a6e98b7b.r2.dev%2Fobjects%2Fpolyhaven%2Fglb%2FArmChair_01.glb&title=Arm%20Chair%2001",+ "glb_url": "https://pub-2534e921bf9c4314addcd4d8a6e98b7b.r2.dev/objects/polyhaven/glb/ArmChair_01.glb",+ "poster_png_url": "https://three.ws/api/render/glb?glbUrl=https%3A%2F%2Fpub-2534e921bf9c4314addcd4d8a6e98b7b.r2.dev%2Fobjects%2Fpolyhaven%2Fglb%2FArmChair_01.glb&width=1024&height=1024"+}+```++A job that is still rendering has no GLB yet, so its result carries only a+`viewer_url` of the form `https://three.ws/viewer?job=<job_id>`: that page waits+for the job and opens the model the moment it lands, so Grok Bot can hand the+link over straight away. Full field rules:+[Links for agents that render no widget](./mcp-studio.md#links-for-agents-that-render-no-widget).++## Jobs and idempotency++Grok calls MCP from xAI's cloud with no published timeout, so on this URL no+call runs longer than 40 seconds. A model usually lands inside that. When it+does not (a GPU booting from zero, a heavy rig), the call answers with a pending+job instead of hanging, and the server's instructions tell Grok to call+`get_job` until it is done.++Every generation tool (`forge_free`, `text_to_avatar`, `mesh_forge`, `rig_mesh`,+`forge_avatar`, `refine_model`) takes an optional `idempotency_key`. A scheduled+task should always pass one built from the task and the date, so a retry after a+timeout collects the first run's job instead of generating twice:++```bash+RESULT=$(curl -s https://three.ws/api/mcp-grok \+ -H 'Content-Type: application/json' \+ -H 'Accept: application/json, text/event-stream' \+ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"forge_free","arguments":{"prompt":"a brass ship lantern with a glass globe","idempotency_key":"lantern-brief-2026-10-09"}}}')+echo "$RESULT" | jq '.result.structuredContent | {status, phase, job_id, progress, eta_seconds, idempotent_replay}'+JOB=$(echo "$RESULT" | jq -r '.result.structuredContent.job_id')+```++```json+{+ "status": "pending",+ "phase": "queued",+ "job_id": "f1.eyJwIjoiZ2NwIiwiayI6bnVsbCwidCI6…",+ "progress": 0.37,+ "eta_seconds": 38,+ "idempotent_replay": false+}+```++Then collect it, as often as you like (`get_job` never starts a generation and+never counts against the quota). Wait the `eta_seconds` it reported, then:++```bash+curl -s https://three.ws/api/mcp-grok \+ -H 'Content-Type: application/json' \+ -H 'Accept: application/json, text/event-stream' \+ -d "$(jq -nc --arg job "$JOB" '{jsonrpc:"2.0",id:2,method:"tools/call",params:{name:"get_job",arguments:{job_id:$job}}}')" \+ | jq '.result.structuredContent | {status, progress, eta_seconds, viewer_url, glb_url}'+```++```json+{+ "status": "done",+ "progress": 1,+ "eta_seconds": 0,+ "viewer_url": "https://three.ws/viewer?src=https%3A%2F%2Fthree.ws%2Fcdn%2Fforge%2Fanon%2F45269fd0-ef73-4056-b288-0d6c5cfa8784.glb&title=a%20brass%20ship%20lantern%20with%20a%20glass%20globe",+ "glb_url": "https://three.ws/cdn/forge/anon/45269fd0-ef73-4056-b288-0d6c5cfa8784.glb"+}+```++What a job reports:++| Field | Meaning |+|---|---|+| `status` | `pending`, `done` or `failed` (`unknown` when only the status check failed; retry after `retry_after`) |+| `phase` | `submitting`, `queued`, `running`, `done` or `failed` |+| `progress` | 0 to 1, an estimate while running, held at 0.95 until actually done |+| `eta_seconds` | Seconds left, absent once a job runs past its estimate |+| `reason`, `remedy` | On failure: `generation_failed`, `unknown_job` or `check_failed`, and the one action that fixes it |++The key rules, in short:++- **Same caller, same key, same arguments, within 24 hours:** the first call's+ job comes back with `idempotent_replay: true`, and the repeat costs no quota.+- **Same key, different arguments or a different tool:** refused with+ `reason: "idempotency_key_reused"`; nothing starts. Use a new key for a new request.+- **A call that never got a job** (a refused prompt, a rate limit) gives its key back.+- **The caller owns the key.** It is whatever the rate limits key on (below), so+ a task that reconnects keeps its keys only on an install-token URL or a+ signed-in connector.++A client that sends `_meta.progressToken` and accepts `text/event-stream` also+gets `notifications/progress` while it waits. Everything else:+[Job status](./mcp-studio.md#job-status-get_job),+[Retries and `idempotency_key`](./mcp-studio.md#retries-and-idempotency_key),+[Progress notifications](./mcp-studio.md#progress-notifications).++## Rate limits and install tokens++Every Grok user reaches three.ws from xAI's shared egress, so per-IP limits would+ration all of Grok as one caller. The free caps therefore key on the most+specific identity the request carries, in this order:++1. the install token in the URL (`?install=`),+2. the signed-in account (connector key or OAuth),+3. the `Mcp-Session-Id` issued on `initialize`,+4. the IP address, for a client that never echoes the session.++| Limit | Value | Keyed on |+|---|---|---|+| Generation burst | 4 a minute | the caller above |+| Generation hourly | 30 an hour | the caller above |+| Per-IP pool | 300 generations an hour | the source IP, across every caller on it |+| Transport | 300 requests a minute | the install token, else the IP |+| Platform breaker | 600 generations an hour (`FORGE_PAID_GLOBAL_HOURLY`) | every free-studio caller combined |+| Install token minting | 10 an hour | the IP |++Generation means the six generators plus `look_at_model`, which renders the+model on a GPU. `get_job`, `check_job`, the catalog and the persona tools ride+the transport cap only. The numbers come from one table, `STUDIO_LIMITS` in+[`api/_lib/rate-limit.js`](../api/_lib/rate-limit.js), and the refusal text is+built from it, so the message always matches what is enforced.++A capped generation answers HTTP 200 with a JSON-RPC error (the Python MCP SDK+raises on a non-2xx before it reads the body), plus `Retry-After` and+`RateLimit-*` headers. The message is written so Grok can relay it as is:++```json+{+ "code": -32000,+ "message": "Rate limited: the free 3D studio allows 30 generations per hour for this MCP session, and that limit is used up. It resets at 2026-10-09T14:25:00.000Z (in 1500 s). Lift it with a free install token: POST https://three.ws/api/mcp-studio/install (no account, no key) and reconnect at https://three.ws/api/mcp-grok?install=<token>, which gets its own budget. Or sign in at https://three.ws/api/mcp-3d (OAuth 2.1), metered per account.",+ "data": {+ "reason": "rate_limited",+ "limit": "generation_hourly",+ "max": 30,+ "window": "1 h",+ "keyed_on": "session",+ "reset_at": "2026-10-09T14:25:00.000Z",+ "retry_after": 1500,+ "remedy": {+ "kind": "install_token",+ "install_endpoint": "https://three.ws/api/mcp-studio/install",+ "connector_url": "https://three.ws/api/mcp-grok?install=<token>"+ }+ }+}+```++A caller that already has its own budget (a token or an account), or that hit+the per-IP pool or the platform breaker, gets `remedy.kind: "account"` instead:+wait for `reset_at`, or use the signed-in server, whose generation is metered+per account. The transport cap alone answers HTTP `429` with `reset_at` and the+same `remedy` object.++## Scoped keys and the spend rule++A key that a cloud agent holds unattended can generate, read and write agent+data. It can never move funds, pay an x402 endpoint, launch a coin, or change+where earnings go. Spending stays a browser action on three.ws, behind its own+confirmation.++**The connector key.** **New key** then **For an AI agent** at+[/dashboard/api](/dashboard/api) (or `POST /api/keys` with+`{"name": "Grok Bot", "preset": "connector"}` from a signed-in browser session)+issues these scopes:++```text+avatars:read avatars:write agents:read agents:write memory:read memory:write connector+```++The `connector` mark caps the key on every request, so no later edit to its+stored scopes can give it `wallet:write`. The key table shows it with an+"AI agent · cannot spend" badge.++**On `/api/mcp-grok`, value-moving tools do not exist.** Signed in, the+connector adds only allowlisted account tools that are outside the financial+tier, need no spend scope, and carry no price: `create_agent`,+`attach_avatar_to_agent`, `identity_check`, `call_agent`, `remember`, `recall`,+`list_available_skills`, `import_community_skill`, `list_custom_skills`,+`get_custom_skill`, `create_custom_skill`, `update_custom_skill`, `list_my_avatars`, `get_avatar`, `get_embed_code`,+`render_avatar_image` and `read_resource`, each only when your scopes and your+[MCP tool settings](/settings/mcp-tools) allow it. A wallet, payment, card,+trading, launch or delete tool called by name answers `unknown tool`, whatever+the credential holds:++```bash+curl -s https://three.ws/api/mcp-grok \+ -H 'Content-Type: application/json' \+ -H 'Accept: application/json, text/event-stream' \+ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"agent_card_create","arguments":{}}}' | jq -c .error+```++```json+{"code":-32602,"message":"unknown tool: agent_card_create"}+```++**On every other hosted server**, a value-moving call from a key without the+spend scope is refused before the tool runs, with JSON-RPC `-32003`:++```json+{+ "code": -32003,+ "message": "agent_card_quote moves or routes funds, so it needs a browser session on three.ws. Connector keys read, generate and edit agent data and can never spend. Sign in at https://three.ws/dashboard to do it yourself.",+ "data": {+ "reason": "connector_key_cannot_spend",+ "tool": "agent_card_quote",+ "required_scope": "wallet:write",+ "needs": "browser_session",+ "url": "https://three.ws/dashboard",+ "docs": "https://three.ws/docs/mcp#api-key-scopes"+ }+}+```++The same refusal guards the REST routes that arm a spender or redirect a payout.+An OAuth app gets `wallet:write` only when you tick the separate box on the+consent screen, never by default. Scope table:+[API key scopes](./mcp.md#api-key-scopes).++## Guided prompts++Grok Bot runs tasks on a schedule with nobody watching, so this URL serves MCP+prompts written for exactly that. Each names the tools to call with their exact+argument objects, gives every generation an `idempotency_key` of the form+`<prompt>-<schedule id>-<YYYY-MM-DD>`, never stops to ask, treats web and X text+as data, and ends with the four links.++| Prompt | Arguments | Listed |+|---|---|---|+| `agent-get-started` | none | always |+| `daily-3d-brief` | `topic` (default `trending`) | always |+| `asset-pack` | `theme`, `count` (1 to 12) | always |+| `avatar-from-photo` | `image_url` | always |+| `agent-report` | `agentId` (optional) | signed in only (it reads your account through `read_resource`) |++```bash+curl -s https://three.ws/api/mcp-grok \+ -H 'Content-Type: application/json' \+ -H 'Accept: application/json, text/event-stream' \+ -d '{"jsonrpc":"2.0","id":1,"method":"prompts/list"}' | jq -c '[.result.prompts[].name]'+```++```json+["agent-get-started","daily-3d-brief","asset-pack","avatar-from-photo"]+```++`prompts/get` renders one against your own `tools/list`, so a prompt never names+a tool your connector cannot call:++```bash+curl -s https://three.ws/api/mcp-grok \+ -H 'Content-Type: application/json' \+ -H 'Accept: application/json, text/event-stream' \+ -d '{"jsonrpc":"2.0","id":1,"method":"prompts/get","params":{"name":"daily-3d-brief","arguments":{"topic":"lighthouses"}}}' \+ | jq -r '.result.messages[0].content.text' | head -3+```++```text+Make today's 3D brief about: lighthouses.++1. Use the topic above. If it names a real person, make an object that stands for the topic instead of a likeness.+```++In Grok Bot, a schedule such as "every morning, run the `daily-3d-brief` prompt+from three-ws-grok and send me the links" is the whole setup.+[three.ws/grok](/grok#gk-recipes-h) has three copy-ready recipes, and+[MCP use cases](./mcp.md#use-cases) writes each prompt out as its calls. The+prompts live in [`api/_mcp/prompts.js`](../api/_mcp/prompts.js).++## Troubleshooting++### Check the connector the way Grok Bot does++From a clone of the repository, the connector probe connects with the official+MCP SDK client over Streamable HTTP (falling back to the legacy SSE transport),+anonymously, with `THREE_WS_API_KEY` when it is set, and against the OAuth+challenge on the sign-in URL. It calls only free tools and never pays:++```bash+npm run probe:mcp-clients -- --only mcp-grok+```++```text+PASS | https://three.ws/api/mcp-grok | init 200 | GET 405 | anon ok tools=15 prompts=4 | key ok tools=26 prompts=5 | oauth ok | call search_catalog=ok 228ms+all 1 servers passed+```++Without `--only` it probes every server in+[`/.well-known/mcp.json`](https://three.ws/.well-known/mcp.json); `--base` points+it at your own server, and `--json <file>` keeps the full evidence. Each line it+can print under a failing server, what it means, and the fix:++| Probe says | What it means | Fix |+|---|---|---|+| `anonymous connect failed: …` | Neither transport finished `initialize` and `tools/list` without credentials. | Check the URL is exactly `https://three.ws/api/mcp-grok` (no trailing path), reachable from the public internet, and answering `POST`. The text after the colon is the SDK's own error. |+| `anonymous tools/list returned no tools` | The handshake worked but the server listed nothing. | A deployment that lost its studio tool table; report it with the probe output. |+| `initialize answered content-type …` | `initialize` came back as something other than JSON or an event stream, usually an HTML error page from a proxy. | Remove whatever sits between the client and three.ws, or point at the real origin. |+| `GET answered 405 without an Allow header` | A `GET` was refused without saying which methods work, so some clients give up instead of switching to `POST`. | Server-side defect; three.ws always sends `Allow: POST, OPTIONS`. |+| `GET answered 401 without WWW-Authenticate` | A protected `GET` gave the client nothing to sign in with. | Server-side defect; every 401 must carry the challenge. |+| `GET with accept: text/event-stream answered …` | A `GET` returned neither a stream, a 405, nor a 401. | Usually a proxy or CDN rewriting the response; connect to the origin URL. |+| `sign-in URL: unauthenticated initialize answered 200, an OAuth client needs 401 to start sign-in` | The OAuth connector was given the plain URL, which serves anonymous callers, so it never starts sign-in. | Use `https://three.ws/api/mcp-grok?auth=oauth` as the server URL for OAuth 2.1. |+| `sign-in URL: 401 carries no Bearer WWW-Authenticate challenge` | The 401 does not tell the client how to authenticate. | Server-side defect in the challenge; report it. |+| `sign-in URL: WWW-Authenticate does not name resource_metadata` | The client cannot find the protected-resource document, so it cannot find the authorization server. | Server-side defect; the challenge must name `resource_metadata`. |+| `sign-in URL: protected-resource metadata at … answered …` | The protected-resource document is missing or not JSON. | It lives at `https://three.ws/.well-known/oauth-protected-resource/api/mcp-grok`; a 404 there means the route table lost its RFC 9728 rewrite. |+| `sign-in URL: protected resource … does not cover …, so an MCP SDK client refuses to sign in` | The document names a different server than the one connected to; the MCP SDK's `checkResourceAllowed` then refuses to redirect anyone. | Server-side: each server must publish its own resource. This was the failure on four servers before the per-server metadata fix. |+| `sign-in URL: WWW-Authenticate resource … disagrees with the metadata resource …` | The challenge and the document name different resources. | Server-side defect; both come from one resource map and must agree. |+| `sign-in URL: protected-resource metadata lists no authorization_servers` | Nowhere to send the user to sign in. | Server-side defect in the document. |+| `sign-in URL: authorization server metadata at … is incomplete` | `/.well-known/oauth-authorization-server` lacks an authorization or token endpoint. | Server-side defect; report it. |+| `sign-in URL: authorization server does not advertise PKCE S256, which OAuth 2.1 requires` | A strict OAuth 2.1 client refuses an authorization server without `S256`. | Server-side defect; three.ws only accepts `S256`. |+| `sign-in URL: an invalid bearer answered … without a resource_metadata challenge` | An expired or revoked token got an answer the client cannot recover from. | Server-side defect: a bad bearer must get `401` and the challenge so the connector signs in again, never anonymous service. |+| `anonymous MCP client was served on a server that requires auth` | Seen when probing a protected server (`/api/mcp`, `/api/mcp-3d`, `/api/mcp-bazaar`): it answered a client with no credentials, so an OAuth connector would never be asked to sign in. | Server-side defect on that server; `/api/mcp-grok` is open by design and is judged on its `?auth=oauth` URL instead. |+| `signing in with an API key listed N tools, no more than the M an anonymous client sees` | The key was accepted but added no account tools. | The key's scopes allow none of the account tools, or [MCP tool settings](/settings/mcp-tools) turn them all off. Make a connector key, or turn the tools on. |+| `api key connect failed: …` | The key was refused, or the call errored. | The key is revoked, mistyped, or missing the `Bearer ` prefix. Make a new connector key and store `Bearer sk_live_…` as the secret. |+| `api key tools/list returned no tools` | The key connected but listed nothing. | Same as above: check the key's scopes and your MCP tool settings. |+| `requested …, server answered … which no SDK client supports` | The server negotiated a protocol version current SDKs do not know. | Server-side defect; three.ws answers `2025-06-18` to every version a client opens with. |++### Errors a connected Grok Bot can see++| Error | Meaning | Fix |+|---|---|---|+| `-32000`, `data.reason: "rate_limited"` | A generation cap is used up. `data.limit` says which, `data.reset_at` when it lifts. | Follow `data.remedy`: reconnect with an install-token URL, or sign in. A scheduled task should wait until `reset_at` rather than retry in a loop. |+| HTTP `429` with `reset_at` | More than 300 requests a minute from one IP or token. | Slow the polling loop; `get_job` after the `eta_seconds` it reports, never faster than every few seconds. |+| `-32002`, `data.reason: "sign_in_required"` | An account tool was called on an anonymous connector. | Reconnect with a connector key, or OAuth at the `data.oauth_url` the error gives. |+| `-32002`, `data.reason: "tool_not_granted"` | Signed in, but the key's scopes or your MCP tool settings leave that tool off. | Turn it on at [/settings/mcp-tools](/settings/mcp-tools), or use a key with the scope. |+| `-32602`, `unknown tool: …` | The tool is not on this connector. On `/api/mcp-grok` every value-moving tool answers this way. | Spending happens at [three.ws/dashboard](/dashboard), not through a connector. Otherwise check the name against `tools/list`. |+| `-32602`, `invalid params for …` | An argument is not in the tool's `inputSchema` (for example `query` where `search_catalog` takes `q`). | Read the schema from `tools/list`; the guided prompts already use the exact argument objects. |+| `-32003`, `connector_key_cannot_spend` | A connector key tried a value-moving tool on another server. | By design. Do it yourself in a browser at the `data.url` the error gives. |+| `idempotency_key_reused` | The key was already used for a different request. | Use a new key for a new generation (add the item or the date). |+| `status: "failed"` with a `remedy` | The generation itself failed. | Do what `remedy` says: start a new generation with a new `idempotency_key`; the retry is routed to a healthy engine. |+| `status: "unknown"`, `reason: "check_failed"` | Only the status check timed out; the job keeps running. | Call `get_job` again after `retry_after` seconds. |+| `401` after working for a while | The OAuth app was revoked, or the key was revoked or rotated. | Reconnect: OAuth signs in again on its own; a key needs replacing in the Bot secret. |+| Connector added, but account tools vanished | The bearer no longer verifies, so the server answers `401` with the challenge rather than quietly serving the free tier. | Same as above. |+| "Cannot connect" from Grok Bot to a local server | Grok Bot connects from xAI's cloud. | Use the public `https://three.ws` URL; a `localhost` server is never reachable. |++## Keeping this page true++Every `bash` sample here runs as written, in order, in one shell: the job+sample's `$JOB` feeds the `get_job` sample. To re-run them all against+production, or against a server built from your tree:++```text+node scripts/run-doc-samples.mjs docs/grok-bot.md+node scripts/run-doc-samples.mjs docs/grok-bot.md --base http://localhost:3108+```++Set `THREE_WS_API_KEY` to a connector key first, or the key sample counts+anonymous tools. [`tests/grok-bot-doc.test.js`](../tests/grok-bot-doc.test.js)+checks the rest against the code on every test run: each sample's tool and+arguments against the served `inputSchema`, the account tools, the prompt table,+the limit numbers against `STUDIO_LIMITS`, and that the troubleshooting table+has a row for every failure the connector probe can print.++## Related++- [three.ws for Grok](./grok.md): the overview, the xAI Responses API, the skill file.+- [three.ws/grok](/grok): the live page, demo and recipes; [three.ws/connect](/connect?client=grok): the connector card.+- [The free 3D Studio MCP](./mcp-studio.md): every studio tool in depth.+- [MCP integration](./mcp.md): every hosted server, authentication, client compatibility.+- [MCP client analytics](./ops/mcp-clients.md): how three.ws counts which AI clients connect.+- [`STRUCTURE.md`](../STRUCTURE.md): where the Grok surfaces live in the repository.diff --git a/docs/grok.md b/docs/grok.mdindex e31be4a38..21b2a828d 100644--- a/docs/grok.md+++ b/docs/grok.md@@ -9,6 +9,8 @@ without ever being able to spend.**Live page and demo:** [three.ws/grok](/grok)+**Connector reference** (exact fields per sign-in mode, the result and job contracts, limits, troubleshooting): [Grok Bot connector reference](./grok-bot.md)+| | ||---|---|| **URL** | `https://three.ws/api/mcp-grok` |diff --git a/docs/mcp.md b/docs/mcp.mdindex ed3d93c3d..2a6df22b4 100644--- a/docs/mcp.md+++ b/docs/mcp.md@@ -155,7 +155,7 @@ Ready-to-submit listing packages for each directory, plus the canonical metadataDeep dives — every tool, argument, env var, and example:-- **Hosted remote:** [3D Studio (free)](./mcp-studio.md) · [3D Studio (paid)](./mcp-3d-studio.md) · [Agent wallet](./mcp-agent.md) · [x402 Bazaar](./mcp-x402-bazaar.md) · [IBM x402](./ibm-x402-mcp.md)+- **Hosted remote:** [3D Studio (free)](./mcp-studio.md) · [Grok Bot connector](./grok-bot.md) · [3D Studio (paid)](./mcp-3d-studio.md) · [Agent wallet](./mcp-agent.md) · [x402 Bazaar](./mcp-x402-bazaar.md) · [IBM x402](./ibm-x402-mcp.md)- **Runs against your machine:** [Blender MCP](./blender-mcp.md) drives the Blender installed on your own computer, headless: inspect, convert, render and script 3D files, plus text-to-3D straight into a scene.- **Install-and-run:** each npm server ships its usage guide (tools, arguments, env vars, examples) in its package README on [npmjs.com/org/three-ws](https://www.npmjs.com/org/three-ws). The [MCP Tools Catalog](./mcp-tools.md) maps every tool to its server and price.- **Solana Memo Media:** [full guide](./mcp-solana-memo-media.md) for validating and rendering data URI images embedded in SPL Memo instructions.@@ -295,6 +295,10 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)This uses the standalone npm package, which handles OAuth locally. The `--url` flag lets you point at a local dev server.+### Grok Bot++Grok Bot connects from xAI's cloud as a custom MCP connector: transport Streamable HTTP, server URL `https://three.ws/api/mcp-grok`, authentication None for the free studio, a connector key for your agents, or OAuth 2.1 at `https://three.ws/api/mcp-grok?auth=oauth`. The [Grok Bot connector reference](./grok-bot.md) has the exact fields for each mode, which server to pick, the result and job contracts, the limits, and a fix for every failure the connector probe reports.+### Any MCP-compatible clientSend `POST /api/mcp` with valid JSON-RPC 2.0 messages and a bearer token. The server is stateless, so no session setup is needed beyond the `initialize` handshake. `initialize` returns an `Mcp-Session-Id` header; echo it on later requests, as the MCP SDKs do, so your calls are attributed to your client in the platform's [client analytics](./ops/mcp-clients.md). It holds no state, and a request without it is served the same way.@@ -346,7 +350,7 @@ What every hosted server does on the wire, so a connector never fails silently:- `initialize` answers JSON (`application/json`) and negotiates protocol version `2025-06-18` whatever version the client opens with; every current MCP SDK accepts it.- A `GET` with `accept: text/event-stream` answers a `405` with an `Allow` header where there is no server-to-client stream, a `401` with the OAuth challenge when the caller is unauthenticated, or the event stream itself (resource subscriptions on an authenticated core, 3D Studio, wallet or Bazaar connection, and the pump.fun feed).-- These servers are stateless and issue no `Mcp-Session-Id`, so a connector has no session to echo, resume or tear down; every request stands alone.+- `initialize` issues an `Mcp-Session-Id` (`grk_…` on `/api/mcp-grok`, `mcs_…` on the core, 3D, free studio, agent wallet, Bazaar and IBM servers) that a connector echoes on later requests. The servers hold no state on it: a request without it is served the same way. `/api/mcp-grok` also keys its free generation caps on it ([limits](./grok-bot.md#rate-limits-and-install-tokens)).- An unauthenticated or expired-token request on a protected server gets `401` with `WWW-Authenticate: Bearer resource_metadata="…", resource="…"` naming that server, so the connector can sign in again on its own.- On the free 3D Studio (`/api/mcp-studio` and `/api/mcp-grok`), a `tools/call` that carries `_meta.progressToken` from a client that accepts `text/event-stream` is answered as an event stream: `notifications/progress` while the job runs, then the result. Without a token it answers plain JSON.diff --git a/docs/start-here.md b/docs/start-here.mdindex fb978399b..af75cdd2c 100644--- a/docs/start-here.md+++ b/docs/start-here.md@@ -92,6 +92,7 @@ Want the model in your hands rather than on a screen? [Materialize](./materializ- **Placing agents in the real world?** → [IRL](./irl.md): pin an agent at a real GPS spot from your phone, and anyone who physically walks up can see it, talk to it, and pay it. Real crypto can be escrowed at places ([Money Drops](./irl.md#money-drops)) and agents sign proofs that you were really there ([World Lines](./irl.md#world-lines))- **Making 3D models?** → [The free 3D Studio MCP](./mcp-studio.md) turns a prompt into a model, avatar, or rigged character — and lets you refine it by talking to it (*"make it metallic"*) with a revertable version history. Publish a model as remixable and earn on-chain royalties when others build on it: [the remix economy](./remix.md). Vote on the best community models and win the weekly board: [Forge-Off](./forge-off.md)- **Using ChatGPT?** → [AR in ChatGPT](./chatgpt-ar.md) is how a sentence typed into ChatGPT becomes a 3D model standing in your room, from the free generation lane to the one-tap AR link; [your first prompt to 3D](/tutorials/first-prompt-to-3d) walks you through it in five minutes+- **Using Grok Bot?** → [The Grok Bot connector reference](./grok-bot.md): add `https://three.ws/api/mcp-grok` as a custom MCP connector and Grok Bot can generate 3D models and rigged avatars, find ready-made assets, and run your agents on a schedule. It has the exact connector fields for each sign-in mode, which server to pick, how long jobs and safe retries work, the free limits, why a connector key can never spend, and a fix for every connection failure. The overview is [three.ws for Grok](./grok.md)- **Making videos without showing your face?** → [Motion Swap](./motion-swap.md) — upload a video of yourself and get it back with your 3D avatar performing your exact motion instead of you; pose tracking and masking run server-side, compositing and export happen in your browser at [/motion-swap](https://three.ws/motion-swap)- **Want a support chat with a face on your own site?** → [Concierge](./concierge.md) — a one-tag chat widget where a rigged 3D avatar lipsyncs streaming answers grounded in your live page, with voice in and out; [the build tutorial](./tutorials/build-a-site-concierge.md) shows how every part works- **Want a full-body avatar assistant on your site instead?** → [Assistant widget](./assistant-widget.md) — a launcher button opens an animated 3D character standing directly on your page (or a color/gradient), with a free-lane or bring-your-own-key chatbot and a speak mode that says whatever you type, out loud, in a speech bubblediff --git a/pages/grok.html b/pages/grok.htmlindex 7b934fb86..2b4710ed5 100644--- a/pages/grok.html+++ b/pages/grok.html@@ -555,6 +555,7 @@ print(chat.sample().content)</pre></div><div class="gk-next"><a class="gk-btn" href="/docs/grok">Read the Grok guide</a>+ <a class="gk-btn" href="/docs/grok-bot">Connector reference</a><a class="gk-btn" href="/connect">Connect other AI clients</a><a class="gk-btn" href="/forge">Open the 3D studio</a></div>diff --git a/public/locales/en.json b/public/locales/en.jsonindex 29f00261d..5d2e2df4f 100644--- a/public/locales/en.json+++ b/public/locales/en.json@@ -3451,7 +3451,7 @@"grok_key_alternative": "Running it unattended, on a schedule? A connector key from <a href=\"/dashboard/api\">Dashboard → API</a> (choose <strong>For an AI agent</strong>), stored as a Bot secret, works on this URL too and can never spend.","grok_localhost_never_works": "<strong>Use the public URL.</strong> Grok Bot connects from xAI's cloud, not from your computer, so a <code>localhost</code> or private-network URL never works. The three.ws URLs above are public.","grok_server_is_built_for_grok_bot": "The <strong>Grok</strong> server is built for Grok Bot: the free 3D studio with no sign-in, plus your own agents when you sign in, on one URL.",- "grok_source": "Grok Bot is in beta and its connector screen still changes: if these steps drift, <a href=\"https://github.com/nirholas/three.ws/issues\" target=\"_blank\" rel=\"noopener\">tell us</a>. See what Grok Bot can do with it, live, at <a href=\"/grok\">three.ws/grok</a>, and read the full guide, with the xAI API and Grok connectors, at <a href=\"/docs/grok\">three.ws for Grok</a>.",+ "grok_source": "Grok Bot is in beta and its connector screen still changes: if these steps drift, <a href=\"https://github.com/nirholas/three.ws/issues\" target=\"_blank\" rel=\"noopener\">tell us</a>. See what Grok Bot can do with it, live, at <a href=\"/grok\">three.ws/grok</a>, read the full guide, with the xAI API and Grok connectors, at <a href=\"/docs/grok\">three.ws for Grok</a>, and fix a connection that fails with the <a href=\"/docs/grok-bot#troubleshooting\">connector reference</a>.","grok_step_add_custom": "In Grok Bot, open <strong>Connectors</strong> and add a <strong>custom MCP</strong> server with the settings above. Asking in chat works too: say \"custom server\", or Grok Bot may look for a marketplace plugin instead.","grok_step_confirm": "Grok Bot shows the name and URL. Check both, then confirm.","grok_step_use": "Ask for 3D in any task, or attach the server with <code>@</code> and its name. Grok Bot runs on its own cloud computer, so it can save the GLB to its files or run the request on a schedule.",diff --git a/scripts/run-doc-samples.mjs b/scripts/run-doc-samples.mjsnew file mode 100644index 000000000..172b1e352--- /dev/null+++ b/scripts/run-doc-samples.mjs@@ -0,0 +1,87 @@+#!/usr/bin/env node+// Run every ```bash block of one Markdown doc, in order, in a single shell+// session (so a variable one sample sets is there for the next), and print each+// sample beside its output, exit status and duration. This is how a doc's+// "every sample runs against production as written" claim is checked.+//+// node scripts/run-doc-samples.mjs docs/grok-bot.md+// node scripts/run-doc-samples.mjs docs/grok-bot.md --base http://localhost:3108 --skip 10+//+// --base swaps the `https://three.ws/api/` prefix for another origin, to run the+// same samples against a local server built from this tree. --skip takes+// 1-based sample numbers to leave out. The samples run exactly as written, so+// only point this at a doc whose samples are safe to execute (free reads and+// free generation); it never decides that for you. Exits non-zero when any+// sample exits non-zero.++import { readFileSync, writeFileSync, mkdtempSync, rmSync } from 'node:fs';+import { spawnSync } from 'node:child_process';+import { tmpdir } from 'node:os';+import path from 'node:path';++function parseArgs(argv) {+ const out = { file: null, base: null, skip: new Set() };+ for (let i = 0; i < argv.length; i++) {+ const a = argv[i];+ if (a === '--base') out.base = String(argv[++i] || '').replace(/\/+$/, '');+ else if (a === '--skip') for (const n of String(argv[++i] || '').split(',')) out.skip.add(Number(n));+ else if (!out.file) out.file = a;+ else throw new Error(`unknown argument ${a}`);+ }+ if (!out.file) throw new Error('usage: node scripts/run-doc-samples.mjs <doc.md> [--base <origin>] [--skip 1,2]');+ return out;+}++export function bashSamples(markdown) {+ return [...markdown.matchAll(/```bash\n([\s\S]*?)```/g)].map((m) => m[1].trim());+}++// One script: each sample is echoed, run, and followed by a status line that+// the summary counts. `set -o pipefail` makes a failing curl in a pipe count.+export function sessionScript(samples, { base, skip }) {+ const lines = ['set -o pipefail', 'FAILED=0'];+ samples.forEach((src, i) => {+ const n = i + 1;+ const cmd = base ? src.replaceAll('https://three.ws/api/', `${base}/api/`) : src;+ lines.push(`printf '\\n===== sample ${n} =====\\n'`, `cat <<'__SAMPLE_${n}__'`, src, `__SAMPLE_${n}__`);+ if (skip.has(n)) {+ lines.push(`echo '----- skipped'`);+ return;+ }+ lines.push(+ `echo '----- output'`,+ 'T0=$(date +%s)',+ cmd,+ 'RC=$?',+ `echo "----- exit $RC, $(( $(date +%s) - T0 )) s"`,+ '[ "$RC" -ne 0 ] && FAILED=$((FAILED + 1))',+ );+ });+ lines.push(`printf '\\n%s of ${samples.length} samples failed\\n' "$FAILED"`, 'exit $(( FAILED > 0 ))');+ return lines.join('\n');+}++function main() {+ const args = parseArgs(process.argv.slice(2));+ const samples = bashSamples(readFileSync(args.file, 'utf8'));+ if (!samples.length) throw new Error(`${args.file} has no bash samples`);+ console.log(`${samples.length} samples in ${args.file}, against ${args.base || 'https://three.ws'}`);+ const dir = mkdtempSync(path.join(tmpdir(), 'doc-samples-'));+ const file = path.join(dir, 'samples.sh');+ try {+ writeFileSync(file, sessionScript(samples, args));+ const r = spawnSync('bash', [file], { stdio: 'inherit', env: process.env });+ process.exitCode = r.status ?? 1;+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+}++if (import.meta.url === `file://${process.argv[1]}`) {+ try {+ main();+ } catch (err) {+ console.error(err?.message || err);+ process.exitCode = 1;+ }+}diff --git a/src/grok-connector.js b/src/grok-connector.jsindex 37873d43c..807c7a444 100644--- a/src/grok-connector.js+++ b/src/grok-connector.js@@ -93,7 +93,7 @@ const TEMPLATE = `<li data-i18n-html="connect.grok_step_use">Ask for 3D in any task, or attach the server with <code>@</code> and its name. Grok Bot runs on its own cloud computer, so it can save the GLB to its files or run the request on a schedule.</li></ol><p class="gc-callout" role="note" data-i18n-html="connect.grok_localhost_never_works"><strong>Use the public URL.</strong> Grok Bot connects from xAI's cloud, not from your computer, so a <code>localhost</code> or private-network URL never works. The three.ws URLs above are public.</p>- <p class="gc-src" id="gc-source" data-i18n-html="connect.grok_source">Grok Bot is in beta and its connector screen still changes: if these steps drift, <a href="https://github.com/nirholas/three.ws/issues" target="_blank" rel="noopener">tell us</a>. See what Grok Bot can do with it, live, at <a href="/grok">three.ws/grok</a>, and read the full guide, with the xAI API and Grok connectors, at <a href="/docs/grok">three.ws for Grok</a>.</p>+ <p class="gc-src" id="gc-source" data-i18n-html="connect.grok_source">Grok Bot is in beta and its connector screen still changes: if these steps drift, <a href="https://github.com/nirholas/three.ws/issues" target="_blank" rel="noopener">tell us</a>. See what Grok Bot can do with it, live, at <a href="/grok">three.ws/grok</a>, read the full guide, with the xAI API and Grok connectors, at <a href="/docs/grok">three.ws for Grok</a>, and fix a connection that fails with the <a href="/docs/grok-bot#troubleshooting">connector reference</a>.</p>`;async function copyFrom(btn, source) {diff --git a/tests/grok-bot-doc.test.js b/tests/grok-bot-doc.test.jsnew file mode 100644index 000000000..e53e896d2--- /dev/null+++ b/tests/grok-bot-doc.test.js@@ -0,0 +1,110 @@+// docs/grok-bot.md is the reference a Grok Bot integrator copies from: tool+// calls, prompt names, limit numbers and the troubleshooting table for the+// connector probe. Each of those has a source of truth in code, and this test+// fails when the doc and the code disagree, so a renamed tool, a retuned limit+// or a new probe failure breaks the build instead of the integration.+import { describe, it, expect } from 'vitest';+import fs from 'node:fs';+import path from 'node:path';++process.env.PUBLIC_APP_ORIGIN ||= 'https://three.ws';++const { toolCatalogFor } = await import('../api/_mcp-studio/dispatch.js');+const { GROK_ACCOUNT_TOOLS } = await import('../api/_mcp-studio/account-tools.js');+const { PROMPTS } = await import('../api/_mcp/prompts.js');+const { STUDIO_LIMITS } = await import('../api/_lib/rate-limit.js');+const { GROK_ENDPOINT, slugForEndpoint } = await import('../src/grok-connector.js');++const ROOT = path.resolve(import.meta.dirname, '..');+const doc = fs.readFileSync(path.join(ROOT, 'docs/grok-bot.md'), 'utf8');+const bashBlocks = [...doc.matchAll(/```bash\n([\s\S]*?)```/g)].map((m) => m[1]);++const STUDIO = new Map(toolCatalogFor('grok').map((t) => [t.name, t]));+const SERVED = new Set([...STUDIO.keys(), ...GROK_ACCOUNT_TOOLS]);+// The one sample that calls a tool on purpose to show it is not served.+const REFUSED_SAMPLE = 'agent_card_create';++// Every JSON-RPC body a sample sends with -d '...'.+const sentBodies = bashBlocks.flatMap((src) => [...src.matchAll(/-d '(\{"jsonrpc"[^']*)'/g)].map((m) => JSON.parse(m[1])));++describe('docs/grok-bot.md samples call what /api/mcp-grok serves', () => {+ it('has runnable samples for every contract the doc covers', () => {+ const methods = sentBodies.map((b) => (b.method === 'tools/call' ? b.params.name : b.method));+ expect(methods).toEqual(expect.arrayContaining(['initialize', 'tools/list', 'prompts/list', 'prompts/get', 'search_catalog', 'forge_free']));+ expect(bashBlocks.some((src) => src.includes('name:"get_job"'))).toBe(true);+ expect(bashBlocks.some((src) => src.includes('/api/mcp-studio/install'))).toBe(true);+ });++ it('every tools/call names a served tool with arguments its inputSchema accepts', () => {+ for (const body of sentBodies.filter((b) => b.method === 'tools/call')) {+ const { name, arguments: args = {} } = body.params;+ if (name === REFUSED_SAMPLE) continue;+ const tool = STUDIO.get(name);+ expect(tool, name).toBeTruthy();+ const props = Object.keys(tool.inputSchema?.properties || {});+ expect(Object.keys(args).filter((k) => !props.includes(k)), name).toEqual([]);+ expect((tool.inputSchema?.required || []).filter((k) => !(k in args)), name).toEqual([]);+ }+ });++ it('the refused-tool sample really is refused on this surface', () => {+ expect(sentBodies.some((b) => b.params?.name === REFUSED_SAMPLE)).toBe(true);+ expect(SERVED.has(REFUSED_SAMPLE)).toBe(false);+ });++ it('every generation sample carries an idempotency_key', () => {+ for (const body of sentBodies.filter((b) => b.params?.name === 'forge_free')) {+ expect(body.params.arguments.idempotency_key).toBeTruthy();+ }+ });+});++describe('docs/grok-bot.md matches the code it describes', () => {+ it('lists exactly the account tools a signed-in connector can get', () => {+ const section = doc.slice(doc.indexOf('**On `/api/mcp-grok`, value-moving tools do not exist.**'), doc.indexOf('**On every other hosted server**'));+ const named = new Set([...section.matchAll(/`([a-z_]+)`/g)].map((m) => m[1]).filter((n) => n !== REFUSED_SAMPLE));+ expect([...named].sort()).toEqual([...GROK_ACCOUNT_TOOLS].sort());+ });++ it('the prompts table is every agent prompt', () => {+ const table = doc.slice(doc.indexOf('| Prompt | Arguments | Listed |'));+ const rows = [...table.matchAll(/^\| `([a-z0-9-]+)` \|/gm)].map((m) => m[1]);+ expect(rows.sort()).toEqual(PROMPTS.filter((p) => p.agent).map((p) => p.name).sort());+ });++ it('the limits table states the enforced numbers', () => {+ const row = (label) => doc.match(new RegExp(`^\\| ${label} \\| ([0-9]+) `, 'm'))?.[1];+ expect(Number(row('Generation burst'))).toBe(STUDIO_LIMITS.genBurst.limit);+ expect(Number(row('Generation hourly'))).toBe(STUDIO_LIMITS.genHourly.limit);+ expect(Number(row('Per-IP pool'))).toBe(STUDIO_LIMITS.genPoolHourly.limit);+ expect(Number(row('Transport'))).toBe(STUDIO_LIMITS.transport.limit);+ expect(Number(row('Platform breaker'))).toBe(STUDIO_LIMITS.genGlobal.limit);+ expect(Number(row('Install token minting'))).toBe(STUDIO_LIMITS.installMint.limit);+ });++ it('uses the connector name the CLI and /connect use', () => {+ const slug = slugForEndpoint(GROK_ENDPOINT);+ expect(doc).toContain(`called ${slug} at ${GROK_ENDPOINT}`);+ expect(doc).toContain(`| Name | \`${slug}\` |`);+ });+});++describe('troubleshooting covers every failure the connector probe reports', () => {+ // The static start of each message scripts/mcp-client-probe.mjs can print.+ const probe = fs.readFileSync(path.join(ROOT, 'scripts/mcp-client-probe.mjs'), 'utf8');+ const messages = [+ ...probe.matchAll(/failures\.push\(\s*[`'](.*?)[`']\s*\)/g),+ ...probe.matchAll(/return '([A-Z][^']+)';/g),+ ...probe.matchAll(/: '(GET [^']+)'/g),+ ...probe.matchAll(/return `(GET [^`]+)`/g),+ ].map((m) => m[1].split('${')[0].replace(/\.trim\(\)$/, '').trim());++ it('finds the probe messages', () => {+ expect(messages.length).toBeGreaterThanOrEqual(22);+ });++ it('has a row for each one', () => {+ const table = doc.slice(doc.indexOf('| Probe says |'), doc.indexOf('### Errors a connected Grok Bot can see'));+ expect(messages.filter((m) => m && !table.includes(m))).toEqual([]);+ });+});