# etabs-mcp

Servidor MCP para ETABS 22. Se adjunta a la instancia de ETABS que ya tienes abierta y
expone geometria, secciones, materiales, cargas y resultados como herramientas MCP, ademas
de herramientas para crear y editar el modelo (grids, niveles, secciones, frames, muros,
cargas, combos y analisis).

## Requisitos

- Windows con **ETABS 22** instalado y el modelo abierto.
- Python 3.10 o superior (64 bits, igual que ETABS).

## Instalacion

```powershell
cd etabs-mcp
py -3 -m venv .venv
.venv\Scripts\pip install -e .
```

## Uso

1. Abre ETABS 22 y carga tu modelo.
2. Registra el servidor en tu cliente MCP:

```json
{
  "mcpServers": {
    "etabs22": {
      "command": "C:\\ruta\\a\\etabs-mcp\\.venv\\Scripts\\etabs-mcp.exe"
    }
  }
}
```

3. Prueba la conexion desde el cliente con `etabs_model_info`.

### Modo HTTP (para usarlo desde Devin u otro cliente remoto)

ETABS corre en tu PC, asi que el servidor debe escuchar por HTTP y exponerse con un tunel.
El token es obligatorio: sin `Authorization: Bearer <token>` toda peticion recibe 401.

```powershell
$env:ETABS_MCP_TOKEN = python -c "import secrets; print(secrets.token_urlsafe(32))"
$env:ETABS_MCP_TOKEN                      # guarda este valor
.\.venv\Scripts\etabs-mcp.exe --http --port 8756
```

En otra terminal, publica el puerto (cualquiera de los dos):

```powershell
cloudflared tunnel --url http://127.0.0.1:8756
ngrok http 8756
```

La URL del MCP es `https://<tu-tunel>/mcp`. Agrega `--readonly` si quieres exponerlo sin
herramientas de escritura.

Para verificar sin cliente MCP:

```powershell
.venv\Scripts\python -c "from etabs_mcp.server import etabs_model_info; print(etabs_model_info())"
```

## Herramientas

| Herramienta | Descripcion |
| --- | --- |
| `etabs_model_info` | Archivo, version, unidades y si el modelo esta analizado |
| `etabs_set_units` | Unidades de presentacion al leer datos (p. ej. `Ton_m_C`) |
| `etabs_stories` | Niveles con elevacion y altura |
| `etabs_grid_systems` | Sistemas de ejes |
| `etabs_points` | Nudos con coordenadas, etiqueta y nivel |
| `etabs_frames` | Vigas/columnas con seccion y nudos extremos |
| `etabs_areas` | Losas/muros con propiedad y contorno |
| `etabs_frame_sections` | Secciones de frame y sus propiedades geometricas |
| `etabs_area_sections` | Propiedades de area |
| `etabs_materials` | Materiales, tipo y peso especifico |
| `etabs_load_patterns` | Patrones de carga y multiplicador de peso propio |
| `etabs_load_cases` | Casos de carga |
| `etabs_load_combinations` | Combinaciones con sus casos y factores |
| `etabs_select_output` | Selecciona casos/combos para consultar resultados |
| `etabs_modal_periods` | Periodos y frecuencias modales |
| `etabs_base_reactions` | Reacciones en la base |
| `etabs_story_drifts` | Derivas por nivel |
| `etabs_joint_reactions` | Reacciones en nudos |
| `etabs_frame_forces` | Fuerzas internas en frames |
| `etabs_reconnect` | Re-adjunta a ETABS si cerraste o reabriste el programa |

### Escritura

| Herramienta | Descripcion |
| --- | --- |
| `etabs_new_model` | Modelo nuevo con reticula regular y niveles |
| `etabs_new_blank_model` | Modelo vacio |
| `etabs_open_model` / `etabs_save_model` | Abrir y guardar .EDB |
| `etabs_set_stories` | Define niveles y alturas |
| `etabs_define_concrete_material` | Material de concreto (f'c, E, peso) |
| `etabs_define_rectangular_section` / `etabs_define_circular_section` | Secciones de frame |
| `etabs_define_slab` / `etabs_define_wall` | Propiedades de losa y muro |
| `etabs_add_frame` | Viga o columna por coordenadas |
| `etabs_add_area` | Losa o muro por vertices |
| `etabs_set_point_restraint` | Apoyos en nudos |
| `etabs_add_load_pattern` | Patrones de carga |
| `etabs_assign_frame_distributed_load` | Carga distribuida en frames |
| `etabs_assign_area_uniform_load` | Carga uniforme en areas |
| `etabs_add_load_combination` | Combinaciones de carga |
| `etabs_run_analysis` | Corre el analisis |
| `etabs_unlock_model` / `etabs_refresh_view` | Desbloquear tras analisis y refrescar vistas |

Para dejar el servidor en modo consulta, exporta `ETABS_MCP_READONLY=1`: las herramientas de
escritura quedan deshabilitadas y devuelven error.

### Ejemplo de proyecto nuevo

1. `etabs_new_model` (units `Ton_m_C`, 3 niveles de 3 m, retícula 4x4 a 6 m)
2. `etabs_define_concrete_material` -> `etabs_define_rectangular_section` (columna y viga)
3. `etabs_add_frame` para columnas y vigas, `etabs_define_slab` + `etabs_add_area` para losas
4. `etabs_set_point_restraint` en la base
5. `etabs_add_load_pattern` + `etabs_assign_area_uniform_load` + `etabs_add_load_combination`
6. `etabs_run_analysis` y luego `etabs_select_output` con `etabs_story_drifts` / `etabs_base_reactions`
7. `etabs_save_model` con la ruta del .edb

Los resultados requieren que el analisis ya este corrido en ETABS y que antes llames a
`etabs_select_output` con los casos o combinaciones que te interesan. Las listas largas se
paginan con `limit` y `offset` (maximo 500 elementos por llamada).

## Notas

- Las herramientas de escritura desbloquean el modelo automaticamente cuando quedo bloqueado
  por un analisis previo.
- `etabs_new_model` descarta el modelo abierto sin guardar: guarda antes si te interesa.
- Si ETABS se cierra o cambias de modelo, usa `etabs_reconnect`.
- La API de CSI expone sus salidas como parametros ByRef; `call_api` prueba las dos
  convenciones que puede generar `comtypes` para que funcione en distintas instalaciones.