Panna3d

Appearance

MCP Server API 仕様 (v0.5.1) ​

適用バージョン: @dta-tutorials/mbp-mcp-server@0.5.0 (MakeBuilding Pro v5.9.0 同梱) 最終更新: 2026-07-14 ステータス: Implemented & Released 関連: MCP セットアップガイド / GH 編集モード協調ロック契約

ℹ️ 本ページは概要ページです。完全な技術仕様 (各ツールのパラメータ詳細、エラーモデル、retry ロジック等) は MakeBuilding Pro に同梱されている docs/MCP_v0.2_API_Spec.md (Yak install 後は %APPDATA%\McNeel\Rhinoceros\packages\8.0\MakeBuildingPro\<version>\docs\ 配下) を参照してください。

1. できること ​

AI が BuildingData (.mbp.json) を「理解」し (Read tools)、opt-in で「編集」できます (Write tools)。これにより、次のような対話的設計フローが成立します:

ユーザー: "X1 通りの 1F 柱を SC_500x500 に変更して"
   ↓
Claude が bulk_modify ツールを 1 回呼出
   ↓
.mbp.json が更新される
   ↓
(Watch=True なら) Grasshopper が自動再読込
   ↓
3D / 解析 / 図面が即時更新

2. ツール総数 ​

区分ツール数
Read tools (常時有効)26
Write tools (MBP_WRITE_ENABLED=true で有効化)25
合計51

3. Read tools (26) ​

常時有効。環境変数の設定なしで利用できます。

3.1 Meta / Query (10) ​

ツール説明
read_building.mbp.json を読み込みアクティブ建物として登録 (以降の get_* の対象になる)
get_summary階・通り芯・全 16 Catalog・全 18 Layout の件数サマリー
get_metadataBuilding_Metadata (設計規準・地震・地盤) と Global (原点・単位・北方向)
get_grids通り芯を X/Y 軸別・原点距離昇順で返却。v0.5: 移動交点 nodes を含む
get_levels階 (Level) 一覧を標高昇順で返却
get_catalog16 種の Catalog の汎用アクセサ (name で種類選択、type_id で単一検索)
validate軽量サーバー側検証 (Instance_ID 一意性 / Floor 参照 / Type_ID 参照 ほか)
get_approval_statsDiff & Approval 監査ログ (*.approved.json) の集計 (v0.4 追加)
find_by_id全 18 Layout を Instance_ID (GUID) で横断検索
find_at_grid(floor, 交点) 位置の部材検索 (Column / Post / IsolatedFoundation / Pile)

3.2 部材別 Layout 取得 (16) ​

いずれも floor / type_id / mark 等の optional フィルタと limit / offset ページングを持ちます。

ツール説明
get_columnsLayout_Column (柱)
get_postsLayout_Post (間柱)
get_pilesLayout_Pile (杭。配置 1P/5P/7P/8P フィルタ可)
get_beamsLayout_MainBeam (大梁)
get_sec_beamsLayout_SecondaryBeam (小梁。Spans[] / Trailing_Slab_Type_ID を保持したまま返却)
get_tertiary_beamsLayout_TertiaryBeam (孫梁。parent_instance_id / parent_area_code フィルタ可)
get_cantilever_beamsLayout_CantileverBeam (片持ち梁。Beam / BeamNose)
get_slabsLayout_Slab (トップレベルのスラブのみ。Spans 内は get_sec_beams で)
get_cantilever_slabsLayout_CantileverSlab (片持ちスラブ)
get_wallsLayout_Wall (壁)
get_bracesLayout_Brace (ブレース。Single / X / V / K フィルタ可)
get_wall_openingsLayout_WallOpening (壁開口。親壁 parent_instance_id フィルタ可)
get_slab_openingsLayout_SlabOpening (スラブ開口)
get_foundations基礎 3 種 (Isolated / Strip / Mat) を一括返却。kind で絞込み
get_beam_point_loadsLayout_BeamPointLoad (梁集中荷重)
get_beam_line_loadsLayout_BeamLineLoad (梁線分布荷重)

4. Write tools (25) ​

すべて MBP_WRITE_ENABLED=true の設定が必須です (デフォルト無効 = read-only)。加えて GH 編集ロック契約 の配下にあり、Grasshopper 側エディタが対象ファイルを編集中は拒否されます。

4.1 Add (14) ​

ツール説明
add_columnLayout_Column を追加 (floor / type_id / grid_intersection を検証、Instance_ID 自動生成)
add_main_beamLayout_MainBeam を追加 (重複検査あり。逆向き start↔end も衝突扱い)
add_sec_beamLayout_SecondaryBeam を追加 (Spans[] を Division 数で自動初期化)
add_tertiary_beamLayout_TertiaryBeam を追加 (親小梁の存在 / Span_Index 範囲 / 直交方向を検証)
add_wallLayout_Wall を追加 (wall_load_id は Catalog_WallLoad と照合)
add_slabトップレベルの Layout_Slab を追加 (Spans 内スラブは対象外)
add_braceLayout_Brace を追加 (brace_orientation: Single / X / V / K)
add_postLayout_Post を追加
add_cantilever_beamLayout_CantileverBeam を追加 (Catalog_MainBeam を共用)
add_cantilever_slabLayout_CantileverSlab を追加
add_foundation基礎を追加 (isolated=交点 / strip=start+end / mat=area_code)
add_pileLayout_Pile を追加 (配置 1P / 5P / 7P / 8P)
add_wall_openingLayout_WallOpening を追加 (親壁 Parent_Instance_ID 必須)
add_slab_openingLayout_SlabOpening を追加 (既存スラブ領域内であること)

