rhino-gh-spatial-mcp

空間推論 + 性能評価レイヤー。これは jingcheng-chen/rhinomcp の上に構築されている（rhino-gh-spatial-mcp-brief.md を参照）。

rhinomcp は「どう操作するか」（ジオメトリ作成、GH コンポーネントの接続、スライダー設定、ソルブ、スクリーンショット）を担当する。このリポジトリが追加するのはレイヤーだけ、つまりシーンを構造化された空間関係 (spatial_graph) として読み取り、いくつかの純粋なジオメトリ性能指標 (performance_report) を計算し、evaluate → adjust → recompute → re-evaluate のクローズドループを実行する。ジオメトリ作成 / GH 配線ロジックは一切書き直さない。Rhino ドキュメントを変更する操作はすべて、既存の rhinomcp の GH コマンド（gh_set_parameter_value / gh_run_solution / gh_add_component / gh_connect_components など）を直接呼び出す。

構成

Agent (Claude Code / Cursor / ...)
   │  MCP (stdio)                     │ MCP (stdio)
   ▼                                  ▼
rhinomcp 的 Python MCP Server    rhino-gh-spatial-mcp (本仓库)
   │  TCP  127.0.0.1:1999            │  TCP 127.0.0.1:1999 (同一个端口)
   └──────────────┬───────────────────┘
                   ▼
         Rhino 8 内的 rhinomcp 插件 (mcpstart 后监听)
                   │
                   ▼
             Rhino + Grasshopper

2 つの MCP サーバーは独立したプロセスで、どちらも Rhino プラグイン内の同じリッスンソケットに TCP クライアントとして接続する（rhinomcp プラグイン自体が複数クライアント接続をサポートしており、1 台のマシンに 2 つのエージェントツールをインストールするのは本来このパターンである）。このリポジトリは rhinomcp の Python パッケージには依存しない（外部に Python API を公開しておらず、ツールは独自の MCP プロセス内にのみ存在する）。その代わり、rhinomcp の極めてシンプルな 4 バイト長プレフィックス + JSON フレームプロトコルを再現し、同じプラグインと直接通信する（bridge.py を参照）。

Related MCP server: cad-mcp

前提条件

1. Rhino 8（Windows/macOS）に rhinomcp プラグインをインストールする：Rhino 内の Tools → Package Manager で rhinomcp を検索してインストールし、Rhino を再起動する。

2. Rhino を開いたら、コマンドラインで mcpstart を実行する（毎回 Rhino セッションで手動実行が必要。プラグインは自動ではリッスンしない）。

3. uv をインストールする（brew install uv）。

インストール

cd rhino-gh-mcp
uv sync            # 或者: pip install -e ".[dev]"

Python ≥3.10 が必要（rhinomcp と同様）。

2 つの MCP サーバーを登録する

# 底座：负责建几何 / 连 GH 组件 / 求解 / 截图
claude mcp add rhino -- uvx rhinomcp

# 本仓库：负责空间推理 / 性能评估
claude mcp add rhino-gh-spatial -- uv run --directory /path/to/rhino-gh-mcp rhino-gh-spatial-mcp

または MCP 設定を手動で書く：

{
  "mcpServers": {
    "rhino": { "command": "uvx", "args": ["rhinomcp"], "env": { "RHINO_MCP_HOST": "127.0.0.1" } },
    "rhino-gh-spatial": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/rhino-gh-mcp", "rhino-gh-spatial-mcp"],
      "env": { "RHINO_MCP_HOST": "127.0.0.1", "RHINO_GH_SPATIAL_CONFIG": "/path/to/rhino-gh-mcp/massing.json" }
    }
  }
}

環境変数

rhinomcp と完全に同じ RHINO_MCP_* 変数名を再利用するため、1 つの .env で両方のサーバーを設定できる：

massing 設定 (massing.json)

