CommunityImagemgithub.com

lego-moc

Reconhece peças LEGO soltas em fotos, cria um inventário de peças, projeta um modelo LEGO (MOC) a partir dessas peças como um arquivo LDraw e faz um servidor verificá-lo fisicamente, retornando notas de correção ou uma página pública com visualização 3D e instruções de montagem passo a passo.

O que é lego-moc?

Esta skill permite que um agente de IA (como Claude Code, Cursor ou Codex) reconheça peças LEGO em fotografias fornecidas pelo usuário, construa um inventário de peças, projete um modelo MOC (My Own Creation) exclusivamente a partir dessas peças e verifique se o modelo é fisicamente construível. O servidor valida a montagem e, se aprovada, gera uma página pública com visualização 3D e instruções de montagem detalhadas. A skill oferece duas formas de uso: ferramentas MCP integradas (como scan_photos, inventory, submit_model) para uma experiência simplificada, e um script Python (`scripts/lego.py`) como alternativa. É ideal para entusiastas de LEGO que desejam digitalizar peças, gerenciar inventários, projetar modelos personalizados e obter validação técnica, com suporte a gatilhos em português e chinês para facilitar o uso.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/garmanwu/lego-moc/tree/HEAD

Installed? Explore more Imagem skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Reconhecimento de peças LEGO e design de MOC

Duas etapas:

  1. Digitalizar. O usuário fotografa peças soltas; o servidor as reconhece e mantém o inventário (por ID de usuário).
  2. Projetar e verificar. Você projeta um modelo (MOC) a partir desse inventário e o escreve como um arquivo LDraw. O servidor verifica fisicamente: em caso de falha, nomeia as linhas problemáticas; em caso de aprovação, publica uma página com visualização 3D e instruções de montagem passo a passo. O servidor não projeta nada: o design é seu.

Existem duas formas de trabalhar. Ferramentas MCP (seção 2) não precisam de comandos shell; use-as sempre que estiverem disponíveis. O script scripts/lego.py (seção 5) faz o mesmo por meio de comandos shell e é a alternativa.

1. As ferramentas MCP estão disponíveis?

Verifique em sua lista de ferramentas por estes nomes, geralmente mostrados sob um prefixo de servidor como lego-moc (por exemplo, mcp__lego-moc__scan_photos ou lego-moc.scan_photos):

scan_photos, scan_status, inventory, edit_inventory, design_guide, connectors, submit_model, moc_status

  • Todas presentes: trabalhe conforme a seção 2.
  • Todas exceto scan_photos: o host usa o endpoint do servidor remoto, que não pode ler arquivos neste computador. Faça upload das fotos com o script (scan), faça todo o resto com as ferramentas.
  • Nenhuma presente: use o script (seção 5) para esta tarefa; tudo funciona com ele. Em seguida, ofereça ao usuário a configuração única abaixo, que remove as aprovações por comando.

Configuração única (o usuário faz)

  1. Execute python3 <pasta desta skill>/scripts/lego.py mcp-config (Windows: python). Isso imprime um bloco JSON e não faz nenhuma chamada de rede.
  2. Dê esse JSON ao usuário e peça que adicione a entrada lego-moc à seção mcpServers das configurações MCP do agente (página de configurações ou arquivo de configuração MCP) e, em seguida, reinicie o agente ou recarregue seus servidores MCP. Edite a configuração do host você mesmo apenas se o usuário solicitar.
  3. Após a reinicialização, o agente inicia a ponte por conta própria (lego.py mcp, um servidor MCP stdio local) e as ferramentas aparecem. A mesma pasta ~/.lego-parts/ e ID de usuário são usados, então nada digitalizado até agora é perdido.

lego.py mcp-config --remote imprime o endpoint do próprio servidor (type: http, uma URL que contém o ID de usuário; ele cria um ID se nenhum existir). Use-o apenas para hosts que não podem executar comandos locais. Ele não tem scan_photos, e sua URL é uma credencial: nunca a publique em lugar público.

2. Fluxo MCP

Todo resultado de ferramenta tem uma parte de texto para você ler e um objeto structuredContent com os campos. Um erro retorna como um resultado com isError: true cujo texto informa o que aconteceu e o que fazer a seguir. Siga as instruções; não contorne com suas próprias chamadas HTTP.

