rhino-gh-spatial-mcp

Capa de razonamiento espacial + evaluación de rendimiento, construida sobre jingcheng-chen/rhinomcp (ver rhino-gh-spatial-mcp-brief.md).

rhinomcp se encarga del «cómo operar» (crear geometría, conectar componentes de GH, ajustar sliders, resolver, capturar pantalla). Este repositorio solo añade una capa: lee la escena como relaciones espaciales estructuradas (spatial_graph), calcula unas pocas métricas de rendimiento puramente geométricas (performance_report) y ejecuta un bucle cerrado de evaluate → adjust → recompute → re-evaluate. No reescribe ninguna lógica de creación de geometría / conexión de GH — todas las operaciones que modifican el documento de Rhino son llamadas directas a los comandos GH existentes de rhinomcp (gh_set_parameter_value / gh_run_solution / gh_add_component / gh_connect_components, etc.).

Arquitectura

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

Los dos servidores MCP son dos procesos independientes, ambos conectados como clientes TCP al mismo socket de escucha del plugin de Rhino (el propio plugin de rhinomcp admite múltiples conexiones de clientes; ejecutar dos herramientas de agente en una misma máquina ya es este patrón). Este repositorio no depende del paquete Python de rhinomcp en sí (no expone una API de Python; las herramientas solo existen en su propio proceso MCP), sino que replica el protocolo de tramas minimalista de prefijo de longitud de 4 bytes + JSON para hablar directamente con el mismo plugin (ver bridge.py).

Related MCP server: cad-mcp

Requisitos previos

1. Rhino 8 (Windows/macOS), instala el plugin rhinomcp: en Rhino, Tools → Package Manager, busca rhinomcp, instala y reinicia Rhino.

2. Tras abrir Rhino, escribe mcpstart en la línea de comandos (hay que ejecutarlo manualmente una vez por sesión de Rhino; el plugin no escucha automáticamente).

3. Instala uv (brew install uv).

Instalación

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

Requiere Python ≥3.10 (igual que rhinomcp).

Registrar los dos servidores 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

O escribe la configuración MCP manualmente:

{
  "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" }
    }
  }
}

Variables de entorno

Reutiliza exactamente los mismos nombres de variables RHINO_MCP_* que rhinomcp; un único .env puede configurar ambos servidores a la vez:

Configuración de massing (massing.json)

La simplificación central del MVP: el bbox de cada masa paramétrica se calcula directamente a partir de los valores actuales de los sliders numéricos de GH (gh_get_component_info lee value/min/max por nickname), en lugar de parsear la geometría Brep de la salida de GH — de modo que la capa de razonamiento espacial es solo un cliente ligero que lee el estado de los parámetros de GH, sin reimplementar la serialización de geometría de 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 solo admite +Y/-Y/+X/-X cuatro direcciones (asume masas alineadas con los ejes, sin rotación — una limitación conocida dentro del alcance del MVP). context_layer_filter / site_layer_filter apuntan a objetos estáticos del documento de Rhino filtrados por capa (leídos mediante get_objects), y entrarán en spatial_graph junto con las masas paramétricas.

Recursos / Herramientas

• Recurso spatial://graph: el grafo espacial calculado más recientemente (bbox/dimensiones de cada objeto + adyacencia/contención/orientación/distancia por pares).

• Recurso performance://report: el informe de métricas de rendimiento calculado más recientemente.

• Herramienta analyze_spatial_relationships(): vuelve a leer la escena y actualiza spatial_graph. Solo lectura.

• Herramienta compute_metrics(names=None): calcula south_facing_area / far / shape_factor / nearest_neighbor_distance / sightline_count y actualiza performance_report. Solo lectura.

• Herramienta evaluate_design(goal): puntúa el diseño según el objetivo (palabras clave en lenguaje natural o {"metric":..., "direction":...}) y sugiere qué slider ajustar (análisis de sensibilidad en forma cerrada, sin disparar recálculo). Solo lectura.

• Herramienta propose_and_apply_adjustment(goal, step_fraction=0.1, revert_if_worse=True): ajusta realmente el slider → gh_run_solution recalcula → vuelve a evaluar, y devuelve la comparación de puntuaciones antes/después. Esta es la única herramienta de este repositorio que modifica el documento de Rhino.

• Herramienta setup_demo_scene(...): prepara la escena de demostración del MVP de una sola vez (ver más abajo). La preparación se realiza por completo mediante los propios gh_add_component/gh_search_components/gh_connect_components/create_object de rhinomcp.

Ejecutar el bucle cerrado del MVP (aceptación)

1. Ejecuta mcpstart en Rhino.

2. Haz que el agente llame a setup_demo_scene(): prepara 3 sliders (Width/Depth/Height) conectados a un componente Box, más una masa fija "Context" para demostrar las relaciones de separación, y escribe massing.json.

3. analyze_spatial_relationships() → debería leer spatial_graph: dos piezas, bbox, orientación, separación.

4. evaluate_design("maximizar la luz orientada al sur de esta masa") → debería devolver la puntuación actual del área orientada al sur y sugerir si ajustar Width o Height.

5. propose_and_apply_adjustment("maximizar la luz orientada al sur de esta masa") → ajusta realmente el slider, recalcula y devuelve las puntuaciones antes/después (debería mostrar una mejora reproducible).

Lo que no se hace (fuera del alcance del MVP)

• No se reescribe la creación de geometría / conexión de GH / capturas de viewport (rhinomcp ya las tiene; llamadas directas).

• No hay simulación real de luz solar (Ladybug, etc.) / CFD / estructural — solo métricas puramente geométricas.

• No se admite rotación de masas (solo bbox alineado con los ejes).

• No hay GUI.

Pruebas

uv run pytest

Las pruebas usan un servidor TCP simulado dentro del proceso (tests/mock_rhino_plugin.py, que implementa el mismo protocolo de tramas que el plugin real) para ejecutar toda la lógica de bridge / spatial / metrics / evaluator / demo sin necesidad de abrir Rhino.