MVP の中心となる簡略化：各パラメトリックボリュームの bbox は、GH の number slider の現在値から直接計算する（gh_get_component_info で nickname から value/min/max を読む）。GH 出力の Brep ジオメトリをパースするのではなく、これにより空間推論レイヤーは「GH パラメータ状態を読む」だけの軽量クライアントとなり、GH ジオメトリのシリアライズを再実装する必要がない。

{
  "north_axis": "+Y",
  "site_area_sqm": 900,
  "site_layer_filter": null,
  "context_layer_filter": "Context",
  "adjacency_threshold_m": 0.5,
  "massings": [
    {
      "name": "MainBlock",
      "size_sliders": { "width": "Width", "depth": "Depth", "height": "Height" },
      "origin_sliders": { "x": null, "y": null, "z": null },
      "floors": 1
    }
  ]
}

north_axis は +Y/-Y/+X/-X の 4 種類のみサポートする（ボリュームは軸合わせで回転なしと仮定 — MVP 範囲での既知の制限）。context_layer_filter / site_layer_filter は、Rhino ドキュメント内でレイヤーによりフィルタされた静的オブジェクトを指す（get_objects で読み取る）。これらはパラメトリックボリュームと一緒に spatial_graph に入る。

Resources / Tools

• Resource spatial://graph：直近で計算された空間グラフ（各オブジェクトの bbox/寸法 + オブジェクト間の隣接/包含/方位/距離）。

• Resource performance://report：直近で計算された性能指標レポート。

• Tool analyze_spatial_relationships()：シーンを再読み込みし、spatial_graph を更新する。読み取り専用。

• Tool compute_metrics(names=None)：south_facing_area / far / shape_factor / nearest_neighbor_distance / sightline_count を計算し、performance_report を更新する。読み取り専用。

• Tool evaluate_design(goal)：目標（自然言語キーワードまたは {"metric":..., "direction":...}）に基づいてスコアを計算し、どのスライダーを調整すべきかを提案する（閉形式の感度分析。再計算はトリガーしない）。読み取り専用。

• Tool propose_and_apply_adjustment(goal, step_fraction=0.1, revert_if_worse=True)：実際にスライダーを調整 → gh_run_solution で再計算 → 再評価し、調整前後のスコア比較を返す。これはこのリポジトリで唯一 Rhino ドキュメントを変更するツールである。

• Tool setup_demo_scene(...)：MVP デモシーンを一度だけセットアップする（下記参照）。セットアップは rhinomcp 自身の gh_add_component/gh_search_components/gh_connect_components/create_object のみで完了する。

MVP クローズドループを実行する（受入テスト）

1. Rhino で mcpstart を実行する。

2. エージェントに setup_demo_scene() を呼び出させる：3 つのスライダー（Width/Depth/Height）を Box コンポーネントに接続し、間隔関係をデモするための固定の "Context" 隣接ボリュームも配置し、massing.json を書き出す。

3. analyze_spatial_relationships() → spatial_graph を読めるはず：2 つのオブジェクト、bbox、方位、間隔。

4. evaluate_design("このボリュームの南向き受光を最大化する") → 現在の南向き受光面積スコア + Width と Height のどちらを調整すべきかの提案を返す。

5. propose_and_apply_adjustment("このボリュームの南向き受光を最大化する") → 実際にスライダーを調整、再計算し、調整前後のスコアを返す（再現可能な改善があるはず）。

やらないこと（MVP 範囲外）

• ジオメトリ作成 / GH 配線 / viewport スクリーンショットは書き直さない（rhinomcp が既に持っており、直接呼び出す）。

• 実際の日照（Ladybug など）/ CFD / 構造シミュレーションは行わない — すべての指標は純粋なジオメトリ代理値である。

• ボリュームの回転はサポートしない（軸合わせ bbox のみ）。

• GUI は作らない。

テスト

uv run pytest

テストはプロセス内のモック TCP サーバー（tests/mock_rhino_plugin.py。実際のプラグインと同じフレームプロトコルを実装）を使用して、bridge / spatial / metrics / evaluator / demo の全ロジックを実行する。実際に Rhino を開く必要はない。