Metadata-Version: 2.5
Name: robot-structural-mcp
Version: 0.1.0
Summary: MCP server for Autodesk Robot Structural Analysis: model, results, NEC-15 checks and ACI 318 reinforcement
Project-URL: Repository, https://github.com/brdz4/robot-mcp
Project-URL: Issues, https://github.com/brdz4/robot-mcp/issues
Author: brdz4
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: aci 318,autodesk,mcp,nec,robot structural analysis,structural engineering
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.12
Requires-Dist: mcp<3,>=2.3
Requires-Dist: pythonnet>=3.0.3
Description-Content-Type: text/markdown

# robot-structural-mcp

<!-- mcp-name: io.github.brdz4/robot-mcp -->

Servidor MCP para Autodesk Robot Structural Analysis. Se conecta por COM (RobotOM) al Robot
que tengas abierto y deja que Claude lea el modelo activo y sus resultados, y que lo modifique
con ensayo previo (crear, asignar y, con permiso expreso, borrar).

> **Estado: en pruebas, pero funciona.** Lo he probado en copias de proyectos reales con NEC-15
> y ACI 318-19 y pasan todas sus pruebas (162 comprobaciones, 156 de ellas contra Robot), pero
> aún no se ha usado fuera de mi equipo. Trabaja siempre sobre una copia del modelo, revisa el ensayo (`dry_run`) antes de
> aplicar y comprueba los resultados de diseño a mano. Se agradecen issues y PR.

Probado con Robot 2026 (39.0.1) en español, Python 3.12, `mcp` 2.3.0 y `pythonnet` 3.2.1,
contra un pórtico de prueba y la copia de un edificio real.

*English:* MCP server for Autodesk Robot Structural Analysis (Windows, COM API). It lets Claude
read the open model and its results, run Ecuadorian seismic code checks (NEC-SE-DS), size
reinforcement per ACI 318-19 and make guarded edits (every write is a dry run first). Status:
in testing but working. Tool descriptions and messages are in Spanish. Apache-2.0 license.
Contributions welcome: see [CONTRIBUTING.md](CONTRIBUTING.md).

## Instalación

Requiere Windows, Robot Structural Analysis instalado con licencia y Python 3.12 o superior.
La forma más simple es dejar que `uv` lo instale desde PyPI al registrarlo
(`.mcp.json` en la carpeta del proyecto de Claude Code):

```json
{
  "mcpServers": {
    "robot": {
      "command": "uvx",
      "args": ["robot-structural-mcp"]
    }
  }
}
```

Sin `uv`: `pip install robot-structural-mcp` y usa `"command": "robot-structural-mcp"`.

Desde el código, para desarrollar:

```bash
git clone https://github.com/brdz4/robot-mcp.git
cd robot-mcp
python -m venv .venv
.venv\Scripts\python.exe -m pip install -e .
```

y en `.mcp.json`, `"command": "C:/ruta/robot-mcp/.venv/Scripts/robot-structural-mcp.exe"`.

## Herramientas

| Herramienta | Qué devuelve |
|---|---|
| `robot_health` | Si Robot está abierto, versión, proyecto activo, estado de resultados |
| `robot_get_project_info` | Nombre, archivo, tipo de estructura y conteos |
| `robot_list_nodes` | Nudos: coordenadas (m) y apoyo |
| `robot_list_bars` | Barras: nudos, longitud, sección, material. Filtros: selección, sección, piso, columna o viga |
| `robot_list_panels` | Paneles: espesor, material y modelo de cálculo (elementos finitos o solo reparto de cargas, diafragma) |
| `robot_list_storeys` | Pisos: niveles y alturas |
| `robot_list_sections` | Secciones: b, h, área, inercias, coeficientes de inercia agrietada |
| `robot_list_materials` | Materiales: E, ν, peso unitario, resistencia y dónde se usan |
| `robot_list_thicknesses` | Espesores de panel: homogéneos (cm) u ortótropos (tipo y dimensiones) |
| `robot_list_supports` | Tipos de apoyo, grados de libertad fijos y nudos asignados |
| `robot_list_load_cases` | Casos: naturaleza y tipo de análisis |
| `robot_list_combinations` | Combinaciones manuales con sus factores |
| `robot_list_loads` | Cargas de un caso simple: tipo, elementos y valores (kN, kN/m, kN/m²), para auditarlo |

