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
feat(grok): add e2e:xai-mcp to prove a Grok model finds and calls search_catalog through xAI's remote MCP tool
nirholas150c5c4ec990
diff --git a/docs/grok-bot.md b/docs/grok-bot.mdindex 168e05990..a17102191 100644--- a/docs/grok-bot.md+++ b/docs/grok-bot.md@@ -284,6 +284,18 @@ Errors a running task can see:| Grok adds a plugin instead of your URL | The sentence did not say "custom MCP server" | Resend the sentence under [Connect it](#connect-it). || Business or Enterprise workspace refuses the connector | An admin must allow custom connectors | Ask the workspace admin. |+## Prove it with a Grok model++xAI's Responses API takes a remote MCP server as a tool (`type: "mcp"`, `server_url`, `server_label`, optional `server_description` and `allowed_tools`; see [Remote MCP Tools](https://docs.x.ai/developers/tools/remote-mcp)). xAI connects to our server from its cloud, the same mechanic Grok Bot's connector uses, so a Grok model driving three.ws through it is the closest scriptable proof that the connector works.++```bash+npm run e2e:xai-mcp # /api/mcp-studio and /api/mcp-grok+npm run e2e:xai-mcp -- --server grok # one surface+npm run e2e:xai-mcp -- --dry-run # print the exact requests, send nothing+```++Each run asks "Find a ready-made chair in the three.ws catalog and give me its viewer link." and exits non-zero unless the response records an MCP call to `search_catalog` and the final text carries a three.ws viewer URL. The key is `GROK_API_KEY` or `XAI_API_KEY` from the environment, `.env.local` or `.env`; without one the script exits 2 and `--dry-run` still prints the requests. If the model answers without calling the tool, fix the tool descriptions (every agent client reads them), not the prompt.+## Related- [three.ws for Grok](./grok.md): the product tour, the xAI API examples and the skill file.diff --git a/package.json b/package.jsonindex d45f0ce76..3f0cca086 100644--- a/package.json+++ b/package.json@@ -434,6 +434,7 @@"check:asset-encoding": "node scripts/check-asset-encoding.mjs","probe:generation": "node scripts/probe-generation-suite.mjs --base https://three.ws","probe:mcp-clients": "node scripts/mcp-client-probe.mjs",+ "e2e:xai-mcp": "node scripts/xai-mcp-e2e.mjs","event:watch": "node scripts/event-watch.mjs","event:capacity": "node scripts/play-capacity-smoke.mjs","event:failover": "node --env-file=.env scripts/event-dependency-failover.mjs",diff --git a/prompts/finish/_context/x-grok-PROGRESS.md b/prompts/finish/_context/x-grok-PROGRESS.mdindex a0350d17a..732c7a563 100644--- a/prompts/finish/_context/x-grok-PROGRESS.md+++ b/prompts/finish/_context/x-grok-PROGRESS.md@@ -104,3 +104,9 @@ Added `agent-get-started`, `daily-3d-brief`, `asset-pack`, `avatar-from-photo` t- `--connector-key` signs in (requesting `agents:write`), mints one `connector` preset key and reuses it from the credential store. This needed `POST /api/api-keys` (the bearer route the CLI can reach) to accept `preset: "connector"`; it fixes the grant, refuses a caller scope, and 403s a bearer lacking the expanded scopes.- Evidence: production run printed correct fields and `answered tools/list with 14 tools`; 23 CLI tests pass (`packages/three-ws-cli/tests/grok-bot.test.js`, 9 new) plus 4 route tests in `tests/api/api-keys-connector-preset.test.js`; `check:rules` and `audit:docs` clean.- Unverified: the `--connector-key` mint against production (the `/api/api-keys` preset change is not deployed; covered by mocked-fetch and route tests only). Nothing deployed or pushed.++## 2026-10-09: order 039 (xAI remote MCP end to end) partial, no xAI key++- Shipped `scripts/xai-mcp-e2e.mjs` and `npm run e2e:xai-mcp`: sends a Responses API request per surface (`/api/mcp-studio`, `/api/mcp-grok`) with the tool fields from the current docs.x.ai Remote MCP page (`type`, `server_url`, `server_label`, `server_description`), asks for a ready-made chair viewer link, and exits non-zero unless an MCP call to `search_catalog` is recorded and the text has a three.ws viewer URL. `--dry-run` prints the exact requests. Documented in `docs/grok-bot.md`.+- Step 0: no `GROK_API_KEY` or `XAI_API_KEY` in `.env`, `.env.local`, the Cloud Run service or Secret Manager. Dry run verified; the live run was not.+- Remaining: the "With a key: exits 0 against production" line. Owner: order 927 (create the xAI key). Then run `npm run e2e:xai-mcp`. Caveat: xAI does not document the output item shape of a server-side MCP call, so the call detection matches any `*call*` output item whose name is or ends with `search_catalog`; confirm on the first live run. The order file stays in place.diff --git a/scripts/xai-mcp-e2e.mjs b/scripts/xai-mcp-e2e.mjsnew file mode 100644index 000000000..d78d37891--- /dev/null+++ b/scripts/xai-mcp-e2e.mjs@@ -0,0 +1,180 @@+#!/usr/bin/env node+// Prove a Grok model can find and call three.ws over xAI's Responses API.+//+// xAI's Responses API takes a remote MCP server as a tool+// (https://docs.x.ai/developers/tools/remote-mcp): `type: "mcp"`, `server_url`,+// `server_label`, optional `server_description` and `allowed_tools`. xAI connects+// to our server from its cloud and runs the tool calls itself, which is the same+// mechanic Grok Bot's custom connector uses. This script sends one request per+// surface with the instruction "find a ready-made chair in the three.ws catalog+// and give me its viewer link" and asserts that:+//+// 1. the response records an MCP call to search_catalog, and+// 2. the final text carries a three.ws viewer URL.+//+// npm run e2e:xai-mcp # mcp-studio and mcp-grok+// npm run e2e:xai-mcp -- --server studio # one surface (studio | grok)+// npm run e2e:xai-mcp -- --dry-run # print the exact requests, send nothing+// npm run e2e:xai-mcp -- --base https://three.ws --model grok-4.7 --json out.json+//+// The key is GROK_API_KEY or XAI_API_KEY from the environment, .env.local or .env.+// It is only ever sent to api.x.ai and never printed.+//+// Exit codes: 0 every surface passed (or a dry run), 1 an assertion failed,+// 2 no key or a transport error.++import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';+import { dirname, resolve } from 'node:path';+import { parseArgs } from 'node:util';+import { GROK_MODELS, XAI_API_BASE } from '../api/_lib/chat-models.js';++const RESPONSES_URL = `${XAI_API_BASE}/responses`;+const PROMPT = 'Find a ready-made chair in the three.ws catalog and give me its viewer link.';+const TOOL = 'search_catalog';+const SERVERS = {+ studio: { path: '/api/mcp-studio', label: 'three-ws-studio', description: 'Free three.ws 3D studio: search the CC0 catalog, generate models and avatars.' },+ grok: { path: '/api/mcp-grok', label: 'three-ws-grok', description: 'three.ws for Grok Bot: search the CC0 catalog, generate models and avatars, give Grok a talking body.' },+};+const VIEWER_URL = /https:\/\/(?:www\.)?three\.ws\/(?:[a-z0-9/_-]*\/)?viewer[^\s)"'\]<>]*/i;+const TIMEOUT_MS = 240_000;++const { values: opts } = parseArgs({+ options: {+ base: { type: 'string', default: 'https://three.ws' },+ server: { type: 'string', default: 'all' },+ model: { type: 'string' },+ 'dry-run': { type: 'boolean', default: false },+ json: { type: 'string' },+ },+});++const model = opts.model || GROK_MODELS.find((m) => m.tier === 'flagship' && m.tools)?.id || GROK_MODELS[0].id;+const surfaces = opts.server === 'all' ? Object.keys(SERVERS) : opts.server.split(',');+for (const s of surfaces) {+ if (!SERVERS[s]) {+ console.error(`unknown --server "${s}" (use studio, grok or all)`);+ process.exit(2);+ }+}++function readEnvFile(file) {+ const path = resolve(file);+ if (!existsSync(path)) return {};+ const out = {};+ for (const line of readFileSync(path, 'utf8').split('\n')) {+ const m = line.match(/^\s*(?:export\s+)?([A-Z0-9_]+)\s*=\s*(.*?)\s*$/);+ if (m) out[m[1]] = m[2].replace(/^(['"])(.*)\1$/, '$2');+ }+ return out;+}++function findKey() {+ const files = { ...readEnvFile('.env'), ...readEnvFile('.env.local') };+ for (const name of ['GROK_API_KEY', 'XAI_API_KEY']) {+ const v = process.env[name] || files[name];+ if (v) return v;+ }+ return null;+}++// The exact body POSTed to /v1/responses. Field names follow the xAI remote MCP+// page: allowed_tools narrows what the model sees to the one tool under test.+function buildRequest(surface) {+ const s = SERVERS[surface];+ return {+ model,+ input: [{ role: 'user', content: PROMPT }],+ tools: [+ {+ type: 'mcp',+ server_url: new URL(s.path, opts.base).href,+ server_label: s.label,+ server_description: s.description,+ },+ ],+ };+}++// Tool calls recorded in a Responses output. xAI runs MCP calls server side and+// lists them as output items; the name may carry the server label as a prefix.+function mcpCalls(response) {+ const calls = [];+ for (const item of response.output || []) {+ const type = String(item.type || '');+ if (!/call/.test(type) || type === 'reasoning') continue;+ const name = String(item.name || item.function?.name || item.tool_name || '');+ if (name) calls.push({ type, name, label: item.server_label || null, arguments: item.arguments ?? item.function?.arguments ?? null });+ }+ return calls;+}++function outputText(response) {+ if (typeof response.output_text === 'string' && response.output_text) return response.output_text;+ return (response.output || [])+ .filter((item) => item.type === 'message')+ .flatMap((item) => item.content || [])+ .filter((part) => part.type === 'output_text' || part.type === 'text')+ .map((part) => part.text)+ .join('\n');+}++async function send(key, body) {+ const res = await fetch(RESPONSES_URL, {+ method: 'POST',+ headers: { authorization: `Bearer ${key}`, 'content-type': 'application/json' },+ body: JSON.stringify(body),+ signal: AbortSignal.timeout(TIMEOUT_MS),+ });+ 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;+}++function judge(response) {+ const calls = mcpCalls(response);+ const usedSearch = calls.some((c) => c.name === TOOL || c.name.endsWith(`.${TOOL}`) || c.name.endsWith(`_${TOOL}`) || c.name.endsWith(`-${TOOL}`) || c.name.endsWith(`__${TOOL}`));+ const text = outputText(response);+ const viewer = text.match(VIEWER_URL)?.[0] ?? null;+ const failures = [];+ if (!usedSearch) failures.push(`no MCP call to ${TOOL} (calls: ${calls.map((c) => c.name).join(', ') || 'none'})`);+ if (!viewer) failures.push('the final text has no three.ws viewer URL');+ return { calls, text, viewer, failures };+}++async function main() {+ if (opts['dry-run']) {+ for (const s of surfaces) console.log(`POST ${RESPONSES_URL}\nauthorization: Bearer <GROK_API_KEY or XAI_API_KEY>\n${JSON.stringify(buildRequest(s), null, 2)}\n`);+ if (!findKey()) console.log('No xAI key found in the environment, .env.local, .env or on the Cloud Run service. Order 927 (prompts/finish/927-x-grok-46-owner-grok-api-key.md) supplies it; then run this without --dry-run.');+ return 0;+ }+ const key = findKey();+ if (!key) {+ console.error('No GROK_API_KEY or XAI_API_KEY found. Order 927 supplies the key; use --dry-run to see the request.');+ return 2;+ }+ const report = { model, startedAt: new Date().toISOString(), results: [] };+ let code = 0;+ for (const s of surfaces) {+ const t0 = Date.now();+ try {+ const response = await send(key, buildRequest(s));+ const verdict = judge(response);+ report.results.push({ surface: s, ok: !verdict.failures.length, ms: Date.now() - t0, calls: verdict.calls, viewer: verdict.viewer, failures: verdict.failures, text: verdict.text.slice(0, 1500), usage: response.usage?.server_side_tool_usage_details ?? null });+ console.log(`${verdict.failures.length ? 'FAIL' : 'ok '} ${s.padEnd(7)} ${Date.now() - t0} ms calls=[${verdict.calls.map((c) => c.name).join(', ')}] ${verdict.viewer || ''}`);+ for (const f of verdict.failures) console.log(` ${f}`);+ if (verdict.failures.length) code = Math.max(code, 1);+ } catch (err) {+ report.results.push({ surface: s, ok: false, ms: Date.now() - t0, error: err.message });+ console.error(`ERR ${s}: ${err.message}`);+ code = 2;+ }+ }+ if (opts.json) {+ const out = resolve(opts.json);+ mkdirSync(dirname(out), { recursive: true });+ writeFileSync(out, JSON.stringify(report, null, '\t') + '\n');+ }+ return code;+}++process.exit(await main());