furniture-designer-mcp 0.1.2

MCP Server for professional furniture design — structural validation, cut optimization, BOM generation, and ergonomic standards.

furniture-designer-mcp

v0.1.2 — Servidor MCP para diseño profesional de muebles

Servidor Model Context Protocol que convierte dimensiones y tipo de mueble en un paquete completo listo para fabricación: especificación técnica, validación estructural, optimización de cortes, lista de materiales, instrucciones de ensamble, reporte HTML interactivo con viewer 3D, y exportación opcional a FreeCAD.

Flujo general

"closet 180x240x60 en melamina 18mm, 2 secciones"
                    |
        +-----------------------+
        |   design_furniture    |  -> Spec: paneles, posiciones, hardware, secciones
        +-----------+-----------+
                    |
    +---------------+---------------+
    |               |               |
validate      generate_bom    optimize_cuts
    |               |               |
0 errores     18 paneles       3 tableros
1 warning     34 confirmats    32% desperdicio
              8.4m cantos      veta alineada
                    |
            get_assembly_steps
                    |
            14 pasos ordenados
            con tornilleria por paso
                    |
        update_design_report
                    |
        Reporte HTML interactivo
        http://localhost:8432/closet-dormitorio

Instalacion

Como servidor MCP (recomendado)

uvx furniture-designer-mcp

En .mcp.json de tu proyecto:

{
  "mcpServers": {
    "furniture-designer": {
      "command": "uvx",
      "args": ["furniture-designer-mcp"]
    }
  }
}

Desarrollo local

git clone https://github.com/LuisEnVilla/furniture-designer-mcp.git
cd furniture-designer-mcp
uv sync
uv run furniture-designer-mcp

Funcionalidades principales

Reporte HTML interactivo

El entregable principal es un reporte HTML servido en http://localhost:8432/{design_id} con:

• Pagina Diseno — Viewer 3D (Three.js) del mueble ensamblado + ficha tecnica con specs, roles, hardware y notas. Incluye herramienta de medicion interactiva y diagrama 2D de dimensiones internas (tipo IKEA)
• Pagina Partes — Vista 3D explosionada + tabla de partes con dimensiones y canteado + guia de ensamble
• Pagina Cortes — Layout SVG por tablero con piezas coloreadas por rol, canteado visual, barra de uso (verde/amarillo/rojo)
• Pagina Historial — Timeline vertical de iteraciones con badges de cambios

Multi-diseno con persistencia

Cada diseño se almacena en ./designs/{design_id}/ con:

designs/
  closet-dormitorio/
    report.html       <- servido en http://localhost:8432/closet-dormitorio
    spec.json         <- ultimo spec (lectura rapida para el agente)
    metadata.json     <- {name, type, created, updated, iterations}
  cocina-isla/
    report.html
    spec.json
    metadata.json

Puedes trabajar en multiples diseños simultáneamente y retomar cualquiera en sesiones futuras.

Live reload via WebSocket

El reporte se actualiza automáticamente en el navegador cada vez que el agente genera una nueva iteración. No necesitas recargar la página — el WebSocket notifica el cambio y el JS actualiza la vista.

Mapa de secciones con lenguaje natural

El motor genera etiquetas de sección automáticamente basadas en los divisores verticales del diseño:

{
  "S1": {
    "label_es": "Seccion izquierda",
    "aliases": ["izq", "left", "primera"],
    "x_start_mm": 18, "x_end_mm": 900,
    "parts": ["shelf_S1_1", "bar_S1"]
  },
  "S2": {
    "label_es": "Seccion derecha",
    "aliases": ["der", "right", "ultima"],
    "x_start_mm": 918, "x_end_mm": 1782,
    "parts": ["drawer_S2_1_front", "drawer_S2_2_front"]
  }
}

Esto permite que el usuario diga "haz la izquierda mas ancha" y el agente resuelva la referencia a la sección correcta.

Zocalo como marco estructural

El zócalo no es un panel suelto — es un marco rectangular de 4 piezas que soporta todo el peso del mueble:

Vista superior del zocalo:

    +------ kickplate_front ------+    <- frente (retranqueado 5cm)
    |                              |
    kickplate_return_l    kickplate_return_r    <- retornos laterales
    |                              |
    +------ kickplate_back -------+    <- fondo

El frente se retranquea 5cm para que los pies no choquen. Los laterales del mueble se apoyan encima de este marco.

Filtro automatico de paneles MDF

Los paneles de MDF 3mm (respaldos, fondos de cajón) se filtran automáticamente del optimizador de cortes — se cortan de un stock diferente (tablero MDF, no melamina). El filtro actúa sobre roles back, drawer_bottom, y cualquier panel con espesor menor al material principal.

Herramientas (23 tools)

Diseno

Tool	Descripcion
design_furniture	Genera spec completa con paneles, hardware, posiciones, secciones y notas estructurales

Conocimiento

Tool	Descripcion
get_standards	Estándares ergonómicos por tipo de mueble
get_material_specs	Propiedades del material (espesor, tramo máximo, agarre de tornillo)
get_structural_rules	10 reglas estructurales con severidad y solución
get_hardware_catalog	Catálogo de herrajes con reglas de cantidad y colocación
get_assembly_specs	Especificaciones de ensamble: uniones, adhesivos, pre-taladrado, montaje

Todas aceptan brief=true para respuestas compactas (ahorro 60-80% tokens).

Validacion y fabricacion

