Use the composite file physical-properties endpoint for CAD analysis

[JordanNoone]

Problem

calculate_cad_physical_properties currently makes separate Zoo API requests for volume, mass, surface area, center of mass, and CAD-to-STL conversion for local bounds. The same source can therefore be uploaded, imported, and tessellated up to five times for one MCP tool call. When STEP analysis is asynchronous, this can create multiple long-running worker jobs for the same customer request.

KittyCAD/api#4491 adds a composite POST /file/physical-properties operation that imports and tessellates once, computes the selected measurements, optionally renders from the same intermediate representation, and returns per-output status plus authenticated render artifacts.

Expected behavior

• Submit one composite physical-properties request for the complete MCP CAD-analysis tool call.
• Poll the returned operation ID through the bounded asynchronous resolver from Poll asynchronous file analysis operations #253.
• Do not resubmit or launch one job per property while polling.
• Request volume, mass, surface area, center of mass, and bounding box with the caller units.
• Add an optional render argument. When true, request isometric, front, right, and top PNGs from the same analysis operation.
• Download completed artifacts through the generated authenticated SDK endpoint and return each image exactly once in the same MCP result, labeled by view.
• Preserve privacy-safe per-property, render-stage, render-delivery, and terminal worker errors.
• A render or image-download failure must not erase completed measurements or successfully downloaded views.
• Keep the existing narrow property tools unchanged unless they are explicitly migrated later.

Rollout dependency

The unified endpoint, its render-download endpoint, and the FilePhysicalProperties async result variant must be deployed and available in a released generated Python SDK before the typed MCP integration can replace the legacy calls. Coordinate deployment so the API and SDK land before the MCP change; do not merge a client that calls unavailable generated methods.

Acceptance criteria

• One source upload and one composite analysis request per calculate_cad_physical_properties call.
• uploaded -> in_progress -> completed returns all five requested outputs.
• With render=false, no render artifacts are requested or downloaded.
• With render=true, the result includes render status and emits isometric, front, right, and top images once each when available.
• A failed individual property is reported without erasing completed outputs.
• A render-stage or artifact-download failure is reported without erasing measurements or other images.
• A terminal worker failure and a bounded poll timeout remain distinguishable.
• Tests prove the legacy five-request sequence is no longer used.

Related

• KittyCAD/api#4491
• Poll asynchronous file-analysis results instead of treating uploaded responses as failures #252
• Poll asynchronous file analysis operations #253