Community图像github.com

lego-moc

Recognise loose LEGO parts from photos into a parts inventory, then design a LEGO model (MOC) from those parts as an LDraw file and have a server verify it physically - it returns fix notes, or a public page with a 3D preview and step-by-step building instructions. Works through MCP tools (scan_photos, inventory, submit_model and others) or a fallback Python script. Use when the user wants to identify, scan or count LEGO pieces from photos, build, show or correct a parts inventory, design or build a MOC from parts they own (a car, a house, a description, a picture), check, validate or verify a LEGO model or .ldr file, or get building instructions or a 3D preview for it. Chinese triggers - 乐高零件识别, 识别乐高零件, 拍照识别积木, 乐高零件清单, 零件库存, 用我有的零件设计 MOC, 设计乐高作品, 检验 MOC, 检查乐高模型能不能拼, 拼装步骤, 搭建说明, 3D 预览.

lego-moc 是什么?

lego-moc is a Claude Code agent skill that recognise loose LEGO parts from photos into a parts inventory, then design a LEGO model (MOC) from those parts as an LDraw file and have a server verify it physically - it returns fix notes, or a public page with a 3D preview and step-by-step building instructions. Works through MCP tools (scan_photos, inventory, submit_model and others) or a fallback Python script. Use when the user wants to identify, scan or count LEGO pieces from photos, build, show or correct a parts inventory, design or build a MOC from parts they own (a car, a house, a description, a picture), check, validate or verify a LEGO model or .ldr file, or get building instructions or a 3D preview for it. Chinese triggers - 乐高零件识别, 识别乐高零件, 拍照识别积木, 乐高零件清单, 零件库存, 用我有的零件设计 MOC, 设计乐高作品, 检验 MOC, 检查乐高模型能不能拼, 拼装步骤, 搭建说明, 3D 预览.

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

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

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

LEGO parts recognition and MOC design

Two stages:

  1. Scan. The user photographs loose parts; the server recognises them and keeps the inventory (per user ID).
  2. Design and verify. You design a model (MOC) from that inventory and write it as an LDraw file. The server checks it physically: on failure it names the offending lines; on a pass it publishes a page with a 3D view and step-by-step building instructions. The server designs nothing: the design is yours.

There are two ways to work. MCP tools (section 2) need no shell commands; use them whenever they are available. The script scripts/lego.py (section 5) does the same through shell commands and is the fallback.

1. Are the MCP tools available?

Look in your tool list for these names, usually shown under a server prefix such as lego-moc (for example mcp__lego-moc__scan_photos or lego-moc.scan_photos):

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

  • All present: work as in section 2.
  • All but scan_photos: the host uses the remote server endpoint, which cannot read files on this computer. Upload photos with the script (scan), do everything else with the tools.
  • None present: use the script (section 5) for this task; everything works with it. Then offer the user the one-time setup below, which removes the per-command approvals.

One-time setup (the user does it)

  1. Run python3 <this skill folder>/scripts/lego.py mcp-config (Windows: python). It prints a JSON block and makes no network call.
  2. Give the user that JSON and ask them to add the lego-moc entry to the mcpServers section of the agent's MCP settings (settings page or MCP config file), then restart the agent or reload its MCP servers. Edit the host's configuration yourself only if the user asks you to.
  3. After the restart the agent starts the bridge itself (lego.py mcp, a local stdio MCP server) and the tools appear. The same ~/.lego-parts/ folder and user ID are used, so nothing scanned so far is lost.

lego.py mcp-config --remote prints the server's own endpoint instead (type: http, a URL that contains the user ID; it creates an ID if none exists). Use it only for hosts that cannot run local commands. It has no scan_photos, and its URL is a credential: never post it anywhere public.

2. MCP flow

Every tool result has a text part for you to read and a structuredContent object with the fields. An error comes back as a result with isError: true whose text says what happened and what to do next. Do it; don't work around it with your own HTTP calls.

Scan

  1. scan_photos {"paths": [...]}: absolute paths of photo files, folders or glob patterns on this computer, 1–30 photos per call (JPEG, PNG, WEBP, HEIC, 25 MB each). It returns at once with one task per photo; it does not wait for recognition. Tell the user every entry of rejected and not_uploaded with its reason. A duplicate_photo entry means that exact file was uploaded before: it is not recognised again, and previous is the first upload's result (its parts are in the inventory already). If the host times the call out, the upload goes on: call scan_status instead of uploading again. With many large photos, use several calls of about 8 photos.
  2. scan_status {"wait_s": 50}: repeat until pending is 0 (recognition takes minutes; the first photo can wait for the GPU to start). Relay every entry of notices (pile_photo, no_pieces) to the user verbatim and name the failed photos with their error. If it stays pending for a long time, tell the user how many photos are still being processed instead of looping forever.