Resultados (`results.py`; requieren el modelo calculado):

| Herramienta | Qué devuelve |
|---|---|
| `robot_get_reactions` | Reacciones por nudo apoyado y caso, y suma por caso (peso, cortante basal) |
| `robot_get_node_displacements` | Desplazamientos y giros de nudos por caso |
| `robot_get_bar_forces` | Esfuerzos N, V, M, T por barra, caso y estación |
| `robot_get_result_extremes` | Máximo y mínimo de esfuerzos, reacciones o desplazamientos, con ubicación (barra, piso, sección, caso) |
| `robot_get_modal_results` | Periodos, masas participantes, acumulados y modo en que se alcanza el 90 % |
| `robot_get_storey_results` | Tabla de pisos: desplazamientos, derivas, cortantes, masa y centros |
| `robot_get_bar_deflections` | Flecha máxima de cada barra respecto a su cuerda, L/flecha y, si se pide, si cumple L/n |
| `robot_get_panel_forces` | Máximo y mínimo de MXX, MYY, MXY, NXX… en paneles con elementos finitos, con su nudo |

Verificaciones NEC-SE-DS 2015 (`checks.py`; solo lectura, también en modo `ROBOT_MCP_READ_ONLY`):

| Herramienta | Qué verifica |
|---|---|
| `robot_check_drifts` | Deriva inelástica ΔM = 0.75·R·ΔE por piso frente al límite (§6.3.9), con la tabla de pisos y con la peor línea de pórtico (la que gobierna sin diafragma rígido) |
| `robot_check_p_delta` | Índice de estabilidad Qi = Pi·Δi/(Vi·hi) por piso (§6.3.8) |
| `robot_check_base_shear` | Cortante dinámico ≥ 80 % u 85 % del estático, y factor de ajuste (§6.2.2) |
| `robot_check_irregularities` | Irregularidad torsional, piso flexible y masa (§5.2) |
| `robot_check_rc_members` | Cuantías ACI 318-19 de vigas y columnas rectangulares de hormigón (`design.py`): As superior e inferior, ρ de columna por flexocompresión biaxial y Av/s de estribos |

En `robot_check_rc_members` se pasan las combinaciones últimas, y f'c y fy son datos del
proyecto. Las columnas se resuelven por compatibilidad de deformaciones con las barras
repartidas en el perímetro y la flexión biaxial por el contorno lineal Mx/φMnx + My/φMny ≤ 1,
que es conservador. Los momentos se toman en los nudos, no a la cara del apoyo. No incluye
diseño por capacidad (cortante por momentos probables, columna fuerte-viga débil) ni esbeltez.
Las secciones que no son rectangulares de hormigón, como las dobles T prefabricadas, se omiten.

R, los factores de escala de cada caso sísmico y el cortante estático (o su coeficiente) son
datos del proyecto que aporta quien llama: las herramientas aplican la fórmula, no eligen esos
valores. No sustituyen la revisión de un ingeniero responsable.

Escritura (`writes.py`):

