# Grok2Blender

Natural language control system for Blender 4.2+ with vision feedback and Grok Resolve Studio (GRS) handoff.

**Repository:** https://github.com/VisionaryPOV/Grok2Blender

## Quick Start (Mac)

```bash
cd /Users/nesta/Grok2Blender
./scripts/install.sh
```

1. **Blender** → Preferences → Add-ons → Install `dist/grok2blender.zip` → Enable
2. View3D sidebar → **Grok2Blender** → **Start Server** (port 9876)
3. Register MCP: `./scripts/register-mcp.sh`
4. Verify: `grok mcp doctor grok2blender`

## First Test

In Grok Build:

> Create a dramatic three-point lighting setup on a product cube and show me the viewport.

## Architecture

```
Grok Build → FastMCP (stdio) → TCP JSON (:9876) → Blender Addon (bpy)
```

See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for details.

## Documentation

- [USAGE.md](docs/USAGE.md) — 30+ prompt examples
- [SAFETY.md](docs/SAFETY.md) — Safe mode, undo, recovery
- [GRS_INTEGRATION.md](docs/GRS_INTEGRATION.md) — Resolve handoff
- [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) — Common issues

## GRS Handoff

Exports to `~/Movies/Grok2Blender/<project>/` with full GRS payload.

```bash
# In Grok: "Prepare GRS handoff for shot Hero_Previz_001"
# Then in Resolve: Grok Resolve Studio → Import Campaign Folder
```

## Development

```bash
uv sync --dev
uv run pytest -v
./scripts/smoke_test.sh
```

## Requirements

- macOS (v1)
- Blender 4.2+ with GUI (vision requires viewport)
- Python 3.11+
- [uv](https://docs.astral.sh/uv/)