MCP server Reverse3D-tool

reverse3d

Modelado 3D e ingeniería inversa con tu agente de IA, en local

Fotos → modelo 3D medido · Plano o careta → pieza · Escaneo → CAD paramétrico · Render automático. Se instala pasándole la URL del repo a tu agente y funciona con Claude, Cursor, VS Code/Copilot, Gemini, Codex, OpenCode, Windsurf y cualquier cliente MCP. En GPU o en CPU.

Desarrollado por Voxel Enterprise

---

Tabla de contenidos

• ⚡ Instalación en 1 minuto
• 🗣️ Úsalo con tu agente
• 🚀 GPU o CPU
• 💰 Ahorro de tokens
• 🔌 Sin internet (modo offline)
• 🤖 Piloto automático
• 🛠️ Modo trabajo: tus modelos con manos
• 🧠 Reverse3D Core (motor exclusivo)
• Capacidades
• Herramientas externas opcionales
• Referencia de la CLI
• Configuración
• Integración avanzada
• Stack tecnológico
• Arquitectura
• Seguridad
• 🔏 Autenticidad y autoría
• Solución de problemas
• Estructura del repositorio
• Desarrollo
• Hoja de ruta
• Sobre Voxel Enterprise
• Licencia

---

⚡ Instalación en 1 minuto

No necesitas instalar nada antes: ni Python, ni Git, ni permisos de administrador. Solo conexión a internet y unos 4 GB libres.

Opción 1 — Pídeselo a tu agente (recomendado)

Copia y pega esta frase en tu agente de IA (Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Copilot, Windsurf…):

Instala reverse3d desde https://github.com/rellytechgame/Reverse3D-tool siguiendo su AGENTS.md. Tienes mi permiso para ejecutar el instalador; no me hagas preguntas.

Eso es todo. Tu agente te pedirá permiso una sola vez, para ejecutar el instalador; acéptalo, por ejemplo con "Sí" o "Permitir siempre". A partir de ahí no te preguntará nada más:

• instala Python, todos los módulos, Blender (renders fotorrealistas) y COLMAP (fotos → 3D);
• detecta tu tarjeta gráfica (GPU) y la usa si existe;
• conecta reverse3d con todos tus agentes de IA y deja sus herramientas aprobadas, para que no te pidan permiso en cada uso;
• comprueba que todo funciona.

Tarda entre 10 y 20 minutos según tu conexión. Al terminar, cierra y vuelve a abrir tu agente.

¿Quieres algo concreto? Dilo en la misma frase:

Instala reverse3d desde https://github.com/rellytechgame/Reverse3D-tool siguiendo su AGENTS.md, en modo ligero y usando solo CPU. Tienes mi permiso; no me hagas preguntas.

Opción 2 — Un comando en la terminal

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/rellytechgame/Reverse3D-tool/main/scripts/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/rellytechgame/Reverse3D-tool/main/scripts/install.ps1 | iex

Con opciones:

# Linux/macOS: GPU + calidad máxima
curl -fsSL https://raw.githubusercontent.com/rellytechgame/Reverse3D-tool/main/scripts/install.sh | bash -s -- --device gpu --profile quality

# Windows: GPU + calidad máxima
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/rellytechgame/Reverse3D-tool/main/scripts/install.ps1))) -Device gpu -Performance quality

¿Prefieres revisar el script antes de ejecutarlo? Descárgalo, léelo y ejecútalo: curl -fsSLO …/install.sh && less install.sh && bash install.sh.

Qué hace el instalador

Nunca hace preguntas y no necesita administrador. Si se interrumpe, por ejemplo porque el agente lo corta por tiempo, basta con volver a ejecutarlo: continúa donde se quedó.

1. Python: descarga uv y con él un Python 3.12 privado en ~/.reverse3d. No toca el Python de tu sistema; si uv no está disponible, usa un Python ≥ 3.10 que ya tengas.

2. Entorno aislado en ~/.reverse3d/venv.

3. reverse3d con todos los módulos:

   • mallado (Open3D);
   • render (PyVista);
   • IA de profundidad (PyTorch): con CUDA si hay GPU NVIDIA y, si no, la versión CPU, mucho más ligera.

   Si un módulo opcional falla, la instalación sigue y lo indica al final.

4. Blender 5.2 y COLMAP 4.2 portables en ~/.reverse3d/tools. Las versiones están fijadas y cada descarga se verifica con su huella SHA-256 oficial.

   • En Linux no existe un COLMAP portable: se instala con apt o brew solo si no hace falta contraseña. Si no se puede, el instalador lo indica y todo lo demás funciona.