| Herramienta | Qué hace |
|---|---|
| `robot_create_nodes` | Crea nudos por coordenadas; no duplica los coincidentes |
| `robot_create_bars` | Crea barras entre nudos existentes, con sección opcional |
| `robot_define_concrete_section` | Crea o redefine una sección rectangular de hormigón con inercia agrietada |
| `robot_assign_section` | Asigna una sección a barras |
| `robot_define_support` | Crea o redefine un tipo de apoyo rígido |
| `robot_assign_support` | Asigna un apoyo a nudos |
| `robot_create_load_case` | Crea un caso simple estático |
| `robot_add_loads` | Añade peso propio, fuerzas en nudos, cargas repartidas en barras o cargas superficiales en paneles |
| `robot_create_combinations` | Crea combinaciones manuales con sus factores |
| `robot_create_nec_combinations` | Genera y crea las combinaciones LRFD de la NEC-SE-CG §3.4.3 (y D+L de servicio) a partir de los casos D, L, Lr, W, Ex y Ey; `seismic_scale_x/y` aplica la escala del espectro cuando va en las combinaciones (p. ej. I·g/R) |
| `robot_create_panel` | Crea un panel plano por su contorno, con espesor y modelo de cálculo existentes |
| `robot_delete_elements` | Borra barras, nudos, paneles o casos y combinaciones |
| `robot_delete_loads` | Borra cargas de un caso por su índice en `robot_list_loads` |
| `robot_run_calculation` | Lanza el cálculo y espera |
| `robot_save_project` | Guarda o «guarda como» |

Reglas de toda escritura:

1. `dry_run=true` por defecto: valida y devuelve el plan sin tocar el modelo. Se aplica con
   `dry_run=false`.
2. Si el modelo tiene resultados vigentes y el cambio los invalida, hace falta además
   `discard_results=true`. Las combinaciones no invalidan resultados; todo lo demás sí.
3. Se valida antes de escribir y se relee lo escrito. Si algo no cuadra, la herramienta falla.
4. No hay deshacer: guarda antes de cambios grandes. El borrado se niega a dejar el modelo
   incoherente: no borra nudos que usan barras, casos que usa una combinación que se queda, ni
   las cargas que Robot genera al repartir paneles.

No incluye: casos modales o espectrales (el espectro se define en Robot), espesores ni
modelos de cálculo de panel nuevos, ni secciones que no sean rectangulares de hormigón. Eso se
hace en Robot.

Unidades: m, cm, cm², cm⁴, MPa, kN/m³; resultados y cargas en kN, kN/m, kN·m, mm, rad y t.
Las listas largas están paginadas (`limit`, `offset`).

## Variables de entorno

| Variable | Efecto |
|---|---|
| `ROBOT_INTEROP_DLL` | Ruta de `Interop.RobotOM.dll` si no está en la instalación estándar |
| `ROBOT_MCP_AUTOSTART=1` | El servidor arranca Robot si no está abierto (por defecto no lo hace) |
| `ROBOT_MCP_READ_ONLY=1` | No registra las herramientas de escritura, cálculo ni guardado (quedan 26) |
| `ROBOT_MCP_TIMEOUT` | Segundos de espera por llamada (120) |
| `ROBOT_MCP_STARTUP_GRACE` | Segundos que debe llevar abierto Robot antes de conectar (40) |

## Pruebas

```bash
.venv\Scripts\python.exe tests\smoke_test.py
```

Con Robot cerrado comprueba el arranque y los errores; con un modelo abierto muestra datos reales
(solo lectura).

```bash
.venv\Scripts\python.exe tests\state_test.py
```

Prueba de estados, con Robot **cerrado**: abre su propio Robot, crea un pórtico de 2 pisos, lo
calcula y contrasta reacciones con el peso calculado a mano, lo desactualiza, cierra y reabre
Robot con el servidor en marcha, y al final lo cierra sin guardar (31 comprobaciones, ~3 min).
No requiere tocar nada: verifica que Robot no haga ninguna pregunta. Se niega a empezar si ya hay
un Robot abierto.

```bash
.venv\Scripts\python.exe tests\write_test.py
```

Prueba de escritura, también con Robot **cerrado**: construye el mismo pórtico solo con las
herramientas MCP, lo carga, combina y calcula, contrasta con la cuenta a mano y comprueba los
rechazos (duplicados, números existentes, resultados vigentes) y que Robot no pregunte nada
(58 comprobaciones, ~2 min).

```bash
.venv\Scripts\python.exe tests\checks_test.py
```

