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
test(mcp): add a connector compatibility probe that drives every hosted MCP server like a cloud client
nirholas62903ced4af4
diff --git a/package.json b/package.jsonindex c0e71f897..9f3f6ae7d 100644--- a/package.json+++ b/package.json@@ -428,6 +428,7 @@"smoke:prod": "node scripts/check-pages.mjs --base https://three.ws","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","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/mcp-client-probe.mjs b/scripts/mcp-client-probe.mjsnew file mode 100644index 000000000..7ff6a82f5--- /dev/null+++ b/scripts/mcp-client-probe.mjs@@ -0,0 +1,515 @@+#!/usr/bin/env node+// Connector compatibility probe for every hosted three.ws MCP server.+//+// Behaves like a cloud MCP client (Grok Bot, claude.ai connectors, the xAI+// Responses API): it drives the official MCP SDK client over Streamable HTTP,+// falls back to the legacy SSE transport when Streamable HTTP fails for a+// reason other than auth, and checks the raw handshake details a connector+// trips on silently: the GET a client opens for its server-to-client stream,+// protocol-version negotiation, Mcp-Session-Id issue and echo, and the 401+// that must point an OAuth client at the protected-resource metadata.+//+// The server list is public/.well-known/mcp.json, so a server added there is+// probed with no change here. Three modes per server:+//+// anonymous no credentials. Must fully work when the server's auth names+// `none`; otherwise must answer with an OAuth-shaped 401.+// api key Authorization: Bearer $THREE_WS_API_KEY, when that is set.+// oauth asserts the challenge shape only: WWW-Authenticate carries+// resource_metadata, that document resolves, its `resource`+// is one the MCP SDK accepts for this server URL, and the+// authorization server metadata supports PKCE S256. An+// invalid bearer must earn the same challenge (re-auth path).+//+// Records initialize, tools/list count, prompts/list count, and one free+// tools/call where a free tool exists (search_catalog, getting_started).+// No paid tool is ever called and no payment header is ever sent.+//+// node scripts/mcp-client-probe.mjs # https://three.ws+// node scripts/mcp-client-probe.mjs --base http://localhost:3000+// node scripts/mcp-client-probe.mjs --json prompts/x-grok/_generated/connector-probe.json+// node scripts/mcp-client-probe.mjs --only mcp-studio --timeout 45000+//+// Exit code 0 when every server passes, 1 otherwise.++import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';+import { dirname, resolve } from 'node:path';+import { fileURLToPath } from 'node:url';+import { Client } from '@modelcontextprotocol/sdk/client/index.js';+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';+import { checkResourceAllowed, resourceUrlFromServerUrl } from '@modelcontextprotocol/sdk/shared/auth-utils.js';+import { LATEST_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS } from '@modelcontextprotocol/sdk/types.js';++const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');+const CLIENT_INFO = { name: 'three-ws-connector-probe', version: '1.0.0' };++// Free tools a probe may call: read-only, no GPU, no spend. First match wins.+const FREE_CALLS = [+ { name: 'search_catalog', arguments: { q: 'chair', limit: 3 } },+ { name: 'getting_started', arguments: {} },+];++// Versions a real client may open with. The SDK's latest leads; the rest are+// what older connectors still send.+const NEGOTIATION_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];++function parseArgs(argv) {+ const out = { base: 'https://three.ws', json: null, only: null, timeout: 30_000 };+ for (let i = 0; i < argv.length; i++) {+ const a = argv[i];+ const next = () => {+ const v = argv[++i];+ if (v === undefined) throw new Error(`${a} needs a value`);+ return v;+ };+ if (a === '--base') out.base = next().replace(/\/+$/, '');+ else if (a === '--json') out.json = next();+ else if (a === '--only') out.only = next();+ else if (a === '--timeout') out.timeout = Number(next());+ else if (a === '--help' || a === '-h') {+ console.log('usage: node scripts/mcp-client-probe.mjs [--base <origin>] [--json <path>] [--only <substring>] [--timeout <ms>]');+ process.exit(0);+ } else throw new Error(`unknown argument ${a}`);+ }+ return out;+}++function loadApiKey() {+ if (process.env.THREE_WS_API_KEY) return process.env.THREE_WS_API_KEY;+ for (const f of ['.env', '.env.local']) {+ const p = resolve(ROOT, f);+ if (!existsSync(p)) continue;+ try {+ process.loadEnvFile(p);+ } catch {+ continue;+ }+ if (process.env.THREE_WS_API_KEY) return process.env.THREE_WS_API_KEY;+ }+ return null;+}++// What the manifest's free-text `auth` promises, as flags the checks key on.+export function authExpectations(auth) {+ const s = String(auth || '');+ return {+ anonymous: /\bnone\b/i.test(s),+ oauth: /oauth/i.test(s),+ apiKey: /api key|authenticated three\.ws principals/i.test(s),+ };+}++export function serverUrlFor(endpoint, base) {+ const u = new URL(endpoint);+ return new URL(u.pathname + u.search, `${base}/`).href;+}++// RFC 9110 auth-param parsing, enough for `Bearer k="v", k2="v2"`.+export function parseWwwAuthenticate(header) {+ if (!header) return null;+ const m = /^\s*(\S+)\s*(.*)$/.exec(header);+ if (!m) return null;+ const params = {};+ const re = /([a-zA-Z0-9_-]+)\s*=\s*(?:"((?:[^"\\]|\\.)*)"|([^\s,]+))/g;+ let p;+ while ((p = re.exec(m[2]))) params[p[1].toLowerCase()] = p[2] !== undefined ? p[2].replace(/\\(.)/g, '$1') : p[3];+ return { scheme: m[1], params };+}++async function timedFetch(url, init, timeout) {+ return fetch(url, { ...init, signal: AbortSignal.timeout(timeout) });+}++function initBody(protocolVersion, id = 1) {+ return JSON.stringify({+ jsonrpc: '2.0',+ id,+ method: 'initialize',+ params: { protocolVersion, capabilities: {}, clientInfo: CLIENT_INFO },+ });+}++const PROTOCOL_HEADERS = { 'content-type': 'application/json', accept: 'application/json, text/event-stream' };++// A Streamable HTTP response body is either one JSON object or an SSE stream+// whose `data:` lines carry the JSON-RPC messages.+export function parseRpcBody(text, contentType) {+ if (String(contentType || '').includes('text/event-stream')) {+ for (const line of text.split(/\r?\n/)) {+ if (!line.startsWith('data:')) continue;+ try {+ const msg = JSON.parse(line.slice(5).trim());+ if (msg && (msg.result || msg.error)) return msg;+ } catch {+ continue;+ }+ }+ return null;+ }+ try {+ return JSON.parse(text);+ } catch {+ return null;+ }+}++async function rawInitialize(url, { headers = {}, protocolVersion = LATEST_PROTOCOL_VERSION, timeout }) {+ const res = await timedFetch(url, { method: 'POST', headers: { ...PROTOCOL_HEADERS, ...headers }, body: initBody(protocolVersion) }, timeout);+ const contentType = res.headers.get('content-type') || '';+ const text = await res.text();+ const msg = parseRpcBody(text, contentType);+ return {+ status: res.status,+ contentType,+ sessionId: res.headers.get('mcp-session-id'),+ wwwAuthenticate: res.headers.get('www-authenticate'),+ protocolVersion: msg?.result?.protocolVersion ?? null,+ rpcError: msg?.error ? { code: msg.error.code, message: msg.error.message } : null,+ };+}++async function probeGetStream(url, { headers = {}, timeout }) {+ const controller = new AbortController();+ const timer = setTimeout(() => controller.abort(), timeout);+ try {+ const res = await fetch(url, { method: 'GET', headers: { accept: 'text/event-stream', ...headers }, signal: controller.signal });+ const out = {+ status: res.status,+ contentType: res.headers.get('content-type') || '',+ allow: res.headers.get('allow'),+ wwwAuthenticate: res.headers.get('www-authenticate'),+ };+ // A live stream never ends on its own; the headers are the answer.+ controller.abort();+ await res.body?.cancel().catch(() => {});+ return out;+ } finally {+ clearTimeout(timer);+ }+}++// What a connector needs from a GET: an event stream, a 405 that says which+// methods do work, or an auth challenge it can act on.+export function judgeGetStream(get) {+ if (get.status === 200 && get.contentType.includes('text/event-stream')) return null;+ if (get.status === 405) return get.allow ? null : 'GET answered 405 without an Allow header';+ if (get.status === 401) return get.wwwAuthenticate ? null : 'GET answered 401 without WWW-Authenticate';+ return `GET with accept: text/event-stream answered ${get.status} ${get.contentType}`.trim();+}++async function probeChallenge(url, { timeout }) {+ const out = { failures: [] };+ const anon = await rawInitialize(url, { timeout });+ out.status = anon.status;+ out.wwwAuthenticate = anon.wwwAuthenticate;+ if (anon.status !== 401) {+ out.failures.push(`unauthenticated initialize answered ${anon.status}, an OAuth client needs 401 to start sign-in`);+ return out;+ }+ const parsed = parseWwwAuthenticate(anon.wwwAuthenticate);+ if (!parsed || parsed.scheme.toLowerCase() !== 'bearer') {+ out.failures.push('401 carries no Bearer WWW-Authenticate challenge');+ return out;+ }+ out.resourceMetadataUrl = parsed.params.resource_metadata || null;+ if (!out.resourceMetadataUrl) {+ out.failures.push('WWW-Authenticate does not name resource_metadata');+ return out;+ }+ const mdRes = await timedFetch(out.resourceMetadataUrl, { headers: { accept: 'application/json' } }, timeout);+ const mdType = mdRes.headers.get('content-type') || '';+ const md = mdType.includes('json') ? await mdRes.json().catch(() => null) : null;+ if (!mdType.includes('json')) await mdRes.body?.cancel().catch(() => {});+ out.metadata = {+ status: mdRes.status,+ resource: md?.resource ?? null,+ authorizationServers: md?.authorization_servers ?? null,+ };+ if (mdRes.status !== 200 || !md) {+ out.failures.push(`protected-resource metadata at ${out.resourceMetadataUrl} answered ${mdRes.status} ${mdType}`);+ return out;+ }+ // The exact gate the MCP SDK client runs before it redirects anyone to sign in.+ out.resourceAllowed = Boolean(md.resource) && checkResourceAllowed({ requestedResource: resourceUrlFromServerUrl(url), configuredResource: md.resource });+ if (!out.resourceAllowed) {+ out.failures.push(`protected resource ${md.resource} does not cover ${url}, so an MCP SDK client refuses to sign in`);+ }+ if (parsed.params.resource && parsed.params.resource !== md.resource) {+ out.failures.push(`WWW-Authenticate resource ${parsed.params.resource} disagrees with the metadata resource ${md.resource}`);+ }+ const as = Array.isArray(md.authorization_servers) ? md.authorization_servers[0] : null;+ if (!as) {+ out.failures.push('protected-resource metadata lists no authorization_servers');+ return out;+ }+ const asUrl = new URL('/.well-known/oauth-authorization-server', as).href;+ const asRes = await timedFetch(asUrl, { headers: { accept: 'application/json' } }, timeout);+ const asMd = await asRes.json().catch(() => null);+ out.authorizationServer = {+ url: asUrl,+ status: asRes.status,+ issuer: asMd?.issuer ?? null,+ pkceS256: Boolean(asMd?.code_challenge_methods_supported?.includes('S256')),+ dynamicRegistration: Boolean(asMd?.registration_endpoint),+ };+ if (asRes.status !== 200 || !asMd?.authorization_endpoint || !asMd?.token_endpoint) {+ out.failures.push(`authorization server metadata at ${asUrl} is incomplete (${asRes.status})`);+ } else if (!out.authorizationServer.pkceS256) {+ out.failures.push('authorization server does not advertise PKCE S256, which OAuth 2.1 requires');+ }+ // A connector holding an expired token must be told to re-authenticate, not+ // handed a dead end.+ const stale = await rawInitialize(url, { headers: { authorization: 'Bearer probe.invalid.token' }, timeout });+ out.invalidBearer = { status: stale.status, wwwAuthenticate: stale.wwwAuthenticate };+ const staleParsed = parseWwwAuthenticate(stale.wwwAuthenticate);+ if (stale.status !== 401 || !staleParsed?.params.resource_metadata) {+ out.failures.push(`an invalid bearer answered ${stale.status} without a resource_metadata challenge`);+ }+ return out;+}++async function probeNegotiation(url, { headers = {}, timeout }) {+ const rows = [];+ for (const v of NEGOTIATION_VERSIONS) {+ const r = await rawInitialize(url, { headers, protocolVersion: v, timeout }).catch((err) => ({ error: err.message }));+ rows.push({+ requested: v,+ status: r.status ?? null,+ negotiated: r.protocolVersion ?? null,+ echoed: r.protocolVersion === v,+ clientSupportsAnswer: r.protocolVersion ? SUPPORTED_PROTOCOL_VERSIONS.includes(r.protocolVersion) : false,+ error: r.error ?? r.rpcError?.message ?? null,+ });+ }+ return rows;+}++// Raw session check, run only when the server issued an id: the echoed id+// must work, and an id the server never issued should earn 404 (spec MUST for+// a session the server does not hold).+async function probeSession(url, sessionId, { headers = {}, negotiated, timeout }) {+ const call = (sid) =>+ timedFetch(+ url,+ {+ method: 'POST',+ headers: { ...PROTOCOL_HEADERS, ...headers, 'mcp-session-id': sid, 'mcp-protocol-version': negotiated },+ body: JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} }),+ },+ timeout,+ ).then(async (r) => {+ await r.body?.cancel().catch(() => {});+ return r.status;+ });+ return { echoed: await call(sessionId), unknown: await call(`probe-unknown-${Date.now()}`) };+}++function errorStatus(err) {+ if (!err) return null;+ if (typeof err.code === 'number' && err.code >= 100 && err.code < 600) return err.code;+ const m = /\b(4\d\d|5\d\d)\b/.exec(String(err.message || ''));+ return m ? Number(m[1]) : null;+}++function isAuthError(err) {+ return err?.name === 'UnauthorizedError' || errorStatus(err) === 401 || /unauthori[sz]ed/i.test(String(err?.message));+}++async function runSdk(url, { headers = {}, transport: kind, timeout }) {+ const client = new Client(CLIENT_INFO, { capabilities: {} });+ const warnings = [];+ let closing = false;+ // Closing aborts the open GET stream; that abort is the probe's own doing.+ client.onerror = (e) => {+ if (!closing) warnings.push(String(e?.message || e));+ };+ const requestInit = { headers };+ const transport =+ kind === 'sse'+ ? new SSEClientTransport(new URL(url), {+ requestInit,+ eventSourceInit: { fetch: (u, init) => fetch(u, { ...init, headers: { ...(init?.headers || {}), ...headers } }) },+ })+ : new StreamableHTTPClientTransport(new URL(url), { requestInit });+ const out = { transport: kind, ok: false };+ const opts = { timeout };+ try {+ await client.connect(transport, opts);+ out.serverInfo = client.getServerVersion() ?? null;+ out.protocolVersion = transport.protocolVersion ?? null;+ out.sessionId = transport.sessionId ?? null;+ const caps = client.getServerCapabilities() || {};+ out.capabilities = Object.keys(caps);+ const tools = await client.listTools(undefined, opts);+ out.tools = tools.tools.length;+ out.toolNames = tools.tools.map((t) => t.name);+ out.prompts = caps.prompts ? (await client.listPrompts(undefined, opts)).prompts.length : null;+ const free = FREE_CALLS.find((c) => out.toolNames.includes(c.name));+ if (free) {+ const started = Date.now();+ const r = await client.callTool(free, undefined, opts);+ out.call = {+ name: free.name,+ ok: !r.isError,+ ms: Date.now() - started,+ contentItems: Array.isArray(r.content) ? r.content.length : 0,+ structured: r.structuredContent !== undefined,+ };+ }+ out.ok = !out.call || out.call.ok;+ } catch (err) {+ out.error = String(err?.message || err).slice(0, 400);+ out.status = errorStatus(err);+ out.authRequired = isAuthError(err);+ } finally {+ closing = true;+ if (out.sessionId && kind !== 'sse') await transport.terminateSession().catch((e) => warnings.push(`terminate: ${e.message}`));+ await client.close().catch(() => {});+ }+ delete out.toolNames;+ if (warnings.length) out.warnings = [...new Set(warnings)].slice(0, 5);+ return out;+}++// Streamable HTTP first; the legacy SSE transport only when Streamable HTTP+// failed for a reason other than auth (an auth failure is an answer, not a+// transport problem).+async function runMode(url, { headers, timeout }) {+ const primary = await runSdk(url, { headers, transport: 'streamable-http', timeout });+ if (primary.ok || primary.authRequired) return primary;+ const fallback = await runSdk(url, { headers, transport: 'sse', timeout });+ return { ...primary, fallback };+}++export function judgeServer(r) {+ const failures = [];+ const { expects, modes, http } = r;+ if (http.getStreamProblem) failures.push(http.getStreamProblem);+ if (expects.anonymous) {+ const a = modes.anonymous;+ if (!a.ok && !a.fallback?.ok) failures.push(`anonymous connect failed: ${a.error || a.call?.name + ' call errored'}`);+ else if (!(a.tools > 0 || a.fallback?.tools > 0)) failures.push('anonymous tools/list returned no tools');+ if (http.initialize && !/application\/json|text\/event-stream/.test(http.initialize.contentType)) {+ failures.push(`initialize answered content-type ${http.initialize.contentType}`);+ }+ } else {+ if (modes.anonymous.ok) failures.push('anonymous MCP client was served on a server that requires auth');+ for (const f of modes.oauth?.failures || []) failures.push(f);+ }+ if (modes.apiKey && !modes.apiKey.skipped && (expects.apiKey || expects.oauth)) {+ const k = modes.apiKey;+ if (!k.ok) failures.push(`api key connect failed: ${k.error || k.call?.name + ' call errored'}`);+ else if (!(k.tools > 0)) failures.push('api key tools/list returned no tools');+ }+ for (const n of http.negotiation || []) {+ if (n.negotiated && !n.clientSupportsAnswer) failures.push(`requested ${n.requested}, server answered ${n.negotiated} which no SDK client supports`);+ }+ return failures;+}++async function probeServer(server, { base, timeout, apiKey }) {+ const url = serverUrlFor(server.endpoint, base);+ const expects = authExpectations(server.auth);+ const r = { name: server.name, endpoint: server.endpoint, url, auth: server.auth, expects, http: {}, modes: {} };+ const guard = async (label, fn) => {+ try {+ return await fn();+ } catch (err) {+ return { error: `${label}: ${String(err?.message || err).slice(0, 300)}` };+ }+ };++ r.http.initialize = await guard('initialize', () => rawInitialize(url, { timeout }));+ // One retry on a timeout: a cold instance can hold the first GET past the+ // budget, and a connector retries that too.+ r.http.getStream = await guard('get', () => probeGetStream(url, { timeout: Math.min(timeout, 15_000) }));+ if (r.http.getStream.error) {+ r.http.getStream = await guard('get', () => probeGetStream(url, { timeout: Math.min(timeout, 15_000) }));+ r.http.getStream.retried = true;+ }+ r.http.getStreamProblem = r.http.getStream.error || judgeGetStream(r.http.getStream);++ r.modes.anonymous = await runMode(url, { headers: {}, timeout });+ if (!expects.anonymous) r.modes.oauth = await guard('oauth', () => probeChallenge(url, { timeout }));+ if (!apiKey) r.modes.apiKey = { skipped: 'THREE_WS_API_KEY is not set' };+ else r.modes.apiKey = await runMode(url, { headers: { authorization: `Bearer ${apiKey}` }, timeout });++ // Negotiation and session checks run on whichever mode actually connects.+ const authed = expects.anonymous ? {} : apiKey && r.modes.apiKey.ok ? { authorization: `Bearer ${apiKey}` } : null;+ const working = expects.anonymous ? r.modes.anonymous : r.modes.apiKey;+ if (authed) {+ r.http.negotiation = await guard('negotiation', () => probeNegotiation(url, { headers: authed, timeout }));+ if (working?.sessionId) {+ r.http.session = await guard('session', () =>+ probeSession(url, working.sessionId, { headers: authed, negotiated: working.protocolVersion, timeout }),+ );+ }+ r.http.sessionIssued = Boolean(working?.sessionId);+ }+ if (Array.isArray(r.http.negotiation) === false && r.http.negotiation?.error) r.http.negotiation = [{ error: r.http.negotiation.error }];++ r.failures = judgeServer(r);+ r.pass = r.failures.length === 0;+ return r;+}++function summaryLine(r) {+ const a = r.modes.anonymous;+ const k = r.modes.apiKey;+ const bits = [+ r.pass ? 'PASS' : 'FAIL',+ r.url,+ `init ${r.http.initialize?.status ?? 'err'}`,+ `GET ${r.http.getStream?.status ?? 'err'}`,+ `anon ${a.ok ? `ok tools=${a.tools} prompts=${a.prompts ?? '-'}` : a.authRequired ? '401' : 'fail'}`,+ `key ${k.skipped ? 'skipped' : k.ok ? `ok tools=${k.tools} prompts=${k.prompts ?? '-'}` : 'fail'}`,+ ];+ if (r.modes.oauth) bits.push(`oauth ${r.modes.oauth.failures?.length ? 'bad' : r.modes.oauth.error ? 'err' : 'ok'}`);+ const call = (a.ok && a.call) || (k.ok && k.call);+ if (call) bits.push(`call ${call.name}=${call.ok ? 'ok' : 'error'} ${call.ms}ms`);+ return bits.join(' | ');+}++async function main() {+ const args = parseArgs(process.argv.slice(2));+ const manifest = JSON.parse(readFileSync(resolve(ROOT, 'public/.well-known/mcp.json'), 'utf8'));+ const servers = manifest.servers.filter((s) => !args.only || s.endpoint.includes(args.only) || s.name.includes(args.only));+ if (!servers.length) throw new Error(`no server in public/.well-known/mcp.json matches --only ${args.only}`);+ const apiKey = loadApiKey();+ const startedAt = new Date().toISOString();+ const results = [];+ for (const s of servers) {+ const r = await probeServer(s, { base: args.base, timeout: args.timeout, apiKey });+ results.push(r);+ console.log(summaryLine(r));+ for (const f of r.failures) console.log(` - ${f}`);+ }+ const report = {+ probe: 'scripts/mcp-client-probe.mjs',+ base: args.base,+ startedAt,+ finishedAt: new Date().toISOString(),+ sdkVersion: JSON.parse(readFileSync(resolve(ROOT, 'node_modules/@modelcontextprotocol/sdk/package.json'), 'utf8')).version,+ clientProtocolVersion: LATEST_PROTOCOL_VERSION,+ apiKeyMode: apiKey ? 'ran' : 'skipped (THREE_WS_API_KEY not set)',+ pass: results.every((r) => r.pass),+ servers: results,+ };+ if (args.json) {+ const out = resolve(process.cwd(), args.json);+ mkdirSync(dirname(out), { recursive: true });+ writeFileSync(out, `${JSON.stringify(report, null, '\t')}\n`);+ console.log(`wrote ${args.json}`);+ }+ const failed = results.filter((r) => !r.pass).length;+ console.log(failed ? `${failed} of ${results.length} servers failed` : `all ${results.length} servers passed`);+ process.exitCode = failed ? 1 : 0;+}++if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {+ main().catch((err) => {+ console.error(err?.stack || err);+ process.exit(2);+ });+}diff --git a/scripts/smoke-mcp-remotes.mjs b/scripts/smoke-mcp-remotes.mjsindex 4aade2f8e..c155b045c 100644--- a/scripts/smoke-mcp-remotes.mjs+++ b/scripts/smoke-mcp-remotes.mjs@@ -38,6 +38,13 @@ const ENDPOINTS = [type: 'free',requireTools: ['mesh_forge', 'rig_mesh', 'forge_avatar', 'text_to_avatar', 'check_job'],},+ {+ // The same free studio behind the door Grok Bot and the xAI API connect to.+ // Catalog only, like /api/mcp-studio, so the probe never spends a generation.+ path: '/api/mcp-grok',+ type: 'free',+ requireTools: ['forge_free', 'forge_avatar', 'check_job', 'create_agent_persona', 'persona_say'],+ },{ path: '/api/mcp', type: 'paid' },{ path: '/api/mcp-3d', type: 'paid' },{ path: '/api/mcp-agent', type: 'paid' },diff --git a/tests/mcp-client-probe.test.js b/tests/mcp-client-probe.test.jsnew file mode 100644index 000000000..24e5b01e0--- /dev/null+++ b/tests/mcp-client-probe.test.js@@ -0,0 +1,102 @@+// The connector probe's verdicts, pinned so a change to it cannot quietly+// start passing a server a cloud MCP client would fail on.+import { describe, it, expect } from 'vitest';+import {+ authExpectations,+ serverUrlFor,+ parseWwwAuthenticate,+ parseRpcBody,+ judgeGetStream,+ judgeServer,+} from '../scripts/mcp-client-probe.mjs';++describe('authExpectations', () => {+ it('reads the free-text auth field of /.well-known/mcp.json', () => {+ expect(authExpectations('none')).toEqual({ anonymous: true, oauth: false, apiKey: false });+ expect(authExpectations('OAuth 2.1 (end-user), API key (server-to-server), or x402 pay-per-call')).toEqual({+ anonymous: false,+ oauth: true,+ apiKey: true,+ });+ expect(authExpectations('none for the read-only tools; API key or x402 for pumpfun_upload_metadata').anonymous).toBe(true);+ expect(authExpectations('x402 pay-per-call (authenticated three.ws principals call without per-call payment)').apiKey).toBe(true);+ });+});++describe('serverUrlFor', () => {+ it('moves a published endpoint onto another origin', () => {+ expect(serverUrlFor('https://three.ws/api/mcp-3d', 'http://localhost:3000')).toBe('http://localhost:3000/api/mcp-3d');+ });+});++describe('parseWwwAuthenticate', () => {+ it('parses a quoted Bearer challenge', () => {+ const c = parseWwwAuthenticate(+ 'Bearer resource_metadata="https://three.ws/.well-known/oauth-protected-resource/api/mcp-3d", resource="https://three.ws/api/mcp-3d"',+ );+ expect(c.scheme).toBe('Bearer');+ expect(c.params.resource_metadata).toBe('https://three.ws/.well-known/oauth-protected-resource/api/mcp-3d');+ expect(c.params.resource).toBe('https://three.ws/api/mcp-3d');+ });++ it('returns null for no header', () => {+ expect(parseWwwAuthenticate(null)).toBeNull();+ });+});++describe('parseRpcBody', () => {+ it('reads a JSON-RPC result from an SSE body', () => {+ const body = 'event: message\ndata: {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18"}}\n\n';+ expect(parseRpcBody(body, 'text/event-stream').result.protocolVersion).toBe('2025-06-18');+ });+});++describe('judgeGetStream', () => {+ it('accepts a stream, a 405 with Allow, or an auth challenge', () => {+ expect(judgeGetStream({ status: 200, contentType: 'text/event-stream' })).toBeNull();+ expect(judgeGetStream({ status: 405, contentType: '', allow: 'POST, OPTIONS' })).toBeNull();+ expect(judgeGetStream({ status: 401, contentType: '', wwwAuthenticate: 'Bearer resource_metadata="x"' })).toBeNull();+ });++ it('fails a 405 without Allow and anything else', () => {+ expect(judgeGetStream({ status: 405, contentType: '', allow: null })).toMatch(/Allow/);+ expect(judgeGetStream({ status: 404, contentType: 'text/html' })).toMatch(/404/);+ });+});++describe('judgeServer', () => {+ const base = { http: { initialize: { contentType: 'application/json' }, getStreamProblem: null, negotiation: [] } };++ it('passes an open server that connects and lists tools', () => {+ const r = { ...base, expects: { anonymous: true }, modes: { anonymous: { ok: true, tools: 14 }, apiKey: { skipped: 'x' } } };+ expect(judgeServer(r)).toEqual([]);+ });++ it('fails a protected server whose OAuth metadata the SDK would refuse', () => {+ const r = {+ ...base,+ expects: { anonymous: false, oauth: true },+ modes: {+ anonymous: { ok: false, authRequired: true },+ oauth: { failures: ['protected resource https://three.ws/api/mcp does not cover https://three.ws/api/mcp-3d'] },+ apiKey: { skipped: 'x' },+ },+ };+ expect(judgeServer(r)).toHaveLength(1);+ });++ it('fails a protected server that serves an anonymous MCP client', () => {+ const r = { ...base, expects: { anonymous: false, oauth: true }, modes: { anonymous: { ok: true, tools: 3 }, oauth: { failures: [] }, apiKey: { skipped: 'x' } } };+ expect(judgeServer(r)[0]).toMatch(/requires auth/);+ });++ it('fails a negotiated version no SDK client supports', () => {+ const r = {+ ...base,+ http: { ...base.http, negotiation: [{ requested: '2025-06-18', negotiated: '1999-01-01', clientSupportsAnswer: false }] },+ expects: { anonymous: true },+ modes: { anonymous: { ok: true, tools: 1 }, apiKey: { skipped: 'x' } },+ };+ expect(judgeServer(r)[0]).toMatch(/1999-01-01/);+ });+});