4.2 Modify / Bulk (6) ​

ツール説明
modify_by_idInstance_ID で特定した 1 レコードに patch を shallow-merge (Instance_ID は不変)
delete_by_idInstance_ID で 1 レコード削除 (子参照が残る場合は cascade=true が必要)
move_member位置フィールド (Floor / Grid_Intersection / Start_Grid / End_Grid / Area_Code / Offset_*) の変更
bulk_modify単一 Layout 内の複数レコードを一括変更 (空フィルタ拒否、100 件超は confirm=true 必須)
bulk_delete単一 Layout 内の複数レコードを一括削除 (子参照は cascade=true、100 件超は confirm=true)
replace_catalog指定 Catalog の Type_ID を全 Layout 横断で置換 (SecondaryBeam / TertiaryBeam の Spans[] も対応)

4.3 形状操作 (2) ​

ツール説明
set_bay_voidベイ単位の欠き取り一括トグル (v0.4 追加。詳細は §6)
set_grid_node_offsetグリッド交点の水平移動 (v0.5 追加。詳細は §7)

4.4 Meta (3) ​

ツール説明
saveメモリ内の BuildingData をディスクへ永続化 (atomic write + .bak ローテーション)
undo直近 N 操作をメモリ内 Undo Stack から巻き戻し、自動保存
validate_with_auto_fix軽量検証を retry ループで実行し、自動修正可能なルール (現状 R2_Floor_Valid) を適用

5. Write tools の共通挙動 (永続化・undo・dry_run・auto_save) ​

すべての Write tool は共通入力 path / auto_save (default true) / dry_run (default false) を持ち、共通実行フロー (executeWrite) を通ります:

  1. opt-in ガード — MBP_WRITE_ENABLED=true でなければ CorrectableToolError で拒否
  2. 対象解決 + サンドボックス検証 — path 省略時は最後に読み込んだ建物。MBP_ROOT 配下であること
  3. GH 編集ロック検査 — <target>.gh-editing が存在すれば拒否 (契約)
  4. ファイルロック取得 — proper-lockfile (タイムアウト MBP_LOCK_TIMEOUT_MS、default 5 秒)
  5. 変更実行 — メモリ内の BuildingData を変更
  6. Undo Stack へ push — 逆操作を記録 (MBP_UNDO_STACK_SIZE 段、default 10)
  7. auto_save — auto_save=true (default) なら atomic write (一時ファイル → fsync → rename) + .bak 世代バックアップ (MBP_BACKUP_GENERATIONS、default 3) で永続化
  8. ロック解放

補足:

  • dry_run=true: 変更のプレビューのみ。ディスク書込みも Undo Stack への push も行わない
  • auto_save=false: メモリ内のみ変更し、後でまとめて save を呼ぶ運用が可能
  • 各 Write tool のレスポンスには auto_saved / dry_run フラグが必ず含まれる
  • 訂正可能なエラー (存在しない Floor / Grid ラベル等) は isError: true + Hint 付きテキストで返り、AI が自己訂正リトライできる (CorrectableToolError)

6. v0.4 追加分 (MakeBuilding Pro v5.7.0 同梱) ​

6.1 set_bay_void (Write) — ベイ単位の欠き取り ​

Layout Editor (D04) の「このベイを欠く / 戻す」の MCP 版。L 字・セットバック等の非整形平面を Is_Void=true で表現するワークフローを AI から実行できます。

  • 指定 floor + area_code (完全一致のみ。部分包含・ベイ分解はしない) の Layout_Slab / Layout_SecondaryBeam、およびその小梁を親とする Layout_TertiaryBeam (Parent_Instance_ID、または人間可読キー Parent_Area_Code) の Is_Void を一括設定
  • 境界部材 (大梁・柱) には触れない — void ベイでも境界の骨組は残るのが規約
  • レスポンスに Layout 種別ごとの件数 (breakdown) と対象 instance_ids を返却

6.2 get_approval_stats (Read) — 承認統計 ​

Diff & Approval の監査ログ *.approved.json (.mbp.json の隣に出力される) をセッション別・全体で集計します。総数 / 承認 / 却下件数、承認率、カテゴリ別の承認変更数を返します。単一ファイルまたはディレクトリ (subdirectory は recursive=true) を指定可能。read-only で建物キャッシュを使いません。

7. v0.5 追加分 (MakeBuilding Pro v5.9.0 同梱) ​

7.1 set_grid_node_offset (Write) — グリッド交点の移動 ​