5. Deja el comando reverse3d disponible: ~/.local/bin en Linux/macOS, PATH de usuario en Windows.

6. Ejecuta reverse3d setup, que registra el servidor MCP en todos los agentes que encuentre:

Agente	Dónde se registra
Claude Code	claude mcp add --scope user + Skill en ~/.claude/skills/reverse3d
Claude Desktop	claude_desktop_config.json
Cursor	~/.cursor/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
VS Code (Copilot)	<user>/Code/User/mcp.json
Gemini CLI	~/.gemini/settings.json
OpenCode	~/.config/opencode/opencode.json
Codex CLI	~/.codex/config.toml

Cada archivo modificado se respalda antes (*.reverse3d-backup-<fecha>). Solo se toca la entrada reverse3d y, si un archivo no se puede leer con seguridad (por ejemplo, JSON con comentarios), no se modifica y se muestra el bloque para pegarlo a mano.

Herramientas aprobadas de antemano, para que el agente no te pregunte en cada uso:

Agente	Aprobación automática
Claude Code	mcp__reverse3d en permissions.allow de ~/.claude/settings.json
Gemini CLI	"trust": true en la entrada reverse3d
Resto	No tienen ese ajuste: la primera vez elige "Permitir siempre"

Solo se aprueban las herramientas de reverse3d, que trabajan únicamente dentro del workspace (ver Seguridad). Para desactivarlo usa --no-auto-approve.

1. Verifica todo con reverse3d doctor y guarda el resultado en ~/.reverse3d/install-status.json. El registro completo queda en ~/.reverse3d/install.log. Reinicia tu agente y listo.

Opciones del instalador

bash (install.sh)	PowerShell (install.ps1)	Efecto
(sin opciones)	(sin opciones)	Todo: núcleo, MCP, render, mallado, IA local (con CUDA si hay NVIDIA), Blender y COLMAP
--lite	-Lite	Todo, con la IA local en la CPU (PyTorch CPU, ~250 MB en vez de ~2.5 GB)
--minimal	-Minimal	Núcleo + MCP + IA local, sin herramientas externas
--no-tools	-NoTools	No instalar Blender ni COLMAP
(en todos los modos)	(en todos los modos)	La IA local se instala y se descarga siempre (clasificador, segmentación, profundidad y puntos con IA, unos 800 MB) para que todo funcione sin internet
--no-auto-approve	-NoAutoApprove	Que los agentes pregunten antes de cada herramienta
--with recon,depth	-With recon,depth	Extras a elección
--device auto|cpu|gpu	-Device …	Dispositivo por defecto
--profile fast|balanced|quality	-Performance …	Perfil de rendimiento
--toolset lean	-Toolset lean	Expone 5 herramientas en lugar de 14 (menos tokens)
--agents auto|all|claude-code,cursor	-Agents …	Qué agentes registrar
--workspace DIR	-Workspace DIR	Carpeta que pueden usar los agentes (por defecto ~/reverse3d-workspace)
--ref v0.2.0	-Ref v0.2.0	Instalar una versión o etiqueta concreta
--source .	-Source .	Instalar desde un clon local
--no-setup	-NoSetup	No registrar agentes
--uninstall	-Uninstall	Desinstalar (conserva el workspace y la configuración)

Opción 3 — Sin instalar nada (con uv)

Si tienes uv, cualquier cliente MCP puede ejecutar reverse3d directamente desde GitHub:

{
  "mcpServers": {
    "reverse3d": {
      "command": "uvx",
      "args": ["--from", "reverse3d[mcp,render] @ git+https://github.com/rellytechgame/Reverse3D-tool",
               "reverse3d", "agent", "mcp"],
      "env": { "REVERSE3D_WORKSPACE": "/ruta/a/mi-workspace" }
    }
  }
}

Opción 4 — Manual (desarrolladores)

git clone https://github.com/rellytechgame/Reverse3D-tool.git && cd Reverse3D-tool
python -m venv .venv && source .venv/bin/activate      # Windows: .venv\Scripts\Activate.ps1
pip install -e ".[mcp,render]"                          # o ".[all]" / ".[dev]"
reverse3d setup                                         # registra en tus agentes
reverse3d doctor

---

🗣️ Úsalo con tu agente

Coloca tus archivos en el workspace (~/reverse3d-workspace) y habla normal:

