Skip to content

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.

feat(grok): add the /grok page, the Grok connector guide, and a runnable Grok remote-MCP example

nirholas49b3a514130e
diff --git a/data/examples.json b/data/examples.json
index 273aa1a31..411c6de2d 100644
--- a/data/examples.json
+++ b/data/examples.json
@@ -2,9 +2,9 @@
"$comment": "Generated by scripts/build-examples-index.mjs from what is on disk. Do not edit by hand; run npm run build:examples.",
"generated_by": "scripts/build-examples-index.mjs",
"counts": {
- "total": 48,
+ "total": 49,
"html_demos": 12,
- "projects": 10,
+ "projects": 11,
"packages": 26
},
"examples": [
@@ -62,6 +62,18 @@
"runKind": "command",
"readme": "examples/skills/README.md"
},
+ {
+ "id": "project:grok-remote-mcp",
+ "kind": "project",
+ "group": "Example projects",
+ "title": "grok-remote-mcp",
+ "description": "Grok generates a real 3D model through the free three.ws MCP server, using xAI's Responses API remote MCP tools. Zero dependencies.",
+ "path": "examples/grok-remote-mcp",
+ "files": [],
+ "run": "cd examples/grok-remote-mcp && npm install && npm run start",
+ "runKind": "command",
+ "readme": null
+ },
{
"id": "project:metamask-agent-wallet",
"kind": "project",
diff --git a/docs/examples.md b/docs/examples.md
index 64502fdbf..e9771f6cb 100644
--- a/docs/examples.md
+++ b/docs/examples.md
@@ -735,7 +735,7 @@ genuinely invested in the user's progress.
## Every runnable example in the repo
-The repo ships 48 examples: 12 web component demos, 10 end-to-end projects, and 26 package example sets. This table is generated from what is on disk, so it cannot list one that was deleted or miss one that was added. The machine-readable version is [data/examples.json](../data/examples.json).
+The repo ships 49 examples: 12 web component demos, 11 end-to-end projects, and 26 package example sets. This table is generated from what is on disk, so it cannot list one that was deleted or miss one that was added. The machine-readable version is [data/examples.json](../data/examples.json).
### Example projects
@@ -745,6 +745,7 @@ The repo ships 48 examples: 12 web component demos, 10 end-to-end projects, and
| [`examples/agent-native-3d`](../examples/agent-native-3d) | An agent given a goal ("get yourself a body") generates the 3D assets it needs and uses them - no browser, no mocks, no human in the loop. | `node examples/agent-native-3d/run.mjs` |
| [`examples/coach-leo`](../examples/coach-leo) | A complete, minimal example of a three.ws agent defined entirely as files: a manifest pointing at a 3D body, a brain, a voice, a memory policy, and one installed skill. | Reference files, nothing to execute |
| [`examples/skills`](../examples/skills) | Six installable skill bundles for the three.ws agent runtime. | Reference files, nothing to execute |
+| [`examples/grok-remote-mcp`](../examples/grok-remote-mcp) | Grok generates a real 3D model through the free three.ws MCP server, using xAI's Responses API remote MCP tools. Zero dependencies. | `cd examples/grok-remote-mcp && npm install && npm run start` |
| [`examples/metamask-agent-wallet`](../examples/metamask-agent-wallet) | A single-page demo that gives a three.ws agent a real server-side wallet through the MetaMask Agentic CLI (mm). | `node examples/metamask-agent-wallet/server.mjs` |
| [`examples/monicas-apartment`](../examples/monicas-apartment) | A single, self-contained HTML file that rebuilds the iconic Monica Geller apartment set from Friends as a walkable first-person 3D scene: purple walls, the purple front door with the yellow peephole frame, teal kitchen cabinets, the mismatched dining chairs, | `npm run dev, then open /examples/monicas-apartment/index.html` |
| [`examples/paid-mcp-server`](../examples/paid-mcp-server) | A complete, runnable MCP server whose tools charge per call in USDC on Solana over x402. It ships two tools on purpose: | `cd examples/paid-mcp-server && npm install && npm run start` |
diff --git a/docs/grok.md b/docs/grok.md
new file mode 100644
index 000000000..f798eb499
--- /dev/null
+++ b/docs/grok.md
@@ -0,0 +1,136 @@
+# three.ws for Grok and Grok Bot
+
+Give Grok a 3D studio and a body. One remote MCP server lets Grok Bot, Grok
+connectors and the xAI API turn text or an image into a textured 3D model, a
+rigged animation-ready avatar, or a named 3D persona that lip-syncs its replies.
+It is free: no account, no payment, no API key.
+
+**Live page and demo:** [three.ws/grok](/grok)
+
+| | |
+|---|---|
+| **URL** | `https://three.ws/api/mcp-grok` |
+| **Transport** | Streamable HTTP (JSON-RPC over `POST`) |
+| **Auth** | None |
+| **Protocol** | MCP `2025-06-18` |
+| **Tools** | The full free studio: the same fourteen tools as [`/api/mcp-studio`](./mcp-studio.md) |
+
+## Grok Bot
+
+Grok Bot adds a custom MCP server from chat. Send:
+
+```
+Add a custom MCP server called three-ws at https://three.ws/api/mcp-grok
+```
+
+Say "custom server" (the sentence above does), or Grok Bot may look for a
+marketplace plugin instead. It shows the name and URL and asks you to confirm.
+No sign-in card appears, because there is nothing to sign in to. Then ask for 3D
+in any task, or attach the server with `@three-ws`:
+
+- "Make a 3D model of a reusable rocket booster with grid fins, then send me the viewer link and the GLB."
+- "Give yourself a body: forge a friendly white robot, save it as your persona, and say hello to me with it."
+- "Turn this photo into a rigged, animation-ready 3D avatar and save the GLB to my files."
+
+Grok Bot works on its own cloud computer, so it can save the GLB to its files,
+hand it to another tool in the same task, or run the request on a schedule.
+
+## Grok connectors
+
+On paid Grok plans, custom connectors take a remote MCP URL (remote servers
+only, which this is). Open **Connectors**, add a **custom** connector, paste
+`https://three.ws/api/mcp-grok`, and leave authentication off. Business and
+Enterprise workspaces may need an admin to allow custom connectors first.
+
+## xAI API
+
+The Responses API connects to remote MCP servers on xAI's side. Pass the server
+as a tool ([xAI's Remote MCP docs](https://docs.x.ai/developers/tools/remote-mcp)):
+
+```bash
+curl https://api.x.ai/v1/responses \
+ -H "Authorization: Bearer $XAI_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "model": "grok-4.7",
+ "input": [{"role": "user", "content": "Make a 3D model of a lunar lander and give me the viewer link."}],
+ "tools": [{
+ "type": "mcp",
+ "server_url": "https://three.ws/api/mcp-grok",
+ "server_label": "three-ws"
+ }]
+ }'
+```
+
+With the Python SDK (`pip install xai-sdk`):
+
+```python
+import os
+from xai_sdk import Client
+from xai_sdk.chat import user
+from xai_sdk.tools import mcp
+
+client = Client(api_key=os.environ["XAI_API_KEY"])
+chat = client.chat.create(
+ model="grok-4.7",
+ tools=[mcp(server_url="https://three.ws/api/mcp-grok", server_label="three-ws")],
+)
+chat.append(user("Make a 3D model of a lunar lander and give me the viewer link."))
+print(chat.sample().content)
+```
+
+Add `allowed_tools` (`allowed_tool_names` in the Python SDK) to expose only the
+tools a task needs, for example `["search_catalog", "forge_free", "check_job"]`.
+A complete, zero-dependency Node script that also collects slow renders lives in
+[examples/grok-remote-mcp](../examples/grok-remote-mcp/README.md).
+
+## What Grok gets
+
+| Tool | What it does |
+|---|---|
+| `forge_free` | Text to a textured 3D model (GLB). |
+| `text_to_avatar`, `mesh_forge` | An avatar or an art-directed mesh from text or a reference image. |
+| `forge_avatar` | Generate and rig a character in one step. |
+| `rig_mesh` | Add a humanoid skeleton to any static GLB. |
+| `refine_model` | Change a model in words ("make it metallic") with a version history. |
+| `check_job` | Collect a render that outlived one call. |
+| `look_at_model` | Render a GLB from several angles so Grok can see what it made. |
+| `search_catalog`, `get_catalog_item`, `get_item_source` | Thousands of ready-made CC0 props, rigged characters and motion clips, plus paste-ready embed code. |
+| `create_agent_persona`, `get_agent_persona`, `persona_say` | Save a rigged model as a named body, bring it back later, and make it speak a reply with lip-sync and emotion. |
+
+Every finished model comes back with a `viewer_url` (an interactive viewer that
+opens in any browser), a `glb_url`, a `poster_png_url` and `embed_html`. Nothing
+renders inline in Grok, and the server's instructions tell Grok to hand those
+links to the user.
+
+## How it behaves under Grok
+
+**No call hangs.** A model usually lands in under a minute, but a GPU that has
+scaled to zero boots first, and a render can take a few minutes. Grok calls MCP
+from xAI's cloud with no published timeout, so this surface answers every call
+within 40 seconds: with the model, or with a pending job and the seconds to
+wait. The server's instructions tell Grok to call `check_job(job_id)` until the
+model is done and keep going without asking the user. In the Responses API,
+where Grok cannot wait between calls in one response, continue the conversation
+with `previous_response_id`, as the example does.
+
+**Your own quota.** Every Grok user reaches three.ws from xAI's shared egress,
+so per-IP limits would ration all of Grok as a single caller. MCP Streamable
+HTTP has a per-connection identity: on `initialize` the server issues an
+`Mcp-Session-Id`, and a conforming client sends it back on every later request.
+`/api/mcp-grok` keys the per-caller generation caps on that session. Minting a
+session is free, so a per-IP pool cap and the platform-wide breaker still bound
+the total, the same design the ChatGPT surface uses with OpenAI's per-user
+subject. A client that never echoes the session falls back to per-IP limits.
+
+**When generation is refused.** A rate-limited request answers HTTP 429 with a
+`retry-after` header and a plain sentence Grok can relay.
+
+## How it fits the platform
+
+`/api/mcp-grok` is one of three front doors on the same handler
+([`api/_mcp-studio/handler.js`](../api/_mcp-studio/handler.js)); `SURFACES` in
+[`api/_mcp-studio/dispatch.js`](../api/_mcp-studio/dispatch.js) defines what each
+advertises. They share one generation quota and one breaker, so the Grok door
+never adds GPU spend of its own. See [the free 3D Studio MCP](./mcp-studio.md)
+for the tools in depth and [MCP integration](./mcp.md) for every hosted server.
diff --git a/examples/README.md b/examples/README.md
index f72032556..f7f772baa 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -44,6 +44,7 @@ The demos import the framework source directly (`../src/element.js`, `../src/lib
| [pump-fun-agent/](./pump-fun-agent/) | An agent manifest composing all four production skills from [pump-fun-skills/](../pump-fun-skills/): swap, coin creation, creator fees, and token payments. |
| [skills/](./skills/) | Six installable skill bundles (`wave`, `solana-wallet`, `pump-fun`, `pump-fun-trade`, `pump-fun-compose`, `pump-fun-strategy`). Each `SKILL.md` documents its tools, config, and safety caps. |
| [agent-native-3d/](./agent-native-3d/) | A Node script that drives the free `/api/mcp-studio` MCP server end to end: generate a mesh, rig it, save it as a persistent agent persona, speak through it, and emit every distribution snippet. |
+| [grok-remote-mcp/](./grok-remote-mcp/) | Grok generates a real 3D model through `/api/mcp-grok` over xAI's Responses API remote MCP tools, collecting a slow render across turns with `previous_response_id`. Zero dependencies; `--check` and `--dry-run` need no key. |
| [agenc-task-roundtrip/](./agenc-task-roundtrip/) | End-to-end AgenC coordination-protocol demo on Solana devnet: two wallets register, post, claim, and complete a task with real on-chain transactions. |
| [metamask-agent-wallet/](./metamask-agent-wallet/) | A localhost bridge plus single page that gives an agent a real server-side wallet through the authenticated MetaMask Agentic CLI. |
| [paid-mcp-server/](./paid-mcp-server/) | An MCP server whose tools charge per call in USDC on Solana over x402: one free orientation tool, one paid glTF/GLB inspector. The seller side of the agent economy, with the verify-work-settle ordering that means a failed call never takes money. |
diff --git a/examples/grok-remote-mcp/README.md b/examples/grok-remote-mcp/README.md
new file mode 100644
index 000000000..7c4d26b64
--- /dev/null
+++ b/examples/grok-remote-mcp/README.md
@@ -0,0 +1,62 @@
+# Grok makes a 3D model through three.ws
+
+Grok generates a real, downloadable 3D model (GLB) by calling the free three.ws
+MCP server through xAI's Responses API. xAI connects to the server and runs the
+tool calls on its side; this script only talks to `api.x.ai`. Zero dependencies,
+Node 20 or newer.
+
+The server is `https://three.ws/api/mcp-grok`, the three.ws surface built for
+Grok: every free studio tool, no account, no key. See the [Grok guide](../../docs/grok.md)
+for Grok Bot and Grok connectors, and [three.ws/grok](https://three.ws/grok) for a live demo.
+
+## Run it
+
+```bash
+cd examples/grok-remote-mcp
+
+# 1. Prove the three.ws server answers and offers the tools (no key needed)
+node index.mjs --check
+
+# 2. See the exact request the script sends to xAI (no key, no call)
+node index.mjs --dry-run
+
+# 3. The real thing
+XAI_API_KEY=xai-... node index.mjs "a lunar lander with gold foil legs"
+```
+
+Get a key at [console.x.ai](https://console.x.ai). The run prints Grok's reply and
+the viewer link, which opens an interactive 3D viewer in any browser.
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `XAI_API_KEY` | none | Your xAI API key. Required for a real run. |
+| `XAI_MODEL` | `grok-4.7` | Any xAI model that supports remote MCP tools. |
+| `THREE_WS_MCP_URL` | `https://three.ws/api/mcp-grok` | Point at a local server (`http://localhost:8080/api/mcp-grok`) while developing. |
+
+## How it works
+
+The request carries one remote MCP tool:
+
+```json
+{
+ "type": "mcp",
+ "server_url": "https://three.ws/api/mcp-grok",
+ "server_label": "three-ws",
+ "allowed_tools": ["search_catalog", "forge_free", "forge_avatar", "check_job"]
+}
+```
+
+`allowed_tools` keeps Grok's context small and limits it to the tools this task
+needs. Remove it to expose the whole catalog, including rigging, refinement and
+the persona tools that give Grok a talking 3D body.
+
+**Slow renders.** A model usually lands in under a minute, but a GPU that has
+scaled to zero boots first. The server never holds a call past 40 seconds: it
+answers with a pending job and tells Grok to collect it with `check_job`. Grok
+cannot wait between calls inside one response, so the script continues the same
+conversation with `previous_response_id`, every 30 seconds, until Grok replies
+with a viewer link. Grok Bot needs none of this; it waits on its own.
+
+**Quota.** Generation is free and rate-limited per MCP session. The server
+issues an `Mcp-Session-Id` on `initialize`, and xAI echoes it, so your quota is
+yours even though every Grok user reaches three.ws from xAI's cloud.
diff --git a/examples/grok-remote-mcp/index.mjs b/examples/grok-remote-mcp/index.mjs
new file mode 100644
index 000000000..6fa7cbfb7
--- /dev/null
+++ b/examples/grok-remote-mcp/index.mjs
@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+// Grok makes a 3D model through three.ws, over xAI's Responses API.
+//
+// XAI_API_KEY=xai-... node index.mjs "a lunar lander with gold foil legs"
+// node index.mjs --check verify the three.ws MCP server answers (no key)
+// node index.mjs --dry-run print the exact xAI request (no key, no call)
+//
+// xAI connects to the remote MCP server and runs the tool calls on its side.
+// A render can outlast one response (a cold GPU boots for a minute or more), in
+// which case the three.ws server answers with a pending job instead of hanging.
+// Grok cannot wait inside a single response, so this script continues the same
+// conversation with previous_response_id until Grok hands back a viewer link.
+
+const XAI_URL = 'https://api.x.ai/v1/responses';
+const MCP_URL = process.env.THREE_WS_MCP_URL || 'https://three.ws/api/mcp-grok';
+const MODEL = process.env.XAI_MODEL || 'grok-4.7';
+const MAX_ROUNDS = 12;
+const WAIT_BETWEEN_ROUNDS_MS = 30_000;
+const VIEWER_LINK = /https:\/\/three\.ws\/viewer\?src=[^\s)"'\]]+/;
+
+// Only the tools this task needs: less context for the model, and nothing it
+// can call by surprise. Drop allowed_tools to expose the whole catalog.
+const ALLOWED_TOOLS = ['search_catalog', 'forge_free', 'forge_avatar', 'check_job'];
+
+const args = process.argv.slice(2);
+const flags = new Set(args.filter((a) => a.startsWith('--')));
+const prompt = args.filter((a) => !a.startsWith('--')).join(' ') || 'a lunar lander with gold foil legs';
+
+function request(input, previousResponseId) {
+ return {
+ model: MODEL,
+ input,
+ ...(previousResponseId ? { previous_response_id: previousResponseId } : {}),
+ tools: [
+ {
+ type: 'mcp',
+ server_url: MCP_URL,
+ server_label: 'three-ws',
+ server_description: 'Free 3D studio: text or image to textured 3D models, rigged avatars and talking personas.',
+ allowed_tools: ALLOWED_TOOLS,
+ },
+ ],
+ };
+}
+
+// The assistant's text, from the message items of a Responses API output.
+function outputText(response) {
+ if (typeof response.output_text === 'string') return response.output_text;
+ return (response.output || [])
+ .filter((item) => item.type === 'message')
+ .flatMap((item) => item.content || [])
+ .filter((part) => part.type === 'output_text')
+ .map((part) => part.text)
+ .join('\n');
+}
+
+async function callXai(body) {
+ const res = await fetch(XAI_URL, {
+ method: 'POST',
+ headers: { authorization: `Bearer ${process.env.XAI_API_KEY}`, 'content-type': 'application/json' },
+ body: JSON.stringify(body),
+ });
+ const json = await res.json().catch(() => ({}));
+ if (!res.ok) throw new Error(`xAI answered ${res.status}: ${json?.error?.message || json?.error || JSON.stringify(json).slice(0, 300)}`);
+ return json;
+}
+
+async function mcp(method, params, sessionId) {
+ const res = await fetch(MCP_URL, {
+ method: 'POST',
+ headers: {
+ 'content-type': 'application/json',
+ accept: 'application/json, text/event-stream',
+ ...(sessionId ? { 'mcp-session-id': sessionId } : {}),
+ },
+ body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
+ });
+ if (!res.ok) throw new Error(`${MCP_URL} answered ${res.status} to ${method}`);
+ return { body: await res.json(), sessionId: res.headers.get('mcp-session-id') || sessionId };
+}
+
+async function check() {
+ const init = await mcp('initialize', { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'grok-remote-mcp-example', version: '0.1.0' } });
+ const list = await mcp('tools/list', {}, init.sessionId);
+ const names = list.body.result.tools.map((t) => t.name);
+ console.log(`server ${init.body.result.serverInfo.name} (${MCP_URL})`);
+ console.log(`session ${init.sessionId || 'none issued'}`);
+ console.log(`tools ${names.length}: ${names.join(', ')}`);
+ const missing = ALLOWED_TOOLS.filter((n) => !names.includes(n));
+ if (missing.length) throw new Error(`the server does not offer: ${missing.join(', ')}`);
+ console.log('ok every allowed tool is offered');
+}
+
+async function run() {
+ if (!process.env.XAI_API_KEY) throw new Error('Set XAI_API_KEY (console.x.ai), or run with --check or --dry-run.');
+ const ask = `Use three-ws to make a 3D model of ${prompt}. When it is done, reply with the viewer link and the GLB link.`;
+ let response = await callXai(request([{ role: 'user', content: ask }]));
+ for (let round = 1; round <= MAX_ROUNDS; round++) {
+ const text = outputText(response);
+ const link = text.match(VIEWER_LINK);
+ if (link) {
+ console.log(text.trim());
+ console.log(`\nviewer ${link[0]}`);
+ return;
+ }
+ console.log(`round ${round}: the model is still rendering, asking Grok to collect it in ${WAIT_BETWEEN_ROUNDS_MS / 1000}s`);
+ await new Promise((r) => setTimeout(r, WAIT_BETWEEN_ROUNDS_MS));
+ response = await callXai(
+ request([{ role: 'user', content: 'Call check_job on that job again. When it is done, reply with the viewer link and the GLB link.' }], response.id),
+ );
+ }
+ throw new Error(`no finished model after ${MAX_ROUNDS} rounds; the last reply was:\n${outputText(response)}`);
+}
+
+try {
+ if (flags.has('--check')) await check();
+ else if (flags.has('--dry-run')) console.log(`POST ${XAI_URL}\n${JSON.stringify(request([{ role: 'user', content: `Use three-ws to make a 3D model of ${prompt}.` }]), null, 2)}`);
+ else await run();
+} catch (err) {
+ console.error(`error: ${err.message}`);
+ process.exit(1);
+}
diff --git a/examples/grok-remote-mcp/package.json b/examples/grok-remote-mcp/package.json
new file mode 100644
index 000000000..b68b2f37c
--- /dev/null
+++ b/examples/grok-remote-mcp/package.json
@@ -0,0 +1,15 @@
+{
+ "name": "@three-ws/example-grok-remote-mcp",
+ "private": true,
+ "version": "0.1.0",
+ "type": "module",
+ "description": "Grok generates a real 3D model through the free three.ws MCP server, using xAI's Responses API remote MCP tools. Zero dependencies.",
+ "scripts": {
+ "start": "node index.mjs",
+ "check": "node index.mjs --check",
+ "dry-run": "node index.mjs --dry-run"
+ },
+ "engines": {
+ "node": ">=20"
+ }
+}
diff --git a/pages/grok.html b/pages/grok.html
new file mode 100644
index 000000000..974049fcd
--- /dev/null
+++ b/pages/grok.html
@@ -0,0 +1,439 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <script>/* three.ws theme boot: no-flash */(function(){try{var m=localStorage.getItem('twx_theme');var l=m==='auto'?(window.matchMedia&&window.matchMedia('(prefers-color-scheme: light)').matches):m==='light';document.documentElement.setAttribute('data-theme',l?'light':'dark');}catch(e){document.documentElement.setAttribute('data-theme','dark');}})();</script>
+ <meta charset="utf-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+ <title>three.ws for Grok Bot: a free 3D studio and a body for Grok · three.ws</title>
+ <meta name="description" content="One sentence gives Grok Bot a 3D studio. Text and images become textured 3D models, rigged avatars, and a talking 3D body Grok can wear. Works in Grok Bot, Grok connectors and the xAI API. Free, no account, no key." />
+ <link rel="canonical" href="https://three.ws/grok" />
+ <link rel="icon" href="/favicon.ico" sizes="any" />
+ <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+ <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
+ <link rel="manifest" href="/manifest.webmanifest" />
+ <link rel="stylesheet" href="/style.css" />
+ <link rel="stylesheet" href="/nav.css" />
+ <link rel="stylesheet" href="/mobile.css" />
+ <meta property="og:type" content="website" />
+ <meta property="og:title" content="Give Grok a 3D studio, and a body" />
+ <meta property="og:description" content="One sentence adds three.ws to Grok Bot: text to 3D models, rigged avatars, and a talking 3D body. Free, no key." />
+ <meta property="og:url" content="https://three.ws/grok" />
+ <meta property="og:image" content="https://three.ws/api/page-og?s=learn&amp;t=Give+Grok+a+3D+studio%2C+and+a+body&amp;d=One+sentence+adds+three.ws+to+Grok+Bot%3A+text+to+3D+models%2C+rigged+avatars%2C+and+a+talking+3D+body.+Free%2C+no+key.&amp;p=%2Fgrok" />
+ <meta property="og:image:alt" content="Give Grok a 3D studio, and a body" />
+ <meta property="og:locale" content="en_US" />
+ <meta name="twitter:card" content="summary_large_image" />
+ <meta name="twitter:site" content="@trythreews" />
+ <meta name="twitter:title" content="Give Grok a 3D studio, and a body" />
+ <meta name="twitter:description" content="One sentence adds three.ws to Grok Bot: text to 3D models, rigged avatars, and a talking 3D body. Free, no key." />
+ <meta name="twitter:image" content="https://three.ws/api/page-og?s=learn&amp;t=Give+Grok+a+3D+studio%2C+and+a+body&amp;d=One+sentence+adds+three.ws+to+Grok+Bot%3A+text+to+3D+models%2C+rigged+avatars%2C+and+a+talking+3D+body.+Free%2C+no+key.&amp;p=%2Fgrok" />
+ <meta name="robots" content="index, follow, max-image-preview:large, max-snippet:-1" />
+ <style>
+ :root { --gk-maxw: 1080px; }
+ * { box-sizing: border-box; }
+ html, body { margin: 0; background: var(--bg-0); color: var(--ink); }
+ body { font-family: var(--font-body, 'Inter', system-ui, sans-serif); min-height: 100vh; }
+ .site-header { position: sticky; top: 0; z-index: 50; background: color-mix(in srgb, var(--bg-0) 82%, transparent); backdrop-filter: blur(10px); }
+ a { color: inherit; }
+ code, pre, kbd { font-family: var(--font-mono, ui-monospace, monospace); }
+ .gk-wrap { max-width: var(--gk-maxw); margin: 0 auto; padding: 0 18px 96px; }
+ .sr-only { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; border: 0; }
+
+ /* ── hero ───────────────────────────────────────────────────────── */
+ .gk-hero { padding: 44px 0 6px; }
+ .gk-eyebrow { font-size: 0.74rem; text-transform: uppercase; letter-spacing: 0.08em; color: var(--accent); font-weight: 650; margin: 0 0 10px; }
+ .gk-hero h1 { font-size: clamp(2rem, 5.4vw, 3.3rem); line-height: 1.05; margin: 0 0 14px; letter-spacing: -0.03em; color: var(--ink-bright, var(--ink)); max-width: 18ch; }
+ .gk-hero p { margin: 0; max-width: 62ch; color: var(--ink-dim); line-height: 1.6; font-size: 1.04rem; }
+ .gk-hero p strong { color: var(--ink-bright, var(--ink)); font-weight: 650; }
+
+ /* ── the one sentence ───────────────────────────────────────────── */
+ .gk-say { margin-top: 24px; border: 1px solid var(--stroke-strong); border-radius: var(--radius-lg, 14px); background: var(--surface-2, rgba(255,255,255,0.05)); overflow: hidden; }
+ .gk-say-label { display: flex; align-items: center; justify-content: space-between; gap: 10px; padding: 10px 14px; font-size: 0.72rem; font-weight: 650; text-transform: uppercase; letter-spacing: 0.06em; color: var(--ink-dim); border-bottom: 1px solid var(--stroke); }
+ .gk-say-row { display: flex; align-items: stretch; }
+ .gk-say-text { flex: 1; min-width: 0; margin: 0; padding: 16px 16px; font-size: 1.02rem; line-height: 1.5; color: var(--ink-bright, var(--ink)); word-break: break-word; }
+ .gk-say-text code { color: var(--accent); font-size: 0.96rem; }
+ .gk-say-row .gk-btn { border-radius: 0; border-width: 0 0 0 1px; }
+
+ /* ── buttons ────────────────────────────────────────────────────── */
+ .gk-btn {
+ display: inline-flex; align-items: center; justify-content: center; gap: 8px; text-decoration: none;
+ font: inherit; font-size: 0.88rem; font-weight: 650; padding: 10px 16px; cursor: pointer;
+ color: var(--btn-secondary-fg, var(--ink)); background: var(--btn-secondary-bg, var(--surface-3));
+ border: 1px solid var(--btn-secondary-border, var(--stroke-strong)); border-radius: var(--radius-md, 10px);
+ transition: background var(--duration-fast) var(--ease-standard), transform var(--duration-instant, 80ms) var(--ease-standard), border-color var(--duration-fast) var(--ease-standard), opacity var(--duration-fast) var(--ease-standard);
+ }
+ .gk-btn:hover { background: var(--btn-secondary-bg-hover, rgba(255,255,255,0.12)); }
+ .gk-btn:active { transform: translateY(1px); }
+ .gk-btn:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+ .gk-btn[disabled] { opacity: 0.55; cursor: not-allowed; transform: none; }
+ .gk-btn[data-variant="primary"] { color: var(--btn-primary-fg, #fff); background: var(--btn-primary-bg, var(--accent)); border-color: var(--btn-primary-border, transparent); }
+ .gk-btn[data-variant="primary"]:hover { background: var(--btn-primary-bg-hover, var(--accent)); }
+ .gk-btn[data-variant="primary"]:active { background: var(--btn-primary-bg-active, var(--accent)); }
+ .gk-btn[data-copied="true"] { color: var(--success); }
+ .gk-btn svg { width: 16px; height: 16px; flex: none; }
+ .gk-btn-sm { font-size: 0.76rem; padding: 4px 10px; }
+
+ /* ── ask chips ──────────────────────────────────────────────────── */
+ .gk-then { margin: 18px 0 0; font-size: 0.86rem; color: var(--ink-dim); }
+ .gk-asks { display: grid; grid-template-columns: repeat(auto-fit, minmax(250px, 1fr)); gap: 8px; margin-top: 10px; }
+ .gk-ask {
+ display: flex; flex-direction: column; gap: 6px; text-align: left; font: inherit; cursor: pointer;
+ padding: 12px 14px; color: var(--ink); background: var(--surface-1, rgba(255,255,255,0.03));
+ border: 1px solid var(--stroke); border-radius: var(--radius-md, 10px);
+ transition: border-color var(--duration-fast) var(--ease-standard), background var(--duration-fast) var(--ease-standard), transform var(--duration-instant, 80ms) var(--ease-standard);
+ }
+ .gk-ask:hover { border-color: var(--stroke-strong); background: var(--surface-2, rgba(255,255,255,0.06)); }
+ .gk-ask:active { transform: translateY(1px); }
+ .gk-ask:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+ .gk-ask-kind { font-size: 0.68rem; font-weight: 700; text-transform: uppercase; letter-spacing: 0.07em; color: var(--accent); display: flex; justify-content: space-between; gap: 8px; }
+ .gk-ask-kind span:last-child { color: var(--ink-faint, var(--ink-dim)); font-weight: 600; text-transform: none; letter-spacing: 0; }
+ .gk-ask[data-copied="true"] .gk-ask-kind span:last-child { color: var(--success); }
+ .gk-ask-text { font-size: 0.88rem; line-height: 1.5; color: var(--ink-bright, var(--ink)); }
+
+ /* ── section chrome ─────────────────────────────────────────────── */
+ .gk-sec { margin-top: 52px; }
+ .gk-sec-head { margin: 0 0 14px; }
+ .gk-sec-head h2 { margin: 0 0 4px; font-size: 1.3rem; letter-spacing: -0.015em; color: var(--ink-bright, var(--ink)); }
+ .gk-sec-head p { margin: 0; font-size: 0.92rem; color: var(--ink-dim); line-height: 1.55; max-width: 72ch; }
+ .gk-sec-head p code { font-size: 0.84rem; }
+
+ /* ── live demo ──────────────────────────────────────────────────── */
+ .gk-demo { display: grid; grid-template-columns: minmax(0, 1fr) minmax(0, 1.1fr); gap: 14px; }
+ .gk-card { border: 1px solid var(--stroke); border-radius: var(--radius-lg, 14px); background: linear-gradient(180deg, var(--surface-2, rgba(255,255,255,0.05)), transparent 70%); padding: 16px; min-width: 0; }
+ .gk-form label { display: block; font-size: 0.8rem; font-weight: 650; color: var(--ink-dim); margin: 0 0 6px; }
+ .gk-form textarea {
+ width: 100%; min-height: 76px; resize: vertical; font: inherit; font-size: 0.95rem; line-height: 1.5; padding: 11px 12px;
+ color: var(--ink-bright, var(--ink)); background: var(--bg-1, rgba(0,0,0,0.25)); border: 1px solid var(--stroke-strong); border-radius: var(--radius-md, 10px);
+ transition: border-color var(--duration-fast) var(--ease-standard);
+ }
+ .gk-form textarea:hover { border-color: var(--ink-faint, var(--stroke-strong)); }
+ .gk-form textarea:focus-visible { outline: 2px solid var(--accent); outline-offset: 1px; border-color: var(--accent); }
+ .gk-form-row { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; margin-top: 10px; }
+ .gk-form-hint { font-size: 0.78rem; color: var(--ink-faint, var(--ink-dim)); margin-left: auto; }
+ .gk-log {
+ margin: 14px 0 0; padding: 10px 0; list-style: none; max-height: 290px; overflow-y: auto;
+ font-family: var(--font-mono, ui-monospace, monospace); font-size: 0.76rem; line-height: 1.5;
+ background: var(--bg-1, rgba(0,0,0,0.3)); border: 1px solid var(--stroke); border-radius: var(--radius-md, 10px);
+ }
+ .gk-log li { display: grid; grid-template-columns: 52px 18px minmax(0, 1fr); gap: 4px; padding: 2px 12px; animation: gk-in var(--duration-base, 180ms) var(--ease-standard) both; }
+ .gk-log .t { color: var(--ink-faint, var(--ink-dim)); font-variant-numeric: tabular-nums; }
+ .gk-log .d { color: var(--ink-dim); }
+ .gk-log .m { color: var(--ink); overflow-wrap: anywhere; }
+ .gk-log li[data-dir="out"] .d { color: var(--accent); }
+ .gk-log li[data-tone="ok"] .m { color: var(--success); }
+ .gk-log li[data-tone="error"] .m { color: var(--danger); }
+ .gk-log-empty { padding: 6px 12px !important; display: block !important; color: var(--ink-faint, var(--ink-dim)); font-family: var(--font-body, system-ui, sans-serif); font-size: 0.82rem; }
+ @keyframes gk-in { from { opacity: 0; transform: translateY(3px); } to { opacity: 1; transform: none; } }
+
+ .gk-stage { position: relative; display: flex; flex-direction: column; min-height: 420px; padding: 0; overflow: hidden; }
+ .gk-stage model-viewer { flex: 1; width: 100%; min-height: 360px; background: transparent; --poster-color: transparent; }
+ .gk-stage-empty, .gk-stage-wait, .gk-stage-error { flex: 1; display: grid; place-items: center; text-align: center; padding: 28px; }
+ .gk-stage-empty p, .gk-stage-wait p, .gk-stage-error p { margin: 6px auto 0; max-width: 40ch; font-size: 0.88rem; line-height: 1.55; color: var(--ink-dim); }
+ .gk-stage h3 { margin: 0; font-size: 1rem; color: var(--ink-bright, var(--ink)); }
+ .gk-stage-error h3 { color: var(--danger); }
+ .gk-orb { width: 84px; height: 84px; margin: 0 auto 14px; border-radius: 50%; background: radial-gradient(circle at 35% 30%, color-mix(in srgb, var(--ink-bright, #fff) 92%, transparent), color-mix(in srgb, var(--ink-dim) 40%, transparent) 62%, transparent 72%); position: relative; }
+ .gk-orb::before, .gk-orb::after { content: ''; position: absolute; top: 30px; width: 9px; height: 22px; border-radius: 6px; background: var(--bg-0); transform: rotate(-14deg); }
+ .gk-orb::before { left: 30px; }
+ .gk-orb::after { left: 46px; }
+ .gk-stage-wait .gk-orb { animation: gk-breathe 2.4s var(--ease-standard) infinite; }
+ @keyframes gk-breathe { 0%, 100% { transform: scale(1); opacity: 0.85; } 50% { transform: scale(1.06); opacity: 1; } }
+ .gk-progress { width: min(260px, 80%); height: 4px; margin: 16px auto 0; border-radius: 999px; background: var(--surface-3, rgba(255,255,255,0.08)); overflow: hidden; }
+ .gk-progress span { display: block; height: 100%; width: 0; background: var(--accent); border-radius: inherit; transition: width 600ms var(--ease-standard); }
+ .gk-stage-bar { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; padding: 10px 12px; border-top: 1px solid var(--stroke); }
+ .gk-stage-bar .gk-src { margin-left: auto; font-size: 0.76rem; color: var(--ink-faint, var(--ink-dim)); }
+ .gk-stage [hidden] { display: none !important; }
+
+ /* ── live strip ─────────────────────────────────────────────────── */
+ .gk-strip { display: grid; grid-template-columns: repeat(6, minmax(0, 1fr)); gap: 8px; }
+ .gk-made { display: flex; flex-direction: column; text-decoration: none; border: 1px solid var(--stroke); border-radius: var(--radius-md, 10px); overflow: hidden; background: var(--surface-1, rgba(255,255,255,0.03)); transition: border-color var(--duration-fast) var(--ease-standard), transform var(--duration-fast) var(--ease-standard); }
+ .gk-made:hover { border-color: var(--stroke-strong); transform: translateY(-2px); }
+ .gk-made:active { transform: translateY(0); }
+ .gk-made:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+ .gk-made img { display: block; width: 100%; aspect-ratio: 1; object-fit: cover; background: var(--surface-2, rgba(255,255,255,0.05)); }
+ .gk-made span { padding: 7px 9px 8px; font-size: 0.74rem; line-height: 1.35; color: var(--ink-dim); display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden; }
+ .gk-strip .gk-skel { height: auto; aspect-ratio: 0.8; }
+ @media (max-width: 860px) { .gk-strip { grid-template-columns: repeat(3, minmax(0, 1fr)); } }
+
+ /* ── tools ──────────────────────────────────────────────────────── */
+ .gk-tools { display: grid; grid-template-columns: repeat(auto-fill, minmax(240px, 1fr)); gap: 8px; }
+ .gk-tool { padding: 12px 14px; border: 1px solid var(--stroke); border-radius: var(--radius-md, 10px); background: var(--surface-1, rgba(255,255,255,0.03)); transition: border-color var(--duration-fast) var(--ease-standard); }
+ .gk-tool:hover { border-color: var(--stroke-strong); }
+ .gk-tool code { font-size: 0.84rem; font-weight: 650; color: var(--ink-bright, var(--ink)); }
+ .gk-tool p { margin: 5px 0 0; font-size: 0.8rem; line-height: 1.5; color: var(--ink-dim); }
+ .gk-skel { height: 86px; border-radius: var(--radius-md, 10px); border: 1px solid var(--stroke); background: linear-gradient(90deg, var(--surface-1, rgba(255,255,255,0.03)) 0%, var(--surface-2, rgba(255,255,255,0.07)) 50%, var(--surface-1, rgba(255,255,255,0.03)) 100%); background-size: 200% 100%; animation: gk-shimmer 1.4s linear infinite; }
+ @keyframes gk-shimmer { from { background-position: 200% 0; } to { background-position: -200% 0; } }
+ .gk-note { margin: 10px 0 0; font-size: 0.84rem; color: var(--ink-dim); line-height: 1.55; }
+ .gk-note[data-tone="error"] { color: var(--danger); }
+ .gk-note button { font: inherit; color: inherit; background: none; border: 0; padding: 0; text-decoration: underline; text-underline-offset: 3px; cursor: pointer; }
+ .gk-note button:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; border-radius: 3px; }
+
+ /* ── setup tabs ─────────────────────────────────────────────────── */
+ .gk-tabs { display: flex; flex-wrap: wrap; gap: 6px; margin-bottom: 14px; }
+ .gk-tab {
+ font: inherit; font-size: 0.86rem; font-weight: 600; padding: 7px 14px; cursor: pointer; color: var(--ink-dim);
+ background: transparent; border: 1px solid var(--stroke); border-radius: 999px;
+ transition: color var(--duration-fast) var(--ease-standard), border-color var(--duration-fast) var(--ease-standard), background var(--duration-fast) var(--ease-standard);
+ }
+ .gk-tab:hover { color: var(--ink); border-color: var(--stroke-strong); background: var(--surface-1, rgba(255,255,255,0.04)); }
+ .gk-tab:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+ .gk-tab[aria-selected="true"] { color: var(--ink-bright, var(--ink)); border-color: var(--accent); background: var(--accent-soft, var(--surface-3)); }
+ .gk-panel { border: 1px solid var(--stroke); border-radius: var(--radius-lg, 14px); padding: 20px 20px 22px; background: linear-gradient(180deg, var(--surface-2, rgba(255,255,255,0.05)), transparent 70%); animation: gk-in var(--duration-base, 180ms) var(--ease-standard) both; }
+ .gk-panel[hidden] { display: none; }
+ .gk-panel-lede { margin: 0 0 14px; font-size: 0.92rem; line-height: 1.6; color: var(--ink-dim); max-width: 72ch; }
+ .gk-panel-lede strong { color: var(--ink-bright, var(--ink)); font-weight: 650; }
+ .gk-list { margin: 0 0 14px; padding: 0 0 0 20px; display: grid; gap: 8px; font-size: 0.9rem; line-height: 1.55; max-width: 72ch; }
+ .gk-list li::marker { color: var(--ink-dim); font-variant-numeric: tabular-nums; }
+ .gk-list code { font-size: 0.84rem; padding: 1px 5px; border-radius: 5px; background: var(--surface-1, rgba(255,255,255,0.05)); }
+ .gk-snippet { margin: 0 0 14px; }
+ .gk-snippet-head { display: flex; align-items: center; justify-content: space-between; gap: 8px; margin: 0 0 6px; font-size: 0.74rem; text-transform: uppercase; letter-spacing: 0.06em; color: var(--ink-dim); }
+ .gk-snippet-head .gk-btn { text-transform: none; letter-spacing: 0; }
+ .gk-snippet pre { margin: 0; padding: 13px 14px; font-size: 0.82rem; line-height: 1.55; overflow-x: auto; color: var(--ink-bright, var(--ink)); background: var(--bg-1, rgba(0,0,0,0.3)); border: 1px solid var(--stroke); border-radius: var(--radius-md, 10px); }
+ .gk-src-note { margin: 12px 0 0; font-size: 0.78rem; color: var(--ink-faint, var(--ink-dim)); }
+ .gk-src-note a, .gk-panel-lede a { text-decoration: underline; text-underline-offset: 3px; }
+ .gk-src-note a:hover, .gk-panel-lede a:hover { color: var(--ink); }
+
+ /* ── facts ──────────────────────────────────────────────────────── */
+ .gk-facts { display: grid; grid-template-columns: repeat(auto-fit, minmax(230px, 1fr)); gap: 10px; }
+ .gk-fact { padding: 15px 16px; border: 1px solid var(--stroke); border-radius: var(--radius-md, 10px); background: var(--surface-1, rgba(255,255,255,0.03)); }
+ .gk-fact h3 { margin: 0 0 6px; font-size: 0.94rem; color: var(--ink-bright, var(--ink)); }
+ .gk-fact p { margin: 0; font-size: 0.84rem; line-height: 1.55; color: var(--ink-dim); }
+ .gk-fact a { text-decoration: underline; text-underline-offset: 3px; }
+ .gk-fact a:hover { color: var(--ink); }
+ .gk-next { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 30px; }
+
+ @media (max-width: 860px) {
+ .gk-demo { grid-template-columns: minmax(0, 1fr); }
+ .gk-stage { min-height: 360px; }
+ }
+ @media (max-width: 640px) {
+ .gk-hero { padding-top: 28px; }
+ .gk-say-row { flex-direction: column; }
+ .gk-say-row .gk-btn { border-width: 1px 0 0 0; padding: 12px; }
+ .gk-panel { padding: 16px 14px 18px; }
+ .gk-form-hint { margin-left: 0; flex-basis: 100%; }
+ }
+ @media (prefers-reduced-motion: reduce) {
+ .gk-skel, .gk-panel, .gk-log li, .gk-stage-wait .gk-orb { animation: none; }
+ .gk-made { transition: none; }
+ .gk-btn, .gk-tab, .gk-ask, .gk-progress span { transition: none; }
+ }
+ </style>
+ <script type="application/ld+json">{"@context":"https://schema.org","@type":"HowTo","name":"Add three.ws to Grok Bot","description":"Give Grok Bot a free 3D studio: text and images to textured 3D models, rigged avatars and a talking 3D body, through one custom MCP server.","url":"https://three.ws/grok","step":[{"@type":"HowToStep","name":"Add the server","text":"Tell Grok Bot: Add a custom MCP server called three-ws at https://three.ws/api/mcp-grok"},{"@type":"HowToStep","name":"Confirm","text":"Grok Bot shows the name and URL. Accept. There is no sign-in and no key."},{"@type":"HowToStep","name":"Ask for 3D","text":"Ask for a model, an avatar, or a body. Grok returns a viewer link and a downloadable GLB."}]}</script>
+</head>
+<body>
+ <script src="/nav.js"></script>
+ <main class="gk-wrap" id="main">
+ <section class="gk-hero">
+ <p class="gk-eyebrow">For Grok Bot, Grok and the xAI API</p>
+ <h1>Give Grok a 3D studio, and a body.</h1>
+ <p>
+ Grok Bot routes every task to the best tool for it. For 3D, that is one sentence away:
+ <strong>text and images become textured 3D models, rigged avatars, and a talking 3D body Grok can wear.</strong>
+ Free, no account, no key.
+ </p>
+
+ <div class="gk-say" role="group" aria-labelledby="gk-say-label">
+ <div class="gk-say-label"><span id="gk-say-label">Say this to Grok Bot</span><span>No sign-in, no key</span></div>
+ <div class="gk-say-row">
+ <p class="gk-say-text" id="gk-say-text">Add a custom MCP server called three-ws at <code>https://three.ws/api/mcp-grok</code></p>
+ <button type="button" class="gk-btn" data-variant="primary" data-copy-target="gk-say-text" aria-label="Copy the sentence for Grok Bot">
+ <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><rect x="9" y="9" width="12" height="12" rx="2"/><path d="M5 15V5a2 2 0 0 1 2-2h10"/></svg>
+ <span>Copy</span>
+ </button>
+ </div>
+ </div>
+
+ <p class="gk-then">Then ask for something. Click one to copy it.</p>
+ <div class="gk-asks" id="gk-asks">
+ <button type="button" class="gk-ask" data-ask="Use three-ws to make a 3D model of a reusable rocket booster with grid fins, then send me the viewer link and the GLB.">
+ <span class="gk-ask-kind"><span>Model</span><span>Copy</span></span>
+ <span class="gk-ask-text">Make a 3D model of a reusable rocket booster with grid fins, then send me the viewer link and the GLB.</span>
+ </button>
+ <button type="button" class="gk-ask" data-ask="Use three-ws to give yourself a body: forge_avatar a friendly white robot, save it as your persona named Grok, and say hello to me with it.">
+ <span class="gk-ask-kind"><span>Body</span><span>Copy</span></span>
+ <span class="gk-ask-text">Give yourself a body: forge a friendly white robot, save it as your persona, and say hello to me with it.</span>
+ </button>
+ <button type="button" class="gk-ask" data-ask="Use three-ws to turn this photo into a rigged, animation-ready 3D avatar and save the GLB to my files.">
+ <span class="gk-ask-kind"><span>Avatar</span><span>Copy</span></span>
+ <span class="gk-ask-text">Turn this photo into a rigged, animation-ready 3D avatar and save the GLB to my files.</span>
+ </button>
+ </div>
+ </section>
+
+ <section class="gk-sec" aria-labelledby="gk-demo-h">
+ <div class="gk-sec-head">
+ <h2 id="gk-demo-h">Run exactly what Grok runs</h2>
+ <p>This box is an MCP client talking to <code>/api/mcp-grok</code>, the same server and the same calls Grok Bot makes. Every request and answer is logged as it happens. A cold GPU can take a few minutes; the job keeps running and the page collects it.</p>
+ </div>
+ <div class="gk-demo">
+ <div class="gk-card">
+ <form class="gk-form" id="gk-form" novalidate>
+ <label for="gk-prompt">Describe one object or character</label>
+ <textarea id="gk-prompt" name="prompt" maxlength="600" required placeholder="a small reusable rocket booster with grid fins"></textarea>
+ <div class="gk-form-row">
+ <button type="submit" class="gk-btn" data-variant="primary" id="gk-go">Generate in 3D</button>
+ <button type="button" class="gk-btn" id="gk-stop" hidden>Stop collecting</button>
+ <span class="gk-form-hint">Free. Counts toward this session's hourly quota.</span>
+ </div>
+ </form>
+ <ol class="gk-log" id="gk-log" aria-live="polite" aria-label="MCP transcript">
+ <li class="gk-log-empty">The JSON-RPC transcript appears here: initialize, tools/call, then check_job until the model lands.</li>
+ </ol>
+ </div>
+ <div class="gk-card gk-stage" id="gk-stage" aria-live="polite">
+ <div class="gk-stage-empty" id="gk-empty">
+ <div>
+ <div class="gk-orb" aria-hidden="true"></div>
+ <h3>Your model lands here</h3>
+ <p>Write a prompt and press Generate. You get an interactive model you can spin, plus the same viewer link and GLB Grok hands back.</p>
+ </div>
+ </div>
+ <div class="gk-stage-wait" id="gk-wait" hidden>
+ <div>
+ <div class="gk-orb" aria-hidden="true"></div>
+ <h3 id="gk-wait-h">Submitting the job</h3>
+ <p id="gk-wait-p">Asking the studio to start rendering.</p>
+ <div class="gk-progress" role="progressbar" aria-label="Elapsed against the estimate" aria-valuemin="0" aria-valuemax="100" aria-valuenow="0"><span id="gk-bar"></span></div>
+ </div>
+ </div>
+ <div class="gk-stage-error" id="gk-error" hidden>
+ <div>
+ <h3 id="gk-error-h">That did not work</h3>
+ <p id="gk-error-p"></p>
+ <p><button type="button" class="gk-btn gk-btn-sm" id="gk-retry">Try again</button></p>
+ </div>
+ </div>
+ <model-viewer id="gk-mv" hidden camera-controls auto-rotate touch-action="pan-y" shadow-intensity="0.8" exposure="1.05" alt="The generated 3D model"></model-viewer>
+ <div class="gk-stage-bar" id="gk-bar-actions" hidden>
+ <a class="gk-btn gk-btn-sm" id="gk-open" href="/viewer" target="_blank" rel="noopener">Open viewer</a>
+ <a class="gk-btn gk-btn-sm" id="gk-dl" href="/viewer" download>Download GLB</a>
+ <button type="button" class="gk-btn gk-btn-sm" id="gk-embed" hidden><span>Copy embed code</span></button>
+ <span class="gk-src" id="gk-took"></span>
+ </div>
+ </div>
+ </div>
+ </section>
+
+ <section class="gk-sec" aria-labelledby="gk-made-h">
+ <div class="gk-sec-head">
+ <h2 id="gk-made-h">Made on three.ws, just now</h2>
+ <p>The latest models anyone generated on the free studio, the same pipeline Grok calls. Open one to spin it, download it, or put it on a page.</p>
+ </div>
+ <div class="gk-strip" id="gk-strip" aria-busy="true">
+ <div class="gk-skel"></div><div class="gk-skel"></div><div class="gk-skel"></div><div class="gk-skel"></div><div class="gk-skel"></div><div class="gk-skel"></div>
+ </div>
+ <p class="gk-note" id="gk-strip-note" hidden></p>
+ </section>
+
+ <section class="gk-sec" aria-labelledby="gk-tools-h">
+ <div class="gk-sec-head">
+ <h2 id="gk-tools-h">What Grok gets</h2>
+ <p>Read live from the server's <code>tools/list</code>, so this is always the real catalog.</p>
+ </div>
+ <div class="gk-tools" id="gk-tools" aria-busy="true">
+ <div class="gk-skel"></div><div class="gk-skel"></div><div class="gk-skel"></div><div class="gk-skel"></div><div class="gk-skel"></div><div class="gk-skel"></div>
+ </div>
+ <p class="gk-note" id="gk-tools-note" hidden></p>
+ </section>
+
+ <section class="gk-sec" aria-labelledby="gk-setup-h">
+ <div class="gk-sec-head">
+ <h2 id="gk-setup-h">Set it up anywhere Grok runs</h2>
+ <p>One URL, <code>https://three.ws/api/mcp-grok</code>. Streamable HTTP, authentication none.</p>
+ </div>
+ <div class="gk-tabs" role="tablist" aria-label="Where you use Grok">
+ <button type="button" class="gk-tab" role="tab" id="tab-bot" aria-controls="panel-bot" aria-selected="true" data-tab="bot">Grok Bot</button>
+ <button type="button" class="gk-tab" role="tab" id="tab-app" aria-controls="panel-app" aria-selected="false" tabindex="-1" data-tab="app">Grok connectors</button>
+ <button type="button" class="gk-tab" role="tab" id="tab-api" aria-controls="panel-api" aria-selected="false" tabindex="-1" data-tab="api">xAI API</button>
+ </div>
+
+ <div class="gk-panel" role="tabpanel" id="panel-bot" aria-labelledby="tab-bot">
+ <p class="gk-panel-lede">Grok Bot adds a custom MCP server from chat. Say <strong>custom server</strong>, or it may go looking for a marketplace plugin instead.</p>
+ <ol class="gk-list">
+ <li>Send: <code>Add a custom MCP server called three-ws at https://three.ws/api/mcp-grok</code></li>
+ <li>Grok Bot shows the name and URL. Check the URL and accept. No sign-in card appears, because there is nothing to sign in to.</li>
+ <li>Ask for 3D in any task, or attach the server with <code>@three-ws</code>. Scheduled tasks can use it too.</li>
+ </ol>
+ <p class="gk-src-note">Grok Bot runs on its own cloud computer, so it can also save the GLB to its files or hand it to another tool in the same task.</p>
+ </div>
+
+ <div class="gk-panel" role="tabpanel" id="panel-app" aria-labelledby="tab-app" hidden>
+ <p class="gk-panel-lede">On paid Grok plans, custom connectors take a remote MCP URL. Only remote servers work there, which is exactly what this is.</p>
+ <ol class="gk-list">
+ <li>In Grok, open <strong>Connectors</strong> and add a <strong>custom</strong> connector.</li>
+ <li>Paste <code>https://three.ws/api/mcp-grok</code> and leave authentication off.</li>
+ <li>Ask Grok for a 3D model in any chat. It answers with a viewer link and a GLB.</li>
+ </ol>
+ <p class="gk-src-note">Business and Enterprise workspaces may need an admin to allow custom connectors first.</p>
+ </div>
+
+ <div class="gk-panel" role="tabpanel" id="panel-api" aria-labelledby="tab-api" hidden>
+ <p class="gk-panel-lede">The xAI Responses API connects remote MCP servers for you: pass the URL as a tool and Grok calls it server side. Set <code>XAI_API_KEY</code> and run.</p>
+ <div class="gk-snippet">
+ <div class="gk-snippet-head"><span>curl</span><button type="button" class="gk-btn gk-btn-sm" data-copy-target="gk-curl">Copy</button></div>
+ <pre id="gk-curl">curl https://api.x.ai/v1/responses \
+ -H "Authorization: Bearer $XAI_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "model": "grok-4.7",
+ "input": [{"role": "user", "content": "Make a 3D model of a lunar lander and give me the viewer link."}],
+ "tools": [{
+ "type": "mcp",
+ "server_url": "https://three.ws/api/mcp-grok",
+ "server_label": "three-ws"
+ }]
+ }'</pre>
+ </div>
+ <div class="gk-snippet">
+ <div class="gk-snippet-head"><span>Python (xai-sdk)</span><button type="button" class="gk-btn gk-btn-sm" data-copy-target="gk-py">Copy</button></div>
+ <pre id="gk-py">import os
+from xai_sdk import Client
+from xai_sdk.chat import user
+from xai_sdk.tools import mcp
+
+client = Client(api_key=os.environ["XAI_API_KEY"])
+chat = client.chat.create(
+ model="grok-4.7",
+ tools=[mcp(server_url="https://three.ws/api/mcp-grok", server_label="three-ws")],
+)
+chat.append(user("Make a 3D model of a lunar lander and give me the viewer link."))
+print(chat.sample().content)</pre>
+ </div>
+ <p class="gk-src-note">A full Node example, with the pending-job loop and an <code>allowed_tools</code> list, lives in <a href="https://github.com/nirholas/three.ws/tree/main/examples/grok-remote-mcp" target="_blank" rel="noopener">examples/grok-remote-mcp</a>. Request shape from <a href="https://docs.x.ai/developers/tools/remote-mcp" target="_blank" rel="noopener">xAI's Remote MCP docs</a>.</p>
+ </div>
+ </section>
+
+ <section class="gk-sec" aria-labelledby="gk-facts-h">
+ <div class="gk-sec-head"><h2 id="gk-facts-h">Built for an agent that works while you sleep</h2></div>
+ <div class="gk-facts">
+ <div class="gk-fact">
+ <h3>Never hangs a task</h3>
+ <p>A render can take minutes on a cold GPU. Every call answers within 40 seconds, with the model or a job id, and Grok collects it with <code>check_job</code>. Nothing times out half-done.</p>
+ </div>
+ <div class="gk-fact">
+ <h3>Your own quota</h3>
+ <p>Every Grok user reaches us from xAI's cloud. Limits follow your MCP session, not xAI's IP address, so one busy user never spends yours.</p>
+ </div>
+ <div class="gk-fact">
+ <h3>A body, not just a file</h3>
+ <p><code>create_agent_persona</code> turns a rigged model into a named body that lip-syncs and emotes. Grok can bring the same body back in any later task.</p>
+ </div>
+ <div class="gk-fact">
+ <h3>Check the catalog first</h3>
+ <p>Thousands of ready-made CC0 props, rigged characters and motion clips. Grok searches them before generating, so common asks come back instantly.</p>
+ </div>
+ </div>
+ <div class="gk-next">
+ <a class="gk-btn" href="/docs/grok">Read the Grok guide</a>
+ <a class="gk-btn" href="/connect">Connect other AI clients</a>
+ <a class="gk-btn" href="/forge">Open the 3D studio</a>
+ </div>
+ </section>
+ </main>
+
+ <script src="/brand.js" defer></script>
+ <script src="/model-viewer-meshopt.js"></script>
+ <script type="module" src="https://ajax.googleapis.com/ajax/libs/model-viewer/4.0.0/model-viewer.min.js"></script>
+ <script type="module" src="/src/grok-page.js"></script>
+ <script type="module" src="/i18n.js"></script>
+</body>
+</html>
diff --git a/public/examples.json b/public/examples.json
index cce3488d9..a402fca10 100644
--- a/public/examples.json
+++ b/public/examples.json
@@ -2,9 +2,9 @@
"$comment": "GENERATED by scripts/mirror-examples-index.mjs from data/examples.json. Do not edit; run `npm run build:examples`.",
"generated_by": "scripts/build-examples-index.mjs",
"counts": {
- "total": 48,
+ "total": 49,
"html_demos": 12,
- "projects": 10,
+ "projects": 11,
"packages": 26
},
"examples": [
@@ -62,6 +62,18 @@
"runKind": "command",
"readme": "examples/skills/README.md"
},
+ {
+ "id": "project:grok-remote-mcp",
+ "kind": "project",
+ "group": "Example projects",
+ "title": "grok-remote-mcp",
+ "description": "Grok generates a real 3D model through the free three.ws MCP server, using xAI's Responses API remote MCP tools. Zero dependencies.",
+ "path": "examples/grok-remote-mcp",
+ "files": [],
+ "run": "cd examples/grok-remote-mcp && npm install && npm run start",
+ "runKind": "command",
+ "readme": null
+ },
{
"id": "project:metamask-agent-wallet",
"kind": "project",
diff --git a/scripts/grok-connector-demo.mjs b/scripts/grok-connector-demo.mjs
new file mode 100644
index 000000000..79b136eff
--- /dev/null
+++ b/scripts/grok-connector-demo.mjs
@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+// "Give Grok a body", run end to end against the Grok Bot connector.
+//
+// Drives the official MCP SDK client over Streamable HTTP, the transport Grok
+// Bot's custom MCP connector uses, against /api/mcp-grok and walks the flow the
+// surface's instructions tell Grok to follow:
+//
+// 1. forge_avatar(prompt) a rigged humanoid GLB, or a pending job
+// 2. check_job(job_id) until done honouring the suggested wait, then
+// rig_mesh when the pending handle said the rig comes next
+// 3. create_agent_persona(glb, name) a persistent body with a persona_id
+// 4. persona_say(persona_id, text) the body speaks a line, returns embed_url
+//
+// Every request carries the Mcp-Session-Id the server issued on initialize, the
+// same id Grok Bot echoes, so this run is metered exactly like a Grok user.
+// The transcript (each call, its arguments, elapsed time, and the links it
+// returned) is written as JSON for the announcement that cites it.
+//
+// node scripts/grok-connector-demo.mjs --prompt "..." --name "..." --say "..."
+// node scripts/grok-connector-demo.mjs --base http://localhost:3000 --json out.json
+// node scripts/grok-connector-demo.mjs --path /api/mcp-studio ... (same tools, no session caps)
+// node scripts/grok-connector-demo.mjs --job <job_id> --rig-after-job ... (resume a pending avatar)
+//
+// Exit code 0 when the persona spoke, 1 on any failed step.
+
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+
+const { values: opts } = parseArgs({
+ options: {
+ base: { type: 'string', default: 'https://three.ws' },
+ path: { type: 'string', default: '/api/mcp-grok' },
+ prompt: { type: 'string' },
+ name: { type: 'string' },
+ say: { type: 'string' },
+ json: { type: 'string' },
+ job: { type: 'string' },
+ 'rig-after-job': { type: 'boolean', default: false },
+ 'max-wait': { type: 'string', default: '900' },
+ },
+});
+
+for (const key of ['prompt', 'name', 'say']) {
+ if (!opts[key]) {
+ console.error(`missing --${key}`);
+ process.exit(2);
+ }
+}
+
+const endpoint = new URL(opts.path, opts.base);
+const maxWaitMs = Number(opts['max-wait']) * 1000;
+const transcript = { endpoint: endpoint.href, startedAt: new Date().toISOString(), steps: [] };
+
+// A tool result's links, from structuredContent first, then any URL in the text.
+function linksOf(result) {
+ const sc = result?.structuredContent || {};
+ const out = {};
+ const walk = (obj, depth = 0) => {
+ if (!obj || typeof obj !== 'object' || depth > 3) return;
+ for (const [k, v] of Object.entries(obj)) {
+ if (typeof v === 'string' && /^https?:\/\//.test(v)) out[k] = v;
+ else if (typeof v === 'object') walk(v, depth + 1);
+ }
+ };
+ walk(sc);
+ return out;
+}
+
+function textOf(result) {
+ return (result?.content || []).filter((c) => c.type === 'text').map((c) => c.text).join('\n');
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+async function call(client, name, args, { retryable = false } = {}) {
+ const t0 = Date.now();
+ const result = await client.callTool({ name, arguments: args }, undefined, { timeout: 300_000 });
+ const step = {
+ tool: name,
+ arguments: args,
+ elapsedMs: Date.now() - t0,
+ isError: !!result.isError,
+ status: result.structuredContent?.status ?? null,
+ links: linksOf(result),
+ structured: result.structuredContent ?? null,
+ text: textOf(result).slice(0, 2000),
+ };
+ transcript.steps.push(step);
+ console.log(`${name.padEnd(22)} ${String(step.elapsedMs).padStart(6)} ms ${step.status || (step.isError ? 'error' : 'ok')}`);
+ if (result.isError && !(retryable && result.structuredContent?.retryable)) throw new Error(`${name} failed: ${step.text.slice(0, 400)}`);
+ return result;
+}
+
+// A generation answers inside the surface's call budget with the model or a
+// pending handle; collect it the way the instructions tell Grok to. A retryable
+// check error (a slow poll, a busy bucket) leaves the job running, so the same
+// handle is checked again rather than abandoned.
+async function collect(client, first) {
+ let result = first;
+ let handle = first.structuredContent;
+ const deadline = Date.now() + maxWaitMs;
+ while (result.structuredContent?.status === 'pending' || result.isError) {
+ if (Date.now() > deadline) throw new Error(`job still pending after ${opts['max-wait']} s`);
+ if (!result.isError) handle = result.structuredContent;
+ const sc = handle;
+ const waitS = Math.min(Math.max(Number(sc.coldStartRemainingSeconds || sc.etaRemainingSeconds || 10), 5), 30);
+ await sleep(waitS * 1000);
+ result = await call(client, 'check_job', { job_id: sc.job_id || sc.jobId }, { retryable: true });
+ }
+ return { result, stage: handle?.stage ?? null, next: handle?.next ?? null };
+}
+
+function glbOf(result) {
+ const sc = result.structuredContent || {};
+ return sc.glb_url || sc.glbUrl || sc.model?.glb_url || sc.model?.glbUrl || linksOf(result).glb_url || linksOf(result).glbUrl;
+}
+
+async function main() {
+ const client = new Client({ name: 'grok-connector-demo', version: '1.0.0' });
+ const transport = new StreamableHTTPClientTransport(endpoint);
+ await client.connect(transport);
+ transcript.sessionId = transport.sessionId ?? null;
+ transcript.server = client.getServerVersion();
+ const { tools } = await client.listTools();
+ transcript.toolCount = tools.length;
+ console.log(`connected ${endpoint.href} session=${transcript.sessionId} tools=${tools.length}`);
+
+ const first = opts.job
+ ? await call(client, 'check_job', { job_id: opts.job }, { retryable: true })
+ : await call(client, 'forge_avatar', { prompt: opts.prompt });
+ const forged = await collect(client, first);
+ let glbUrl = glbOf(forged.result);
+ if (!glbUrl) throw new Error('forge_avatar finished without a GLB url');
+ transcript.meshUrl = glbUrl;
+
+ // A pending avatar is collected as its bare mesh; the rig is the second half.
+ if (forged.next === 'rig' || (opts.job && opts['rig-after-job'])) {
+ const rigged = await collect(client, await call(client, 'rig_mesh', { glb_url: glbUrl }));
+ glbUrl = glbOf(rigged.result);
+ if (!glbUrl) throw new Error('rig_mesh finished without a GLB url');
+ }
+ transcript.glbUrl = glbUrl;
+
+ const persona = await call(client, 'create_agent_persona', { glb_url: glbUrl, name: opts.name, source_prompt: opts.prompt });
+ const personaId = persona.structuredContent?.persona_id || persona.structuredContent?.persona?.persona_id;
+ if (!personaId) throw new Error('create_agent_persona returned no persona_id');
+ transcript.personaId = personaId;
+
+ const said = await call(client, 'persona_say', { persona_id: personaId, text: opts.say });
+ transcript.embedUrl = said.structuredContent?.embed_url || linksOf(said).embed_url || null;
+ transcript.finishedAt = new Date().toISOString();
+ await client.close();
+}
+
+let code = 0;
+try {
+ await main();
+} catch (err) {
+ transcript.error = err.message;
+ console.error(err.message);
+ code = 1;
+}
+if (opts.json) {
+ const out = resolve(opts.json);
+ mkdirSync(dirname(out), { recursive: true });
+ writeFileSync(out, JSON.stringify(transcript, null, '\t') + '\n');
+ console.log(`transcript: ${out}`);
+}
+process.exit(code);
diff --git a/src/grok-page.js b/src/grok-page.js
new file mode 100644
index 000000000..ab6b57b94
--- /dev/null
+++ b/src/grok-page.js
@@ -0,0 +1,458 @@
+// /grok: three.ws for Grok Bot, Grok connectors and the xAI API.
+//
+// The demo on this page is a real MCP client for /api/mcp-grok, the surface
+// Grok connects to. It runs the same sequence Grok does: initialize (which
+// issues the Mcp-Session-Id the server keys its quota on), tools/call, then
+// check_job until the model lands. Every request and answer goes into the
+// visible transcript, so what you watch is what Grok sees.
+
+const ENDPOINT = '/api/mcp-grok';
+const POLL_MIN_S = 5;
+const POLL_MAX_S = 30;
+const POLL_DEFAULT_S = 15;
+
+const $ = (id) => document.getElementById(id);
+
+// ── copy buttons ─────────────────────────────────────────────────────────
+
+async function copyText(text, btn) {
+ try {
+ await navigator.clipboard.writeText(text);
+ } catch {
+ const ta = document.createElement('textarea');
+ ta.value = text;
+ ta.setAttribute('readonly', '');
+ ta.style.position = 'fixed';
+ ta.style.opacity = '0';
+ document.body.appendChild(ta);
+ ta.select();
+ document.execCommand('copy');
+ ta.remove();
+ }
+ flashCopied(btn);
+}
+
+function flashCopied(btn) {
+ const label = btn.querySelector('.gk-ask-kind span:last-child') || btn.querySelector('span') || btn;
+ const before = label.textContent;
+ btn.dataset.copied = 'true';
+ label.textContent = 'Copied';
+ clearTimeout(btn._copyTimer);
+ btn._copyTimer = setTimeout(() => {
+ btn.dataset.copied = 'false';
+ label.textContent = before;
+ }, 1600);
+}
+
+function wireCopy() {
+ for (const btn of document.querySelectorAll('[data-copy-target]')) {
+ btn.addEventListener('click', () => copyText($(btn.dataset.copyTarget).textContent.trim(), btn));
+ }
+ for (const btn of document.querySelectorAll('[data-ask]')) {
+ btn.addEventListener('click', () => copyText(btn.dataset.ask, btn));
+ }
+}
+
+// ── setup tabs (WAI-ARIA tabs pattern, roving tabindex) ──────────────────
+
+function wireTabs() {
+ const tabs = [...document.querySelectorAll('.gk-tab')];
+ const select = (tab, focus) => {
+ for (const t of tabs) {
+ const on = t === tab;
+ t.setAttribute('aria-selected', String(on));
+ t.tabIndex = on ? 0 : -1;
+ $(t.getAttribute('aria-controls')).hidden = !on;
+ }
+ if (focus) tab.focus();
+ };
+ tabs.forEach((tab, i) => {
+ tab.addEventListener('click', () => select(tab, false));
+ tab.addEventListener('keydown', (e) => {
+ const step = { ArrowRight: 1, ArrowLeft: -1 }[e.key];
+ if (step) {
+ e.preventDefault();
+ select(tabs[(i + step + tabs.length) % tabs.length], true);
+ } else if (e.key === 'Home' || e.key === 'End') {
+ e.preventDefault();
+ select(tabs[e.key === 'Home' ? 0 : tabs.length - 1], true);
+ }
+ });
+ });
+}
+
+// ── the MCP client ───────────────────────────────────────────────────────
+
+class RpcError extends Error {
+ constructor(message, { status = 0, retryAfter = 0 } = {}) {
+ super(message);
+ this.status = status;
+ this.retryAfter = retryAfter;
+ }
+}
+
+function createClient() {
+ let sessionId = null;
+ let nextId = 0;
+ return {
+ get sessionId() {
+ return sessionId;
+ },
+ async call(method, params, signal) {
+ const headers = { 'content-type': 'application/json', accept: 'application/json, text/event-stream' };
+ if (sessionId) headers['mcp-session-id'] = sessionId;
+ const res = await fetch(ENDPOINT, {
+ method: 'POST',
+ headers,
+ body: JSON.stringify({ jsonrpc: '2.0', id: ++nextId, method, params }),
+ signal,
+ });
+ const issued = res.headers.get('mcp-session-id');
+ if (issued) sessionId = issued;
+ const body = await res.json().catch(() => null);
+ if (!res.ok) {
+ const message = body?.error_description || body?.error?.message || `The server answered ${res.status}.`;
+ throw new RpcError(message, { status: res.status, retryAfter: Number(res.headers.get('retry-after')) || 0 });
+ }
+ if (body?.error) throw new RpcError(body.error.message || 'The server rejected the request.');
+ return body?.result;
+ },
+ };
+}
+
+// ── transcript ───────────────────────────────────────────────────────────
+
+function createLog(el) {
+ let t0 = 0;
+ return {
+ reset() {
+ el.replaceChildren();
+ t0 = performance.now();
+ },
+ add(dir, text, tone) {
+ const li = document.createElement('li');
+ li.dataset.dir = dir;
+ if (tone) li.dataset.tone = tone;
+ const t = document.createElement('span');
+ t.className = 't';
+ t.textContent = `${((performance.now() - t0) / 1000).toFixed(1)}s`;
+ const d = document.createElement('span');
+ d.className = 'd';
+ d.textContent = dir === 'out' ? '→' : '←';
+ d.setAttribute('aria-label', dir === 'out' ? 'sent' : 'received');
+ const m = document.createElement('span');
+ m.className = 'm';
+ m.textContent = text;
+ li.append(t, d, m);
+ el.append(li);
+ el.scrollTop = el.scrollHeight;
+ },
+ };
+}
+
+// ── stage (empty / waiting / error / model) ──────────────────────────────
+
+function createStage() {
+ const panes = { empty: $('gk-empty'), wait: $('gk-wait'), error: $('gk-error'), model: $('gk-mv') };
+ const show = (name) => {
+ for (const [k, el] of Object.entries(panes)) el.hidden = k !== name;
+ $('gk-bar-actions').hidden = name !== 'model';
+ };
+ return {
+ empty: () => show('empty'),
+ wait(title, detail, fraction) {
+ $('gk-wait-h').textContent = title;
+ $('gk-wait-p').textContent = detail;
+ const pct = Math.max(4, Math.min(96, Math.round((fraction ?? 0) * 100)));
+ $('gk-bar').style.width = `${pct}%`;
+ $('gk-bar').parentElement.setAttribute('aria-valuenow', String(pct));
+ show('wait');
+ },
+ error(title, detail) {
+ $('gk-error-h').textContent = title;
+ $('gk-error-p').textContent = detail;
+ show('error');
+ },
+ model(sc, seconds) {
+ const glb = sc.glb_url || sc.glbUrl;
+ panes.model.setAttribute('src', glb);
+ const posterUrl = sc.poster_png_url;
+ if (posterUrl) panes.model.setAttribute('poster', posterUrl);
+ $('gk-open').href = sc.viewer_url || sc.viewerUrl;
+ $('gk-dl').href = glb;
+ const embed = $('gk-embed');
+ embed.hidden = !sc.embed_html;
+ embed.dataset.embed = sc.embed_html || '';
+ $('gk-took').textContent = `Landed in ${seconds}s`;
+ show('model');
+ },
+ };
+}
+
+// ── demo flow ────────────────────────────────────────────────────────────
+
+const sleep = (ms, signal) =>
+ new Promise((resolve, reject) => {
+ const timer = setTimeout(resolve, ms);
+ signal?.addEventListener(
+ 'abort',
+ () => {
+ clearTimeout(timer);
+ reject(new DOMException('stopped', 'AbortError'));
+ },
+ { once: true },
+ );
+ });
+
+// How long to wait before the next check_job, from the numbers the server put
+// on the pending result: the boot time left on a cold worker, else the render
+// ETA, else a steady default.
+function nextWaitSeconds(sc) {
+ const hint = Number(sc?.cold?.remainingSeconds) || Number(sc?.etaRemainingSeconds) || POLL_DEFAULT_S;
+ return Math.max(POLL_MIN_S, Math.min(POLL_MAX_S, Math.round(hint)));
+}
+
+function pendingCopy(sc) {
+ if (sc?.cold) {
+ const left = Number(sc.cold.remainingSeconds);
+ return {
+ title: 'Waking a GPU',
+ detail: left > 0
+ ? `The job is accepted. The GPU worker is booting, about ${left}s left, and rendering starts the moment it answers.`
+ : 'The job is accepted. The GPU worker is booting and rendering starts the moment it answers.',
+ };
+ }
+ const eta = Number(sc?.etaRemainingSeconds);
+ return {
+ title: 'Rendering your model',
+ detail: eta > 0 ? `Roughly ${eta}s to go. The page collects it with check_job, exactly like Grok.` : 'Still rendering. The page collects it with check_job, exactly like Grok.',
+ };
+}
+
+function describeFailure(err) {
+ if (err?.status === 429) {
+ const wait = err.retryAfter ? ` Try again in about ${Math.ceil(err.retryAfter / 60)} min.` : '';
+ return { title: 'Free quota reached for now', detail: `${err.message}.${wait}` };
+ }
+ if (err instanceof TypeError) return { title: 'Could not reach three.ws', detail: 'Check your connection, then try again.' };
+ return { title: 'That did not work', detail: err?.message || 'The studio could not finish this one. Try again, or reword the prompt.' };
+}
+
+function brief(sc) {
+ if (sc?.glb_url || sc?.glbUrl) return 'done, glbUrl ready';
+ if (sc?.status === 'pending') {
+ const wait = nextWaitSeconds(sc);
+ return `pending (${sc.cold ? 'GPU booting' : 'rendering'}), check_job again in ~${wait}s`;
+ }
+ return 'result received';
+}
+
+function startDemo() {
+ const form = $('gk-form');
+ const prompt = $('gk-prompt');
+ const go = $('gk-go');
+ const stop = $('gk-stop');
+ const log = createLog($('gk-log'));
+ const stage = createStage();
+ let controller = null;
+
+ const setBusy = (busy) => {
+ go.disabled = busy;
+ go.textContent = busy ? 'Generating…' : 'Generate in 3D';
+ stop.hidden = !busy;
+ prompt.readOnly = busy;
+ };
+
+ async function run(text) {
+ controller = new AbortController();
+ const { signal } = controller;
+ const client = createClient();
+ const started = performance.now();
+ const elapsed = () => Math.round((performance.now() - started) / 1000);
+ setBusy(true);
+ log.reset();
+ stage.wait('Submitting the job', 'Opening an MCP session with the studio.', 0.04);
+ try {
+ log.add('out', 'initialize');
+ const init = await client.call('initialize', { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'three.ws/grok demo', version: '1' } }, signal);
+ log.add('in', `${init?.serverInfo?.name || 'server'} ready${client.sessionId ? `, session ${client.sessionId.slice(0, 12)}…` : ''}`);
+
+ log.add('out', `tools/call forge_free { prompt: "${text.length > 60 ? `${text.slice(0, 60)}…` : text}" }`);
+ stage.wait('Submitting the job', 'The studio paints a concept, then sculpts it into a mesh.', 0.08);
+ let result = await client.call('tools/call', { name: 'forge_free', arguments: { prompt: text } }, signal);
+ let sc = result?.structuredContent || {};
+ if (result?.isError) throw new Error(sc.message || result?.content?.[0]?.text || 'The studio could not start this one.');
+ log.add('in', brief(sc), sc.glbUrl ? 'ok' : undefined);
+
+ let firstEta = null;
+ while (sc.status === 'pending' && sc.jobId) {
+ const wait = nextWaitSeconds(sc);
+ firstEta ??= elapsed() + wait;
+ const copy = pendingCopy(sc);
+ stage.wait(copy.title, copy.detail, elapsed() / Math.max(firstEta, elapsed() + wait));
+ await sleep(wait * 1000, signal);
+ log.add('out', `tools/call check_job { job_id: "${sc.jobId.slice(0, 10)}…" }`);
+ result = await client.call('tools/call', { name: 'check_job', arguments: { job_id: sc.jobId } }, signal);
+ sc = result?.structuredContent || {};
+ if (result?.isError) throw new Error(sc.message || result?.content?.[0]?.text || 'The job failed.');
+ log.add('in', brief(sc), sc.glbUrl || sc.glb_url ? 'ok' : undefined);
+ }
+
+ if (!(sc.glbUrl || sc.glb_url)) throw new Error('The studio answered without a model. Try again.');
+ stage.model(sc, elapsed());
+ } catch (err) {
+ if (err?.name === 'AbortError') {
+ log.add('in', 'stopped collecting; the job keeps running on the server');
+ stage.empty();
+ } else {
+ log.add('in', err?.message || 'failed', 'error');
+ const f = describeFailure(err);
+ stage.error(f.title, f.detail);
+ }
+ } finally {
+ controller = null;
+ setBusy(false);
+ }
+ }
+
+ form.addEventListener('submit', (e) => {
+ e.preventDefault();
+ const text = prompt.value.trim() || prompt.placeholder;
+ if (!controller) run(text);
+ });
+ prompt.addEventListener('keydown', (e) => {
+ if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) form.requestSubmit();
+ });
+ stop.addEventListener('click', () => controller?.abort());
+ $('gk-retry').addEventListener('click', () => form.requestSubmit());
+ $('gk-embed').addEventListener('click', (e) => copyText(e.currentTarget.dataset.embed, e.currentTarget));
+}
+
+// ── live tool catalog ────────────────────────────────────────────────────
+
+function firstSentence(text) {
+ const s = String(text || '').replace(/\s+/g, ' ').trim();
+ const end = s.search(/[.!?](\s|$)/);
+ return end > 0 ? s.slice(0, end + 1) : s;
+}
+
+async function loadTools() {
+ const grid = $('gk-tools');
+ const note = $('gk-tools-note');
+ grid.setAttribute('aria-busy', 'true');
+ note.hidden = true;
+ try {
+ const result = await createClient().call('tools/list', {});
+ const tools = result?.tools || [];
+ if (!tools.length) {
+ grid.replaceChildren();
+ note.hidden = false;
+ note.removeAttribute('data-tone');
+ note.textContent = 'The server listed no tools right now. Reload in a minute.';
+ return;
+ }
+ grid.replaceChildren(
+ ...tools.map((t) => {
+ const card = document.createElement('div');
+ card.className = 'gk-tool';
+ const name = document.createElement('code');
+ name.textContent = t.name;
+ const desc = document.createElement('p');
+ desc.textContent = firstSentence(t.description);
+ card.append(name, desc);
+ return card;
+ }),
+ );
+ note.hidden = false;
+ note.removeAttribute('data-tone');
+ note.textContent = `${tools.length} tools, all free. Grok picks the right one from your request.`;
+ } catch (err) {
+ grid.replaceChildren();
+ note.hidden = false;
+ note.dataset.tone = 'error';
+ note.textContent = `Could not load the tool list (${err?.message || 'network error'}). `;
+ const retry = document.createElement('button');
+ retry.type = 'button';
+ retry.textContent = 'Try again';
+ retry.addEventListener('click', loadTools, { once: true });
+ note.append(retry);
+ } finally {
+ grid.setAttribute('aria-busy', 'false');
+ }
+}
+
+// ── live strip of real creations ─────────────────────────────────────────
+
+const STRIP_COUNT = 6;
+
+function posterFor(item) {
+ const glb = item.web_glb_url || item.glb_url;
+ return `/api/render/glb?glbUrl=${encodeURIComponent(glb)}`;
+}
+
+async function loadStrip() {
+ const strip = $('gk-strip');
+ const note = $('gk-strip-note');
+ strip.setAttribute('aria-busy', 'true');
+ note.hidden = true;
+ try {
+ const res = await fetch(`/api/forge-gallery?limit=${STRIP_COUNT}`);
+ if (!res.ok) throw new Error(`gallery answered ${res.status}`);
+ const data = await res.json();
+ // The store is switched off on this deployment: there is no gallery to show,
+ // so the section goes rather than claiming nobody made anything.
+ if (data?.enabled === false) {
+ strip.closest('section').hidden = true;
+ return;
+ }
+ const items = (data?.creations || []).filter((c) => c.id && (c.web_glb_url || c.glb_url));
+ if (!items.length) {
+ strip.replaceChildren();
+ note.hidden = false;
+ note.removeAttribute('data-tone');
+ note.textContent = 'Nothing has been generated in a while. Be the first: try the demo above.';
+ return;
+ }
+ strip.replaceChildren(
+ ...items.map((item) => {
+ const a = document.createElement('a');
+ a.className = 'gk-made';
+ a.href = `/m/${encodeURIComponent(item.id)}`;
+ const img = document.createElement('img');
+ img.loading = 'lazy';
+ img.decoding = 'async';
+ img.width = 240;
+ img.height = 240;
+ img.alt = item.prompt ? `3D model: ${item.prompt}` : 'A 3D model made on three.ws';
+ img.src = posterFor(item);
+ // The render endpoint draws the GLB itself; if it cannot, the concept
+ // image the model was sculpted from is the next best picture of it.
+ img.addEventListener('error', () => {
+ if (item.preview_image_url && img.src !== item.preview_image_url) img.src = item.preview_image_url;
+ }, { once: true });
+ const label = document.createElement('span');
+ label.textContent = item.prompt || 'Untitled model';
+ a.append(img, label);
+ return a;
+ }),
+ );
+ } catch (err) {
+ strip.replaceChildren();
+ note.hidden = false;
+ note.dataset.tone = 'error';
+ note.textContent = `Could not load recent models (${err?.message || 'network error'}). `;
+ const retry = document.createElement('button');
+ retry.type = 'button';
+ retry.textContent = 'Try again';
+ retry.addEventListener('click', loadStrip, { once: true });
+ note.append(retry);
+ } finally {
+ strip.setAttribute('aria-busy', 'false');
+ }
+}
+
+wireCopy();
+wireTabs();
+loadStrip();
+startDemo();
+loadTools();