# 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:
     ```bash
     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):

```bash
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):

```bash
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
```