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

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

---

1. なぜ必要か

MCP Server の Write Tools (add_*, modify_by_id, bulk_* 等) が 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 v5.5.0 では、以下のエディタ・コンポーネントに既に統合済です:

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

利用方法

1. 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

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

---

4. MCP Server 側の挙動

4.1 検査タイミング

executeWrite (add_*, modify_by_id, bulk_*, replace_catalog, move_member, delete_by_id) と save / undo / validate_with_auto_fix の ファイルロック取得前 に checkGhLock() が実行されます。

4.2 ロック検出時の応答

{
  "isError": true,
  "content": [{
    "type": "text",
    "text": "Grasshopper editor is currently editing this file.\n\nHint: Close the GH editor first. Lock file: D:\\projects\\office.mbp.json.gh-editing"
  }]
}

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

4.3 stale 救済

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

---

5. テスト方法

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

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

---

関連ページ

• MCP 連携について — アーキテクチャ概要
• MCP セットアップガイド
• MCP API 仕様