Tool	Descripcion
validate_structure	Valida spec contra 10 reglas estructurales (errores + warnings)
generate_bom	Bill of Materials: paneles agrupados, herrajes, cantos en metros
optimize_cuts	Optimización 2D en tableros estándar (2440x1220mm) con veta y kerf
get_assembly_steps	Instrucciones de ensamble paso a paso en español

Multi-diseno y reporte

Tool	Descripcion
create_design	Crea proyecto de diseño nuevo (retorna design_id)
list_designs	Lista todos los diseños activos con metadata
get_design_context	Recupera spec + historial de un diseño para retomar
get_section_map	Mapa de secciones con etiquetas y resolución de lenguaje natural
start_design_server	Inicia servidor HTTP (puerto 8432) con WebSocket live reload
update_design_report	Genera/actualiza reporte HTML interactivo

FreeCAD — exportar (requiere FreeCAD + RPC server)

Tool	Descripcion
build_3d_model	Construye modelo 3D ensamblado en FreeCAD via XML-RPC
build_exploded_view	Construye vista explosionada en FreeCAD
build_cut_diagram	Construye diagrama de corte en FreeCAD
build_techdraw	Construye plano técnico TechDraw (vistas ortogonales A3)

FreeCAD — importar (requiere freecad-mcp)

Tool	Descripcion
build_import_script	Script para extraer paneles de un documento FreeCAD existente
parse_freecad_import	Parsear salida del script de importación a spec

Desarrollo

Tool	Descripcion
reload_engine	Recarga módulos del engine sin reiniciar el servidor MCP

Tipos de mueble

Tipo	Descripcion	Caracteristicas clave
kitchen_base	Gabinete base de cocina	Zócalo 4 piezas, travesaños, sin tapa (para cubierta)
kitchen_wall	Gabinete aéreo de cocina	Sin zócalo, tapa superior e inferior
closet	Closet / armario	Zócalo, divisiones auto si >75cm, alerta anclaje si >180cm
bookshelf	Librero / estantería	Repisas múltiples, puertas opcionales
desk	Escritorio	Espacio para rodillas (60cm), panel de recato
vanity	Vanitorio / mueble de baño	Estructura tipo base de cocina

Materiales

Material	Espesor	Tramo max. sin soporte	Mejor para
melamine_16 (default)	16mm	75cm	Uso general, más económico
melamine_18	18mm	85cm	Cocinas y closets de gama alta
mdf_15	15mm	80cm	Muebles pintados
mdf_18	18mm	90cm	Puertas con diseño CNC
plywood_18	18mm	100cm	Tramos largos, alta resistencia
solid_pine_20	20mm	120cm	Muebles de madera maciza

Arquitectura del servidor

furniture-designer-mcp/
  src/furniture_designer_mcp/
    server.py                  <- Punto de entrada MCP (23 tools)
    engine/
      designer.py              <- Motor principal: spec + section_labels
      structural_validator.py  <- 10 reglas estructurales
      cut_optimizer.py         <- Bin packing 2D con veta y kerf
      bom_generator.py         <- Bill of Materials
      spec_validator.py        <- Validacion de formato de spec
      spec_builder.py          <- Construccion de spec desde parametros
      section_mapper.py        <- Mapa de secciones + resolucion natural
      design_store.py          <- Multi-diseno + persistencia ./designs/
      http_server.py           <- HTTP + WebSocket (puerto 8432)
      report_generator.py      <- Template HTML interactivo (~1900 lineas)
      freecad_scripts.py       <- Generacion de scripts FreeCAD
      freecad_client.py        <- XML-RPC client para FreeCAD
    knowledge/
      standards.py             <- Estandares ergonomicos
      materials.py             <- Propiedades de materiales
      structural_rules.py      <- Reglas de ingenieria
      hardware_catalog.py      <- Catalogo de herrajes
      assembly_specs.py        <- Especificaciones de ensamble

Consideraciones tecnicas

Unidades

• Entrada: dimensiones en cm (ancho, alto, fondo)
• Salida: spec en mm (width_mm, height_mm, thickness_mm)
• Cortes: el optimizer usa width/height (sin sufijo _mm) — schema diferente al spec

Veta del material

El optimizador soporta grain_direction="length" para mantener la dirección de veta consistente en melaminas con textura. Esto restringe la rotación de piezas. Si una pieza no cabe con restricción de veta, se relaja automáticamente a none con aviso.

Desbaste de sierra (kerf)

3mm por defecto. Se descuenta en cada corte del optimizador. Ajustable según la hoja utilizada.

Respaldos

Siempre MDF 3mm. El validador genera error si un mueble no tiene panel trasero (rol back). Se excluyen automáticamente del optimizador de cortes de melamina.

Divisiones automaticas

Si el ancho de una sección excede el tramo máximo del material, se agrega una división vertical automáticamente.

Muebles altos (>180cm)

El validador genera warning de anclaje a pared por riesgo de volcamiento.

Cajones completos

design_furniture genera caja completa: frente + 2 laterales + trasera + fondo MDF 3mm + correderas telescópicas.

Modo compact

Las tools principales retornan compact=true por defecto: resumen legible + JSON reducido. Usar compact=false solo si se necesita el JSON completo.

Hot-reload

reload_engine recarga todos los módulos del engine sin reiniciar el servidor MCP. Útil durante desarrollo.

Requisitos

• Python >= 3.12
• uv para gestión de paquetes
• FreeCAD 0.21+ con addon MCP (solo para exportación 3D)

Licencia

MIT