Skip to content

3D engine that AI agents drive

Name the valid hdri and look values in the input error (#2049)

Nguyen Xuan Anb097301f599c
diff --git a/changes/2049.md b/changes/2049.md
new file mode 100644
index 00000000..86ef0188
--- /dev/null
+++ b/changes/2049.md
@@ -0,0 +1 @@
+- An invalid `environment.hdri` or `environment.look` now lists the built-in names and the catalog option instead of only the 64-hex pattern (#2049)
diff --git a/scripts/mcp-server.mjs b/scripts/mcp-server.mjs
index 3901be31..ef0690ea 100644
--- a/scripts/mcp-server.mjs
+++ b/scripts/mcp-server.mjs
@@ -16,6 +16,7 @@ import packageMetadata from '../package.json' with { type: 'json' };
import { MODIFIER_OPERATIONS } from '../src/mesh-operations.js';
import { VIEW_TRANSFORM_NAMES, LOOK_NAMES } from '../src/view-transform-names.js';
import { BUNDLED_ENVIRONMENT_NAMES, BUNDLED_CUBE_LOOK_NAMES, CATALOG_FILE_ID } from '../src/look-catalog.js';
+import { describeReceived } from '../src/field-error.js';
import { MATERIAL_PATTERN_TYPES, MATERIAL_MAPPINGS, LIGHTING_SETUP_NAMES, RENDER_PASS_NAMES, RENDER_OUTPUT_FORMATS, MAXIMUM_JOB_FPS, VIDEO_ENCODERS, MAXIMUM_JOB_SIDE, maximumMemoryMiB, memoryRangeError, MAXIMUM_STILLS_FRAMES } from '../src/agent-scene-capabilities.js';
import { MATERIAL_LAYER_SCALAR_RANGES, MATERIAL_LAYER_COLOR_RANGES } from '../src/material-layers.js';
import { SUBSURFACE_RANGES } from '../src/subsurface-limits.js';
@@ -250,12 +251,18 @@ const volumeFog = z.strictObject({
const affects = z.array(z.string()).optional();
const iesProfile = z.any().optional();
const lines = z.record(z.string(), z.unknown()).describe('Outlines, toon light and polylines as plain JSON; fields and limits in scene_capabilities lineArt. null clears.');
+// An invalid name says which names work. The union alone reports only its 64-hex branch (issue 2049).
+function catalogReference(names, fileKind) {
+ const error = issue => `Invalid value: expected a built-in name (${names.join(', ')}), or a 64-character ${fileKind} ID from scene_asset_catalog (got ${describeReceived(issue.input)})`;
+ return z.union([z.enum(names, { error }), z.string().regex(CATALOG_FILE_ID, { error })], { error });
+}
+
const environment = z.strictObject({
world: z.boolean().optional().describe('Draw the sky and apply surface fog.'),
ground: z.boolean().optional().describe('false: no automatic floor.'),
setup: z.enum(LIGHTING_SETUP_NAMES).optional().describe('Named lighting; resets key, fill and ambient fields. Default daylight.'),
environmentIntensity: bounded(0, 100).optional().describe('Scales the setup environment light and its reflections.'),
- hdri: z.union([z.enum(BUNDLED_ENVIRONMENT_NAMES), z.string().regex(CATALOG_FILE_ID)]).nullable().optional().describe('HDRI instead of the setup sky; scene_capabilities catalogLooks.'),
+ hdri: catalogReference(BUNDLED_ENVIRONMENT_NAMES, '.hdr').nullable().optional().describe('HDRI instead of the setup sky; scene_capabilities catalogLooks.'),
environmentRotation: bounded(-100, 100).optional().describe('Turns the setup environment around the vertical axis, in radians.'),
lightDirection: boundedVector(-1e6, 1e6).optional().describe('Direction toward the key light; shadows follow.'),
keyColor: boundedVector(0, 1000).optional(),
@@ -314,7 +321,7 @@ const environment = z.strictObject({
specularAntiAliasing: z.number().min(0).max(4).optional().describe('Specular anti-aliasing: 0 off, 1 default; widens highlights that sparkle on grainy normal-mapped metal.'),
resolveCoplanar: z.union([z.literal('offset'), z.literal(false)]).optional().describe("Flush faces are ranked at draw time by default ('offset'); false opts out."),
viewTransform: z.enum(VIEW_TRANSFORM_NAMES).optional().describe('Display transform, for example agx to compare with Blender.'),
- look: z.union([z.enum([...LOOK_NAMES, ...BUNDLED_CUBE_LOOK_NAMES]), z.string().regex(CATALOG_FILE_ID)]).nullable().optional().describe('Look preset or .cube; scene_capabilities catalogLooks. null clears.'),
+ look: catalogReference([...LOOK_NAMES, ...BUNDLED_CUBE_LOOK_NAMES], '.cube').nullable().optional().describe('Look preset or .cube; scene_capabilities catalogLooks. null clears.'),
sky: z.record(z.string(), z.unknown()).nullable().optional().describe('Physical sky: {type:"physical", sunElevation, sunRotation, turbidity, groundAlbedo, aerialPerspective}; sets key light, sky and fog. Fields in scene_capabilities physicalSky.'),
wind: z.strictObject({ strength: bounded(0, 4).optional(), direction: bounded(-360, 360).optional().describe('Degrees: 0 toward +x, 90 toward +z.') }).optional().describe('Sway of foliage and grass materials; strength defaults to 0.3.'),
});
diff --git a/tests/mcp-catalog-reference-errors.test.js b/tests/mcp-catalog-reference-errors.test.js
new file mode 100644
index 00000000..2e1d3fff
--- /dev/null
+++ b/tests/mcp-catalog-reference-errors.test.js
@@ -0,0 +1,60 @@
+import './support/load-agent-scene-modules.mjs';
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { Client } from '@modelcontextprotocol/client';
+import { InMemoryTransport } from '@modelcontextprotocol/server';
+import { createAgentMcpServer } from '../scripts/mcp-server.mjs';
+
+// Issue 2049: a wrong hdri or look name used to fail against the 64-hex pattern only.
+
+async function connectedClient(context, runtime) {
+ const server = createAgentMcpServer(runtime);
+ const client = new Client({ name: 'crucible-catalog-reference-test', version: '1' });
+ const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+ await server.connect(serverTransport);
+ await client.connect(clientTransport);
+ context.after(async () => {
+ await client.close();
+ await server.close();
+ });
+ return client;
+}
+
+const idleRuntime = { async close() {}, async capabilities() { return { scene: {}, phase: 'idle' }; }, activeSessionId() { return null; } };
+
+async function rejectedEnvironmentMessage(context, environment) {
+ const client = await connectedClient(context, idleRuntime);
+ const operations = [{ type: 'set-environment', environment }];
+ try {
+ const result = await client.callTool({ name: 'scene_apply', arguments: { expectedRevision: 0, operations } });
+ return result.content?.[0]?.text ?? '';
+ } catch (error) {
+ return error.message;
+ }
+}
+
+test('a wrong environment.hdri lists the built-in names and the catalog option', async context => {
+ const message = await rejectedEnvironmentMessage(context, { hdri: 'no-such-hdri' });
+ assert.match(message, /environment\.hdri: .*built-in name \(sky-clouds, studio-softbox\)/);
+ assert.match(message, /64-character \.hdr ID from scene_asset_catalog/);
+ assert.match(message, /got "no-such-hdri"/);
+ assert.doesNotMatch(message, /must match pattern/);
+});
+
+test('a wrong environment.look lists the preset and bundled look names', async context => {
+ const message = await rejectedEnvironmentMessage(context, { look: 'nope' });
+ assert.match(message, /environment\.look: .*built-in name \(.*warm.*cool.*contrast.*faded.*teal-orange.*noir/);
+ assert.match(message, /64-character \.cube ID from scene_asset_catalog/);
+ assert.doesNotMatch(message, /must match pattern/);
+});
+
+test('built-in names and 64-hex IDs still pass input validation', async context => {
+ const reachedRuntime = [];
+ const runtime = { ...idleRuntime, async apply(argumentsValue) { reachedRuntime.push(argumentsValue); return { revision: 1 }; } };
+ const client = await connectedClient(context, runtime);
+ for (const environment of [{ hdri: 'sky-clouds' }, { look: 'noir' }, { hdri: 'a'.repeat(64) }]) {
+ const operations = [{ type: 'set-environment', environment }];
+ const result = await client.callTool({ name: 'scene_apply', arguments: { expectedRevision: 0, operations } }).catch(error => ({ text: error.message }));
+ assert.doesNotMatch(result.text ?? result.content?.[0]?.text ?? '', /Input validation error/);
+ }
+});