Automation

CLI and MCP for agents

Run reconstruction and codegen from the terminal or an MCP-capable agent.

The phototo3d package

The phototo3d package exposes the same reconstruction pipeline outside Studio. Run it with npx — no global install needed. It has three commands: reconstruct, codegen and mcp.

Two environment variables control it. SCULPT_API_KEY authenticates the metered gateway and is required for reconstruct. SCULPT_API_URL optionally overrides the gateway base URL; leave it unset to use the default.

export SCULPT_API_KEY=sk_sculpt_...
phototo3d --help

reconstruct and codegen

reconstruct takes one image (.png, .jpg, .jpeg or .webp), sends it through the gateway and prints the generated Three.js factory. It needs SCULPT_API_KEY and spends one credit per successful run; a failed reconstruct is never charged. Add -o <path> to write to a file, or --json to emit { spec, usage } instead of code.

codegen is local and free: give it a sculpt spec JSON file and it emits the factory with no network call and no key. It is the offline half of reconstruct — useful for regenerating code after you hand-edit a spec.

# Metered: image -> factory (1 credit)
npx phototo3d reconstruct ref.png -o model.ts

# Free: local spec -> factory
npx phototo3d codegen spec.json -o model.ts

MCP server for agents

phototo3d mcp starts an MCP server over stdio so an agent can reconstruct and generate code as tool calls. It registers two tools: sculpt_reconstruct, which turns one base64 image into a spec plus factory code (requires SCULPT_API_KEY, consumes one credit), and sculpt_spec_to_code, which converts a spec to code locally and free.

Point your MCP client at the command below. The same SCULPT_API_KEY and optional SCULPT_API_URL environment variables apply.

{
  "mcpServers": {
    "phototo3d": {
      "command": "npx",
      "args": ["phototo3d", "mcp"],
      "env": { "SCULPT_API_KEY": "sk_sculpt_..." }
    }
  }
}