GH 編集モード協調ロック契約

対象バージョン: @dta-tutorials/mbp-mcp-server@0.3.0 以降 (現行 v0.5.0 / MakeBuilding Pro v5.9.0 同梱)。プロトコルは v0.2.0-alpha.6 から不変・完全後方互換。最終更新: 2026-07-14 関連: MCP API 仕様 / MCP セットアップガイド

1. なぜ必要か

MCP Server の Write Tools (add_*, modify_by_id, bulk_*, set_bay_void, set_grid_node_offset 等の 25 個) が AI 経由で .mbp.json を編集 する間に、ユーザーが Grasshopper の D01-D09 系エディタを開いて 同じファイルを編集中 だと、保存タイミングによっては変更が競合・上書きされる事故が起きます。

これを防ぐため、Grasshopper 側がエディタを開いている間 だけ、対象 .mbp.json と同じディレクトリに 空のマーカーファイル <target>.gh-editing を置きます。MCP Server の Write 系 Tool 群は書込前にこのファイルの存在を検査し、存在すれば CorrectableToolError で拒否します。

2. ファイル仕様

項目	値
ファイル名	`<target>.gh-editing` (例: `office.mbp.json.gh-editing`)
内容	空ファイルで OK。中身は無視される
拡張子のカスタマイズ	`MBP_GH_EDIT_LOCK_EXT` 環境変数で変更可 (default `.gh-editing`)
stale 閾値	mtime が 1 時間以上前ならロック無効 (= プロセスクラッシュ救済)
作成タイミング	エディタ Form の Show 直前
削除タイミング	エディタ Form の Close / Dispose 時

3. Grasshopper 側 (C#) 実装

MakeBuilding Pro では、以下のエディタ・コンポーネントに統合済です (GhEditingLock クラス + optional File 入力。v5.5.0 で統合、現行 v5.9.0 も同一):

コンポーネント	編集対象	統合状態
D03 Catalog Editor	Catalog_*	✅
D04 Layout Editor	Layout_*	✅
D06 Grids Editor	Grids (+ v5.9.0: Grid_Nodes「Node Offsets」タブ)	✅
D07 Levels Editor	Levels	✅
D08 Load Setting Editor	Load_Settings	✅
D09 Building Frame Editor	Metadata + Levels + Grids	✅
D01 UI Data Editor	(legacy 総合)	📋 計画中 (低優先)

利用方法

Grasshopper 上での配線:

[File path string] ──┬─→ Comp_I03_JsonImport.File
                     ├─→ Comp_D03_CatalogEditor.File
                     ├─→ Comp_D04_LayoutEditor.File
                     ├─→ Comp_D06_GridsEditor.File
                     ├─→ Comp_D07_LevelsEditor.File
                     ├─→ Comp_D08_LoadSettingEditor.File
                     ├─→ Comp_D09_BuildingFrameEditor.File
                     └─→ Comp_E03_JsonExport.File

File を未配線にしておくと、エディタは MCP 協調ロックを 取得しません (Grasshopper 内完結フローでは省略可)。
File 配線 + エディタを Open すると、対象 .mbp.json の隣に <file>.gh-editing マーカーが作成され、MCP の Write Tools は CorrectableToolError を返します。
エディタを Close すると <file>.gh-editing は自動削除されます。
Grasshopper を強制終了した場合は MCP 側の 1 時間 stale 救済 によって自動無効化されます。

4. MCP Server 側の挙動

4.1 検査タイミング

全 25 Write tools がロックを尊重します。共通実行フロー executeWrite (add_* 14 個 / modify_by_id / delete_by_id / move_member / bulk_modify / bulk_delete / replace_catalog / set_bay_void / set_grid_node_offset) と、独自フローの save / undo / validate_with_auto_fix の ファイルロック取得前 に checkGhLock() が実行されます。

4.2 ロック検出時の応答

jsonc

{
  "isError": true,
  "content": [{
    "type": "text",
    "text": "Grasshopper editor is currently editing this file (gh-editing lock present).\n\nHint: Close the GH editor (D01-D09) or save its changes first. Lock file: D:\\projects\\office.mbp.json.gh-editing (mtime: 2026-07-14T02:30:00.000Z)"
  }]
}

CorrectableToolError なので Claude は ユーザーに「GH を閉じてから再試行してください」と案内 します。

4.3 stale 救済

GH のクラッシュやプロセス強制終了でロックファイルが残ったままになる場合に備え、mtime が 1 時間以上前なら自動的に無視 されます。手動削除も可能です。

5. テスト方法

5.1 GH 経由実機テスト (推奨)

Grasshopper を起動して .mbp.json を I03 で読込
同じ File パス Panel を D03/D04/D06/D07/D08/D09 いずれかの File (F) 入力にも配線
エディタコンポーネントの Open を True に
コンポーネント上の Remark に GH lock acquired: D:\...\file.mbp.json.gh-editing が出ることを確認
ディスク上に .gh-editing ファイルが実在することを確認
Claude Desktop で書込み依頼 (例: add_column) → CorrectableToolError が返り、Claude が「GH を閉じてください」と案内
エディタの Open を False に or × で閉じる → .gh-editing 自動削除
Claude で再度書込み依頼 → 成功

5.2 トラブルシュート

症状	原因	対処
`Warning: File input is empty`	`File` 入力未配線	I03 と同じパス Panel を `File (F)` 入力に配線
`Warning: GH lock NOT acquired: IOException`	ファイル作成失敗 (権限/AV/読み取り専用)	フォルダ書込権限を確認、AV 例外設定
`Warning: GH lock NOT acquired: anti-virus`	AV が即削除	`.gh-editing` を AV 除外リストへ
ロック有るのに MCP が書ける	パスの不一致	コンポーネントの Remark が示す `LockPath` と MCP の `entry.path + ".gh-editing"` を比較
MCP が `.gh-editing` を全く見ない	`MBP_GH_EDIT_LOCK_EXT` 不一致	両側で同値か確認 (デフォルト `.gh-editing`)
ロック残ったまま	プロセスクラッシュ	1 時間で stale 自動無視。即時解除は手動削除

6. 完全な実装詳細

C# 側の実装パターン (GhEditingLock クラス、エディタ Form での使用例) や、TypeScript 側の checkGhLock() 関数の完全な仕様、テストスイートの内訳などは、MakeBuilding Pro 同梱の docs/MCP_v0.2_GH_Lock_Contract.md (Yak install 後は %APPDATA%\McNeel\Rhinoceros\packages\8.0\MakeBuildingPro\<version>\docs\ 配下) を参照してください。

更新履歴

日付	内容
2026-07-14	v0.5.0 対応 — 対象バージョン表記を更新、検査対象を全 25 Write tools (`set_bay_void` / `set_grid_node_offset` 含む) に更新、ロック検出時の応答例を実装のメッセージ文言に一致させた、同梱ドキュメントのパス修正。ロックプロトコル自体は変更なし
2026-05-31	初版 (v0.3.0 / v5.5.0)

GH 編集モード協調ロック契約 ​

1. なぜ必要か ​

2. ファイル仕様 ​

3. Grasshopper 側 (C#) 実装 ​

利用方法 ​

4. MCP Server 側の挙動 ​

4.1 検査タイミング ​

4.2 ロック検出時の応答 ​

4.3 stale 救済 ​

5. テスト方法 ​

5.1 GH 経由実機テスト (推奨) ​

5.2 トラブルシュート ​

6. 完全な実装詳細 ​

関連ページ ​

更新履歴 ​