Prueba de las verificaciones NEC, con Robot **cerrado**: añade al pórtico dos casos laterales
de valor conocido (uno asimétrico, que provoca torsión) y compara cada verificación con la
misma cuenta hecha a partir de las herramientas de lectura (26 comprobaciones, ~1 min).

`tests\make_fixture.py` crea ese pórtico en el Robot abierto, pero **reemplaza el proyecto
activo**: no lo ejecutes con un modelo real sin guardar.

```bash
.venv\Scripts\python.exe tests\offline_test.py
```

Prueba sin Robot del marcador de modo no interactivo (incluida la escritura simultánea desde
otro chat), del hilo COM ocupado tras un plazo vencido, de la validación estricta de casos, del
filtro de cargas generadas, del generador de combinaciones NEC y de las fórmulas ACI contra
cálculos a mano (6 pruebas, segundos).

```bash
.venv\Scripts\python.exe tests\panel_test.py
```

Prueba de paneles, con Robot **cerrado**: convierte la losa del pórtico en panel de reparto,
le pone 2 kN/m², calcula y comprueba el modelo de cálculo del panel, la lectura de la carga
superficial, las 4 cargas trapezoidales que Robot genera en las vigas (suman los 40 kN de la
losa) y la reacción total de 400 kN (8 comprobaciones, ~1 min).

```bash
.venv\Scripts\python.exe tests\design_test.py
```

Prueba de las herramientas añadidas el 2026-11-12, con Robot **cerrado**, sobre el pórtico con
su losa de elementos finitos. Crea las combinaciones NEC y las relee. Comprueba:

- La flecha de D+L es la suma de las de D y L.
- Los momentos de la losa salen con ambos signos.
- El As de la viga coincide con el cálculo a mano a partir de `robot_get_bar_forces`.
- La columna queda con la cuantía mínima.
- Un panel nuevo con 3 kN/m² eleva la reacción a 420 kN.
- Cada borrado y cada rechazo funcionan (33 comprobaciones, ~2 min).

## Evaluación

El 2026-11-10 un subagente (Sonnet) resolvió a ciegas 10 preguntas de solo lectura sobre una copia
de un edificio real: 10 de 10 con 20 llamadas. De sus críticas salieron el filtro
`structural_type` y el contexto de barra en los extremos. Ese juego de preguntas y el guion de
la skill `mcp-builder` se retiraron el 2026-11-12 porque el modelo cambió y sus respuestas ya no
valían; si se quiere repetir, hay que generar preguntas nuevas sobre el estado actual del modelo.

## Cosas que no son obvias

- **Selecciones e idioma.** La sintaxis de selección de Robot depende del idioma: `1to4` en inglés
  es `1A4` en español, y en español `1to4` selecciona *todo*. El servidor acepta `1to10`, `1A10`,
  `1to20By2` y los traduce (`Session._from_text`). No llames a `FromText` directamente.
- **Conexión.** `RobotApplicationClass()` tumba el proceso con pythonnet 3. Se instancia por
  ProgID (`create_application`).
- **Un solo hilo.** Toda llamada COM pasa por `on_robot`; el SDK ejecuta las herramientas en un pool.
- **stdout es del protocolo.** Los logs van a stderr; no uses `print` en el servidor.
- **Inercia agrietada: la inercia que reporta la API no dice si la reducción se aplica.**
  Hay dos mediciones que no encajan entre sí y el mecanismo interno de Robot no está aclarado:
  - *Secciones creadas por API* (experimento del 2026-11-11, ya retirado: voladizos contrastados con
    PL³/3EI, en proyectos FRAME_3D y BUILDING, barras tipadas o no): el análisis sigue el valor
    de `GetValue(I_BSDV_IY)`. Coeficiente 0.5 con ese valor reducido da el doble de flecha; el
    mismo coeficiente con ese valor forzado a la inercia bruta da la flecha sin reducir.
  - *Edificio real definido en la interfaz* (una sección de viga con coeficiente 0.5 y
    `GetValue` igual a la inercia bruta): el análisis SÍ usa la inercia reducida. Comprobado tres
    veces sobre una copia: recalcular tal cual y redefinirla con `robot_define_concrete_section`
    y 0.5 dan exactamente el mismo T1; quitarle el coeficiente lo baja un 17 %.
  Consecuencias: `i*_stored_over_gross` es solo informativo y no debe usarse para afirmar que
  falta la reducción; `robot_define_concrete_section` deja la sección en un estado que analiza
  con la reducción aplicada una sola vez en ambos casos; y la única verificación fiable es
  comparar períodos o flechas con y sin coeficiente, en una copia.
