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, напрямую вызывают уже существующие GH-команды rhinomcp (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-сервера — это независимые процессы, и оба подключаются как TCP-клиенты к одному и тому же слушающему сокету в плагине Rhino (сам плагин rhinomcp поддерживает несколько клиентских подключений; одновременное использование двух агентских инструментов на одной машине как раз и работает в этом режиме). Этот репозиторий не использует Python-пакет rhinomcp (он не предоставляет внешнего 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" }
    }
  }
}

Переменные окружения

Используются ровно те же имена RHINO_MCP_*, что и в rhinomcp, поэтому один файл .env настраивает сразу оба сервера:

Конфигурация massing (massing.json)

Ключевое упрощение MVP: bbox каждого параметрического объёма вычисляется напрямую из текущих значений числовых slider'ов GH (gh_get_component_info читает value/min/max по nickname), а не путём разбора Brep-геометрии, выводимой из GH. Таким образом, слой пространственных рассуждений остаётся лёгким клиентом, который лишь «читает состояние параметров 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 вместе с параметрическими объёмами.

Ресурсы / Инструменты

• Ресурс spatial://graph: последний построенный пространственный граф (bbox/размеры каждого объекта + попарные adjacency/containment/направление, подчеркивание/расстояние).

• Ресурс performance://report: последний построенный отчёт о показателях производительности.

• Инструмент analyze_spatial_relationships(): перечитывает сцену и обновляет spatial_graph. Только чтение.

• Инструмент compute_metrics(names=None): вычисляет south_facing_area / far / shape_factor / nearest_neighbor_distance / sightline_count, обновляет performance_report. Только чтение.

• Инструмент evaluate_design(goal): по заданной цели (ключевые слова на естественном языке или объект {"metric": ..., "direction": ...}) считает оценку и даёт рекомендацию, какой из serрегуляторов подстроить (анализ чувствительности в замкнутой форме, без пересчёта). Только чтение.

• Инструмент propose_and_apply_adjustment(goal, step_fraction=0.1, revert_if_worse=True): реально меняет полимер → запускает gh_run_solution для пересчёта → оценивает заново и возвращает сравнение оценок до/после. Это единственный инструмент в этом репозитории, который изменяет документ Rhino.

• Инструмент 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-соединения / скриншоты видимой области (rhinomcp уже умеет, вызываем напрямую).

• Без настоящего солнечного освещения (Ladybug и т.п.) / CFD / конструкционное моделирование — все метрики чисто геометрические прокси.

• Вращение объмов не поддерживается (только выровненные по осям bbox).

• Не делается GUI.

Тестирование

uv run pytest

Тесты прогоняют всю логику bridge / spatial / metrics / evaluator / demo через поддельный TCP-сервер в корпоративе процесса (tests/mock_rhino_plugin.py, реализующий тот же фрейм-протокол, что и настоящий плагин), так что реально запускать Rhino не требуется.