"Convierte las fotos de taza/ en un modelo 3D y dime sus medidas." "Este plano soporte.png mide 120 mm de ancho; sácame la pieza con 4 mm de espesor." "Repara escaneo.stl, alinéalo y genérame el código OpenSCAD." "Hazme un render de pieza.glb en azul metálico." "Usa la GPU de ahora en adelante." · "Cambia a modo rápido."

Comandos / (prompts MCP)

En los clientes que muestran prompts MCP como comandos (Claude Code: /mcp__reverse3d__<nombre>; Claude Desktop: menú + → reverse3d; también VS Code y otros):

Comando	Qué hace
procesar <entrada>	Lo que sea → detecta qué es y lo procesa solo
fotos-a-3d <carpeta>	Fotos → modelo 3D medido + render
plano-a-pieza <imagen> [espesor] [mm_por_pixel]	Plano o careta → pieza extruida
escaneo-a-cad <malla>	Malla → limpieza + cotas + primitivas + OpenSCAD/CadQuery
foto-a-relieve <imagen>	Una foto → relieve 2.5D con IA
medir <malla>	Cotas, volumen y render
usar-gpu · usar-cpu	Cambiar el dispositivo
rendimiento <fast|balanced|quality>	Cambiar el perfil
estado	Qué está instalado, GPU detectada y configuración

Recetas: un flujo completo en una sola llamada

Receta	Entrada	Resultado en output_dir/
auto	Lo que sea	Detecta el tipo, elige la receta y reintenta si sirve; añade RESUMEN.md
photos_to_model	Carpeta de fotos	model.stl, render.png, report.json, nube de puntos
plan_to_part	Plano, careta o silueta	model.stl, render.png, contornos SVG
scan_to_cad	STL/OBJ/PLY/GLB	model.stl, cad.scad, cad.py (CadQuery), render.png
photo_to_relief	Una foto	model.stl (relieve 2.5D), render.png
mesh_report	Una malla	Cotas + render.png

Desde la terminal: reverse3d run plan_to_part plano.png salida/ --thickness 4 --units-per-pixel 0.5.

---

🚀 GPU o CPU

reverse3d detecta tu GPU automáticamente: NVIDIA CUDA mediante nvidia-smi y Apple Silicon (MPS). Si pides GPU y no está disponible, pasa a CPU solo, sin fallar: por ejemplo, con un COLMAP compilado sin CUDA.

Cómo cambiarlo	GPU	CPU	Automático
Hablando con tu agente	"usa la GPU"	"usa la CPU"	"modo automático"
Comando /	usar-gpu	usar-cpu	—
Herramienta	reverse3d_configure {"device":"gpu"}	{"device":"cpu"}	{"device":"auto"}
CLI persistente	reverse3d config set device gpu	… device cpu	… device auto
CLI solo esta vez	reverse3d --device gpu run …	--device cpu	—
Variable de entorno	REVERSE3D_DEVICE=gpu	=cpu	=auto

Los cambios desde el agente se aplican al instante, sin reiniciar: el servidor relee la configuración en cada llamada.

Componente	Usa la GPU para
COLMAP (build CUDA)	Extracción y matching SIFT + reconstrucción densa MVS
Blender Cycles	Render con OptiX, CUDA, HIP, Metal u oneAPI (el que haya disponible)
Depth Anything (PyTorch)	Inferencia en CUDA o Apple MPS

Perfiles de rendimiento

Perfil	Fotogrametría	Muestras de render	Resolución de render	Detalle de relieve	Muestras para primitivas
fast	low	16	960×720	1/4	8 000
balanced (defecto)	medium	64	1600×1200	1/2	20 000
quality	high	256	2400×1800	completo	50 000

Cambia el perfil con "modo rápido", rendimiento quality, reverse3d config set profile fast o --profile. Los argumentos explícitos de una herramienta siempre tienen prioridad sobre el perfil. Hilos de CPU: reverse3d config set threads 8.

---

💰 Ahorro de tokens

reverse3d está diseñado para gastar poco contexto del modelo:

Técnica	Cómo	Ahorro medido*
Recetas	1 llamada en lugar de 5–6; el detalle completo va a report.json en disco	−82 % de tokens de resultados y 5 → 1 idas y vueltas
Salida compacta (por defecto)	Rutas relativas, números redondeados, sin nulos, listas recortadas, solo lo relevante	−44 % por llamada
Toolset lean	Expone 5 herramientas (las recetas cubren el resto)	Esquemas: 4 147 → 1 466 tokens (−65 %)
Skill de Claude Code	Guía que el agente carga solo cuando hace falta	0 tokens fijos
Errores con hint	El agente se corrige a la primera, sin bucles	—

