Reconocimiento de piezas LEGO y diseño de MOC
Dos etapas:
- Escaneo. El usuario fotografía piezas sueltas; el servidor las reconoce y mantiene el inventario (por ID de usuario).
- Diseño y verificación. Tú diseñas un modelo (MOC) a partir de ese inventario y lo escribes como un archivo LDraw. El servidor lo comprueba físicamente: si falla, indica las líneas problemáticas; si pasa, publica una página con una vista 3D e instrucciones de montaje paso a paso. El servidor no diseña nada: el diseño es tuyo.
Hay dos formas de trabajar. Herramientas MCP (sección 2) no necesitan comandos de shell; úsalas siempre que estén disponibles. El script scripts/lego.py (sección 5) hace lo mismo mediante comandos de shell y es la alternativa.
1. ¿Están disponibles las herramientas MCP?
Busca en tu lista de herramientas estos nombres, generalmente bajo un prefijo de servidor como lego-moc (por ejemplo mcp__lego-moc__scan_photos o lego-moc.scan_photos):
scan_photos, scan_status, inventory, edit_inventory, design_guide, connectors, submit_model, moc_status
- Todas presentes: trabaja como en la sección 2.
- Todas excepto
scan_photos: el anfitrión usa el endpoint del servidor remoto, que no puede leer archivos en este ordenador. Sube las fotos con el script (scan), haz todo lo demás con las herramientas. - Ninguna presente: usa el script (sección 5) para esta tarea; todo funciona con él. Luego ofrece al usuario la configuración única que se muestra a continuación, que elimina las aprobaciones por comando.
Configuración única (la hace el usuario)
- Ejecuta
python3 <carpeta de esta habilidad>/scripts/lego.py mcp-config(Windows:python). Imprime un bloque JSON y no realiza ninguna llamada de red. - Dale al usuario ese JSON y pídele que añada la entrada
lego-moca la secciónmcpServersde la configuración MCP del agente (página de configuración o archivo de configuración MCP), luego reinicia el agente o recarga sus servidores MCP. Edita la configuración del anfitrión solo si el usuario te lo pide. - Después del reinicio, el agente inicia el puente por sí mismo (
lego.py mcp, un servidor MCP local stdio) y aparecen las herramientas. Se usa la misma carpeta~/.lego-parts/y el mismo ID de usuario, por lo que nada de lo escaneado hasta ahora se pierde.
lego.py mcp-config --remote imprime el endpoint del propio servidor (type: http, una URL que contiene el ID de usuario; crea un ID si no existe). Úsalo solo para anfitriones que no pueden ejecutar comandos locales. No tiene scan_photos, y su URL es una credencial: nunca la publiques en ningún lugar público.
2. Flujo MCP
Cada resultado de herramienta tiene una parte de texto para que la leas y un objeto structuredContent con los campos. Un error llega como un resultado con isError: true cuyo texto indica qué sucedió y qué hacer a continuación. Hazlo; no lo evites con tus propias llamadas HTTP.
Escaneo
scan_photos{"paths": [...]}: rutas absolutas de archivos de fotos, carpetas o patrones glob en este ordenador, de 1 a 30 fotos por llamada (JPEG, PNG, WEBP, HEIC, 25 MB cada una). Devuelve de inmediato con una tarea por foto; no espera el reconocimiento. Informa al usuario de cada entrada derejectedynot_uploadedcon su motivo. Una entradaduplicate_photosignifica que ese archivo exacto ya se subió antes: no se reconoce de nuevo, ypreviouses el resultado de la primera subida (sus piezas ya están en el inventario). Si el anfitrión agota el tiempo de espera de la llamada, la subida continúa: llama ascan_statusen lugar de volver a subir. Con muchas fotos grandes, usa varias llamadas de unas 8 fotos.scan_status{"wait_s": 50}: repite hasta quependingsea 0 (el reconocimiento lleva minutos; la primera foto puede esperar a que la GPU se inicie). Transmite cada entrada denotices(pile_photo,no_pieces) al usuario textualmente y nombra las fotos fallidas con suerror. Si permanece pendiente durante mucho tiempo, informa al usuario de cuántas fotos se están procesando aún, en lugar de repetir indefinidamente.
Mostrar y corregir el inventario
inventory: muestra el inventario con una imagen de resumen (una imagen en el resultado) yinventory_url. Muestra la imagen al usuario y dale el enlace; si tienes un navegador o panel de vista previa, abre el enlace allí. Nunca presentes una tabla de números de pieza simples: la mayoría de los usuarios no pueden distinguir qué es "3020". Señala las filas de baja confianza (marco naranja y?en la imagen) y pide al usuario que las revise en la página. Las filasdesignable: falseno tienen geometría 3D utilizable y nunca se pueden construir.pending_tasks > 0significa que el inventario está incompleto: dilo. Usafilter: "usable"o"low_confidence"yoffset/limitpara inventarios largos.edit_inventory{"changes": [...]}, solo por orden del usuario (nunca para que un diseño encaje):{"op": "set_quantity", "key": "3001|4", "quantity": 3},{"op": "remove", "key": ...},{"op": "confirm", "key": ...}(el usuario revisó una fila de baja confianza y es correcta),{"op": "replace", "key": ..., "ldraw_part": "3002", "ldraw_color": 4}(en realidad es otra pieza o color),{"op": "add", "ldraw_part": "3003", "ldraw_color": 14, "quantity": 2},{"op": "undo", "key": ...},{"op": "undo_all"}. Cada cambio informaok; informa al usuario cuáles no se aplicaron y por qué. El usuario puede hacer las mismas ediciones en la página del inventario.
Diseño
- Comprende la solicitud (sección 3): tema, descripción, imagen de referencia o nada; verifica que el inventario pueda soportarla antes de diseñar.
design_guide: lee la guía completa antes de tu primer diseño en una conversación. Es el libro de reglas actual del servidor: formato de archivo, coordenadas, qué conectores encajan, reglas del verificador, ejemplos trabajados y cómo usar muchas piezas. También devuelveusable_quantityytarget_percent.connectors{"parts": ["3001", "3023", ...]}(de 1 a 40 números de pieza LDraw por llamada): los límites y cada conector de cada pieza que planees usar. Toma el origen y las posiciones de los conectores de cada pieza de aquí; nunca los adivines. Una pieza reportada comounsupportedno se puede usar.- Escribe el modelo: una línea
0 <título>, luego una línea1 <color> x y z a b c d e f g h i <pieza>.datpor pieza, con<color>=ldraw_colory<pieza>=ldraw_partdel inventario. Solo filas utilizables, y porkeycomo máximo suquantityen todo el modelo; cuenta antes de enviar. Sin submodelos, sin líneas0 STEP.
Verificar y mejorar
submit_model{"ldr": "<el archivo completo>", "title": "...", "brief": "<la solicitud del usuario, sus palabras>"}; añade"moc_id"para enviar una nueva versión del mismo modelo, y"design"solo para piezas móviles declaradas (consulta la guía). Espera hastawait_s(predeterminado 45) y devuelvestatus, losissues(cada fallo nombra la regla, una pista y las piezas con su línea de archivo y posición),usage,resubmissions_lefty, si pasa,urly dos imágenes de vista previa. Sistatusaún no es final (queued,checking,stepping), llama amoc_status{"moc_id": ..., "wait_s": 50}. El estadoerrores un fallo del lado del servidor, no un problema de diseño: envía el mismo modelo de nuevo con sumoc_id.- Falló: corrige exactamente las líneas nombradas (recalcula posiciones a partir de
connectors, no ajustes números) y envía de nuevo con elmoc_id. - Aprobado: mira ambas vistas previas y
usage, luego decide si otra ronda vale la pena (sección 4). La página pública siempre muestra la última versión que pasó, por lo que una ronda posterior fallida no la elimina. - Informe: entrega al usuario la
urlde la página (dile que es pública), el recuento de piezas y pasos, cualquier advertencia, lo que construiste y lo que no pudiste hacer. Que el modelo pase significa que es físicamente consistente en la simulación del verificador, no que la construcción real esté garantizada para mantenerse: dilo.
3. Solicitudes de diseño
El usuario puede dar un tema ("un coche"), una descripción detallada, una imagen de referencia o nada en absoluto.
- Verifica la viabilidad primero. Mira el inventario (formas, colores, cantidades) antes de prometer nada. Un coche necesita ruedas y ejes o algo que pueda sustituirlos; una casa necesita suficientes ladrillos para las paredes y piezas para un techo. Dile al usuario claramente qué se puede y qué no se puede cumplir, y propón alternativas que las piezas sí permitan (una versión más pequeña, otro tema, uno estilizado) en lugar de forzarlo.
- Descripción: mantén las características que el usuario nombró; di cuáles tuviste que omitir o cambiar y por qué.
- Imagen de referencia (solo si puedes ver imágenes): construye un modelo en su espíritu (su forma, proporciones y colores principales) a partir de las piezas que el usuario posee. No será una réplica; dilo.
- Nada dado: elige un tema que se adapte al inventario (sus colores principales y las formas que más tiene) y di lo que elegiste.
- Pasa el texto de la solicitud del usuario, en sus palabras, como
brief. Pon el tema en el título. - Inventario escaso. Si hay menos de unas 60 piezas utilizables, o el inventario consiste principalmente en piezas individuales de muchos colores, díselo al usuario antes de diseñar: solo es posible un modelo pequeño o abstracto. Sugiere confirmar las filas de baja confianza (después de revisarlas en la página del inventario) y fotografiar más piezas extendidas. Una nueva foto de piezas que ya se contaron las vuelve a contar: sugiere fotografiar piezas aún no escaneadas, o corregir las cantidades después con
set_quantity.
4. Usa muchas piezas, luego refina
- Objetivo: usa al menos el 60% de las piezas utilizables (
usage.target_percent) a menos que el usuario haya pedido algo pequeño. Utilizable = diseñable y no de baja confianza, o confirmado.usage.percenten cada resultado de envío muestra dónde estás, yusage.unusedenumera lo que queda, de más abundante a menos. - Organiza el trabajo en etapas. Versión 1: la estructura principal (base, cuerpo, las formas grandes). Las versiones posteriores añaden detalles en pasos grandes: acabado del techo, ventanas y puertas, barandillas, decoración, una placa base o suelo. Solo hay 5 reenvíos por modelo, por lo que cada ronda debe añadir mucho; no gastes uno en una sola pieza.
- Cada resultado: lee
usageyunusedy pregunta qué piezas no utilizadas mejorarían el tema. Si se aprueba, mira ambas vistas previas y corrige lo que se vea mal: una mezcla aleatoria de colores, tacos descubiertos en la parte superior, una forma desequilibrada donde el tema es simétrico, una caja plana. La sección de consejos de la guía dice cómo. - Detente cuando el modelo sea bueno y se cumpla el objetivo, cuando el inventario no pueda añadir nada sensato, o cuando se hayan agotado los reenvíos. Informa al usuario del uso final.
5. Script de respaldo
Usa el script cuando las herramientas MCP no estén disponibles. Python 3.8+, solo biblioteca estándar, nada que instalar.
python3 <carpeta de esta habilidad>/scripts/lego.py <comando> [opciones] [argumentos]
En Windows usa python o py -3. Pon las opciones antes de la lista de fotos.
Mantén las aprobaciones del usuario al mínimo. Muchos agentes piden al usuario que apruebe cada nuevo comando de shell, host de red y escritura fuera del espacio de trabajo. Por lo tanto:
- Siempre llama al script exactamente en esta forma, como un solo comando simple: sin
cd, sin tuberías, sin&&, sin prefijo de entorno, sin script contenedor. Así el usuario puede aprobar "permitir siempre" una vez parapython3 <ruta>/lego.py. Dile esto al usuario la primera vez que aparezca una aprobación, y menciona la configuración MCP (sección 1), que las evita. - El script necesita tres cosas, todas las cuales el usuario puede permitir una vez: ejecutar
lego.py, acceder al host del servidor mostrado porlego.py whoami, y leer/escribir~/.lego-parts/. - No ejecutes el mismo paso dos veces, no consultes en un bucle de comandos cortos (usa
--wait), y no llames al servidor con curl o código propio. - Escribe
model.ldrcon tu herramienta de escritura de archivos en la menor cantidad de pasos posible; evita una serie de scripts desechables.
| Comando | Qué hace |
|---|---|
scan [--no-wait] [--wait SEGUNDOS] [--images] FOTO... | Sube de 1 a 30 fotos (archivos, carpetas o patrones glob), espera hasta 480 segundos (predeterminado) por los resultados y los guarda. --no-wait regresa inmediatamente después de subir. |
status [--wait SEGUNDOS] [--images] [ID_TAREA...] | Verifica las tareas pendientes (o las indicadas) una vez, o sigue consultando hasta SEGUNDOS. Guarda las finalizadas. |
parts [--images] | Guarda las tareas pendientes finalizadas, luego recarga todo el inventario (con las ediciones hechas en la página del inventario o con edit_inventory) en parts.json. |
whoami | Muestra el ID de usuario, servidor y carpeta local. Sin red. |
moc guide [--parts-file RUTA] | Guarda la guía de diseño moc/DESIGN_GUIDE.md y las hojas de conectores de tus piezas moc/connectors.txt. |
moc submit [--title NOMBRE] [--brief TEXTO] [--design design.json] [--moc MOC_ID] [--parts-file RUTA] [--no-wait] [--wait SEGUNDOS] MODELO.ldr | Envía el modelo con parts.json, espera hasta 300 segundos (predeterminado) para la verificación e imprime el resultado, el uso de piezas y, si se aprueba, los enlaces de vista previa. --moc envía una nueva versión de un MOC existente; --brief es la solicitud del usuario. |
moc status [--wait SEGUNDOS] [MOC_ID] | Verifica los envíos de MOC pendientes (o el indicado) una vez, o sigue consultando hasta SEGUNDOS. |
mcp-config [--remote] | Imprime el JSON para la configuración MCP (sección 1). La salida es solo ese JSON; sin línea de RESULTADO. |
mcp | El puente MCP en sí. El anfitrión del agente lo ejecuta; no lo ejecutes tú. |
--images también descarga la imagen LDraw de cada fila del inventario y el recorte de la foto en images/.
- Esperas largas.
scanpuede ejecutarse durante 8 minutos,moc submitdurante 5. Si tu herramienta de shell agota el tiempo de espera antes, aumenta su tiempo de espera o pasa un--waitmás pequeño (ej.--wait 100) y continúa constatus --wait 100/moc status --wait 100. Ser detenido en medio de una espera es seguro: los IDs se guardan primero enpending.json/moc/pending.json, y cualquier comando posterior, de cualquier agente, los recoge. - Dirección del servidor. Integrada en el script descargado. Si un comando dice que no hay servidor configurado, el usuario debe establecer
LEGO_PARTS_SERVER(ej.https://lego.groundrl.com, sin/skill/v1).LEGO_PARTS_HOMEcambia la carpeta local. - Red bloqueada. Si un comando informa
HTTP 403 ... not from the LEGO servero no puede alcanzar el servidor, un sandbox, proxy o cortafuegos lo está bloqueando. Pregunta al usuario si puede permitir que el script acceda al host del servidor, o sugiere la configuración MCP remota (sección 1).