MCP Server API 仕様 (v0.2 / v0.3)
適用バージョン:
@dta-tutorials/mbp-mcp-server@0.3.0以降 (MakeBuilding Pro v5.5.0 同梱) 最終更新: 2026-05-31 ステータス: Implemented & Released プロトコル: MCP 2025-11-25 関連: MCP セットアップガイド / GH 編集モード協調ロック契約
ℹ️ 本ページは概要ページです。完全な技術仕様 (各ツールのパラメータ詳細、エラーモデル、retry ロジック等) は MakeBuilding Pro に同梱されている
docs/MCP_v0.2_API_Spec.md(Yak install 後は%APPDATA%\Grasshopper\Libraries\docs\配下) を参照してください。
1. v0.2 / v0.3 で達成すること
v0.1 (Read-only) で AI が建物データを「理解」できるようになりました。v0.2 / v0.3 では AI が建物データを「編集」できるようにします。これにより、次のような対話的設計フローが成立します:
ユーザー: "X1 通りの 1F 柱を SC_500x500 に変更して"
↓
Claude が bulk_modify ツールを 1 回呼出
↓
.mbp.json が更新される
↓
(Watch=True なら) Grasshopper が自動再読込
↓
3D / 解析 / 図面が即時更新2. ツール総数
| 区分 | ツール数 |
|---|---|
| Read tools (常時有効) | 25 |
Write tools (MBP_WRITE_ENABLED=true で有効化) | 23 |
| 合計 | 48 |
3. Read tools (25)
| グループ | ツール |
|---|---|
| Meta | read_building, get_summary, get_metadata, get_grids, get_levels, get_catalog, validate |
| Vertical | get_columns, get_posts, get_piles |
| Horizontal | get_beams, get_sec_beams, get_tertiary_beams, get_cantilever_beams, get_slabs, get_cantilever_slabs |
| Envelope | get_walls, get_braces, get_wall_openings, get_slab_openings |
| Foundation / Loads | get_foundations, get_beam_point_loads, get_beam_line_loads |
| Query | find_by_id, find_at_grid |
4. Write tools (23)
| グループ | ツール |
|---|---|
| Add (14) | add_column, add_main_beam, add_sec_beam, add_tertiary_beam, add_wall, add_slab, add_brace, add_post, add_cantilever_beam, add_cantilever_slab, add_foundation, add_pile, add_wall_opening, add_slab_opening |
| Bulk (3) | bulk_modify, bulk_delete, replace_catalog |
| Modify (3) | modify_by_id, delete_by_id, move_member |
| Meta (3) | save, undo, validate_with_auto_fix |
すべての Write tool が path / auto_save (default true) / dry_run (default false) を共通入力として持ちます。
5. v5.5.0 schema 拡張 (#138)
v0.3.0 では BuildingData v5.5.0 のスキーマ追加に対応:
5.1 justification 入力 (5 ツールに追加)
add_main_beam / add_sec_beam / add_tertiary_beam / add_cantilever_beam / add_brace に optional justification: 'Top' | 'Center' | 'Bottom' を追加。
add_main_beam/add_cantilever_beam/add_brace: top-level にJustificationフィールドとして格納add_sec_beam/add_tertiary_beam:Spans[]の各 entry にJustificationを伝播 (単一値を全 Span に適用)
デフォルト:
- 梁系:
Top(構造設計の慣習) - Brace:
Center(柱・大梁交点に芯合わせ)
5.2 validate の追加ルール
| ID | ルール | 重要度 |
|---|---|---|
| R5_Justification_Valid | Justification 値が Top / Center / Bottom のいずれか | Error |
| R6_DesignPhase_Valid | Building_Metadata.Design_Phase が Schematic / DD / CD / Construction のいずれか | Warning |
| R7_SlabOnBeam_Consistency | Slab_On_Beam=true の場合 Slab_Type_ID が空でないこと | Warning |
5.3 既知バグ修正
LAYOUT_TO_CATALOG:CantileverBeam→SecondaryBeamcatalog (旧実装は誤ってMainBeamを参照していた)schema_version.ts:5.3.x/5.5.x検知追加 (旧実装は v5.2 まででunknownになっていた)
6. ファイルロックと永続化
proper-lockfileによるプロセス間排他制御- GH 編集ロック (
<target>.gh-editingマーカーで Grasshopper 側との競合回避) — 詳細は GH ロック契約 を参照 - Atomic write (一時ファイル → fsync → rename)
- 世代バックアップ (
.bak,.bak2,.bak3) - メモリ内 Undo Stack (デフォルト 10 段、
undoツールで巻き戻し可)
7. 安全機構 (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 世代保持 |
8. 後方互換性
v0.1 → v0.2 → v0.3 で Read tools (25 個) は完全後方互換。既存の v0.1 利用者は設定変更なしで v0.3 にアップグレード可能。
Write tools は default で 無効 のため、v0.1 互換 (Read-only) 動作が維持される。
9. 完全な仕様
本ページは概要のみです。各ツールの:
- 詳細な入力スキーマ (zod schema)
- 出力フォーマット
- エラーコード一覧
- リトライアルゴリズム (
validate_with_auto_fix) - マイグレーション手順
などは、MakeBuilding Pro 同梱の docs/MCP_v0.2_API_Spec.md (Yak install 後は %APPDATA%\Grasshopper\Libraries\docs\ 配下) を参照してください。
関連ページ
- MCP 連携について — アーキテクチャ概要
- MCP セットアップガイド — インストールと設定
- GH 編集モード協調ロック契約 — Grasshopper 連携時のロックプロトコル
- AI 機能 利用規約