3D engine that AI agents drive
Publish the MCP environment schema once, in scene_create (part of #447)
Nguyen Xuan An7ef9d29a84a1
diff --git a/changes/447-environment-schema-once.md b/changes/447-environment-schema-once.mdnew file mode 100644index 00000000..16fe6f4a--- /dev/null+++ b/changes/447-environment-schema-once.md@@ -0,0 +1 @@+- MCP: `scene_apply` (`set-environment`) and `scene_create_asset` no longer repeat the whole environment schema; they name `recipe.environment` in `scene_create` and the server still checks every field. The tool schemas are about 15 KB smaller, and the environment field descriptions shortened in #444 are back.diff --git a/changes/447-environment-schema-once.size.md b/changes/447-environment-schema-once.size.mdnew file mode 100644index 00000000..02ec4d31--- /dev/null+++ b/changes/447-environment-schema-once.size.md@@ -0,0 +1 @@+- tool:scene_create: +594 bytes for the environment field descriptions #444 had to shorten (shadows follow the key light, the reflection-probe note, the four new fields); the same change removes two copies of the environment schema from scene_apply and scene_create_asset, so the tool total drops by 15,146 bytesdiff --git a/scripts/mcp-server.mjs b/scripts/mcp-server.mjsindex 63377deb..2655691c 100644--- a/scripts/mcp-server.mjs+++ b/scripts/mcp-server.mjs@@ -171,14 +171,14 @@ const volumeFog = z.strictObject({shadowAmbient: unit.optional(),});const affects = z.array(z.string()).optional();-const lines = z.record(z.string(), z.unknown()).describe('Line art JSON; see scene_capabilities lineArt. null clears.');+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.');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, ambient.'),- environmentIntensity: bounded(0, 100).optional().describe('Scales environment light.'),- environmentRotation: bounded(-100, 100).optional().describe('Radians about vertical.'),- lightDirection: boundedVector(-1e6, 1e6).optional().describe('Toward the key light.'),+ 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.'),+ 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(),keyIntensity: bounded(0, 100).optional(),fillIntensity: bounded(0, 100).optional(),@@ -192,12 +192,12 @@ const environment = z.strictObject({intensity: bounded(0, 1e5).optional(),radius: bounded(0.001, 1e6).optional(),range: z.union([z.literal(0), bounded(0.001, 1e6)]).optional(),- castShadow: z.boolean().optional().describe('6 atlas tiles.'),+ castShadow: z.boolean().optional().describe('Casts a shadow; 6 atlas tiles.'),affects,- })).max(8).optional().describe('Replaces the list; [] clears. Candela.'),+ })).max(8).optional().describe('Replaces the list; [] clears. Intensity in candela.'),spotLights: z.array(z.strictObject({position: boundedVector(-1e6, 1e6),- direction: boundedVector(-1e6, 1e6).describe('Nonzero cone direction.'),+ direction: boundedVector(-1e6, 1e6).describe('Nonzero direction the cone points along.'),angle: bounded(0.01, Math.PI / 2 - 0.01).optional().describe('Outer half angle, radians; default pi/4.'),penumbra: unit.optional().describe('Soft edge, 0 hard; default 0.15.'),color: color.optional(),@@ -209,8 +209,8 @@ const environment = z.strictObject({})).max(8).optional().describe('Replaces the list; [] clears.'),areaLights: z.array(z.strictObject({position: boundedVector(-1e6, 1e6).describe('Center of the rectangle.'),- direction: boundedVector(-1e6, 1e6).describe('Facing direction; one side emits.'),- up: boundedVector(-1e6, 1e6).optional().describe('Height axis; default up.'),+ direction: boundedVector(-1e6, 1e6).describe('Direction the rectangle faces; emits that side only.'),+ up: boundedVector(-1e6, 1e6).optional().describe('Height axis direction; default world up.'),width: bounded(0.001, 1e4),height: bounded(0.001, 1e4),color: color.optional(),@@ -222,14 +222,20 @@ const environment = z.strictObject({fogColor: color.optional(),fogDensity: bounded(0, 10).optional(),volumeFog: volumeFog.optional().describe('Directional scattering; needs HDR.'),- liquid: liquidOptics.optional().describe('For liquid or foam materials.'),+ liquid: liquidOptics.optional().describe('Optics for materials tagged liquid or foam.'),lines: lines.nullable().optional(),- objectReflections: z.boolean().optional(),- resolveCoplanar: z.union([z.literal('offset'), z.literal(false)]).optional(),- viewTransform: z.enum(VIEW_TRANSFORM_NAMES).optional(),- look: z.enum(LOOK_NAMES).nullable().optional(),- wind: z.strictObject({ strength: bounded(0, 4).optional(), direction: bounded(-360, 360).optional().describe('Degrees; 0 is +x, 90 is +z.') }).optional().describe('Foliage and grass sway; strength default 0.3.'),+ objectReflections: z.boolean().optional().describe("false turns off reflection probes on smooth metal parts."),+ resolveCoplanar: z.union([z.literal('offset'), z.literal(false)]).optional().describe("'offset' biases the smaller part of each coplanar pair at draw time; false clears."),+ viewTransform: z.enum(VIEW_TRANSFORM_NAMES).optional().describe('Display transform, for example agx to compare with Blender.'),+ look: z.enum(LOOK_NAMES).nullable().optional().describe('Named look preset; null clears.'),+ 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.'),});+// The full environment schema is published once, in scene_create. A JSON Schema $ref can not point from one tool's+// inputSchema into another's, so scene_apply and scene_create_asset publish a plain object that names it and still+// check every field against the same schema here, with the same error paths.+const environmentReference = z.record(z.string(), z.unknown())+ .describe('Same fields as recipe.environment in scene_create.')+ .pipe(environment);const effects = z.strictObject({exposure: bounded(0.01, 16).optional(),saturation: bounded(0, 2).optional(),@@ -587,7 +593,7 @@ const assetRecipe = z.strictObject({schemaVersion: z.literal(1),assetId: z.string().regex(/^[a-f0-9]{64}$/).describe('SHA-256 asset ID from scene_asset_catalog.'),camera: z.strictObject(cameraFields).optional(),- environment: environment.optional(),+ environment: environmentReference.optional(),effects: effects.optional(),shadow: shadow.optional(),root: z.strictObject({@@ -621,7 +627,7 @@ const otherOperations = [z.strictObject({ type: z.literal('set-particles'), particles: z.record(z.string(), z.unknown()).nullable() }),z.strictObject({ type: z.literal('set-bake'), bake: z.record(z.string(), z.unknown()).nullable() }),z.strictObject({ type: z.literal('set-post-passes'), postPasses: z.array(z.record(z.string(), z.unknown())).nullable() }),- z.strictObject({ type: z.literal('set-environment'), environment }),+ z.strictObject({ type: z.literal('set-environment'), environment: environmentReference }),z.strictObject({ type: z.literal('set-effects'), effects }),z.strictObject({ type: z.literal('set-shadow'), shadow }),z.strictObject({ type: z.literal('set-root'), translation: vector3.optional(), rotation: quaternion.optional(), scale: z.tuple([positive, positive, positive]).optional() }),diff --git a/tests/mcp-environment-schema.test.js b/tests/mcp-environment-schema.test.jsindex 579d4781..2cea1aa5 100644--- a/tests/mcp-environment-schema.test.js+++ b/tests/mcp-environment-schema.test.js@@ -36,20 +36,58 @@ function findSetEnvironmentSchema(node) {return null;}-async function mcpEnvironmentFields() {+async function withMcpClient(use) {const server = createAgentMcpServer({ async close() {} });const client = new Client({ name: '67js-environment-schema-test', version: '1' });const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();await server.connect(serverTransport);await client.connect(clientTransport);- const { tools } = await client.listTools();- await client.close();- await server.close();- const schema = findSetEnvironmentSchema(tools.find(tool => tool.name === 'scene_apply').inputSchema);- assert.ok(schema, 'scene_apply no longer lists a set-environment operation');- return Object.keys(schema.properties);+ try {+ return await use(client);+ } finally {+ await client.close();+ await server.close();+ }+}++async function listedTools() {+ return withMcpClient(async client => (await client.listTools()).tools);+}++function toolSchema(tools, name) {+ return tools.find(tool => tool.name === name).inputSchema;+}++// scene_create publishes the one full environment schema; the other tools name it.+async function mcpEnvironmentFields() {+ const environment = toolSchema(await listedTools(), 'scene_create').properties.recipe.properties.environment;+ assert.ok(environment?.properties, 'scene_create no longer publishes recipe.environment');+ return Object.keys(environment.properties);}+test('scene_apply and scene_create_asset point to the environment schema in scene_create instead of repeating it', async () => {+ const tools = await listedTools();+ const references = [+ findSetEnvironmentSchema(toolSchema(tools, 'scene_apply')),+ toolSchema(tools, 'scene_create_asset').properties.recipe.properties.environment,+ ];+ for (const reference of references) {+ assert.equal(reference.properties, undefined);+ assert.match(reference.description, /recipe.environment in scene_create/);+ }+});++test('the server still checks every environment field of scene_apply and scene_create_asset', async () => {+ await withMcpClient(async client => {+ const apply = await client.callTool({ name: 'scene_apply', arguments: { expectedRevision: 0, operations: [{ type: 'set-environment', environment: { skyTop: 'blue', bogus: 1 } }] } });+ const asset = await client.callTool({ name: 'scene_create_asset', arguments: { recipe: { format: '67js.asset', schemaVersion: 1, assetId: 'a'.repeat(64), environment: { world: 'yes' } } } });+ for (const result of [apply, asset]) assert.equal(result.isError, true);+ assert.match(apply.content[0].text, /bogus/);+ assert.match(apply.content[0].text, /skyTop/);+ assert.match(asset.content[0].text, /world/);+ });+});+test('the MCP environment schema lists exactly the fields the backend allows', async () => {const backend = (await backendEnvironmentFields()).sort();assert.deepEqual((await mcpEnvironmentFields()).sort(), backend);