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-bot): prove a Grok model drives three.ws MCP end to end over the xAI Responses API
nirholascfb34e0d4bd0
diff --git a/docs/grok-bot.md b/docs/grok-bot.mdindex 9eff37bad..f48ff1094 100644--- a/docs/grok-bot.md+++ b/docs/grok-bot.md@@ -503,6 +503,49 @@ can print under a failing server, what it means, and the fix:| `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. |+### Prove a real Grok model drives it (xAI Responses API)++`npm run probe:mcp-clients` proves the connector itself works; it never calls+a real Grok model. `scripts/xai-mcp-e2e.mjs` closes that gap: it sends an xAI+Responses API request with `https://three.ws/api/mcp-grok` as a remote MCP+tool and the instruction "find a ready-made chair in the three.ws catalog and+give me its viewer link", then asserts the response contains an `mcp_call`+output item for `search_catalog` and that the final text carries a+`three.ws` viewer URL. With a `GROK_API_KEY` or `XAI_API_KEY` in the+environment, `.env`/`.env.local`, or the `three-ws-api` Cloud Run service (read+in that order, never printed), run it live with `npm run e2e:xai-mcp`:++```text+sending request (key from process.env, model grok-4.7, server mcp-grok)+mcp_call items: 1 (search_catalog)+final text:+...+PASSED: search_catalog called (name "search_catalog"), viewer link https://three.ws/...+```++With no key anywhere, run the dry run instead, which needs no key, sends+nothing, and prints the exact request xAI's docs describe, field for field:++```bash+npm run e2e:xai-mcp -- --dry-run+```++```json+{+ "model": "grok-4.7",+ "input": [{ "role": "user", "content": "Find a ready-made chair in the three.ws catalog and give me its viewer link." }],+ "tools": [{ "type": "mcp", "server_url": "https://three.ws/api/mcp-grok", "server_label": "three-ws", "server_description": "three.ws: ready-made 3D/avatar catalog, generation, agents and personas." }]+}+```++`--server mcp-studio` runs the same proof against the free studio server+instead of the Grok-specific one; `--base`, `--model` and `--prompt` override+the target and the ask. If the model connects but never calls the tool, that+is a defect in our tool descriptions (every agent client reads the same+descriptions), not a prompt to work around: tighten `search_catalog`'s+description in [`api/_mcp/tools/library.js`](../api/_mcp/tools/library.js) and+record the before/after in the commit.+### Errors a connected Grok Bot can see| Error | Meaning | Fix |diff --git a/package.json b/package.jsonindex d647fa36f..3e30f9681 100644--- a/package.json+++ b/package.json@@ -430,6 +430,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 --env-file-if-exists=.env --env-file-if-exists=.env.local 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/scripts/xai-mcp-e2e.mjs b/scripts/xai-mcp-e2e.mjsnew file mode 100644index 000000000..b6941f69a--- /dev/null+++ b/scripts/xai-mcp-e2e.mjs@@ -0,0 +1,186 @@+#!/usr/bin/env node+// Prove a real Grok model drives three.ws end to end over the xAI Responses+// API's remote MCP tool, the same connector mechanics Grok Bot uses.+//+// We cannot script Grok Bot itself (it is a hosted, browser-driven agent with+// no API), but the Responses API lets any Grok model call a remote MCP server+// directly: same model family, same "type": "mcp" tool, same tool discovery+// and invocation path. A passing run here is evidence that a Grok model can+// find our tools, call one correctly, and return a working three.ws link.+//+// Request shape is xAI's documented one, field for field+// (https://docs.x.ai/developers/tools/remote-mcp): a "mcp" tool with+// server_url and server_label. Response shape is the OpenAI-compatible+// Responses API: output items of type "mcp_call" carry the tool name and+// server_label; a final "message" item carries the assistant's answer as+// "output_text" content parts.+//+// USAGE+// npm run e2e:xai-mcp # send the real request, assert, exit non-zero on failure+// npm run e2e:xai-mcp -- --dry-run # print the exact request, send nothing, needs no key+// node scripts/xai-mcp-e2e.mjs --server mcp-studio --base http://localhost:3107+// node scripts/xai-mcp-e2e.mjs --prompt "..." --model grok-4.3+//+// The key (GROK_API_KEY or XAI_API_KEY) is read from this process's env, then+// from .env/.env.local (via --env-file in the npm script), then from the+// three-ws-api Cloud Run service. It is only ever sent to api.x.ai and is+// never printed.++import { fileURLToPath } from 'node:url';+import { resolve } from 'node:path';+import { GROK_DEFAULT_MODEL } from '../api/_lib/chat-models.js';+import { serviceEnvValue } from './lib/service-env.mjs';++const RESPONSES_URL = 'https://api.x.ai/v1/responses';+const TIMEOUT_MS = 120_000;+const DEFAULT_PROMPT = 'Find a ready-made chair in the three.ws catalog and give me its viewer link.';+const SERVER_LABEL = 'three-ws';+const SERVERS = {+ 'mcp-grok': '/api/mcp-grok',+ 'mcp-studio': '/api/mcp-studio',+};++export function parseArgs(argv) {+ const args = { dryRun: false, server: 'mcp-grok', base: 'https://three.ws', model: GROK_DEFAULT_MODEL, prompt: DEFAULT_PROMPT };+ for (let i = 0; i < argv.length; i += 1) {+ const a = argv[i];+ if (a === '--dry-run') args.dryRun = true;+ else if (a === '--server') args.server = argv[++i];+ else if (a === '--base') args.base = argv[++i];+ else if (a === '--model') args.model = argv[++i];+ else if (a === '--prompt') args.prompt = argv[++i];+ else if (a === '--allow-tools') args.allowTools = argv[++i].split(',').map((s) => s.trim()).filter(Boolean);+ }+ if (!SERVERS[args.server]) {+ throw new Error(`unknown --server "${args.server}", expected one of: ${Object.keys(SERVERS).join(', ')}`);+ }+ return args;+}++export function buildRequest(args) {+ const serverUrl = `${args.base.replace(/\/$/, '')}${SERVERS[args.server]}`;+ const tool = {+ type: 'mcp',+ server_url: serverUrl,+ server_label: SERVER_LABEL,+ server_description: 'three.ws: ready-made 3D/avatar catalog, generation, agents and personas.',+ };+ if (args.allowTools?.length) tool.allowed_tools = args.allowTools;+ return {+ model: args.model,+ input: [{ role: 'user', content: args.prompt }],+ tools: [tool],+ };+}++export function resolveKey() {+ const fromEnv = process.env.GROK_API_KEY || process.env.XAI_API_KEY;+ if (fromEnv) return { key: fromEnv, source: 'process.env' };+ const fromService = serviceEnvValue('GROK_API_KEY') || serviceEnvValue('XAI_API_KEY');+ if (fromService) return { key: fromService, source: 'cloud-run:three-ws-api' };+ return { key: null, source: null };+}++export function mcpCalls(output) {+ return (output || []).filter((item) => item?.type === 'mcp_call');+}++export function finalText(output) {+ return (output || [])+ .filter((item) => item?.type === 'message' && item?.role === 'assistant')+ .flatMap((item) => item.content || [])+ .filter((part) => part?.type === 'output_text')+ .map((part) => part.text || '')+ .join('\n')+ .trim();+}++export function matchesToolName(call, name) {+ return call.name === name || call.name === `${SERVER_LABEL}.${name}`;+}++async function sendRequest(body, key) {+ const controller = new AbortController();+ const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);+ try {+ const res = await fetch(RESPONSES_URL, {+ method: 'POST',+ headers: { 'content-type': 'application/json', authorization: `Bearer ${key}` },+ body: JSON.stringify(body),+ signal: controller.signal,+ });+ const text = await res.text();+ let json;+ try {+ json = JSON.parse(text);+ } catch {+ throw new Error(`xAI returned non-JSON (HTTP ${res.status}): ${text.slice(0, 500)}`);+ }+ return { status: res.status, json };+ } finally {+ clearTimeout(timer);+ }+}++async function main() {+ const args = parseArgs(process.argv.slice(2));+ const request = buildRequest(args);++ if (args.dryRun) {+ console.log('POST https://api.x.ai/v1/responses');+ console.log('content-type: application/json');+ console.log('authorization: Bearer <XAI_API_KEY>');+ console.log(JSON.stringify(request, null, '\t'));+ return 0;+ }++ const { key, source } = resolveKey();+ if (!key) {+ console.error('No GROK_API_KEY or XAI_API_KEY in process.env, .env/.env.local, or the three-ws-api Cloud Run service.');+ console.error('Order 927 (prompts/finish/927-x-grok-46-owner-grok-api-key.md) owns creating one.');+ console.error('Printing the dry-run request instead:');+ console.error(JSON.stringify(request, null, '\t'));+ return 1;+ }++ console.log(`sending request (key from ${source}, model ${request.model}, server ${args.server})`);+ const { status, json } = await sendRequest(request, key);++ if (status !== 200) {+ console.error(`xAI answered HTTP ${status}:`);+ console.error(JSON.stringify(json, null, '\t'));+ return 1;+ }++ const output = json.output || [];+ const calls = mcpCalls(output);+ const searchCall = calls.find((c) => matchesToolName(c, 'search_catalog'));+ const text = finalText(output);+ const urlMatch = text.match(/https?:\/\/[^\s)]*three\.ws[^\s)]*/i);++ console.log(`mcp_call items: ${calls.length} (${calls.map((c) => c.name).join(', ') || 'none'})`);+ console.log(`final text:\n${text || '(empty)'}`);++ const problems = [];+ if (!searchCall) problems.push('no mcp_call to search_catalog in response.output');+ if (!urlMatch) problems.push('final text has no three.ws viewer URL');++ if (problems.length) {+ console.error('FAILED:');+ for (const p of problems) console.error(` - ${p}`);+ console.error('If the model never called the tool, tighten the tool description (a real defect for every agent client), not the prompt.');+ return 1;+ }++ console.log(`PASSED: search_catalog called (name "${searchCall.name}"), viewer link ${urlMatch[0]}`);+ return 0;+}++if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {+ main()+ .then((code) => process.exit(code))+ .catch((err) => {+ console.error(err?.stack || String(err));+ process.exit(1);+ });+}diff --git a/tests/xai-mcp-e2e.test.js b/tests/xai-mcp-e2e.test.jsnew file mode 100644index 000000000..4f25ca309--- /dev/null+++ b/tests/xai-mcp-e2e.test.js@@ -0,0 +1,121 @@+// The xAI Responses API remote-MCP proof (order 039): request shape, response+// parsing and key resolution, pinned so a field rename in the script cannot+// quietly stop matching xAI's documented request or our server's response.+import { describe, it, expect, afterEach } from 'vitest';+import { parseArgs, buildRequest, mcpCalls, finalText, matchesToolName, resolveKey } from '../scripts/xai-mcp-e2e.mjs';++describe('parseArgs', () => {+ it('defaults to the Grok connector server and the catalog-chair prompt', () => {+ const args = parseArgs([]);+ expect(args.server).toBe('mcp-grok');+ expect(args.base).toBe('https://three.ws');+ expect(args.dryRun).toBe(false);+ expect(args.prompt).toMatch(/chair/i);+ });++ it('reads every flag', () => {+ const args = parseArgs(['--dry-run', '--server', 'mcp-studio', '--base', 'http://localhost:3107', '--model', 'grok-4.3', '--prompt', 'hi', '--allow-tools', 'search_catalog, get_job']);+ expect(args).toMatchObject({ dryRun: true, server: 'mcp-studio', base: 'http://localhost:3107', model: 'grok-4.3', prompt: 'hi' });+ expect(args.allowTools).toEqual(['search_catalog', 'get_job']);+ });++ it('rejects an unknown server', () => {+ expect(() => parseArgs(['--server', 'mcp-nope'])).toThrow(/unknown --server/);+ });+});++describe('buildRequest', () => {+ it('matches xAI\'s documented remote MCP tool shape field for field', () => {+ const req = buildRequest(parseArgs(['--base', 'https://three.ws']));+ expect(req.tools).toHaveLength(1);+ const tool = req.tools[0];+ expect(tool.type).toBe('mcp');+ expect(tool.server_url).toBe('https://three.ws/api/mcp-grok');+ expect(tool.server_label).toBe('three-ws');+ expect(tool.allowed_tools).toBeUndefined();+ expect(req.input).toEqual([{ role: 'user', content: expect.stringContaining('chair') }]);+ });++ it('points mcp-studio at the free studio server, not the grok one', () => {+ const req = buildRequest(parseArgs(['--server', 'mcp-studio']));+ expect(req.tools[0].server_url).toBe('https://three.ws/api/mcp-studio');+ });++ it('strips a trailing slash from --base', () => {+ const req = buildRequest(parseArgs(['--base', 'http://localhost:3107/']));+ expect(req.tools[0].server_url).toBe('http://localhost:3107/api/mcp-grok');+ });++ it('only sets allowed_tools when given one', () => {+ const req = buildRequest(parseArgs(['--allow-tools', 'search_catalog']));+ expect(req.tools[0].allowed_tools).toEqual(['search_catalog']);+ });+});++describe('mcpCalls / matchesToolName', () => {+ it('picks out mcp_call output items and matches a bare or server-prefixed name', () => {+ const output = [+ { type: 'reasoning' },+ { type: 'mcp_call', name: 'search_catalog', server_label: 'three-ws' },+ { type: 'mcp_call', name: 'three-ws.get_job', server_label: 'three-ws' },+ ];+ const calls = mcpCalls(output);+ expect(calls).toHaveLength(2);+ expect(matchesToolName(calls[0], 'search_catalog')).toBe(true);+ expect(matchesToolName(calls[1], 'get_job')).toBe(true);+ expect(matchesToolName(calls[0], 'get_job')).toBe(false);+ });++ it('returns no calls when the output has none', () => {+ expect(mcpCalls([{ type: 'message' }])).toEqual([]);+ expect(mcpCalls(null)).toEqual([]);+ });+});++describe('finalText', () => {+ it('joins output_text parts of the final assistant message', () => {+ const output = [+ { type: 'mcp_call', name: 'search_catalog' },+ {+ type: 'message',+ role: 'assistant',+ content: [{ type: 'output_text', text: 'Here is a chair: https://three.ws/object/adjustable-chair' }],+ },+ ];+ expect(finalText(output)).toContain('three.ws/object/adjustable-chair');+ });++ it('ignores non-assistant messages and non-text content', () => {+ const output = [+ { type: 'message', role: 'user', content: [{ type: 'output_text', text: 'ignored' }] },+ { type: 'message', role: 'assistant', content: [{ type: 'reasoning_text', text: 'ignored too' }] },+ ];+ expect(finalText(output)).toBe('');+ });+});++describe('resolveKey', () => {+ const KEYS = ['GROK_API_KEY', 'XAI_API_KEY'];+ const saved = {};+ afterEach(() => {+ for (const k of KEYS) {+ if (saved[k] === undefined) delete process.env[k];+ else process.env[k] = saved[k];+ delete saved[k];+ }+ });++ it('prefers GROK_API_KEY from the environment over XAI_API_KEY', () => {+ for (const k of KEYS) saved[k] = process.env[k];+ process.env.GROK_API_KEY = 'grok-key';+ process.env.XAI_API_KEY = 'xai-key';+ expect(resolveKey()).toEqual({ key: 'grok-key', source: 'process.env' });+ });++ it('falls back to XAI_API_KEY', () => {+ for (const k of KEYS) saved[k] = process.env[k];+ delete process.env.GROK_API_KEY;+ process.env.XAI_API_KEY = 'xai-key';+ expect(resolveKey()).toEqual({ key: 'xai-key', source: 'process.env' });+ });+});