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(mcp): serve the 3D studio to Grok Bot and the xAI Responses API at /api/mcp-grok
nirholas2fa7988cabdb
diff --git a/api/_mcp-studio/dispatch.js b/api/_mcp-studio/dispatch.jsindex 198f17db5..514c9ec9a 100644--- a/api/_mcp-studio/dispatch.js+++ b/api/_mcp-studio/dispatch.js@@ -53,6 +53,24 @@ const CHATGPT_INSTRUCTIONS = [// response's own trip back through ChatGPT.export const CHATGPT_CALL_BUDGET_MS = 40_000;+// Grok Bot and the xAI Responses API call MCP tools from xAI's cloud, render no+// widget, and give no published tool-call timeout. Grok Bot runs tasks+// unattended for as long as they take, so on that surface a slow render comes+// back as a pending job inside GROK_CALL_BUDGET_MS and the model is told to keep+// collecting it, then hand the user links, since nothing renders inline.+const GROK_INSTRUCTIONS = [+ 'Nothing renders inline in Grok, so always give the user the viewerUrl (an interactive 3D viewer that opens in any',+ 'browser) and the glbUrl (the downloadable model). A pending result is normal: wait the suggested seconds, then call',+ 'check_job(job_id) again until it is done, and keep going without asking the user; a Grok Bot task should finish',+ 'with the finished model, not the pending handle. To give yourself a body, forge_avatar a character, then',+ 'create_agent_persona(glb_url, name) and share its embed_url; persona_say makes that body speak your reply and',+ 'returns an embed_url that plays it.',+];++// The same headroom as ChatGPT: a call that outlives an unpublished host+// timeout is lost work, while a pending handle costs one check_job round trip.+export const GROK_CALL_BUDGET_MS = 40_000;+const CATALOG_INSTRUCTIONS = ['Before generating a prop, character or animation, search_catalog(q) checks the thousands of ready-made CC0 props,','rigged characters and motion clips three.ws already publishes; get_item_source(id) returns paste-ready code for a',@@ -80,6 +98,11 @@ const PERSONA_INSTRUCTIONS = [// for broad distribution". Framing our own page is not that case, so// the plugin listing leaves the persona tools out rather than ask// review for an exception.+// grok /api/mcp-grok: every tool of the full surface for Grok Bot and the+// xAI Responses API, with a per-call budget and instructions that+// hand out links in place of the widgets Grok does not render.+// ./handler.js keys its generation caps on the MCP session, because+// every Grok user reaches us from xAI's shared egress.// check_job and the persona tools stay out of the generation quota on both; see// ./handler.js callsGenerationTool. look_at_model renders frames server-side, so// it rides that quota.@@ -99,6 +122,14 @@ const SURFACES = {instructions: [...BASE_INSTRUCTIONS, ...CHATGPT_INSTRUCTIONS].join(' '),callBudgetMs: CHATGPT_CALL_BUDGET_MS,},+ grok: {+ server: 'mcp-grok',+ catalog: [...TOOL_CATALOG, ...CATALOG_TOOL_CATALOG, ...PERSONA_TOOL_CATALOG],+ tools: { ...TOOLS, ...CATALOG_TOOLS, ...PERSONA_TOOLS },+ personas: true,+ instructions: [...BASE_INSTRUCTIONS, ...CATALOG_INSTRUCTIONS, ...PERSONA_INSTRUCTIONS, ...GROK_INSTRUCTIONS].join(' '),+ callBudgetMs: GROK_CALL_BUDGET_MS,+ },};export const SURFACE_NAMES = Object.keys(SURFACES);diff --git a/api/_mcp-studio/handler.js b/api/_mcp-studio/handler.jsindex 76f918342..ad94f8c24 100644--- a/api/_mcp-studio/handler.js+++ b/api/_mcp-studio/handler.js@@ -7,7 +7,8 @@// Parameterized by the tool surface it serves (SURFACES in ./dispatch.js):// api/mcp-studio.js surface 'full' every tool, both widgets// api/mcp-chatgpt.js surface 'chatgpt' generation tools, model viewer only-// Both front doors share one transport cap, one per-IP generation quota and one+// api/mcp-grok.js surface 'grok' every tool, for Grok Bot and the xAI API+// Every front door shares one transport cap, one per-IP generation quota and one// platform-wide circuit breaker, so a second door never doubles the free GPU// budget.//@@ -19,6 +20,7 @@// generation caps fail OPEN on a Redis outage, so a Redis blip never dead-ends a// free feature; real paid spend stays fail-closed one layer down in /api/forge.+import { randomUUID } from 'node:crypto';import { cors, wrap, readJson, rateLimited } from '../_lib/http.js';import { limits, clientIp } from '../_lib/rate-limit.js';import { dispatch, PROTOCOL_VERSION } from './dispatch.js';@@ -62,6 +64,33 @@ export function chatgptSubject(body) {return null;}+// Grok Bot and the xAI Responses API also reach us from one shared egress pool,+// and send no per-user id of their own. MCP Streamable HTTP has one: a server+// may assign an Mcp-Session-Id on initialize, and a conforming client echoes it+// on every later request of that connection. The grok surface issues one and+// keys the per-caller caps on it. Minting is free, so a forged or rotated id+// buys nothing past the per-IP pool cap that bounds the ChatGPT subject too.+const SESSION_RE = /^grk_[0-9a-f-]{36}$/;+export function grokSession(req) {+ const sid = req?.headers?.['mcp-session-id'];+ return typeof sid === 'string' && SESSION_RE.test(sid) ? sid : null;+}++function initializes(body) {+ const batch = Array.isArray(body) ? body : [body];+ return batch.some((m) => m && m.method === 'initialize');+}++/** The per-user identity a shared-egress surface carries, or null for per-IP keying. */+export function callerSubject(surface, body, req) {+ if (surface === 'chatgpt') {+ const sub = chatgptSubject(body);+ return sub ? `oai:${sub}` : null;+ }+ if (surface === 'grok') return grokSession(req);+ return null;+}+export function studioHandler({ surface = 'full' } = {}) {return wrap(async (req, res) => {if (cors(req, res, { methods: 'GET,HEAD,POST,OPTIONS', origins: '*', payments: false })) return;@@ -95,12 +124,12 @@ export function studioHandler({ surface = 'full' } = {}) {// Generation quota, burst then hourly, per IP. Applied only when the request// actually calls a generation tool, so discovery is never throttled by it.if (callsGenerationTool(body)) {- const subject = surface === 'chatgpt' ? chatgptSubject(body) : null;+ const subject = callerSubject(surface, body, req);if (subject) {const pool = await limits.studioGenPoolHourly(ip);if (!pool.success) return rateLimited(res, pool, 'the free 3D studio is at capacity right now, please try again later');}- const caller = subject ? `oai:${subject}` : ip;+ const caller = subject || ip;const burst = await limits.studioGenBurst(caller);if (!burst.success) return rateLimited(res, burst, 'generation rate limit, slow down and try again shortly');const hourly = await limits.studioGenHourly(caller);@@ -124,6 +153,12 @@ export function studioHandler({ surface = 'full' } = {}) {res.statusCode = 200;res.setHeader('content-type', 'application/json; charset=utf-8');res.setHeader('mcp-protocol-version', PROTOCOL_VERSION);+ if (surface === 'grok' && initializes(body)) {+ res.setHeader('mcp-session-id', `grk_${randomUUID()}`);+ // A browser MCP client cannot echo a header it is not allowed to read.+ const exposed = res.getHeader('access-control-expose-headers');+ res.setHeader('access-control-expose-headers', exposed ? `${exposed}, mcp-session-id` : 'mcp-session-id');+ }res.end(JSON.stringify(Array.isArray(body) ? responses : (responses[0] ?? null)));});}diff --git a/api/mcp-grok.js b/api/mcp-grok.jsnew file mode 100644index 000000000..b1c6b49e4--- /dev/null+++ b/api/mcp-grok.js@@ -0,0 +1,13 @@+// three.ws 3D Studio for Grok Bot and the xAI Responses API.+//+// POST /api/mcp-grok JSON-RPC (initialize, tools/list, tools/call, resources/*)+//+// Every free studio tool, including the persona tools that give Grok a body.+// Grok calls MCP from xAI's cloud with no published timeout and renders no+// widget, so each call answers inside a budget with the model or a pending job,+// and the instructions tell Grok to collect it and share links. Generation caps+// key on the Mcp-Session-Id this surface issues, since every Grok user shares+// xAI's egress. Transport, quota and breaker: ./_mcp-studio/handler.js.+import { studioHandler } from './_mcp-studio/handler.js';++export default studioHandler({ surface: 'grok' });diff --git a/tests/mcp-grok.test.js b/tests/mcp-grok.test.jsnew file mode 100644index 000000000..075e15f9a--- /dev/null+++ b/tests/mcp-grok.test.js@@ -0,0 +1,172 @@+// The Grok surface (/api/mcp-grok). Grok Bot and the xAI Responses API call MCP+// from xAI's cloud: no published tool-call timeout, no inline widget, and one+// shared egress pool for every Grok user. These tests pin the three answers to+// that: every call is bounded and hands back a pending job instead of hanging,+// the model is told to collect it and share links, and the generation caps key+// on the Mcp-Session-Id this surface issues rather than on xAI's IP.++import { describe, it, expect, vi, afterEach } from 'vitest';++vi.mock('../api/_mcp-studio/gpt-forge-client.js', async (importOriginal) => {+ const real = await importOriginal();+ return { ...real, generate: vi.fn(), rig: vi.fn(), directPrompt: vi.fn(async () => null) };+});++const limitCalls = [];+vi.mock('../api/_lib/rate-limit.js', async (importOriginal) => {+ const real = await importOriginal();+ const pass = (name) => async (key) => {+ limitCalls.push([name, key]);+ return { success: true, limit: 1, remaining: 1, reset: Date.now() + 1000 };+ };+ return {+ ...real,+ limits: {+ ...real.limits,+ studioIp: pass('ip'),+ studioGenBurst: pass('burst'),+ studioGenHourly: pass('hourly'),+ studioGenPoolHourly: pass('pool'),+ studioGenerateGlobal: pass('global'),+ },+ };+});++import { generate } from '../api/_mcp-studio/gpt-forge-client.js';+import { dispatch, toolCatalogFor, GROK_CALL_BUDGET_MS } from '../api/_mcp-studio/dispatch.js';+import { callerSubject, grokSession } from '../api/_mcp-studio/handler.js';+import grokHandler from '../api/mcp-grok.js';++const req = { headers: { host: 'three.ws', 'x-forwarded-proto': 'https' } };+const auth = { userId: null, rateKey: '127.0.0.1', scope: '' };+const SID = 'grk_0f8e2c1a-5b6d-4e7f-8a9b-0c1d2e3f4a5b';++function callMsg(name, args) {+ return { jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name, arguments: args } };+}++// A minimal node-style req/res pair for driving the real HTTP handler.+function httpPair(body, headers = {}) {+ const payload = Buffer.from(JSON.stringify(body));+ const req = {+ method: 'POST',+ url: '/api/mcp-grok',+ headers: { host: 'three.ws', 'content-type': 'application/json', 'x-forwarded-for': '203.0.113.9', ...headers },+ socket: { remoteAddress: '203.0.113.9' },+ async *[Symbol.asyncIterator]() {+ yield payload;+ },+ on(event, cb) {+ if (event === 'data') cb(payload);+ if (event === 'end') cb();+ return this;+ },+ };+ const out = { headers: {}, body: '' };+ const res = {+ statusCode: 200,+ headersSent: false,+ setHeader(k, v) {+ out.headers[k.toLowerCase()] = v;+ },+ getHeader(k) {+ return out.headers[k.toLowerCase()];+ },+ removeHeader(k) {+ delete out.headers[k.toLowerCase()];+ },+ end(chunk) {+ if (chunk) out.body += chunk;+ this.headersSent = true;+ },+ write(chunk) {+ out.body += chunk;+ },+ };+ return { req, res, out };+}++afterEach(() => {+ vi.mocked(generate).mockReset();+ limitCalls.length = 0;+});++describe('grok surface catalog', () => {+ it('offers every tool the full studio surface offers, persona tools included', () => {+ const names = (s) => toolCatalogFor(s).map((t) => t.name).sort();+ expect(names('grok')).toEqual(names('full'));+ expect(names('grok')).toContain('create_agent_persona');+ expect(names('grok')).toContain('check_job');+ });++ it('tells Grok to share links and collect pending jobs on initialize', async () => {+ const r = await dispatch({ jsonrpc: '2.0', id: 1, method: 'initialize', params: {} }, auth, req, { surface: 'grok' });+ const text = r.result.instructions;+ expect(text).toContain('viewerUrl');+ expect(text).toContain('check_job(job_id)');+ expect(text).toContain('embed_url');+ });+});++describe('grok call budget', () => {+ it('bounds each generation with a deadline inside the budget', async () => {+ vi.mocked(generate).mockResolvedValue({ status: 'done', glb_url: 'https://three.ws/cdn/a.glb' });+ const before = Date.now();+ await dispatch(callMsg('forge_free', { prompt: 'a reusable rocket booster' }), auth, req, { surface: 'grok' });+ const opts = vi.mocked(generate).mock.calls[0][2];+ expect(opts.deadline).toBeGreaterThan(before);+ expect(opts.deadline).toBeLessThanOrEqual(Date.now() + GROK_CALL_BUDGET_MS);+ });++ it('returns a pending job with a check_job hint when the render outlives the budget', async () => {+ vi.mocked(generate).mockResolvedValue({ _timedOut: true, job_id: 'job-abc123', status: 'running' });+ const r = await dispatch(callMsg('forge_free', { prompt: 'a reusable rocket booster' }), auth, req, { surface: 'grok' });+ expect(r.result.structuredContent.status).toBe('pending');+ expect(r.result.structuredContent.jobId).toBe('job-abc123');+ expect(r.result.content[0].text).toContain('check_job');+ });+});++describe('grok per-session generation limits', () => {+ it('reads a well-formed session id and rejects anything else', () => {+ expect(grokSession({ headers: { 'mcp-session-id': SID } })).toBe(SID);+ expect(grokSession({ headers: { 'mcp-session-id': 'grk_not-a-uuid' } })).toBeNull();+ expect(grokSession({ headers: { 'mcp-session-id': 'oai:spoof' } })).toBeNull();+ expect(grokSession({ headers: {} })).toBeNull();+ });++ it('keys only shared-egress surfaces on a subject, and the full surface stays per IP', () => {+ const grokReq = { headers: { 'mcp-session-id': SID } };+ expect(callerSubject('grok', callMsg('forge_free', {}), grokReq)).toBe(SID);+ expect(callerSubject('full', callMsg('forge_free', {}), grokReq)).toBeNull();+ const oai = { ...callMsg('forge_free', {}), params: { name: 'forge_free', arguments: {}, _meta: { 'openai/subject': 'v1/abcDEF123456' } } };+ expect(callerSubject('chatgpt', oai, req)).toBe('oai:v1/abcDEF123456');+ });++ it('issues a session id on initialize and exposes it to browser clients', async () => {+ const { req: r, res, out } = httpPair({ jsonrpc: '2.0', id: 1, method: 'initialize', params: {} });+ await grokHandler(r, res);+ expect(out.headers['mcp-session-id']).toMatch(/^grk_[0-9a-f-]{36}$/);+ expect(out.headers['access-control-expose-headers']).toContain('mcp-session-id');+ expect(JSON.parse(out.body).result.serverInfo.name).toBe('three-ws-3d-studio-free');+ });++ it('charges a generation to the session, behind the per-IP pool cap', async () => {+ vi.mocked(generate).mockResolvedValue({ status: 'done', glb_url: 'https://three.ws/cdn/a.glb' });+ const { req: r, res } = httpPair(callMsg('forge_free', { prompt: 'a lunar lander' }), { 'mcp-session-id': SID });+ await grokHandler(r, res);+ const byName = Object.fromEntries(limitCalls.map(([n, k]) => [n, k]));+ expect(byName.pool).toBeDefined();+ expect(byName.burst).toBe(SID);+ expect(byName.hourly).toBe(SID);+ });++ it('falls back to per-IP caps when the client never echoes a session', async () => {+ vi.mocked(generate).mockResolvedValue({ status: 'done', glb_url: 'https://three.ws/cdn/a.glb' });+ const { req: r, res } = httpPair(callMsg('forge_free', { prompt: 'a lunar lander' }));+ await grokHandler(r, res);+ const byName = Object.fromEntries(limitCalls.map(([n, k]) => [n, k]));+ expect(byName.pool).toBeUndefined();+ expect(byName.burst).not.toBe(SID);+ });+});diff --git a/vercel.json b/vercel.jsonindex f7af5dc7b..2f66fe0e1 100644--- a/vercel.json+++ b/vercel.json@@ -118,7 +118,7 @@"includeFiles": "{src/solana/vanity/wasm/**,examples/skills/**,data/pages.json,data/archives/**,data/rss/**,data/_generated/**,sdk/src/sas-config.json}","maxDuration": 60},- "{api/mcp-studio,api/mcp-chatgpt,api/forge-nim,api/nim-forge,api/launch/mm,api/cron/avaturn-seed-cron,api/irl/interactions-stream}.js": {+ "{api/mcp-studio,api/mcp-chatgpt,api/mcp-grok,api/forge-nim,api/nim-forge,api/launch/mm,api/cron/avaturn-seed-cron,api/irl/interactions-stream}.js": {"maxDuration": 300},"api/x402/remix-asset.js": {