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): expose print analysis and quoting as agent tools behind their own rate limits
nirholasc11a0a27c653
diff --git a/api/_lib/print-store.js b/api/_lib/print-store.jsindex 9243fb7fe..45e239c30 100644--- a/api/_lib/print-store.js+++ b/api/_lib/print-store.js@@ -165,7 +165,13 @@ export async function transition({ orderId, to, note = null, actor = 'system', a// Scarcity is enforced where the price is set, so a sold-out edition is// refused before a buyer is ever asked for money.- if (to === 'quoted') {+ //+ // An order printing a bare GLB is skipped, not failed: editions are numbered+ // against a creation, and an upload that belongs to no creation belongs to no+ // series, so there is nothing for it to be sold out of. Without this guard the+ // series key is underivable and a perfectly valid direct-upload order 500s at+ // the moment it is quoted.+ if (to === 'quoted' && order.creation_id) {await assertEditionAvailable({creationId: order.creation_id,quantity: order.quantity || 1,diff --git a/api/_lib/rate-limit.js b/api/_lib/rate-limit.jsindex 457065a9a..ce89a51e9 100644--- a/api/_lib/rate-limit.js+++ b/api/_lib/rate-limit.js@@ -873,6 +873,14 @@ export const limits = {getLimiter('mcp:inspect', { limit: 30, window: '1 m', critical: true }).limit(key),mcpOptimize: (key) =>getLimiter('mcp:optimize', { limit: 10, window: '1 m', critical: true }).limit(key),+ // Materialize. Analysis fetches, parses, welds and probes a mesh, then builds+ // a BVH over it, so it costs about as much as an optimize; quoting adds only+ // arithmetic on top of the same analysis (which is memoized per source URL),+ // so it gets a wider budget for an agent dragging a size or material choice.+ mcpPrintAnalyze: (key) =>+ getLimiter('mcp:print-analyze', { limit: 10, window: '1 m', critical: true }).limit(key),+ mcpPrintQuote: (key) =>+ getLimiter('mcp:print-quote', { limit: 30, window: '1 m', critical: true }).limit(key),// Diffing fetches and fully parses TWO models per call, so it costs roughly// double an inspect and gets half the budget.mcpDiff: (key) =>diff --git a/api/_mcp/catalog.js b/api/_mcp/catalog.jsindex 8c206d9f0..df4754f03 100644--- a/api/_mcp/catalog.js+++ b/api/_mcp/catalog.js@@ -5,6 +5,7 @@ import { buildGettingStartedTool } from '../_lib/mcp-getting-started.js';import { priceFor } from '../_lib/pump-pricing.js';import { toolDefs as avatarDefs } from './tools/avatars.js';import { toolDefs as modelDefs } from './tools/models.js';+import { toolDefs as printDefs } from './tools/print.js';import { toolDefs as solanaDefs } from './tools/solana.js';import { toolDefs as pumpfunDefs } from './tools/pumpfun.js';import { toolDefs as agentDefs } from './tools/agents.js';@@ -23,6 +24,7 @@ const baseDefs = [...avatarDefs,...embedDefs,...modelDefs,+ ...printDefs,...animationDefs,...signDefs,...solanaDefs,diff --git a/api/_mcp/tools/print.js b/api/_mcp/tools/print.jsnew file mode 100644index 000000000..e5b21bf8d--- /dev/null+++ b/api/_mcp/tools/print.js@@ -0,0 +1,277 @@+// Materialize MCP tools: the print lane, discoverable the same way generation is.+//+// An agent that just generated a model has no way to learn it can also have the+// thing manufactured unless the print lane is in the same tool list the+// generation lane is in. These two tools close that gap:+//+// print_analyze is this mesh printable at all, and at what size+// print_quote what would it cost, in what material, shipped where+//+// Both are free and keyless, which is why they live here rather than behind a+// payment. Neither one places an order or moves money: ordering is+// POST /api/x402/print-order, which is an x402 settlement an agent performs+// deliberately, with the address and the exact total in front of it. A tool+// that could silently commit a caller to a physical shipment has no business+// being a read-only lookup, so the quote tool returns the signed token and+// stops there.+//+// The fabrication gate runs inside the quote endpoint these tools call, so a+// refusal reaches the agent here, before any price exists, with the category+// and the policy link rather than a bare error. See+// api/_lib/print/gate.js and docs/materialize.md#content-policy.++import { limits } from '../../_lib/rate-limit.js';+import { loadMeshFromUrl, MeshIoError } from '../../_lib/print/mesh-io.js';+import { analyzeMesh } from '../../_lib/print/analyze.js';+import {+ loadCatalog,+ materialFits,+ publicCatalog,+ quotePrint,+ signQuote,+} from '../../_lib/print/quote.js';+import { loadLineage, runFabricationGate } from '../../_lib/print/gate.js';+import { getPublicCreation } from '../../_lib/forge-store.js';+import { createHash } from 'node:crypto';++function rpcError(code, message, data) {+ const e = new Error(message);+ e.code = code;+ e.data = data;+ return e;+}++// Both tools read a caller-supplied model and compute a deterministic answer:+// same file, same report, same price. destructiveHint defaults to true when+// omitted, so it is set explicitly.+const PRINT_ANNOTATIONS = {+ readOnlyHint: true,+ destructiveHint: false,+ idempotentHint: true,+ openWorldHint: true,+};++/** The same report hash the HTTP quote endpoint binds into a token. */+function reportHashOf(report) {+ return createHash('sha256')+ .update(JSON.stringify([report.version, report.volume_cm3, report.bbox_mm, report.min_wall_mm, report.triangles]))+ .digest('hex')+ .slice(0, 32);+}++/**+ * Resolve the model an agent named: a three.ws creation, or any public GLB.+ * @returns {Promise<{ url: string, creationId: string|null, prompt: string }>}+ */+async function resolveModel(args) {+ if (args.creation_id) {+ const creation = await getPublicCreation({ id: String(args.creation_id) });+ if (!creation) throw rpcError(-32602, 'no finished public creation with that id');+ if (!creation.glb_url) throw rpcError(-32602, 'that creation has no finished model yet');+ return { url: creation.glb_url, creationId: creation.id, prompt: creation.prompt || '' };+ }+ if (args.glb_url) return { url: String(args.glb_url), creationId: null, prompt: '' };+ throw rpcError(-32602, 'pass creation_id or glb_url');+}++/** Load and analyze, translating the typed mesh errors into MCP errors. */+async function reportFor(url) {+ try {+ const mesh = await loadMeshFromUrl(url);+ return await analyzeMesh(mesh, { sourceUrl: url });+ } catch (err) {+ if (err instanceof MeshIoError) throw rpcError(-32602, `${err.code}: ${err.message}`);+ throw err;+ }+}++/**+ * Run the fabrication gate over the same subject the HTTP lane reads. Throws+ * the refusal as an MCP error carrying the category and the policy link, so an+ * agent can tell "this is not printable" from "we will not print this".+ */+async function assertPrintable({ creationId, prompt, note, report }) {+ const lineage = await loadLineage(creationId);+ const gate = await runFabricationGate({+ stage: 'quote',+ lineageText: lineage.text || prompt,+ buyerNote: typeof note === 'string' ? note : '',+ analysis: report,+ });+ if (gate.verdict === 'refuse') {+ throw rpcError(-32000, gate.message, {+ reason: 'fabrication_refused',+ category: gate.category,+ allowed: gate.allowed,+ policy_url: gate.policy_url,+ });+ }+ return gate;+}++function summarizeReport(report) {+ const b = report.bbox_mm;+ const lines = [+ `Printability score ${report.score}/100.`,+ `${report.manifold ? 'Closed solid' : 'Not a closed solid, it will be reconstructed before printing'}, ${report.shells} ${report.shells === 1 ? 'body' : 'separate bodies'}, ${report.triangles} triangles.`,+ `Bounding box ${b.x} x ${b.y} x ${b.z} mm at the model's own scale. Volume ${report.volume_cm3} cm3.`,+ report.min_wall_mm === null+ ? 'Thinnest wall could not be measured (the surface has nothing behind it).'+ : `Thinnest wall ${report.min_wall_mm} mm at this size.`,+ ];+ if (report.recommended_min_height_mm) {+ const r = report.recommended_min_height_mm;+ lines.push(+ `Minimum print height for the detail to survive: resin ${r.resin} mm, SLS nylon ${r.sls_nylon} mm, full colour ${r.full_color} mm.`,+ );+ }+ for (const d of report.deductions) lines.push(` ${d.id} (-${d.points}): ${d.detail}`);+ return lines.join('\n');+}++function summarizeQuote(quote) {+ const lines = [+ `${quote.material.name}, ${quote.targetHeightMm} mm tall, quantity ${quote.quantity}, shipping to ${quote.country}.`,+ ];+ for (const line of quote.lines) {+ lines.push(` ${line.label}: ${line.amount} ${quote.currency}${line.detail ? ` (${line.detail})` : ''}`);+ }+ lines.push(`Total ${quote.total} ${quote.currency} on ${quote.chain}, about ${quote.leadTimeDays} days to arrive.`);+ if (quote.quoteOnRequest) {+ lines.push('This material is quote-on-request: the figure is an estimate and cannot be checked out until an engineer confirms it.');+ } else {+ lines.push('Order it with POST /api/x402/print-order, passing this token and a shipping address.');+ }+ return lines.join('\n');+}++export const toolDefs = [+ {+ name: 'print_analyze',+ title: 'Check whether a 3D model can be printed',+ annotations: PRINT_ANNOTATIONS,+ description:+ 'Measure a 3D model for real-world manufacturing: whether it is a closed solid, how many separate ' ++ 'bodies it contains, how many holes it has, its thinnest wall, its exact volume, and a 0-100 ' ++ 'printability score with named reasons. Also returns, per material, the smallest height the model ' ++ 'can be printed at and still hold its detail. Free, keyless, and read-only: nothing is ordered. ' ++ 'Pass a three.ws creation_id or any public glb_url.',+ inputSchema: {+ type: 'object',+ properties: {+ creation_id: { type: 'string', description: 'A three.ws forge creation id.' },+ glb_url: { type: 'string', format: 'uri', description: 'Public https URL of a .glb file, instead of a creation id.' },+ },+ additionalProperties: false,+ },+ async handler(args, auth) {+ const rl = await limits.mcpPrintAnalyze(auth.userId || auth.rateKey);+ if (!rl.success) {+ throw rpcError(-32000, 'rate_limited', { retry_after: Math.ceil((rl.reset - Date.now()) / 1000) });+ }+ const model = await resolveModel(args);+ const report = await reportFor(model.url);+ await assertPrintable({ creationId: model.creationId, prompt: model.prompt, note: '', report });+ const fits = materialFits({ report, catalog: loadCatalog() });+ return {+ content: [{ type: 'text', text: summarizeReport(report) }],+ structuredContent: { source_url: model.url, report, fits },+ };+ },+ },+ {+ name: 'print_quote',+ title: 'Price a real 3D print and get a signed quote',+ annotations: PRINT_ANNOTATIONS,+ description:+ 'Price a physical print of a 3D model: an itemized quote in USDC (build setup, material with the ' ++ 'exact volume it was computed from, finish, quantity break, shipping) plus a signed quote token ' ++ 'valid for 24 hours. Materials, size limits and lead times come from GET /api/print/catalog. This ' ++ 'tool does NOT place an order and moves no money: settle the token at POST /api/x402/print-order ' ++ 'when you have a shipping address. Free and keyless.',+ inputSchema: {+ type: 'object',+ properties: {+ creation_id: { type: 'string', description: 'A three.ws forge creation id.' },+ glb_url: { type: 'string', format: 'uri', description: 'Public https URL of a .glb file, instead of a creation id.' },+ material_id: { type: 'string', description: 'Material id from the catalog, e.g. resin-standard. Omit to list what fits.' },+ finish_id: { type: 'string', description: 'Optional finish id from that material.' },+ target_height_mm: { type: 'number', minimum: 1, maximum: 1000, description: 'Printed height in millimetres.' },+ quantity: { type: 'integer', minimum: 1, maximum: 500, default: 1, description: 'How many. Price breaks at 5 and 20.' },+ country: { type: 'string', minLength: 2, maxLength: 2, description: 'ISO 3166-1 alpha-2 destination, for shipping.' },+ hollow: { type: 'boolean', description: 'Hollow the solid where it is geometrically safe. Lowers the price.' },+ note: { type: 'string', maxLength: 500, description: 'Optional note about the intended object. Read by the fabrication safety gate.' },+ },+ additionalProperties: false,+ },+ async handler(args, auth) {+ const rl = await limits.mcpPrintQuote(auth.userId || auth.rateKey);+ if (!rl.success) {+ throw rpcError(-32000, 'rate_limited', { retry_after: Math.ceil((rl.reset - Date.now()) / 1000) });+ }+ const model = await resolveModel(args);+ const report = await reportFor(model.url);+ await assertPrintable({ creationId: model.creationId, prompt: model.prompt, note: args.note, report });++ const catalog = loadCatalog();+ const fits = materialFits({ report, catalog });+ if (!args.material_id) {+ // No material chosen yet: answer with what this mesh can be made of+ // rather than an error, so an agent can pick and call again.+ return {+ content: [+ {+ type: 'text',+ text: `${summarizeReport(report)}\n\nMaterials that fit this mesh: ${fits+ .filter((f) => f.ok)+ .map((f) => f.materialId)+ .join(', ') || 'none at any size'}\nCall again with material_id, target_height_mm and country for a price.`,+ },+ ],+ structuredContent: { source_url: model.url, report, fits, catalog: publicCatalog(catalog), quote: null, token: null },+ };+ }++ const priced = quotePrint({+ report,+ materialId: String(args.material_id),+ finishId: args.finish_id ? String(args.finish_id) : null,+ targetHeightMm: Number(args.target_height_mm),+ quantity: Number(args.quantity) || 1,+ country: args.country,+ hollow: Boolean(args.hollow),+ holderDiscountBps: 0,+ catalog,+ });++ if (!priced.ok) {+ // A constraint rejection is guidance, not a failure: it names the+ // measured number, the required number and the fix.+ return {+ content: [{ type: 'text', text: `Cannot print it that way: ${priced.rejection.message}` }],+ structuredContent: { source_url: model.url, report, fits, quote: null, rejection: priced.rejection, token: null },+ };+ }++ const token = priced.quote.quoteOnRequest+ ? null+ : signQuote(priced.quote, {+ reportHash: reportHashOf(report),+ sourceUrl: model.url,+ creationId: model.creationId,+ });++ return {+ content: [{ type: 'text', text: summarizeQuote(priced.quote) }],+ structuredContent: {+ source_url: model.url,+ report,+ quote: priced.quote,+ token,+ order_endpoint: '/api/x402/print-order',+ expires_in_seconds: token ? catalog.pricing.quoteTtlSeconds : null,+ },+ };+ },+ },+];diff --git a/tests/api/print-mcp-tools.test.js b/tests/api/print-mcp-tools.test.jsnew file mode 100644index 000000000..a681c4c31--- /dev/null+++ b/tests/api/print-mcp-tools.test.js@@ -0,0 +1,136 @@+// The Materialize MCP tools: how an agent discovers that a model it just+// generated can also be manufactured.+//+// The pair is deliberately read-only. Ordering is an x402 settlement the agent+// performs with the address and the exact total in front of it, so these tools+// price and stop. This suite pins that boundary, that both tools are actually+// in the served catalog (a tool nothing lists does not exist), and that the+// fabrication gate reaches an agent through this lane with a category and a+// policy link rather than a bare failure.++import { describe, it, expect, vi, beforeEach } from 'vitest';++const REPORT = {+ version: 1,+ manifold: true,+ shells: 1,+ triangles: 4200,+ volume_cm3: 27.14,+ bbox_mm: { x: 41, y: 120, z: 38, diagonal: 133 },+ min_wall_mm: 2.4,+ median_wall_mm: 6.1,+ recommended_min_height_mm: { resin: 120, sls_nylon: 120, full_color: 133, fdm_draft: 120, metal: 120 },+ score: 100,+ deductions: [],+};++let creationPrompt = 'a small brass gear';++vi.mock('../../api/_lib/rate-limit.js', () => ({+ limits: {+ mcpPrintAnalyze: async () => ({ success: true, reset: Date.now() + 60_000 }),+ mcpPrintQuote: async () => ({ success: true, reset: Date.now() + 60_000 }),+ },+ clientIp: () => '203.0.113.11',+}));+vi.mock('../../api/_lib/print/mesh-io.js', () => ({+ loadMeshFromUrl: async () => ({ triangleCount: 4200 }),+ MeshIoError: class extends Error {},+}));+vi.mock('../../api/_lib/print/analyze.js', () => ({ analyzeMesh: async () => REPORT }));+vi.mock('../../api/_lib/forge-store.js', () => ({+ getPublicCreation: async () => ({ id: 'c-9', glb_url: 'https://cdn.three.ws/m.glb', prompt: creationPrompt }),+}));+// Only the gate's lineage read touches the database; the rules and layers under+// test are the shipped ones.+vi.mock('../../api/_lib/db.js', () => ({ sql: async () => [] }));++const { toolDefs } = await import('../../api/_mcp/tools/print.js');+const analyze = toolDefs.find((t) => t.name === 'print_analyze');+const quote = toolDefs.find((t) => t.name === 'print_quote');+const auth = { userId: null, rateKey: 'test' };++beforeEach(() => {+ creationPrompt = 'a small brass gear';+});++describe('discovery', () => {+ it('both tools are in the served MCP catalog', async () => {+ const { TOOL_CATALOG } = await import('../../api/_mcp/catalog.js');+ const names = TOOL_CATALOG.map((t) => t.name);+ expect(names).toContain('print_analyze');+ expect(names).toContain('print_quote');+ });++ it('declares itself read-only, because neither tool can commit a shipment', () => {+ for (const tool of toolDefs) {+ expect(tool.annotations.readOnlyHint, tool.name).toBe(true);+ expect(tool.annotations.destructiveHint, tool.name).toBe(false);+ }+ });++ it('the quote tool points the agent at the endpoint that actually orders', () => {+ expect(quote.description).toContain('/api/x402/print-order');+ expect(quote.description).toContain('does NOT place an order');+ });+});++describe('print_analyze', () => {+ it('returns the report and the materials that fit', async () => {+ const result = await analyze.handler({ creation_id: 'c-9' }, auth);+ expect(result.structuredContent.report.version).toBe(1);+ expect(Array.isArray(result.structuredContent.fits)).toBe(true);+ expect(result.content[0].text).toContain('Printability score 100/100');+ expect(result.content[0].text).toContain('27.14 cm3');+ });++ it('needs a model to look at', async () => {+ await expect(analyze.handler({}, auth)).rejects.toThrow(/creation_id or glb_url/);+ });+});++describe('print_quote', () => {+ it('prices a real material and returns a signed token an agent can settle', async () => {+ const result = await quote.handler(+ { creation_id: 'c-9', material_id: 'resin-standard', target_height_mm: 120, quantity: 1, country: 'US' },+ auth,+ );+ const { quote: priced, token, order_endpoint } = result.structuredContent;+ expect(priced.currency).toBe('USDC');+ expect(priced.chain).toBe('solana');+ expect(priced.total).toBeGreaterThan(0);+ expect(token).toMatch(/^pq1\./);+ expect(order_endpoint).toBe('/api/x402/print-order');+ // The itemization is what the agent shows its user, so it is in the text.+ expect(result.content[0].text).toContain('Build setup');+ expect(result.content[0].text).toContain('Total');+ });++ it('answers "what could this be made of" instead of erroring when no material was picked', async () => {+ const result = await quote.handler({ creation_id: 'c-9' }, auth);+ expect(result.structuredContent.quote).toBeNull();+ expect(result.structuredContent.token).toBeNull();+ expect(result.content[0].text).toContain('Materials that fit this mesh');+ });++ it('carries a fabrication refusal to the agent with a category and a live policy link', async () => {+ const err = await quote+ .handler(+ { creation_id: 'c-9', note: 'add a monocore baffle so it works as a suppressor', material_id: 'resin-standard', target_height_mm: 120, country: 'US' },+ auth,+ )+ .catch((e) => e);+ expect(err.data.reason).toBe('fabrication_refused');+ expect(err.data.category).toBe('suppressors');+ expect(err.data.policy_url).toBe('/docs/materialize#content-policy');+ expect(err.data.allowed).toBeTruthy();+ });++ it('reads the prompt lineage, not just the buyer note', async () => {+ creationPrompt = 'an AR-15 lower receiver';+ const err = await quote+ .handler({ creation_id: 'c-9', material_id: 'resin-standard', target_height_mm: 120, country: 'US' }, auth)+ .catch((e) => e);+ expect(err.data.category).toBe('firearm_components');+ });+});