feat(mcp): natural-language measurements for tool inputs via @pascal-app/lingo

Measurement/angle parameters on the scene tools now accept a bare number OR a natural-language string ("6 in", "180cm", "45°", "1.57rad"), canonicalized to the unit the handler already expects (meters for length, radians/degrees for angles) with min/max bounds and model-readable errors. Makes LLM tool calls safer — "6 in" no longer has to be pre-converted to 0.1524, and a bad value is rejected with a message the model can self-correct from. A shared `measurement(kind, unit)` zod field wraps lingo's parseQuantity as a `number | string` union+transform; numbers pass through unchanged (backward compatible), so no handler changes were needed. Covers create_wall, cut_opening, place_item, create_level, create_story_shell, create_roof, create_stair_between_levels, create_room, add_door, add_window, photo_to_scene. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-08 12:51:08 +02:00
parent a5963560b1
commit f66dcd438b
11 changed files with 264 additions and 35 deletions
@@ -0,0 +1,62 @@
+import { describe, expect, test } from 'bun:test'
+import { z } from 'zod'
+import { measurement } from './measurement'
+
+describe('measurement()', () => {
+  test('parses natural-language length to meters', () => {
+    const m = measurement('length', 'm', { min: 0 })
+    expect(m.parse('6 in')).toBeCloseTo(0.1524, 6)
+    expect(m.parse('180cm')).toBeCloseTo(1.8, 6)
+    expect(m.parse('1m80')).toBeCloseTo(1.8, 6)
+    expect(m.parse(`5'11"`)).toBeCloseTo(1.8034, 4)
+    expect(m.parse('2 ft 3 in')).toBeCloseTo(0.6858, 6)
+  })
+
+  test('passes numbers through unchanged (backward compatible)', () => {
+    const m = measurement('length', 'm', { min: 0 })
+    expect(m.parse(0.15)).toBe(0.15)
+    expect(m.parse(3)).toBe(3)
+  })
+
+  test('reads a bare numeric string as the field unit', () => {
+    expect(measurement('length', 'm').parse('6')).toBe(6)
+    expect(measurement('angle', 'deg').parse('45')).toBe(45)
+  })
+
+  test('canonicalizes angles to the field unit', () => {
+    expect(measurement('angle', 'deg').parse('45°')).toBe(45)
+    expect(measurement('angle', 'deg').parse('1.57rad')).toBeCloseTo(89.954, 3)
+    expect(measurement('angle', 'rad').parse('90deg')).toBeCloseTo(Math.PI / 2, 6)
+    expect(measurement('angle', 'rad').parse('0.25 turn')).toBeCloseTo(Math.PI / 2, 6)
+  })
+
+  test('enforces min/max bounds in the field unit', () => {
+    const m = measurement('length', 'm', { min: 0, max: 3 })
+    expect(m.safeParse('-1').success).toBe(false)
+    expect(m.safeParse('900ft').success).toBe(false)
+    expect(m.safeParse('2m').success).toBe(true)
+    const tooBig = m.safeParse('900ft')
+    expect(tooBig.success).toBe(false)
+    if (!tooBig.success) expect(tooBig.error.issues[0]?.message).toContain('at most 3 m')
+  })
+
+  test('rejects unparseable input with a model-readable message', () => {
+    const r = measurement('length', 'm').safeParse('banana')
+    expect(r.success).toBe(false)
+    if (!r.success) expect(r.error.issues[0]?.message.toLowerCase()).toContain('number')
+  })
+
+  test('emits a number|string JSON schema advertising natural language', () => {
+    const schema = z.toJSONSchema(
+      measurement('length', 'm', { min: 0, description: 'Wall thickness.' }),
+      {
+        io: 'input',
+      },
+    )
+    const json = JSON.stringify(schema)
+    expect(json).toContain('anyOf')
+    expect(json).toContain('number')
+    expect(json).toContain('string')
+    expect((schema as { description?: string }).description).toContain('natural-language')
+  })
+})