LEGOパーツ認識とMOC設計
2段階のプロセス:
- スキャン. ユーザーがバラバラのパーツを撮影。サーバーが認識し、在庫を保持(ユーザーID単位)。
- 設計と検証. その在庫からモデル(MOC)を設計し、LDrawファイルとして作成。サーバーが物理的にチェック: 失敗時は該当行を指摘、合格時は3Dビューとステップバイステップの組み立て説明がある公開ページを発行。サーバーは設計は行いません。設計はあなたの仕事です。
2つの方法があります。MCPツール(セクション2)はシェルコマンド不要。利用可能な場合は常にこちらを使ってください。スクリプト scripts/lego.py(セクション5)はシェルコマンドで同じことを行い、フォールバックです。
1. MCPツールは利用可能ですか?
ツール一覧で以下の名前を探してください。通常、lego-moc のようなサーバープレフィックスが付いています(例: mcp__lego-moc__scan_photos や lego-moc.scan_photos):
scan_photos, scan_status, inventory, edit_inventory, design_guide, connectors, submit_model, moc_status
- すべて存在する: セクション2の手順で作業。
scan_photos以外はすべて存在する: ホストがリモートサーバーエンドポイントを使用しており、このコンピュータ上のファイルを読み取れません。写真のアップロードのみスクリプト(scan)を使用し、それ以外はツールで行います。- 何も存在しない: このタスクにはスクリプト(セクション5)を使用。すべて動作します。その後、ユーザーに以下のワンタイムセットアップを提案してください。これにより、コマンドごとの承認が不要になります。
ワンタイムセットアップ(ユーザーが行う)
python3 <このスキルフォルダ>/scripts/lego.py mcp-configを実行(Windows:python)。JSONブロックが出力され、ネットワーク呼び出しは行われません。- そのJSONをユーザーに渡し、エージェントのMCP設定(設定ページまたはMCP設定ファイル)の
mcpServersセクションにlego-mocエントリを追加するよう依頼し、エージェントを再起動するかMCPサーバーをリロードするよう促します。ユーザーから依頼された場合のみ、ホストの設定を直接編集してください。 - 再起動後、エージェントがブリッジ自体を起動し(
lego.py mcp、ローカルstdio MCPサーバー)、ツールが利用可能になります。同じ~/.lego-parts/フォルダとユーザーIDが使用されるため、これまでスキャンしたデータは失われません。
lego.py mcp-config --remote はサーバー自身のエンドポイントを出力します(type: http、ユーザーIDを含むURL。IDがない場合は作成)。ローカルコマンドを実行できないホストにのみ使用してください。scan_photosはなく、URLは認証情報です。決して公開しないでください。
2. MCPフロー
すべてのツール結果には、表示用のテキスト部分と、フィールドを含む structuredContent オブジェクトがあります。エラーは isError: true の結果として返され、テキストに何が起こったか、次に何をすべきかが記載されています。それに従ってください。独自のHTTP呼び出しで回避しないでください。
スキャン
scan_photos{"paths": [...]}: このコンピュータ上の写真ファイル、フォルダ、またはグロブパターンの絶対パス。1回の呼び出しで1~30枚の写真(JPEG、PNG、WEBP、HEIC、各25 MB)。すぐに戻り、写真ごとに1つのタスクを返します。認識が完了するのを待ちません。rejectedとnot_uploadedのすべてのエントリとその理由をユーザーに伝えてください。duplicate_photoエントリは、同じファイルが以前にアップロードされたことを意味します。再認識はされず、previousは最初のアップロードの結果(パーツはすでに在庫に含まれています)です。ホストがタイムアウトした場合、アップロードは続行されます。再アップロードせずにscan_statusを呼び出してください。多数の大きな写真がある場合は、約8枚ずつ複数回に分けて呼び出してください。scan_status{"wait_s": 50}:pendingが0になるまで繰り返します(認識には数分かかります。最初の写真はGPU起動を待つ場合があります)。noticesのすべてのエントリ(pile_photo、no_pieces)をユーザーにそのまま伝え、失敗した写真をそのerrorとともに名前を挙げてください。長時間 pending が続く場合は、永遠にループせずに、まだ処理中の写真の枚数をユーザーに伝えてください。
在庫の表示と修正
inventory: 概要画像(結果内の画像)とinventory_url付きで在庫を表示します。ユーザーに画像を表示し、リンクを渡してください。ブラウザやプレビューパネルがある場合は、そこでリンクを開いてください。素のパーツ番号の表を提示しないでください。ほとんどのユーザーは3020が何かを識別できません。低信頼度の行(画像内で枠がオレンジ色で?が表示)を指摘し、ページ上で確認するようユーザーに依頼してください。designable: falseの行は使用可能な3D形状がなく、決して組み立てに使用できません。pending_tasks > 0は在庫が不完全であることを意味します。その旨を伝えてください。在庫が多い場合は、filter: "usable"または"low_confidence"とoffset/limitを使用してください。edit_inventory{"changes": [...]}、ユーザーの指示があった場合のみ(設計に合わせるため決して行わないこと):{"op": "set_quantity", "key": "3001|4", "quantity": 3}、{"op": "remove", "key": ...}、{"op": "confirm", "key": ...}(ユーザーが低信頼度行を確認し、正しかった場合)、{"op": "replace", "key": ..., "ldraw_part": "3002", "ldraw_color": 4}(実際には別のパーツまたは色の場合)、{"op": "add", "ldraw_part": "3003", "ldraw_color": 14, "quantity": 2}、{"op": "undo", "key": ...}、{"op": "undo_all"}。各変更はokを報告します。適用されなかったものとその理由をユーザーに伝えてください。ユーザーは在庫ページ上でも同じ編集を行うことができます。
設計
- リクエストを理解する(セクション3): テーマ、説明、参考画像、または何もなし。設計前に在庫で対応可能か確認してください。
design_guide: 会話内での最初の設計前にガイド全体を読んでください。サーバーの現在のルールブックです。ファイル形式、座標、コネクタの組み合わせ、検証ルール、実例、多くのパーツの使い方が含まれています。また、usable_quantityとtarget_percentも返します。connectors{"parts": ["3001", "3023", ...]}(1回の呼び出しで1~40個のLDrawパーツ番号): 使用予定の各パーツのバウンディングボックスとすべてのコネクタ。各パーツの原点とコネクタ位置はここから取得してください。決して推測しないでください。unsupportedとして報告されたパーツは使用できません。- モデルを作成:
0 <タイトル>行、その後、パーツごとに1 <色> x y z a b c d e f g h i <パーツ>.datの行。<色>= 在庫のldraw_color、<パーツ>=ldraw_part。使用可能な行のみ、かつ各keyについてモデル全体で最大quantityの個数まで。提出前にカウントしてください。サブモデルや0 STEP行はなし。
検証と改善
submit_model{"ldr": "<ファイル全体>", "title": "...", "brief": "<ユーザーのリクエスト、ユーザーの言葉そのまま>"}。同じモデルの新バージョンを提出する場合は"moc_id"を追加。可動部品を宣言する場合のみ"design"を追加(ガイド参照)。wait_s(デフォルト45)まで待ち、status、issues(各失敗はルール名、ヒント、該当パーツとそのファイル行・位置を示す)、usage、resubmissions_left、合格時はurlと2つのプレビュー画像を返します。statusがまだ最終状態でない場合(queued、checking、stepping)、moc_status{"moc_id": ..., "wait_s": 50}を呼び出してください。errorステータスはサーバー側の障害であり、設計の問題ではありません。同じモデルをmoc_id付きで再提出してください。- 失敗: 名前の挙がった行だけを修正し(
connectorsから位置を再計算し、数値を微調整しない)、moc_id付きで再提出してください。 - 合格: 両方のプレビューと
usageを確認し、もう一度やり直す価値があるか判断してください(セクション4)。公開ページには常に最新の合格バージョンが表示されます。後続のラウンドで失敗しても、公開ページは非表示になりません。 - 報告: ユーザーに公開
url(公開であることを伝える)、パーツ数とステップ数、すべての警告、作成したもの、できなかったことを伝えてください。合格は、検証ツールのシミュレーション内でモデルが物理的に矛盾しないことを意味し、実際の組み立てが保証されるわけではありません。その旨を伝えてください。
3. 設計リクエスト
ユーザーはテーマ("車")、詳細な説明、参考画像、または何も与えない場合があります。
- まず実現可能性を確認。 何かを約束する前に、在庫(形状、色、数量)を確認してください。車には車輪と車軸、またはそれを代替できるものが必要です。家には壁用の十分なブロックと屋根用のパーツが必要です。何が満たせて何が満たせないかをユーザーに明確に伝え、無理に設計するのではなく、パーツで可能な代替案(小型版、別のテーマ、スタイライズ版)を提案してください。
- 説明: ユーザーが指定した特徴は維持し、どの特徴を削除または変更したか、その理由を伝えてください。
- 参考画像(画像を見られる場合のみ): ユーザーが所有するパーツから、その画像の精神(形状、比率、主な色)に沿ったモデルを作成してください。複製にはなりません。その旨を伝えてください。
- 何も与えられない場合: 在庫に適したテーマ(主要な色と最も多く含まれる形状)を選び、選択した内容を伝えてください。
- ユーザーのリクエストテキストをそのまま
briefとして渡してください。タイトルにテーマを入れてください。 - 薄い在庫. 使用可能なパーツが60個未満、または在庫が大部分が単一パーツで多くの色に分散している場合、設計前にユーザーに伝えてください。小さなモデルまたは抽象的なモデルしか作成できません。低信頼度行を(在庫ページで確認後)確認することと、さらにパーツを広げて写真を撮ることを提案してください。すでにカウント済みのパーツの新しい写真はそれらを再度カウントします。まだスキャンしていないパーツを撮影するか、その後
set_quantityで数量を修正することを提案してください。
4. 多くのパーツを使用し、改良する
- 目標: ユーザーが小さなものを求めていない限り、使用可能なパーツの少なくとも60%を使用する(
usage.target_percent)。usage.percentは各提出結果で現在の達成度を示し、usage.unusedは残りのパーツを多い順にリストします。 - 作業を段階的に行う。 バージョン1: 主要構造(ベース、ボディ、大きな形状)。後のバージョンでは、大きなステップで詳細を追加: 屋根仕上げ、窓とドア、手すり、装飾、ベースプレートや地面。モデルごとに再提出は5回のみなので、各ラウンドで大幅に追加する必要があります。1つのパーツのために再提出を使わないでください。
- 毎回の結果:
usageとunusedを読み、どの未使用パーツがテーマをより良くするかを尋ねてください。合格時は、両方のプレビューを確認し、間違っている箇所を修正: 色の混在、上面の露出スタッド、テーマが対称なのに非対称な形状、平らな箱。ガイドのアドバイスセクションにその方法が記載されています。 - モデルが良好で目標を達成したとき、在庫から意味のある追加ができないとき、または再提出を使い切ったときに停止してください。最終的な使用率をユーザーに伝えてください。
5. スクリプトフォールバック
MCPツールが利用できない場合にスクリプトを使用します。Python 3.8以上、標準ライブラリのみ、インストール不要。
python3 <このスキルフォルダ>/scripts/lego.py <コマンド> [オプション] [引数]
Windowsでは python または py -3 を使用してください。オプションは写真リストの前に置いてください。
ユーザーの承認を最小限に。 多くのエージェントは、新しいシェルコマンド、ネットワークホスト、ワークスペース外への書き込みのたびにユーザーの承認を求めます。そのため:
- スクリプトは常にこの正確な形式で、1つの単純なコマンドとして呼び出してください。
cd、パイプ、&&、環境変数プレフィックス、ラッパースクリプトは使用しないでください。そうすれば、ユーザーはpython3 <パス>/lego.pyに対して一度「常に許可」を承認できます。最初の承認が表示されたときにこのことをユーザーに伝え、承認を回避できるMCPセットアップ(セクション1)についても言及してください。 - スクリプトに必要な3つのこと(
lego.pyの実行、lego.py whoamiで表示されるサーバーホストへのアクセス、~/.lego-parts/の読み書き)は、ユーザーが一度許可できます。 - 同じ手順を2回実行しないでください。短いコマンドのループでポーリングしないでください(
--waitを使用)。curlや独自のコードでサーバーを呼び出さないでください。 model.ldrはファイル書き込みツールを使用して、できるだけ少ないステップで作成してください。使い捨てスクリプトの連続は避けてください。
| コマンド | 説明 |
|---|---|
scan [--no-wait] [--wait SECONDS] [--images] PHOTO... | 1~30枚の写真(ファイル、フォルダ、グロブパターン)をアップロードし、デフォルトで最大480秒待機して結果を保存。--no-wait はアップロード後すぐに戻る。 |
status [--wait SECONDS] [--images] [TASK_ID...] | 保留中のタスク(または指定されたタスク)を1回チェックするか、SECONDS秒までポーリングを続ける。完了したタスクを保存。 |
parts [--images] | 完了した保留タスクを保存し、その後、在庫全体(在庫ページまたは edit_inventory で行った編集を含む)を parts.json に再読み込み。 |
whoami | ユーザーID、サーバー、ローカルフォルダを表示。ネットワーク不要。 |
moc guide [--parts-file PATH] | 設計ガイド moc/DESIGN_GUIDE.md とパーツのコネクタシート moc/connectors.txt を保存。 |
moc submit [--title NAME] [--brief TEXT] [--design design.json] [--moc MOC_ID] [--parts-file PATH] [--no-wait] [--wait SECONDS] MODEL.ldr | parts.json と共にモデルを送信し、デフォルトで最大300秒待機してチェック結果、パーツ使用率、合格時はプレビューリンクを出力。--moc は既存のMOCの新バージョンを提出。--brief はユーザーのリクエスト。 |
moc status [--wait SECONDS] [MOC_ID] | 保留中のMOC提出(または指定されたもの)を1回チェックするか、SECONDS秒までポーリング。 |
mcp-config [--remote] | MCPセットアップのJSONを出力(セクション1)。出力はそのJSONのみ。RESULT行はなし。 |
mcp | MCPブリッジ自体。エージェントホストが実行します。自分で実行しないでください。 |
--images は各在庫行のLDraw画像と写真クロップを images/ にダウンロードします。
- 長時間待機.
scanは最大8分、moc submitは最大5分実行される場合があります。シェルツールのタイムアウトが短い場合は、タイムアウトを延長するか、より小さい--wait(例:--wait 100)を渡し、status --wait 100/moc status --wait 100で続行してください。待機中に停止しても安全です。IDは最初にpending.json/moc/pending.jsonに保存され、後でどのエージェントのどのコマンドでも収集できます。 - サーバーアドレス. ダウンロードしたスクリプトに組み込まれています。サーバーが設定されていないとコマンドが報告した場合、ユーザーは
LEGO_PARTS_SERVERを設定する必要があります(例:https://lego.groundrl.com、/skill/v1は除く)。LEGO_PARTS_HOMEでローカルフォルダを変更できます。 - ネットワークブロック. コマンドが
HTTP 403 ... not from the LEGO serverまたはサーバーに到達できないと報告した場合、サンドボックス、プロキシ、ファイアウォールがブロックしています。ユーザーにその旨を伝え、ネットワーク設定を確認するよう依頼してください。