Instant Meshes MCP

Un servidor de procesamiento de modelos 3D para retopología automática, simplificación y análisis de calidad de modelos OBJ/GLB.

GitHub
2
Prueba este MCPPatrocinado

Documentación

instant-meshes-mcp

Este proyecto proporciona servicios de procesamiento de modelos 3D a través del protocolo MCP, basado en Instant Meshes y pymeshlab para realizar retopología automática, reducción de mallas y análisis de calidad en modelos 3D (OBJ/GLB). Admite procesamiento por lotes, entrada por URL, conservación de texturas de materiales, gestión de archivado y otras funciones.

Características

🔧 Funciones de procesamiento de modelos

  • Reducción inteligente de mallas: admite reducción progresiva de mallas para evitar la fragmentación del modelo, protegiendo las coordenadas UV y las texturas
  • Retopología: utiliza Instant Meshes para la reconstrucción de mallas y la reparación de problemas de topología
  • Selección automática: selecciona automáticamente el mejor método de procesamiento (reducción/retopología) según la calidad del modelo
  • Soporte de formatos: admite entrada GLB/OBJ y salida unificada en GLB

📁 Capacidades de procesamiento de archivos

  • Múltiples entradas: admite archivos locales, carpetas y URL remotas
  • Conservación de materiales: procesa automáticamente archivos MTL y texturas para mantener la integridad de los materiales
  • Integridad del paquete: verifica la integridad de los paquetes OBJ, comprobando la ausencia de archivos MTL y texturas

📊 Análisis de calidad

  • Verificación de calidad de mallas: analiza el número de caras, vértices y problemas de topología
  • Diagnóstico de modelos: detecta agujeros, componentes separados, anomalías de longitud de aristas y otros problemas
  • Recomendaciones de procesamiento: proporciona sugerencias de reducción y parámetros recomendados según las características del modelo

🗂️ Gestión de archivado

  • Archivado automático: crea automáticamente una carpeta de archivado que contiene el modelo, las texturas y los registros después del procesamiento
  • Gestión de archivado: admite listar, limpiar y copiar carpetas de archivado
  • Almacenamiento estructurado: clasificación en model/, textures/ y logs/, con metadatos detallados

Requisitos del entorno

  • Python 3.8+
  • Windows 10/11
  • Se debe colocar Instant Meshes.exe en el directorio raíz del proyecto
  • Blender 3.6 (para el procesamiento de archivos GLB y la extracción de texturas)

Instalación de dependencias

pip install -r requirements.txt

Configuración de Blender 3.6

El sistema detecta automáticamente la ubicación de instalación de Blender 3.6 y admite múltiples métodos de instalación:

Rutas de detección automática:

  • Instalación estándar: C:\Program Files\Blender Foundation\Blender 3.6\
  • Versión portátil: [用户自定义路径]\Blender\3.6\ (por ejemplo, D:\Software\Blender\3.6\)
  • Versión Steam: C:\Program Files (x86)\Steam\steamapps\common\Blender\

Configuración manual (opcional):

# 设置环境变量（根据实际安装路径修改）
set BLENDER_EXECUTABLE=D:\Software\Blender\3.6\blender.exe

Verificación de instalación:

# 测试Blender检测
result = await test_blender_detection_tool()

Funciones de herramientas MCP

1. process_model - Procesamiento unificado de modelos

Principal herramienta de procesamiento de modelos, admite reducción de mallas y retopología:

# 自动处理（智能选择减面或重拓扑）
result = await process_model(
    input_model="model.glb",
    target_faces=5000,
    operation="simplify"  # auto/simplify/remesh
)

# 纯减面处理
result = await process_model(
    input_model="model.obj",
    target_faces=3000,
    operation="simplify",
    preserve_uv=True
)

# 重拓扑处理
result = await process_model(
    input_model="broken_model.obj",
    target_faces=8000,
    operation="remesh",
    mode="fine"  # balanced/fine/coarse/fix_holes
)