Digitalizar

  1. scan_photos {"paths": [...]}: caminhos absolutos de arquivos de foto, pastas ou padrões glob neste computador, de 1 a 30 fotos por chamada (JPEG, PNG, WEBP, HEIC, 25 MB cada). Retorna imediatamente com uma tarefa por foto; não espera pelo reconhecimento. Informe ao usuário cada entrada de rejected e not_uploaded com seu motivo. Uma entrada duplicate_photo significa que o arquivo exato foi enviado antes: não é reconhecido novamente, e previous é o resultado do primeiro upload (suas peças já estão no inventário). Se o host exceder o tempo limite da chamada, o upload continua: chame scan_status em vez de fazer upload novamente. Com muitas fotos grandes, use várias chamadas de cerca de 8 fotos.
  2. scan_status {"wait_s": 50}: repita até que pending seja 0 (o reconhecimento leva minutos; a primeira foto pode esperar a GPU iniciar). Transmita cada entrada de notices (pile_photo, no_pieces) ao usuário literalmente e nomeie as fotos com falha com seu error. Se permanecer pendente por muito tempo, informe ao usuário quantas fotos ainda estão sendo processadas, em vez de repetir indefinidamente.

Exibir e corrigir o inventário

  1. inventory: mostra o inventário com uma imagem de visão geral (uma imagem no resultado) e inventory_url. Mostre a imagem ao usuário e forneça o link; se você tiver um navegador ou painel de visualização, abra o link lá. Nunca apresente uma tabela de números de peça simples: a maioria dos usuários não sabe o que é 3020. Aponte as linhas de baixa confiança (moldura laranja e ? na imagem) e peça ao usuário para verificá-las na página. As linhas designable: false não têm geometria 3D utilizável e nunca podem ser usadas na construção. pending_tasks > 0 significa que o inventário está incompleto: diga isso. Use filter: "usable" ou "low_confidence" e offset/limit para inventários longos.
  2. edit_inventory {"changes": [...]}, apenas sob orientação do usuário (nunca para fazer um design se ajustar): {"op": "set_quantity", "key": "3001|4", "quantity": 3}, {"op": "remove", "key": ...}, {"op": "confirm", "key": ...} (o usuário verificou uma linha de baixa confiança e está correta), {"op": "replace", "key": ..., "ldraw_part": "3002", "ldraw_color": 4} (é realmente outra peça ou cor), {"op": "add", "ldraw_part": "3003", "ldraw_color": 14, "quantity": 2}, {"op": "undo", "key": ...}, {"op": "undo_all"}. Cada alteração relata ok; informe ao usuário quais não se aplicaram e por quê. O usuário pode fazer as mesmas edições na página de inventário.

Projetar

  1. Entenda a solicitação (seção 3): assunto, descrição, imagem de referência ou nada; verifique se o inventário pode suportá-la antes de projetar.
  2. design_guide: leia o guia completo antes do seu primeiro design em uma conversa. É o livro de regras atual do servidor: formato de arquivo, coordenadas, quais conectores se encaixam, regras do verificador, exemplos práticos e como usar muitas peças. Também retorna usable_quantity e target_percent.
  3. connectors {"parts": ["3001", "3023", ...]} (1–40 números de peça LDraw por chamada): os limites e cada conector de cada peça que você planeja usar. Obtenha a origem e as posições dos conectores de cada peça daqui; nunca as adivinhe. Uma peça relatada como unsupported não pode ser usada.
  4. Escreva o modelo: uma linha 0 <título>, em seguida, uma linha 1 <cor> x y z a b c d e f g h i <peça>.dat por peça, com <cor> = ldraw_color e <peça> = ldraw_part do inventário. Apenas linhas utilizáveis, e por key no máximo sua quantity em todo o modelo; conte antes de enviar. Sem submodelos, sem linhas 0 STEP.

