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.

5.7 KB
Raw Blame
// ─────────────────────────────────────────────────────────────────────────────
// MCP server — viewer-control tools for three.ws.
//
// Exposes the same tool catalog as POST /api/chat (setWireframe, loadModel,
// takeScreenshot, …) but over MCP 2025-06-18 JSON-RPC so external agents
// (Claude Desktop, LobeHub, Cursor) can drive the viewer without going through
// our chat UI.
//
// Execution model: tool calls return an "action intent" — { action, input,
// resource } — that the MCP client is expected to relay to the live three.ws
// viewer (via the LobeHub iframe postMessage bridge or a future WS channel).
// We do NOT execute against a browser viewer from the server: there is none.
//
// Auth: Bearer token (OAuth/API key) — same as /api/mcp.
// ─────────────────────────────────────────────────────────────────────────────

import { env } from '../_lib/env.js';
import { authenticateBearer, extractBearer } from '../_lib/auth.js';
import { cors, method, readJson, wrap } from '../_lib/http.js';
import { recordEvent, logger } from '../_lib/usage.js';
import { VIEWER_TOOLS } from '../_lib/viewer-mcp-tools.js';

const PROTOCOL_VERSION = '2025-06-18';
const SERVER_INFO = { name: 'three-ws-viewer-mcp', version: '0.1.0' };
const log = logger('chat-mcp');

const TOOL_NAMES = new Set(VIEWER_TOOLS.map((t) => t.name));

export default wrap(async (req, res) => {
	// `origins: '*'` matches every other MCP server in this repo (api/mcp.js,
	// mcp-3d, mcp-studio, mcp-agent, mcp-bazaar, ibm-mcp, pump-fun-mcp). This one
	// exists so browser-hosted MCP clients (the LobeHub plugin iframe) can drive
	// the viewer, and the default APP_ORIGIN allowlist blocked exactly those.
	// Safe because the endpoint is Bearer-only: no credentials flag is set, so a
	// cross-origin page still cannot ride a signed-in user's session, it can only
	// spend a token it already holds.
	if (cors(req, res, { methods: 'POST,OPTIONS', origins: '*' })) return;
	// A wrong method is a 405 with an Allow header, NOT a 401. Answering GET with
	// "unauthorized" sent MCP clients into a re-auth loop over what was only ever
	// a method mismatch, and hid the real contract from anyone probing the URL.
	if (!method(req, res, ['POST'])) return;

	const auth = await authenticateBearer(extractBearer(req), { audience: env.MCP_RESOURCE });
	if (!auth) return send401(res, 'missing or invalid access token');

	const body = await readJson(req);
	const result = await dispatch(body, auth);
	res.setHeader('mcp-protocol-version', PROTOCOL_VERSION);
	// JSON-RPC notifications (a message with no `id`) must never be answered.
	// dispatch() returns null for those; every real MCP client sends
	// `notifications/initialized` straight after initialize, and replying to it
	// with a -32601 error made the handshake look broken to the client.
	if (result === null) {
		res.statusCode = 202;
		res.end();
		return;
	}
	res.statusCode = 200;
	res.setHeader('content-type', 'application/json');
	res.end(JSON.stringify(result));
});

async function dispatch(msg, auth) {
	if (!msg || msg.jsonrpc !== '2.0' || typeof msg.method !== 'string') {
		return rpcErr(msg?.id ?? null, -32600, 'invalid request');
	}

	// A message without an `id` is a notification: the caller expects no reply at
	// all, not even an error one. Handled before the switch so an unknown
	// notification stays silent instead of drawing a -32601 the client can only
	// read as a failed handshake.
	const isNotification = msg.id === undefined || msg.id === null;
	if (isNotification) {
		if (msg.method === 'notifications/initialized') {
			log.info('client-initialized', { actor: auth.userId ?? auth.payer ?? 'anonymous' });
		}
		return null;
	}

	switch (msg.method) {
		case 'initialize':
			return rpcOk(msg.id, {
				protocolVersion: PROTOCOL_VERSION,
				serverInfo: SERVER_INFO,
				capabilities: { tools: { listChanged: false } },
			});

		case 'tools/list':
			return rpcOk(msg.id, { tools: VIEWER_TOOLS });

		case 'tools/call': {
			const name = msg.params?.name;
			const input = msg.params?.arguments ?? {};
			if (!TOOL_NAMES.has(name)) {
				return rpcErr(msg.id, -32601, `unknown tool: ${name}`);
			}
			const intent = {
				action: name,
				input,
				resource: 'three.ws/viewer',
				hint:
					'Relay this intent to the live three.ws viewer via the LobeHub plugin postMessage bridge or a session WS. The MCP server has no direct viewer handle.',
				issuedAt: new Date().toISOString(),
				actor: auth.userId ?? auth.payer ?? 'anonymous',
			};
			recordEvent({
				userId: auth.userId,
				apiKeyId: auth.apiKeyId,
				clientId: auth.clientId,
				kind: 'chat-mcp',
				tool: name,
				meta: { input },
			});
			log.info('viewer-intent', { tool: name, actor: intent.actor });
			return rpcOk(msg.id, {
				content: [{ type: 'text', text: JSON.stringify(intent) }],
				structuredContent: intent,
			});
		}

		case 'ping':
			return rpcOk(msg.id, {});

		default:
			return rpcErr(msg.id, -32601, `method not found: ${msg.method}`);
	}
}

function rpcOk(id, result) {
	return { jsonrpc: '2.0', id, result };
}
function rpcErr(id, code, message) {
	return { jsonrpc: '2.0', id, error: { code, message } };
}
function send401(res, message) {
	res.statusCode = 401;
	res.setHeader(
		'www-authenticate',
		`Bearer realm="three.ws", resource_metadata="${env.ISSUER}/.well-known/oauth-protected-resource"`,
	);
	res.setHeader('content-type', 'application/json');
	res.end(JSON.stringify({ error: 'unauthorized', error_description: message }));
}