Show and correct the inventory

  1. inventory: shows the inventory with an overview picture (an image in the result) and inventory_url. Show the user the picture and give them the link; if you have a browser or preview panel, open the link there. Never present a table of bare part numbers: most users cannot tell what 3020 is. Point out the low-confidence rows (orange frame and ? in the picture) and ask the user to check them on the page. designable: false rows have no usable 3D geometry and can never be built with. pending_tasks > 0 means the inventory is incomplete: say so. Use filter: "usable" or "low_confidence" and offset/limit for long inventories.
  2. edit_inventory {"changes": [...]}, only on the user's word (never to make a design fit): {"op": "set_quantity", "key": "3001|4", "quantity": 3}, {"op": "remove", "key": ...}, {"op": "confirm", "key": ...} (the user checked a low-confidence row and it is right), {"op": "replace", "key": ..., "ldraw_part": "3002", "ldraw_color": 4} (it is really another part or colour), {"op": "add", "ldraw_part": "3003", "ldraw_color": 14, "quantity": 2}, {"op": "undo", "key": ...}, {"op": "undo_all"}. Each change reports ok; tell the user which did not apply and why. The user can make the same edits on the inventory page.

Design

  1. Understand the request (section 3): subject, description, reference picture or nothing; check that the inventory can carry it before you design.
  2. design_guide: read the whole guide before your first design in a conversation. It is the server's current rule book: file format, coordinates, which connectors mate, the verifier's rules, worked examples and how to use many parts. It also returns usable_quantity and target_percent.
  3. connectors {"parts": ["3001", "3023", ...]} (1–40 LDraw part numbers per call): the bounds and every connector of each part you plan to use. Take every part's origin and connector positions from here; never guess them. A part reported as unsupported cannot be used.
  4. Write the model: a 0 <title> line, then one line 1 <colour> x y z a b c d e f g h i <part>.dat per part, with <colour> = ldraw_color and <part> = ldraw_part from the inventory. Only usable rows, and per key at most its quantity across the whole model; count before you submit. No sub-models, no 0 STEP lines.