Verificar e melhorar

  1. submit_model {"ldr": "<arquivo inteiro>", "title": "...", "brief": "<solicitação do usuário, palavras dele>"}; adicione "moc_id" para enviar uma nova versão do mesmo modelo e "design" apenas para peças móveis declaradas (veja o guia). Aguarda até wait_s (padrão 45) e retorna status, os issues (cada falha nomeia a regra, uma dica e as peças com sua linha de arquivo e posição), usage, resubmissions_left e, em caso de aprovação, url e duas imagens de visualização. Se status ainda não for final (queued, checking, stepping), chame moc_status {"moc_id": ..., "wait_s": 50}. O status error é uma falha do lado do servidor, não um problema de design: envie o mesmo modelo novamente com seu moc_id.
  2. Falhou: corrija exatamente as linhas nomeadas (recalcule posições a partir de connectors, não ajuste números) e envie novamente com o moc_id.
  3. Aprovado: veja ambas as visualizações e o usage, e decida se outra rodada vale a pena (seção 4). A página pública sempre mostra a versão mais recente que foi aprovada, então uma rodada posterior com falha não a derruba.
  4. Relatório: forneça ao usuário a url da página (diga que é pública), a contagem de peças e etapas, todos os avisos, o que você construiu e o que não conseguiu fazer. A aprovação significa que o modelo é fisicamente consistente na simulação do verificador, não que a construção real seja garantida de segurar: diga isso.

3. Solicitações de design

O usuário pode dar um assunto ("um carro"), uma descrição detalhada, uma imagem de referência ou nada.

  • Verifique a viabilidade primeiro. Olhe o inventário (formas, cores, quantidades) antes de prometer algo. Um carro precisa de rodas e eixos ou algo que possa substituí-los; uma casa precisa de tijolos suficientes para paredes e peças para um telhado. Diga claramente ao usuário o que pode e o que não pode ser atendido e proponha alternativas que as peças permitam (uma versão menor, outro assunto, um estilizado) em vez de forçar.
  • Descrição: mantenha as características que o usuário nomeou; diga quais você teve que descartar ou alterar e por quê.
  • Imagem de referência (apenas se você puder ver imagens): construa um modelo no espírito dela (sua forma, proporções e cores principais) a partir das peças que o usuário possui. Não será uma réplica; diga isso.
  • Nada fornecido: escolha um assunto que se adapte ao inventário (suas cores principais e as formas que mais tem) e diga o que escolheu.
  • Passe o texto da solicitação do usuário, nas palavras dele, como brief. Coloque o assunto no título.
  • Inventário enxuto. Se houver menos de cerca de 60 peças utilizáveis, ou o inventário for principalmente peças únicas em muitas cores, avise o usuário antes de projetar: apenas um modelo pequeno ou abstrato é possível. Sugira confirmar as linhas de baixa confiança (após verificá-las na página de inventário) e fotografar mais peças espalhadas. Uma nova foto de peças que já foram contadas as conta novamente: sugira fotografar peças ainda não digitalizadas ou corrigir as quantidades depois com set_quantity.

4. Use muitas peças e refine

  • Meta: use pelo menos 60% das peças utilizáveis (usage.target_percent) a menos que o usuário tenha solicitado algo pequeno. Utilizável = projetável e não de baixa confiança, ou confirmado. usage.percent em cada resultado de envio mostra onde você está, e usage.unused lista o que sobrou, do mais abundante primeiro.
  • Divida o trabalho. Versão 1: a estrutura principal (base, corpo, as grandes formas). Versões posteriores adicionam detalhes em grandes etapas: acabamento do telhado, janelas e portas, grades, decoração, uma placa de base ou chão. Existem apenas 5 reenvios por modelo, então cada rodada deve adicionar muito; não gaste uma em uma única peça.
  • Cada resultado: leia usage e unused e pergunte quais peças não utilizadas melhorariam o assunto. Em uma aprovação, veja ambas as visualizações e corrija o que parecer errado: uma mistura aleatória de cores, pinos descobertos no topo, uma forma desequilibrada onde o assunto é simétrico, uma caixa chata. A seção de conselhos do guia diz como.
  • Pare quando o modelo estiver bom e a meta for atingida, quando o inventário não puder adicionar nada sensato ou quando os reenvios se esgotarem. Informe ao usuário o uso final.

5. Script alternativo