BuildingData v5.9.0 の Grid_Nodes (方式A: 交点単位の水平移動) に対応する Write tool です。

  • 指定交点 (x_label, y_label) の Grid_Nodes エントリを upsert (無ければ追加、あれば更新)。レスポンスの action は added / updated / removed / noop
  • (0, 0) を指定するとエントリを削除 (疎記録原則 — 零行は保存しない)
  • ラベル実在検査: x_label / y_label が Grids に存在しなければ CorrectableToolError (利用可能なラベル一覧を Hint で提示)
  • 実座標 = 名目グリッド位置 + Offset。通り芯は移動後の交点を結ぶ折れ線になる
  • 健全性判定 (順序保存 V-N1 / ベイ凸性 V-N2 等) は C# 側 Validator (Comp_V01 / GridNodeRuleCore) が正 — 本ツールはラベル実在と数値健全性のみ検査
  • 床領域 (スラブ・小梁等) も MakeBuilding Pro v5.10.0 から移動交点に追随する (v5.9.0 の V-N10 面ゲートは撤去。極端に歪んだ区画は V-Q 群の Warning)

7.2 get_grids の nodes 拡張 (Read) ​

get_grids のレスポンスに nodes 配列が追加されました:

  • Grid_Nodes のうち非零オフセットのみ (疎)。X_Label → Y_Label の数値順で決定的に整列
  • counts に nodes 件数を含む
  • 交点移動を使っていないファイルでは空配列 (完全後方互換)

8. v0.3 スキーマ対応 (参考: v5.5.0 同梱時の拡張) ​

  • justification 入力 ('Top' | 'Center' | 'Bottom') を add_main_beam / add_sec_beam / add_tertiary_beam / add_cantilever_beam / add_brace に追加 (梁系 default Top、Brace default Center。小梁・孫梁は Spans[] の各 entry に伝播)
  • validate の実装ルール: R1_InstanceID_Unique / R2_Floor_Valid / R3_TypeID_Valid (Error)、R5_Justification_Valid (Error)、R6_DesignPhase_Valid / R7_SlabOnBeam_Consistency (Warning)

9. ファイルロックと永続化 ​

  • proper-lockfile によるプロセス間排他制御
  • GH 編集ロック (<target>.gh-editing マーカーで Grasshopper 側との競合回避) — 詳細は GH ロック契約 を参照
  • Atomic write (一時ファイル → fsync → rename)
  • 世代バックアップ (.bak, .bak2, .bak3)
  • メモリ内 Undo Stack (デフォルト 10 段、undo ツールで巻き戻し可)

10. 安全機構 (Defense in Depth) ​

Layer機構
1: opt-in ガードMBP_WRITE_ENABLED=true がデフォルトで無効
2: サンドボックスMBP_ROOT 配下のみ操作可、配下外は throw
3: GH 編集ロック<target>.gh-editing ファイルで Grasshopper 側と協調
4: ファイルロックproper-lockfile で同時編集を防止 (default タイムアウト 5 秒)
5: Undo Stackプロセス内に直近 N 操作を保持
6: バックアップ書込み前に .bak を最大 3 世代保持

11. 後方互換性 ​

サーバー版同梱プラグイン版ツール数追加内容
v0.1—Read 25Read-only 初版
v0.2 / v0.3.0v5.5.048 (Read 25 + Write 23)Write tools 一式 + v5.5.0 スキーマ対応
v0.4.0v5.7.050 (Read 26 + Write 24)get_approval_stats + set_bay_void
v0.5.0v5.9.051 (Read 26 + Write 25)set_grid_node_offset + get_grids の nodes 拡張
v0.5.1v5.10.051 (Read 26 + Write 25)set_grid_node_offset の説明を v5.10.0 仕様に更新 (V-N10 撤去 — ツール挙動・スキーマは不変)
  • Read tools は 追加のみで完全後方互換。既存利用者は設定変更なしでアップグレード可能
  • Write tools は default で無効のため、Read-only 動作が維持される
  • Grid_Nodes を使わないファイルの出力はバイト同一 (静穏出力)

12. 完全な仕様 ​

本ページは概要のみです。各ツールの:

  • 詳細な入力スキーマ (zod schema)
  • 出力フォーマット
  • エラーコード一覧
  • リトライアルゴリズム (validate_with_auto_fix)
  • マイグレーション手順

などは、MakeBuilding Pro 同梱の docs/MCP_v0.2_API_Spec.md (Yak install 後は %APPDATA%\McNeel\Rhinoceros\packages\8.0\MakeBuildingPro\<version>\docs\ 配下) を参照してください。

関連ページ ​

更新履歴 ​

日付内容
2026-07-16v0.5.1 対応 — set_grid_node_offset の注意書きを v5.10.0 仕様に更新 (V-N10 面ゲート撤去 — 床領域も移動交点に追随、歪みは V-Q 群の Warning)
2026-07-14v0.5.0 を正とする本文に全面改稿 (51 ツール = Read 26 + Write 25、set_grid_node_offset / get_grids nodes 拡張、v0.4 追加分の統合、共通挙動 §5 新設、同梱ドキュメントのパス修正)
2026-05-31v0.2 / v0.3 版 (48 ツール)