# Berrio Blender MCP

Servidor MCP y complemento de Blender para preparar personajes de videojuegos de forma segura, repetible y verificable.

El proyecto se concentra en operaciones de alto nivel. No expone una herramienta para ejecutar Python arbitrario dentro de Blender.

## Estado

Versión `0.3.0` (alpha). La API del puente usa el contrato versionado `1.0`.

## Arquitectura

```text
Cliente MCP (Codex, inspector, IDE)
                │ stdio / Streamable HTTP local
                ▼
     Servidor Python FastMCP
       ├─ política de rutas
       ├─ dry-run por defecto
       └─ herramientas estructuradas
                │ JSONL + token, 127.0.0.1:9876
                ▼
       Complemento de Blender
       ├─ cola hacia el hilo principal
       ├─ operaciones permitidas
       └─ checkpoints de archivos .blend
```

## Herramientas MCP

| Herramienta | Función |
|---|---|
| `blender_status` | Comprueba conexión, versiones y capacidades |
| `blender_scene_summary` | Resume escena, armaduras, mallas y acciones |
| `blender_list_objects` | Lista objetos sin modificar la escena |
| `blender_validate_character` | Valida rig, clips, límites, materiales y dimensiones |
| `blender_create_humanoid_character` | Genera un Forjador del Éter original, riggeado y animado, compacto o semirrealista |
| `blender_import_asset` | Importa FBX, GLB, GLTF u OBJ |
| `blender_normalize_character` | Normaliza altura, centro y contacto con el suelo |
| `blender_rename_actions` | Convierte nombres de clips a un contrato estable |
| `blender_export_character_glb` | Exporta armadura, mallas y animaciones a GLB |

Las operaciones que cambian archivos o escenas usan `dry_run=true` de manera predeterminada.

## Requisitos

- Python 3.11 o posterior.
- `uv` para un entorno reproducible.
- Blender 4.2 o posterior para el complemento.

## Preparar el servidor

```powershell
uv sync --extra dev
uv run pytest
uv run python scripts/build_addon.py
```

El último comando genera `dist/blender_mcp_bridge-0.3.0.zip`.

## Arquetipos originales

| Arquetipo | Uso recomendado | Complejidad aproximada |
|---|---|---|
| `ether-forger` | Fallback compacto y prototipos | 18 huesos, 12.396 triángulos, 8 materiales |
| `ether-forger-v2` | Héroe semirrealista para el juego | 39 huesos, 40.522 triángulos evaluados, 12 materiales |

V2 añade proporciones humanas mejoradas, dedos, rasgos faciales, cabello por mechones, ropa dividida,
armadura laminada, huesos de torsión y abrigo, y microdetalle procedural en los materiales. Sigue siendo
un activo semirrealista optimizado para juego; no sustituye un flujo de escultura y texturizado humano
fotorrealista.

Para instalar una copia portátil verificada de Blender 4.5 LTS dentro de `.tools`:

```powershell
powershell -ExecutionPolicy Bypass -File scripts\install_blender_portable.ps1
```

El script descarga desde `download.blender.org`, compara la suma SHA-256 oficial y solo después extrae el programa. `.tools` está excluido de Git.

## Instalar el complemento

1. En Blender, abre **Edit → Preferences → Add-ons**.
2. Selecciona **Install from Disk** e instala el ZIP generado.
3. Activa **Berrio Blender MCP Bridge**.
4. Opcionalmente configura un token en las preferencias.
5. Abre **3D View → Sidebar → Blender MCP** y pulsa **Start MCP Bridge**.

El puente solo acepta conexiones de loopback. Si se configura un token, el servidor MCP debe recibir el mismo valor en `BLENDER_MCP_TOKEN`.

## Ejecutar mediante stdio

```powershell
uv run blender-mcp
```

Configuración MCP genérica:

```json
{
  "mcpServers": {
    "blender-character-pipeline": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\ruta\\a\\blender-MCP",
        "run",
        "blender-mcp"
      ],
      "env": {
        "BLENDER_MCP_WORKSPACE_ROOTS": "C:\\ruta\\a\\Repos",
        "BLENDER_MCP_TOKEN": "el-mismo-token-de-blender"
      }
    }
  }
}
```

También puede ejecutarse mediante Streamable HTTP restringido al equipo local:

```powershell
uv run blender-mcp --transport streamable-http --host 127.0.0.1 --port 8000
```

## Skill de personajes para Codex

La skill versionada en `skills/blender-character-pipeline` enseña a Codex a diagnosticar por capas, ejecutar cambios primero como simulación y distinguir problemas del activo Blender de fallos de animación, navegación o control dentro del motor.

Instálala en el perfil actual de Codex:

```powershell
powershell -ExecutionPolicy Bypass -File scripts\install_codex_skill.ps1
```

Registra después este servidor MCP con el mismo nombre declarado por la skill:

```powershell
codex mcp add blender-character-pipeline `
  --env BLENDER_MCP_WORKSPACE_ROOTS=C:\ruta\a\Repos `
  -- uv --directory C:\ruta\a\blender-MCP run blender-mcp
```

Reinicia Codex después de instalarla o actualizarla. Invócala explícitamente con `$blender-character-pipeline`, aunque también puede activarse al trabajar con personajes `.blend`, FBX, GLB, GLTF u OBJ.

## Seguridad

- Solo se permite `127.0.0.1`, `localhost` o `::1`.
- No existe una operación de código arbitrario.
- Las rutas se restringen con `BLENDER_MCP_WORKSPACE_ROOTS`.
- Las mutaciones comienzan como simulaciones.
- Importar, normalizar y renombrar pueden crear checkpoints del `.blend` guardado.
- Los mensajes tienen límites de tamaño y tiempo.

Un proceso local que comparta la cuenta del sistema sigue teniendo acceso a los mismos archivos. Usa un token cuando convivan procesos que no sean de confianza.

## Flujo recomendado para personajes

1. Consultar estado y resumen de escena.
2. Simular la generación `ether-forger`, `ether-forger-v2` o la importación y luego ejecutarla explícitamente.
3. Validar armadura, mallas, presupuesto y clips.
4. Simular y ejecutar la normalización.
5. Renombrar clips a `Idle`, `Walk`, `Run`, `Attack`, `Dodge`, `Hit` y `Death`.
6. Validar otra vez.
7. Simular y ejecutar la exportación GLB.
8. Conservar el archivo fuente y la licencia del activo.

## Desarrollo

```powershell
uv run ruff check .
uv run pytest --cov=blender_mcp --cov-report=term-missing
uv run python scripts/smoke_mcp.py
```

La prueba de humo inicia el servidor por `stdio`, negocia una sesión MCP real, enumera las herramientas y comprueba `blender_status`. Las pruebas del puente usan un Blender simulado; las operaciones `bpy` deben comprobarse adicionalmente dentro de Blender.

Con la copia portátil, la integración real se comprueba en modo de fábrica y sin interfaz:

```powershell
& '.\.tools\blender-4.5.10-windows-x64\blender.exe' `
  --background --factory-startup --python scripts\blender_integration_test.py
```

El contrato JSONL entre el servidor y el complemento está documentado en [docs/BRIDGE_PROTOCOL.md](docs/BRIDGE_PROTOCOL.md).

## Licencia

MIT. Las licencias de modelos, texturas y animaciones procesados por este servidor permanecen bajo sus términos originales.