Use o script quando as ferramentas MCP não estiverem disponíveis. Python 3.8+, apenas biblioteca padrão, nada para instalar.

python3 <pasta desta skill>/scripts/lego.py <comando> [opções] [argumentos]

No Windows use python ou py -3. Coloque as opções antes da lista de fotos.

Mantenha as aprovações do usuário em poucas. Muitos agentes pedem que o usuário aprove cada novo comando shell, host de rede e gravação fora do espaço de trabalho. Então:

  • Sempre chame o script exatamente desta forma, como um único comando simples: sem cd, sem pipes, sem &&, sem prefixo de ambiente, sem script wrapper. Assim, o usuário pode aprovar "sempre permitir" uma vez para python3 <caminho>/lego.py. Informe o usuário sobre isso na primeira vez que uma aprovação aparecer e mencione a configuração MCP (seção 1), que as evita.
  • O script precisa de três coisas, todas as quais o usuário pode permitir uma vez: executar lego.py, alcançar o host do servidor mostrado por lego.py whoami e ler/gravar ~/.lego-parts/.
  • Não execute a mesma etapa duas vezes, não faça polling em um loop de comandos curtos (use --wait) e não chame o servidor com curl ou código próprio.
  • Escreva model.ldr com sua ferramenta de escrita de arquivos no menor número de etapas possível; evite uma série de scripts descartáveis.
ComandoO que faz
scan [--no-wait] [--wait SEGUNDOS] [--images] FOTO...Envia de 1 a 30 fotos (arquivos, pastas ou padrões glob), aguarda até 480 s (padrão) pelos resultados e os salva. --no-wait retorna imediatamente após o upload.
status [--wait SEGUNDOS] [--images] [ID_TAREFA...]Verifica as tarefas pendentes (ou as fornecidas) uma vez ou continua fazendo polling por até SEGUNDOS. Salva as concluídas.
parts [--images]Salva as tarefas pendentes concluídas e recarrega todo o inventário (com as edições feitas na página de inventário ou com edit_inventory) em parts.json.
whoamiMostra o ID de usuário, servidor e pasta local. Sem rede.
moc guide [--parts-file CAMINHO]Salva o guia de design moc/DESIGN_GUIDE.md e as folhas de conectores de suas peças moc/connectors.txt.
moc submit [--title NOME] [--brief TEXTO] [--design design.json] [--moc MOC_ID] [--parts-file CAMINHO] [--no-wait] [--wait SEGUNDOS] MODELO.ldrEnvia o modelo com parts.json, aguarda até 300 s (padrão) pela verificação e imprime o resultado, o uso de peças e, em caso de aprovação, os links de visualização. --moc envia uma nova versão de um MOC existente; --brief é a solicitação do usuário.
moc status [--wait SEGUNDOS] [MOC_ID]Verifica os envios de MOC pendentes (ou o fornecido) uma vez ou continua fazendo polling por até SEGUNDOS.
mcp-config [--remote]Imprime o JSON para a configuração MCP (seção 1). A saída é apenas esse JSON; nenhuma linha RESULT.
mcpA própria ponte MCP. O host do agente o executa; não execute você mesmo.

--images também baixa a imagem LDraw de cada linha de inventário e o recorte da foto para images/.

  • Esperas longas. scan pode levar 8 minutos, moc submit 5. Se sua ferramenta shell expirar mais cedo, aumente o tempo limite ou passe um --wait menor (ex.: --wait 100) e continue com status --wait 100 / moc status --wait 100. Ser interrompido durante a espera é seguro: os IDs são salvos em pending.json / moc/pending.json primeiro, e qualquer comando posterior, de qualquer agente, os coleta.
  • Endereço do servidor. Incorporado no script baixado. Se um comando disser que nenhum servidor está configurado, o usuário deve definir LEGO_PARTS_SERVER (ex.: https://lego.groundrl.com, sem /skill/v1). LEGO_PARTS_HOME altera a pasta local.
  • Rede bloqueada. Se um comando relatar HTTP 403 ... não do servidor LEGO ou não conseguir alcançar o servidor, um sandbox, proxy ou firewall está bloqueando. Pergunte ao usuário se pode acessar a URL do servidor em um navegador.

Habilidades Relacionadas