*Flujo plano → pieza con 5 pasos medido en la v0.2.0, a ~4 caracteres por token. Cada ida y vuelta evitada ahorra además reenviar todo el historial de la conversación.

reverse3d config set toolset lean       # menos herramientas = menos tokens (reinicia el agente)
reverse3d config set verbosity full     # si alguna vez necesitas el detalle completo

---

🔌 Sin internet (modo offline)

reverse3d funciona sin conexión. Todo el cálculo es local (OpenCV, COLMAP, Open3D, trimesh, Blender). Lo único que se descarga son los modelos de IA local (sujeto, recorte, profundidad y los puntos ALIKED + LightGlue), y el instalador los deja descargados.

• Cambio automático: si el equipo no detecta internet, reverse3d pasa solo a modo offline. No tienes que hacer nada.
• Comprobar: reverse3d offline status dice si hay conexión y qué funciona sin ella. reverse3d doctor lo incluye en su informe.
• Preparar a mano: reverse3d offline prepare descarga los modelos (solo safetensors, en una revisión fijada y revisada) en ~/.reverse3d/models. Usa --all para incluir también los modelos grandes CC-BY-NC.
• Forzarlo: reverse3d config set offline on, para no usar nunca la red. Con off reverse3d asume que hay conexión y no la comprueba; el valor por defecto es auto.

Sin internet funciona	Necesita
Medir, reparar, primitivas, CAD (OpenSCAD/CadQuery), plano → pieza	nada
Fotogrametría (fotos → 3D) y render	COLMAP / Blender instalados (el instalador lo hace)
Foto → relieve con IA	el modelo descargado una vez (el instalador lo hace)

Tu agente de IA (Claude, Cursor, Copilot…) sí necesita internet. Sin agente, usa el piloto automático o la CLI.

🤖 Piloto automático

No hace falta elegir receta ni tener un agente. reverse3d detecta qué le das y lo procesa:

reverse3d auto bandeja/taza          # carpeta de fotos → modelo 3D medido
reverse3d auto plano.png             # plano o silueta → pieza extruida
reverse3d auto pieza.stl             # malla → reparación + cotas + CAD

O déjalo trabajando solo con la carpeta vigilada:

reverse3d watch

1. Suelta en ~/reverse3d-workspace/bandeja una carpeta de fotos, un plano, una foto o un STL/OBJ/PLY/GLB.
2. Cuando termina de copiarse, se procesa solo. El resultado aparece en resultados/<nombre>/, con un RESUMEN.md que explica qué detectó, las medidas, los archivos y el siguiente paso.
3. El original se mueve a bandeja/_procesado/. Si algo falla, va a bandeja/_revisar/ con un LEEME.txt que dice qué corregir.

Qué decide solo:

Detecta	Hace	Si falla, reintenta con
Carpeta con 3 o más fotos	photos_to_model	calidad high
Imagen de alto contraste o con fondo transparente	plan_to_part	otros métodos de máscara (adaptativo, bordes)
Foto normal	photo_to_relief	—
Malla (STL/OBJ/GLB/PLY con caras)	scan_to_cad	reparación fuerte si no queda cerrada
Nube de puntos (XYZ/PCD/PLY sin caras)	mallado Poisson + scan_to_cad	—

Si las fotos están borrosas o falta una herramienta, no reintenta en vano: te explica qué cambiar. Funciona sin internet y sin modelo de IA, porque son reglas, no adivinanzas.

---

💬 Asistente (chat de Studio)

Pide los retoques con tus palabras, en español o en inglés. Optiverse y el Core los ejecutan:

reverse3d assistant ask "descarta las fotos movidas y prepara el resto" --work trabajo/ --photos fotos/
reverse3d assistant ask "rellena los huecos y que mida 24 cm" --work trabajo/ --job resultados/taza/
reverse3d assistant serve      # líneas JSON por stdin/stdout (lo usa reverse3d Studio)

Área	Qué hace
Fotos	Revisar (movidas, oscuras, quemadas, objeto cortado o pequeño), descartar o recuperar, mejorar la luz, ver el recorte de Optiverse, preparar el conjunto
Modelo 3D	Rellenar huecos, suavizar, quitar restos, simplificar, tamaño real, deshacer
Captura	Consejos y qué fotos repetir

