rhino-gh-spatial-mcp

공간 추론 + 성능 평가 레이어로, jingcheng-chen/rhinomcp 위에 구축됨 (rhino-gh-spatial-mcp-brief.md 참조).

rhinomcp는 "어떻게 조작할지"(지오메트리 생성, GH 컴포넌트 연결, slider 설정, 솔버 실행, 스크린샷)를 담당합니다. 이 저장소는 레이어 하나만 추가합니다: 장면을 구조화된 공간 관계(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

두 MCP 서버는 별도의 프로세스이며, 둘 다 Rhino 플러그인의 동일한 수신 소켓에 TCP 클라이언트로 연결됩니다 (rhinomcp 플러그인 자체가 여러 클라이언트 연결을 지원하며, 한 머신에 두 개의 에이전트 도구를 설치하는 것이 원래 이 패턴입니다). 이 저장소는 rhinomcp Python 패키지 자체에 의존하지 않습니다 (Python API를 노출하지 않으며, 도구는 자체 MCP 프로세스에만 존재합니다). 대신 최소한의 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와 동일).

두 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_* 변수 이름을 재사용하며, 하나의 .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 네 가지만 지원합니다 (매스가 축 정렬, 회전 없음 가정 — MVP 범위 내 알려진 제한). context_layer_filter / site_layer_filter는 레이어로 필터링된 Rhino 문서의 정적 객체를 가리키며 (get_objects로 읽음), 파라메트릭 매스와 함께 spatial_graph에 포함됩니다.

Resources / Tools

• Resource spatial://graph: 가장 최근에 계산된 공간 그래프 (각 객체의 bbox/치수 + 쌍별 adjacency/containment/방위/거리).

• 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":...})에 따라 점수를 매기고 어떤 slider를 조정할지 제안합니다 (폐쇄형 민감도 분석, 재계산 없음). 읽기 전용.

• Tool propose_and_apply_adjustment(goal, step_fraction=0.1, revert_if_worse=True): 실제로 slider를 조정 → 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개의 slider(Width/Depth/Height)를 Box 컴포넌트에 연결하고, 간격 관계를 보여주기 위한 고정 "Context" 이웃 매스를 배치하고, massing.json을 작성.

3. analyze_spatial_relationships() → spatial_graph를 읽을 수 있어야 함: 두 객체, bbox, 방위, 간격.

4. evaluate_design("이 매스의 남향 채광을 최대화") → 현재 남향 면적 점수 + Width 또는 Height 조정 제안 반환.

5. propose_and_apply_adjustment("이 매스의 남향 채광을 최대화") → 실제로 slider 조정, 재계산, 전후 점수 반환 (재현 가능한 개선이 있어야 함).

하지 않는 것 (MVP 범위 밖)

• 지오메트리 생성 / GH 배선 / viewport 스크린샷 재작성 없음 (rhinomcp에 이미 있음, 직접 호출).

• 실제 일조(Ladybug 등) / CFD / 구조 시뮬레이션 없음 — 모든 지표는 순수 지오메트리 대리값.

• 매스 회전 지원 없음 (축 정렬 bbox만).

• GUI 없음.

테스트

uv run pytest

테스트는 프로세스 내 가짜 TCP 서버(tests/mock_rhino_plugin.py, 실제 플러그인과 동일한 프레이밍 프로토콜 구현)를 사용하여 Rhino를 실제로 열지 않고도 bridge / spatial / metrics / evaluator / demo 전체 로직을 실행합니다.