- **Etiquetas.** `Labels.GetMany` no devuelve todas (omite espesores ortótropos y su material).
  Usa `_labels()`, que une `GetMany` con `GetAvailableNames` y filtra con `Exist` / `IsUsed`.
- **Pisos.** `CreateByStorey` es fiable para barras; para nudos devuelve números sin sentido.
- **Varias instancias de Robot.** COM se engancha a una sola; trabaja con una abierta.
- **Resultados: unidades y signos.** La API devuelve N, N·m, m, rad y kg. `FX > 0` en barras es
  compresión. En casos espectrales el signo no es físico.
- **Resultados: velocidad.** Cada lectura (`Forces.Value`, `Reactions.Value`…) cuesta unos 10 ms
  por COM, así que cada llamada está limitada a 600 lecturas (`MAX_READS`). Para envolventes se usa
  `Results.Extremes`, que busca dentro de Robot (~50 ms por componente) y coincide con la lectura
  valor a valor.
- **Derivas.** `robot_get_storey_results` devuelve el `dr` de la tabla de pisos de Robot, sin
  amplificar; los factores de norma (0.75·R en NEC) y el de reducción del espectro los aplica quien
  consulta.
- **Resultados desactualizados.** Con estado `OUT_OF_DATE` la API no entrega resultados
  (`Results.Available` es falso); las herramientas lo dicen y piden recalcular.
- **Arranque de Robot.** Si se pide `Robot.Application` mientras Robot arranca (medido a los 2, 5 y
  ~15 s; a los 45 s ya no), Windows abre otra instancia oculta que se queda viva. Por eso el
  servidor no conecta con un Robot abierto hace menos de `ROBOT_MCP_STARTUP_GRACE` segundos
  (`robot_health` responde `ready: false`). Como red de seguridad, si una conexión hace aparecer
  un proceso `robot.exe` nuevo y sin título, lo cierra y pide reintentar.
- **Diálogos al modificar.** Con `Interactive = 1` (lo normal cuando el usuario trabaja en
  Robot), modificar por API un modelo calculado abre el diálogo «Los resultados de cálculos
  pueden desactualizarse. ¿Desea continuar?» y la llamada COM queda bloqueada hasta que alguien
  responde. Con `Interactive = 0` no pregunta y devuelve al instante. Por eso toda escritura y
  el cálculo pasan por `non_interactive()`, que lo restaura al salir y deja un archivo marcador
  en la carpeta temporal para repararlo si el servidor muere a mitad. Cerrar con
  `Quit(I_QO_DISCARD_CHANGES)` no pregunta. `tests\dialog_watch.py` registra estos diálogos.
- **La API de Robot no valida.** Medido: `Nodes.Create` con un número existente **cambia las
  coordenadas** de ese nudo; `Bars.Create` admite barras duplicadas e ignora en silencio las que
  usan nudos inexistentes; `CaseFactors.New` acepta casos que no existen. `Bars.FindWithNodes` y
  `Nodes.GetConnectedBars` devuelven vacío, así que los duplicados se detectan recorriendo las
  barras. Toda validación está en `writes.py`, antes de escribir.
- **Qué invalida resultados.** Nudos, barras, secciones o apoyos en uso, casos y cargas dejan el
  estado en `OUT_OF_DATE`. Las combinaciones y las etiquetas sin usar no. Tras calcular, Robot
  congela los resultados (`ResultsFreeze`), pero una escritura no interactiva los descongela sola.
