Instant Meshes MCP

Um servidor de processamento de modelos 3D para retopologia automática, simplificação e análise de qualidade de modelos OBJ/GLB.

GitHub
2
Experimente este MCPPatrocinado

Documentação

instant-meshes-mcp

Este projeto fornece serviços de processamento de modelos 3D através do protocolo MCP, utilizando Instant Meshes e pymeshlab para realizar retopologia automática, redução de malha e análise de qualidade em modelos 3D (OBJ/GLB), com suporte a processamento em lote, entrada por URL, preservação de texturas de materiais, gerenciamento de arquivos e muito mais.

Recursos

🔧 Funções de processamento de modelos

  • Redução inteligente de malha: suporta redução progressiva de malha, evitando a fragmentação do modelo, protegendo coordenadas UV e texturas
  • Retopologia: usa Instant Meshes para reconstrução da malha, corrigindo problemas de topologia
  • Seleção automática: seleciona automaticamente o melhor método de processamento (redução/retopologia) com base na qualidade do modelo
  • Suporte a formatos: suporta entrada GLB/OBJ, saída unificada em GLB

📁 Capacidades de processamento de arquivos

  • Múltiplas entradas: suporta arquivos locais, pastas e URLs remotas
  • Preservação de materiais: processa automaticamente arquivos MTL e texturas, mantendo a integridade dos materiais
  • Integridade do pacote: valida a integridade do pacote OBJ, verificando arquivos MTL e texturas ausentes

📊 Análise de qualidade

  • Verificação de qualidade da malha: analisa contagem de faces, vértices e problemas de topologia
  • Diagnóstico do modelo: detecta buracos, componentes separados, arestas anormais e outros problemas
  • Recomendações de processamento: fornece sugestões de redução e parâmetros recomendados com base nas características do modelo

🗂️ Gerenciamento de arquivos

  • Arquivamento automático: cria automaticamente uma pasta de arquivo contendo modelo, texturas e logs após o processamento
  • Gerenciamento de arquivos: suporta listagem, limpeza e cópia de pastas de arquivo
  • Armazenamento estruturado: classificação em model/, textures/, logs/, com metadados detalhados

Requisitos de ambiente

  • Python 3.8+
  • Windows 10/11
  • É necessário colocar Instant Meshes.exe na raiz do projeto
  • Blender 3.6 (para processamento de arquivos GLB e extração de texturas)

Instalação de dependências

pip install -r requirements.txt

Configuração do Blender 3.6

O sistema detecta automaticamente a localização da instalação do Blender 3.6, suportando vários métodos de instalação:

Caminhos de detecção automática:

  • Instalação padrão: C:\Program Files\Blender Foundation\Blender 3.6\
  • Versão portátil: [用户自定义路径]\Blender\3.6\ (ex.: D:\Software\Blender\3.6\)
  • Versão Steam: C:\Program Files (x86)\Steam\steamapps\common\Blender\

Configuração manual (opcional):

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

Verificação da instalação:

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

Funções de ferramentas MCP

1. process_model - Processamento unificado de modelos

Principal ferramenta de processamento de modelos, suporta redução de malha e retopologia:

# 自动处理（智能选择减面或重拓扑）
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
)

Descrição dos parâmetros:

  • input_model: caminho do modelo de entrada (suporta arquivos GLB/OBJ, pastas ou URLs)
  • target_faces: contagem de faces alvo
  • operation: tipo de operação
    • auto: seleção automática (usa simplify para modelos à prova d'água, remesh para modelos com problemas)
    • simplify: apenas redução de malha, mantendo a estrutura original da malha
    • remesh: retopologia, corrige problemas de malha
  • mode: modo de retopologia (balanced/fine/coarse/fix_holes)
  • preserve_boundaries: se deve manter características de borda
  • preserve_uv: se deve manter coordenadas UV
  • create_archive: se deve criar pasta de arquivo (padrão: true)

2. analyze_model - Análise de qualidade do modelo

Analisa a qualidade do modelo e a estrutura de arquivos:

# 自动分析
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álise:

  • auto: detecta automaticamente o tipo de entrada e seleciona a análise apropriada
  • quality: análise de qualidade da malha (contagem de faces, topologia, recomendações, etc.)
  • folder: análise da estrutura de pastas OBJ
  • validation: validação da integridade do pacote OBJ
  • full: executa todas as análises disponíveis

3. manage_archives - Gerenciamento de arquivos

Gerencia os arquivos de modelos processados:

# 列出归档
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")

Como usar

1. Iniciar o serviço MCP

python server.py

2. Chamada via 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. Exemplo de configuração 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"
      }
    }
  }
}

