Flint 3D Model Generation Server

FastAPI + MCP stack that turns text prompts into Blender scenes and exports USDZ files via export_model.py.

Overview

• Runs a FastAPI server (api_server.py) with /run, /run-high, /download, and /health endpoints.
• Uses MCP to drive Blender through the blender-mcp toolchain and exports via the bundled Python script.
• Keeps context usage in check with tool allowlists, step caps, and prompt truncation.
• Produces .blend and .usdz artifacts in exports/ for downstream consumption.

Highlights

• 🤖 Claude Sonnet 4.5 integration tuned for MCP workflows
• 🎨 Automated Blender pipeline that saves .blend files and exports USDZ
• 🔄 Context-safe MCP bridge (tool allowlists, token caps, step limits)

Prerequisites

• macOS with Blender available at /Applications/Blender.app/Contents/MacOS/Blender
• Python 3.10+
• uv toolchain (needed for uvx blender-mcp): brew install uv
• Valid Anthropic API key stored in .env (ANTHROPIC_API_KEY=...)
• Recommended: create and activate the project virtual environment (python -m venv .venv then source .venv/bin/activate)

Step-by-Step Setup

1. Install Python 3.10+ and Blender – Blender must be callable at /Applications/Blender.app/Contents/MacOS/Blender or you need to update BLENDER_PATH in api_server.py.
2. Install uv (MCP helper) – brew install uv so the uvx blender-mcp command in api_server.py works.
3. Create a virtual environment – python -m venv .venv && source .venv/bin/activate (recommended but optional).
4. Install dependencies – pip install -r requirements.txt.
5. Create .env in the project root with the secrets required by the scripts:

   cp config.env .env  # optional helper if you track defaults there

   Set at minimum:

   ANTHROPIC_API_KEY=sk-your-key
   BLENDER_PATH=/Applications/Blender.app/Contents/MacOS/Blender  # override if needed
   EXPORT_FOLDER=exports  # optional; defaults to project root
   

6. Start the server – python start_server.py (hot reload enabled).
7. Check health – curl http://localhost:8000/health should report healthy once Blender, the export folder, and the Claude API are accessible.

API Endpoints

Method	Path	Description
GET	/health	Reports Blender, Claude, and export-folder status
GET	/docs	FastAPI interactive docs
POST	/run	Standard-quality MCP generation (token-safe)
POST	/run-high	High-quality MCP generation (more steps/detail)
GET	/download/{filename}	Fetch the latest USDZ export

Example Requests

Standard profile (balanced, ≤5 tool calls):

curl -X POST http://localhost:8000/run \
     -H "Content-Type: application/json" \
     -d '{"prompt": "Create a sci-fi crate with glowing edges"}'

High-detail profile (≤8 tool calls, richer lighting/material cues):

curl -X POST http://localhost:8000/run-high \
     -H "Content-Type: application/json" \
     -d '{"prompt": "Build a stylized medieval watchtower with torches and banners"}'

Quality Profiles & Context Guards

Profile	Steps	LLM Tokens	Notes
standard	5	1024	Uses a minimal tool allowlist and aggressive prompt truncation for reliability
high	8	2048	Adds richer geometry/material hints and allows the set_texture tool

Both modes enforce:

• toolContextSize="small" to shrink tool schema payloads
• Explicit tool allowlists so unused MCP connectors never enter the prompt
• Constraint blocks injected into the LLM prompt (max tool calls, snippet size, mandatory save_file)
• Automatic .blend validation plus USDZ export via export_model.py

Switch to /run-high when you need more detail, then fall back to /run if you hit context limits.

Configuration Notes

• .env is required; load order ensures anything defined there is available to both FastAPI and the export script.
• Populate ANTHROPIC_API_KEY plus any overrides (BLENDER_PATH, EXPORT_FOLDER, etc.).
• config.env can store shared defaults, but sensitive keys must still land in .env before running.
• Exports are written to exports/scene.blend and exports/exported_model.usdz unless you override EXPORT_FOLDER.

Troubleshooting

Symptom	Fix
prompt is too long errors	Use /run, shorten the prompt, or temporarily reduce the MCP allowlist
Blender path errors	Confirm the BLENDER_PATH constant matches your install or update it
Empty/invalid exports	Check server logs for Blender stderr, ensure exports/ is writable
Claude 40x/429 responses	Wait and retry; the service already throttles tokens, but Anthropic quotas may still apply

Project Structure

Flint/
├── api_server.py      # FastAPI app + MCP orchestration
├── export_model.py    # Blender-side USDZ exporter
├── start_server.py    # Entrypoint with env bootstrap + uvicorn
├── requirements.txt   # Python dependencies
├── config.env         # Optional defaults you can copy into .env
├── package.json       # Node helpers (if any future tooling is added)
├── README.md          # This guide
└── exports/           # Generated blend/usdz assets