• Los originales nunca se tocan: las fotos preparadas van a <work>/fotos-preparadas y cada cambio del modelo es una versión nueva en <work>/modelos.
• Entiende frases libres con una IA de lenguaje local: paraphrase-multilingual-MiniLM-L12-v2 (Apache-2.0, 471 MB). Elige entre acciones fijas y, si no está segura, pregunta.
• Conversa como una persona: propone el siguiente paso, actúa si dices «sí», entiende «más» y «menos», y cuenta qué hizo.
• Escucha: las peticiones habladas se transcriben en tu equipo con Whisper base (Apache-2.0, 290 MB). En Studio hay un botón de micrófono, y la respuesta se lee en voz alta con las voces del sistema.

🛠️ Modo trabajo: tus modelos con manos (preguntando antes)

Un modelo trabaja en una carpeta de tu equipo, como Claude Code u OpenCode: lee, busca, edita archivos y ejecuta comandos. Siempre bajo tus permisos.

reverse3d work run "la prueba falla: arréglala y ejecuta las pruebas" -C mi-proyecto/
reverse3d work run "..." -C mi-proyecto/ -p edits    # edita libre, pregunta los comandos
reverse3d work run "..." -C mi-proyecto/ -p free     # todo libre (lo delicado se pregunta)
reverse3d work undo -C mi-proyecto/ -n 3             # deshace los 3 últimos cambios
reverse3d work permissions -C mi-proyecto/ --reset   # olvida los «siempre en esta carpeta»
reverse3d work run "..." --json                      # líneas JSON: Studio o una página en la nube

Tú eliges	Qué pasa
ask (por defecto)	Pregunta antes de cada cambio y cada comando, y te muestra exactamente el cambio (diff) o el comando
edits	Cambia archivos de la carpeta sin preguntar; los comandos se preguntan
free	Cambia y ejecuta sin preguntar
A cada pregunta	sí · sin preguntar en esta sesión · siempre en esta carpeta · no

Lo que nunca está a su alcance, elijas lo que elijas:

• Fuera de la carpeta: salir de ella, también por enlaces. Puedes añadir más carpetas con --add-folder.
• Secretos: claves, .env, credenciales SSH o de la nube, ~/.voxel-keys.
• Comandos destructivos: formatear, rm -rf /, apagar el equipo… se rechazan.
• Comandos delicados: borrar en recursivo, git push, publicar paquetes, instalar programas, descargar y ejecutar… siempre se preguntan, también en free.

Todo cambio se puede deshacer: lo anterior se guarda en <carpeta>/.reverse3d/undo/.

Modelo: cualquier GGUF con llamadas a herramientas, en ~/.reverse3d/models/llm/ o con --model. También un paquete cifrado de Voxel Enterprise (--model arjhit-code-1 o --model archivo.r3dm): se descifra con tu licencia solo mientras carga. Probado de verdad:

• Qwen2.5-Coder-7B-Instruct (Apache-2.0, 4,7 GB) encontró un error, lo arregló y comprobó las pruebas en 83 s, solo con la CPU.
• El de 1.5B usa bien las herramientas, pero no razona lo suficiente para arreglar código.

Los modelos de código de Voxel Enterprise se entrenarán sobre esta base.

🧠 Reverse3D Core (motor exclusivo)

Reverse3D Core es el motor de reconstrucción propio de Voxel Enterprise. Es propietario (no forma parte de este repositorio de código abierto) y viene incluido en reverse3d Studio, que lo instala solo.

• Cuando está instalado, reverse3d lo usa automáticamente para fusionar las siluetas de los objetos. Aprende qué fotos son fiables, así que un brillo, un mal recorte o una foto mal ubicada ya no borran el objeto, y cada foto extra suma precisión.
• Sin él, reverse3d funciona igual con su método abierto.
• Comprobarlo: reverse3d doctor muestra core: {available: true, version: …}. El informe de cada trabajo indica qué motor se usó (details.silhouette.engine).

Prueba interna (objeto de geometría conocida)	Método abierto	Reverse3D Core
Recortes perfectos	0,943	0,941
15 % de recortes defectuosos	0,000 (pierde el objeto)	0,921
Concavidad invisible a las siluetas (error en la ranura)	0,154	0,091 (refinamiento por fotos, Core 0.3)
Mapa de confianza y consejos de captura	—	✅ Core 0.4 (model_quality.glb)

(Coincidencia volumétrica, IoU: 1 = idéntico.)

---