Verify and improve

  1. submit_model {"ldr": "<the whole file>", "title": "...", "brief": "<the user's request, their words>"}; add "moc_id" to submit a new version of the same model, and "design" only for declared moving parts (see the guide). It waits up to wait_s (default 45) and returns status, the issues (each fail names the rule, a hint, and the parts with their file line and position), usage, resubmissions_left and, on a pass, url and two preview pictures. If status is not final yet (queued, checking, stepping), call moc_status {"moc_id": ..., "wait_s": 50}. Status error is a server-side failure, not a design problem: submit the same model again with its moc_id.
  2. Failed: fix exactly the named lines (recompute positions from connectors, don't nudge numbers) and submit again with the moc_id.
  3. Passed: look at both previews and at usage, then decide whether another round is worth it (section 4). The public page always shows the latest version that passed, so a failed later round does not take it down.
  4. Report: give the user the page url (say that it is public), the part and step counts, every warning, what you built and what you could not do. Passing means the model is physically consistent in the verifier's simulation, not that the real build is guaranteed to hold: say so.

3. Design requests

The user may give a subject ("a car"), a detailed description, a reference picture, or nothing at all.

  • Check feasibility first. Look at the inventory (shapes, colours, quantities) before promising anything. A car needs wheels and axles or something that can stand in for them; a house needs enough bricks for walls and parts for a roof. Tell the user plainly what can and cannot be met, and propose alternatives that the parts do allow (a smaller version, another subject, a stylised one) instead of forcing it.
  • Description: keep the features the user named; say which ones you had to drop or change and why.
  • Reference picture (only if you can see images): build a model in its spirit (its shape, proportions and main colours) from the parts the user owns. It will not be a replica; say so.
  • Nothing given: pick a subject that suits the inventory (its main colours and the shapes it has most of) and say what you chose.
  • Pass the user's request text, in their words, as brief. Put the subject in the title.
  • Thin inventory. If there are fewer than about 60 usable pieces, or the inventory is mostly single pieces in many colours, tell the user before designing: only a small or abstract model is possible. Suggest confirming low-confidence rows (after checking them on the inventory page) and photographing more parts spread out. A new photo of parts that were already counted counts them again: suggest photographing parts not scanned yet, or correcting the quantities afterwards with set_quantity.

4. Use many parts, then refine

  • Target: use at least 60% of the usable pieces (usage.target_percent) unless the user asked for something small. Usable = designable and not low-confidence, or confirmed. usage.percent in every submission result shows where you are, and usage.unused lists what is left, most plentiful first.
  • Stage the work. Version 1: the main structure (base, body, the big shapes). Later versions add detail in large steps: roof finishing, windows and doors, railings, decoration, a base plate or ground. Only 5 resubmissions exist per model, so each round must add a lot; don't spend one on a single part.
  • Every result: read usage and unused and ask which unused parts would make the subject better. On a pass, look at both previews and fix what looks wrong: a random mix of colours, bare studs on top, a lopsided shape where the subject is symmetric, a flat box. The guide's advice section says how.
  • Stop when the model is good and the target is met, when the inventory cannot add anything sensible, or when the resubmissions are used up. Tell the user the final usage.

5. Script fallback

Use the script when the MCP tools are not available. Python 3.8+, standard library only, nothing to install.

python3 <this skill folder>/scripts/lego.py <command> [options] [arguments]

On Windows use python or py -3. Put options before the photo list.

Keep the user's approvals few. Many agents ask the user to approve each new shell command, network host and write outside the workspace. So:

  • Always call the script in exactly this form, as one plain command: no cd, no pipes, no &&, no environment prefix, no wrapper script. Then the user can approve "always allow" once for python3 <path>/lego.py. Tell the user this the first time an approval appears, and mention the MCP setup (section 1), which avoids them.
  • The script needs three things, all of which the user can allow once: run lego.py, reach the server host shown by lego.py whoami, and read/write ~/.lego-parts/.
  • Don't run the same step twice, don't poll in a loop of short commands (use --wait), and don't call the server with curl or code of your own.
  • Write model.ldr with your file-writing tool in as few steps as you can; avoid a series of throw-away scripts.
CommandWhat it does
scan [--no-wait] [--wait SECONDS] [--images] PHOTO...Uploads 1–30 photos (files, folders or glob patterns), waits up to 480 s (default) for the results and saves them. --no-wait returns right after uploading.
status [--wait SECONDS] [--images] [TASK_ID...]Checks the pending tasks (or the given ones) once, or keeps polling up to SECONDS. Saves finished ones.
parts [--images]Saves finished pending tasks, then reloads the whole inventory (with the edits made on the inventory page or with edit_inventory) into parts.json.
whoamiShows the user ID, server and local folder. No network.
moc guide [--parts-file PATH]Saves the design guide moc/DESIGN_GUIDE.md and the connector sheets of your parts moc/connectors.txt.
moc submit [--title NAME] [--brief TEXT] [--design design.json] [--moc MOC_ID] [--parts-file PATH] [--no-wait] [--wait SECONDS] MODEL.ldrSends the model with parts.json, waits up to 300 s (default) for the check and prints the result, the parts usage and, on a pass, the preview links. --moc submits a new version of an existing MOC; --brief is the user's request.
moc status [--wait SECONDS] [MOC_ID]Checks the pending MOC submissions (or the given one) once, or keeps polling up to SECONDS.
mcp-config [--remote]Prints the JSON for the MCP setup (section 1). Output is only that JSON; no RESULT line.
mcpThe MCP bridge itself. The agent host runs it; don't run it yourself.

--images also downloads each inventory row's LDraw picture and photo crop into images/.

  • Long waits. scan can run for 8 minutes, moc submit for 5. If your shell tool times out sooner, raise its timeout or pass a smaller --wait (e.g. --wait 100) and continue with status --wait 100 / moc status --wait 100. Being stopped mid-wait is safe: IDs are saved in pending.json / moc/pending.json first, and any later command, from any agent, collects them.
  • Server address. Built into the downloaded script. If a command says no server is configured, the user must set LEGO_PARTS_SERVER (e.g. https://lego.groundrl.com, without /skill/v1). LEGO_PARTS_HOME changes the local folder.
  • Blocked network. If a command reports HTTP 403 ... not from the LEGO server or cannot reach the server, a sandbox, proxy or firewall is blocking it. Ask the

[truncated for translation]

相关技能