Descripción de parámetros:

  • input_model: ruta del modelo de entrada (admite archivos GLB/OBJ, carpetas o URL)
  • target_faces: número de caras objetivo
  • operation: tipo de operación
    • auto: selección automática (simplify para modelos herméticos, remesh para modelos con problemas)
    • simplify: reducción pura, mantiene la estructura de malla original
    • remesh: retopología, repara problemas de malla
  • mode: modo de retopología (balanced/fine/coarse/fix_holes)
  • preserve_boundaries: si se mantienen las características de los bordes
  • preserve_uv: si se mantienen las coordenadas UV
  • create_archive: si se crea una carpeta de archivado (por defecto true)

2. analyze_model - Análisis de calidad del modelo

Analiza la calidad del modelo y la estructura de archivos:

# 自动分析
analysis = await analyze_model(
    input_path="model.obj",
    analysis_type="auto"
)

# 完整分析
analysis = await analyze_model(
    input_path="model_folder/",
    analysis_type="full"
)

# 仅质量分析
quality = await analyze_model(
    input_path="model.glb",
    analysis_type="quality"
)

Tipos de análisis:

  • auto: detección automática del tipo de entrada y selección del análisis adecuado
  • quality: análisis de calidad de mallas (número de caras, topología, recomendaciones, etc.)
  • folder: análisis de la estructura de carpetas OBJ
  • validation: verificación de integridad de paquetes OBJ
  • full: ejecuta todos los análisis disponibles

3. manage_archives - Gestión de archivado

Gestiona los archivados de modelos procesados:

# 列出归档
archives = await manage_archives(action="list", limit=10)

# 清理旧归档（预览模式）
cleanup = await manage_archives(
    action="clean", 
    days_to_keep=30, 
    dry_run=True
)

# 实际清理
cleanup = await manage_archives(
    action="clean", 
    days_to_keep=30, 
    dry_run=False
)

# 复制归档
copy_result = await manage_archives(
    action="copy",
    archive_name="model_20241201_143022",
    copy_to="./extracted_models/"
)

# 获取归档目录信息
info = await manage_archives(action="info")

Método de uso

1. Iniciar el servicio MCP

python server.py

2. Llamada a través del cliente MCP

{
  "method": "tools/call",
  "params": {
    "name": "process_model",
    "arguments": {
      "input_model": "https://example.com/model.glb",
      "target_faces": 5000,
      "operation": "auto",
      "create_archive": true
    }
  }
}

3. Ejemplo de configuración de mcp.json

{
  "mcpServers": {
    "instant-meshes-mcp": {
      "command": "python",
      "args": [
        "your_abs_dir/instant-meshes-mcp/server.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "BLENDER_PATH":"your_blender3.6.abs_dir"
      }
    }
  }
}

Ejemplos de flujo de trabajo

Simplificación básica de modelos

# 1. 分析模型
analysis = await analyze_model("input.glb", "auto")
print(f"原始面数: {analysis['mesh_quality']['faces']}")
print(f"推荐目标: {analysis['mesh_quality']['recommended_target_faces']}")

# 2. 处理模型
result = await process_model(
    input_model="input.glb",
    target_faces=analysis['mesh_quality']['recommended_target_faces'],
    operation="simplify"
)

# 3. 管理归档
archives = await manage_archives("list")
print(f"已创建归档: {result}")

Procesamiento por lotes de carpetas

# 分析文件夹结构
folder_analysis = await analyze_model("model_folder/", "folder")

# 处理主模型
result = await process_model(
    input_model="model_folder/",
    target_faces=5000,
    operation="simplify"
)

Paquetes de dependencias principales

  • trimesh: conversión de formatos de modelos 3D y procesamiento geométrico
  • pymeshlab: simplificación y reparación de mallas
  • requests: descarga de archivos remotos
  • psutil: gestión de procesos
  • mcp: soporte del protocolo MCP

Requisitos del sistema

Blender 3.6

Este sistema requiere Blender 3.6 para el procesamiento de conversión de archivos GLB y la extracción de texturas:

Funciones de detección automática:

  • El sistema detecta automáticamente la ubicación de instalación de Blender 3.6
  • Admite instalación estándar, versión portátil, versión Steam y otros métodos de instalación
  • Admite búsqueda en el registro de Windows y expansión de rutas con comodines