- **Masa de piso.** `Results.Storeys.Values(piso, caso).Mass` depende del caso cuando el modelo
  no tiene masas dinámicas: en el pórtico de prueba da la masa del peso propio para ese caso y
  cero para una combinación. Con análisis modal es la misma para todos los casos. Por eso
  `robot_check_irregularities` lee la masa del caso modal, o del que se indique en `mass_case`, y
  `robot_get_storey_results` también la lee del caso modal si existe.
- **Torsión en casos espectrales.** La deriva de cada borde se aproxima como diferencia de
  desplazamientos ya combinados (CQC), no como combinación de derivas modales; la herramienta lo
  marca con `approximate`. Para una comprobación exacta hace falta un caso estático.
- **P-Δ.** Δ y V salen del mismo caso sísmico, así que el factor de escala no altera Qi.
- **Cargas generadas por Robot.** Con paneles de reparto (modelo de cálculo sin elementos
  finitos, `I_LT_PANEL_CALC_MODEL`), Robot crea al calcular un registro por viga con la carga del
  panel ya repartida (`BAR_UNIFORM` o `BAR_TRAPEZOIDALE`) y lo marca `IsAutoGenerated`
  (`IRobotLoadRecordCommon`). En un edificio real son casi todos los registros de cada caso. No salen en la
  tabla de cargas de Robot, y sumarlos a la carga del panel la cuenta dos veces;
  `robot_list_loads` y `robot_list_load_cases` los separan. Aparecen un momento después de
  `CalculateEx`: leídos en la misma sesión COM justo al terminar, aún no estaban.
- **Cargas trapezoidales.** `GetValue` devuelve 0 en `PX1..PZ2`; la forma se lee por puntos con
  `IRobotLoadRecordBarTrapezoidal.PointCount` y `GetPoint(i, px, py, pz, x)`.
- **Cargas de casos espectrales.** El único registro de un caso sísmico espectral es su espectro
  (tipo 48, sin nombre en la API, con el nombre del espectro en `Description`); pedirle
  `ObjectType` u `Objects` da `E_FAIL`. `robot_list_loads` lo lista con `objects: null`.
- **Paneles sin material.** Un espesor sin material deja pasar la creación del panel, pero una
  losa de elementos finitos así no supera la verificación del cálculo (`FAILED_VERIFICATION`).
  Los paneles de solo reparto sí calculan. `robot_create_panel` avisa en el ensayo.
- **Extremos de paneles.** `IRobotFeExtremeValue.Panel` devuelve 0; el nudo y el elemento sí
  vienen. Por eso `robot_get_panel_forces` no dice el panel.
- **Barras sin tipo estructural.** Las barras creadas por la API no son `BEAM` ni `COLUMN`;
  `robot_check_rc_members` las clasifica por geometría y los filtros `structural_type` no las
  encuentran. Los modelos que vienen de Revit sí traen el tipo.
- **Mensajes de cálculo.** Si el cálculo deja avisos, Robot abre la ventana «Mensajes de
  cálculo». No bloquea, pero queda abierta.
- **Sin verificar:** área de paneles (`CalcArea` devolvió 0 en la prueba, por eso no se expone);
  la red de seguridad del arranque y la reparación del modo no interactivo tras un fallo, que no
  llegaron a dispararse; un cálculo que falle o tarde mucho; y la escritura sobre un modelo
  grande (crear barras recorre todas las existentes, ~4 ms por barra). La escritura solo se ha
  probado sobre el pórtico de prueba, nunca sobre un modelo real.

## Siguientes fases

1. Resultados que faltan: tensiones; flecha diferida (ACI 24.2.4).
2. Escritura que falta: espectro y casos sísmicos, espesores y modelos de cálculo de panel.
3. Diseño: cortante por capacidad y nudo columna fuerte-viga débil (ACI 18), secciones
   prefabricadas (dobles T).