Exemplos de fluxo de trabalho

Simplificação básica de modelo

# 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}")

Processamento em lote de pastas

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

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

Principais pacotes de dependência

  • trimesh: conversão de formatos de modelos 3D e processamento geométrico
  • pymeshlab: simplificação e reparo de malhas
  • requests: download de arquivos remotos
  • psutil: gerenciamento de processos
  • mcp: suporte ao protocolo MCP

Requisitos do sistema

Blender 3.6

Este sistema requer Blender 3.6 para processar a conversão de arquivos GLB e extração de texturas:

Recursos de detecção automática:

  • O sistema detecta automaticamente a localização da instalação do Blender 3.6
  • Suporta instalação padrão, versão portátil, versão Steam e outros métodos de instalação
  • Suporta pesquisa no registro do Windows e expansão de caminhos com curingas

Prioridade de detecção:

  1. Variável de ambiente BLENDER_EXECUTABLE (caminho completo do executável)
  2. Variável de ambiente BLENDER_PATH (diretório de instalação do Blender)
  3. Detecção automática de locais de instalação comuns
  4. Pesquisa na variável de ambiente PATH

Caminhos de instalação comuns:

  • Instalação padrão: C:\Program Files\Blender Foundation\Blender 3.6\blender.exe
  • Versão portátil: [用户自定义路径]\Blender\3.6\blender.exe (ex.: D:\Software\Blender\3.6\blender.exe)
  • Versão Steam: C:\Program Files (x86)\Steam\steamapps\common\Blender\blender.exe

Configuração manual (opcional):

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

Descrição das funções:

  • Conversão de arquivos GLB para formato OBJ (incluindo arquivos de material MTL)
  • Extração automática de texturas incorporadas em GLB (cor, normal, ORM, etc.)
  • Suporte à conversão completa de materiais PBR
  • Geração de arquivos OBJ/MTL compatíveis com ferramentas de terceiros

Diagnóstico de detecção: É possível usar a ferramenta de detecção integrada para verificar a configuração do Blender:

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

Se a detecção automática falhar:

  1. Confirme que o Blender 3.6 está instalado
  2. Defina as variáveis de ambiente correspondentes
  3. Verifique as permissões do executável do Blender

Estrutura de diretórios

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

Estrutura de arquivo

Estrutura da pasta de arquivo criada após cada processamento:

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

Recursos especiais

Redução progressiva de malha

  • Reduções grandes de malha são executadas em etapas automaticamente, evitando a fragmentação do modelo
  • Proteção especial para modelos com coordenadas UV
  • Proteção inteligente de bordas e preservação de topologia

Processamento inteligente de materiais

  • Detecção e cópia automática de arquivos MTL
  • Suporte a vários tipos de texturas (diffuse, normal, specular, etc.)
  • Correção de caminhos de referência de arquivos, garantindo o carregamento correto dos materiais

Monitoramento de qualidade

  • Detecção em tempo real de problemas de qualidade do modelo
  • Fornecimento de recomendações de processamento e parâmetros sugeridos
  • Geração automática de relatórios de qualidade

Observações

  • Suporta apenas plataforma Windows (depende de Instant Meshes.exe)
  • Requer instalação do Blender 3.6 (para processamento de arquivos GLB e extração de texturas)
  • Entrada suporta formatos OBJ e GLB
  • Saída unificada em formato GLB, preservando materiais e texturas
  • Arquivos GLB são convertidos automaticamente para OBJ via Blender para processamento e depois convertidos de volta para GLB
  • Todos os arquivos temporários são limpos automaticamente após o processamento
  • Arquivos de log são nomeados com carimbo de data/hora, facilitando o rastreamento do histórico de processamento
  • O processo do Blender é executado de forma independente, sem bloquear o programa principal

Tratamento de erros

  • Mensagens de erro claras e registro em log
  • Limpeza automática de arquivos temporários, mesmo em condições anormais
  • Proteção contra timeout, evitando que o processo do Instant Meshes trave
  • Validação da qualidade do modelo, garantindo que o resultado da saída seja utilizável