Prioridad de detección:

  1. Variable de entorno BLENDER_EXECUTABLE (ruta completa del ejecutable)
  2. Variable de entorno BLENDER_PATH (directorio de instalación de Blender)
  3. Detección automática de ubicaciones de instalación comunes
  4. Búsqueda en la variable de entorno PATH

Rutas de instalación comunes:

  • Instalación estándar: C:\Program Files\Blender Foundation\Blender 3.6\blender.exe
  • Versión portátil: [用户自定义路径]\Blender\3.6\blender.exe (por ejemplo, D:\Software\Blender\3.6\blender.exe)
  • Versión Steam: C:\Program Files (x86)\Steam\steamapps\common\Blender\blender.exe

Configuración manual (opcional):

# 设置环境变量指定Blender路径（根据实际安装路径修改）
set BLENDER_EXECUTABLE=D:\Software\Blender\3.6\blender.exe
# 或设置Blender安装目录
set BLENDER_PATH=D:\Software\Blender\3.6

Descripción de funciones:

  • Conversión de archivos GLB a formato OBJ (incluidos archivos de material MTL)
  • Extracción automática de texturas incrustadas en GLB (color, normal, ORM, etc.)
  • Compatibilidad con la conversión completa de materiales PBR
  • Generación de archivos OBJ/MTL compatibles con herramientas de terceros

Diagnóstico de detección: Se puede utilizar la herramienta de detección integrada para verificar la configuración de Blender:

# 测试Blender检测功能
result = await test_blender_detection_tool()

Si la detección automática falla, por favor:

  1. Confirme que Blender 3.6 está instalado
  2. Establezca las variables de entorno correspondientes
  3. Verifique los permisos del ejecutable de Blender

Estructura de directorios

instant-meshes-mcp/
├── server.py              # 主服务与MCP工具实现
├── Instant Meshes.exe     # 重拓扑核心程序
├── output_remesh/         # 输出模型目录
├── archives/              # 归档文件夹目录
├── temp/                  # 临时文件目录（自动清理）
├── logs/                  # 运行日志目录
├── requirements.txt       # Python依赖
└── README.md             # 项目说明

Estructura de archivado

Estructura de la carpeta de archivado creada después de cada procesamiento:

archives/model_20241201_143022/
├── model/                 # 主模型文件和MTL
│   ├── model.glb
│   └── model.mtl
├── textures/              # 贴图文件
│   ├── diffuse.jpg
│   └── normal.png
├── logs/                  # 处理日志
│   └── process_model_20241201_143022.log
└── info.json             # 处理元数据和配置信息

Características especiales

Reducción progresiva de mallas

  • Al realizar reducciones grandes, se ejecuta automáticamente en pasos para evitar la fragmentación del modelo
  • Protege especialmente los modelos con coordenadas UV
  • Protección inteligente de bordes y conservación de la topología

Procesamiento inteligente de materiales

  • Detección y copia automática de archivos MTL
  • Compatibilidad con múltiples tipos de texturas (diffuse, normal, specular, etc.)
  • Corrección de rutas de referencia de archivos para garantizar la carga correcta de materiales

Monitoreo de calidad

  • Detección en tiempo real de problemas de calidad del modelo
  • Proporciona recomendaciones de procesamiento y parámetros sugeridos
  • Generación automática de informes de calidad

Notas

  • Solo compatible con la plataforma Windows (depende de Instant Meshes.exe)
  • Se requiere instalar Blender 3.6 (para el procesamiento de archivos GLB y la extracción de texturas)
  • Entrada compatible con formatos OBJ y GLB
  • Salida unificada en formato GLB, conservando materiales y texturas
  • Los archivos GLB se convierten automáticamente a OBJ mediante Blender para su procesamiento y luego se convierten de nuevo a GLB
  • Todos los archivos temporales se limpian automáticamente después del procesamiento
  • Los archivos de registro se nombran con marcas de tiempo para facilitar el seguimiento del historial de procesamiento
  • El proceso de Blender se ejecuta de forma independiente y no bloquea el programa principal

Manejo de errores

  • Mensajes de error claros y registro de eventos
  • Limpieza automática de archivos temporales, incluso en situaciones anormales
  • Protección de tiempo de espera para evitar que el proceso de Instant Meshes se bloquee
  • Verificación de calidad del modelo para garantizar que el resultado de salida sea utilizable