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.

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.js
index 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.js
index 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.js
index 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.js
new file mode 100644
index 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.js
new file mode 100644
index 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');
+ });
+});