SAP2000 Automation Framework

Framework de automatización de SAP2000 mediante Python, COM bridge y Model Context Protocol (MCP).

Permite generar modelos estructurales, asignar cargas, ejecutar análisis y extraer resultados de forma programática — todo orquestado desde VS Code con GitHub Copilot como interfaz conversacional.

Características Principales

• MCP Bridge — Servidor MCP que conecta GitHub Copilot con SAP2000 vía COM automation
• 212 funciones API verificadas — Registry con firmas, parámetros ByRef y wrappers testeados
• 127 wrapper scripts — Funciones individuales documentadas y verificadas contra SAP2000 real
• Scripts parametrizados — Modelos completos generados programáticamente (vigas, domos, naves, placas base)
• 8 aplicaciones GUI standalone — Interfaces PySide6 con worker threads para operación asíncrona
• Sandbox seguro — Ejecución aislada de scripts con restricciones de imports y timeout
• Documentación API completa — 25 archivos markdown cubriendo toda la API de SAP2000

Arquitectura

graph LR
    A["👤 Usuario"] --> B["🤖 GitHub Copilot"]
    B -->|MCP Protocol| C["🐍 MCP Server<br/>(Python)"]
    C -->|COM Automation| D["🏗️ SAP2000"]
    
    C --- E["📋 Script Library"]
    C --- F["📖 API Docs Index"]
    C --- G["🔧 Function Registry"]
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#fff3e0
    style D fill:#e8f5e9

Flujo de Trabajo

1. El usuario describe lo que necesita en lenguaje natural a Copilot
2. Copilot consulta el MCP Server para buscar documentación y funciones verificadas
3. El MCP Server genera y ejecuta scripts en un sandbox aislado
4. SAP2000 procesa los comandos vía COM automation y retorna resultados
5. El script se guarda automáticamente en la biblioteca de scripts

Componentes del MCP Server

Requisitos

Instalación

# 1. Clonar repositorio
git clone https://github.com/tu-usuario/Skills_SAP.git
cd Skills_SAP

# 2. Crear y activar entorno virtual
python -m venv .venv
.venv\Scripts\Activate.ps1

# 3. Instalar dependencias
pip install -r mcp_server/requirements.txt

# 4. (Opcional) Para GUIs standalone
pip install PySide6

Configuración en VS Code

El servidor MCP se autoconfigura via .vscode/mcp.json. Al abrir el workspace y usar Copilot, el server se inicia automáticamente — no requiere configuración manual.

Configuración en Claude Code

Para usar las herramientas MCP desde Claude Code, crear .claude/settings.json en la raíz del proyecto con rutas absolutas:

{
  "mcpServers": {
    "sap2000": {
      "command": "<ruta-al-proyecto>/.venv/Scripts/python.exe",
      "args": [
        "<ruta-al-proyecto>/mcp_server/server.py"
      ],
      "env": {}
    }
  }
}

Diferencias con VS Code:

• Root key es "mcpServers" (no "servers")
• No incluir "type": "stdio" (Claude Code lo asume)
• Usar rutas absolutas — ${workspaceFolder} no está disponible

Uso:

1. Asegurarse de que SAP2000 esté abierto
2. Llamar connect_sap2000 una vez por sesión para establecer el bridge COM
3. Las 12 herramientas MCP quedan disponibles automáticamente

Ejemplos de Aplicación

Scripts completos en scripts/ejemplos/, generados conversacionalmente con Copilot y verificados contra SAP2000 real.

Aplicaciones GUI Standalone

Interfaces gráficas completas construidas con PySide6, operables sin VS Code ni Copilot. Cada GUI se conecta directamente a SAP2000 via COM.

Modelo Base Estandarizado

Archivos: scripts/modelo_base/

Generador de modelo base con materiales, patrones de carga, secciones de acero/HA, espectros NCh2369 y combinaciones LRFD/ASD/NCh. Configuración completa en archivo config.py con parámetros sísmicos por zona.

Placa Base Paramétrica

Archivos: scripts/placabase/

Interfaz para generar placas base con control visual de todos los parámetros: pernos, silla de anclaje, balasto, y mallado. Incluye worker threads para ejecución asíncrona sin bloquear la GUI.

Anillo Circular

Archivos: scripts/ring_areas/

GUI para generar anillos circulares parametrizados con control de radios, espesores y calidad de malla por zona concéntrica.

Explorador de Database Tables

Archivos: scripts/database_tables/

Navegador y editor de las tablas internas de SAP2000. Permite listar todas las tablas, leer datos, editar celdas y exportar a CSV/XML/Excel. Cubre las 37 funciones de DatabaseTables.*.

Post-Proceso: Estabilidad y Shells

Archivos: scripts/post_proceso/

Extracción de resultados de análisis: desplazamientos de nodos (JointDispl) para verificación de estabilidad y fuerzas en shells (AreaForceShell) para todas las combinaciones de carga. Opera sobre la selección manual del usuario en SAP2000.

Combinaciones de Carga

Archivos: scripts/comb_cargas/

Gestor de combinaciones de carga con CRUD completo y templates de combinaciones normativas (LRFD, ASD, NCh). Permite crear, editar y eliminar combinaciones directamente en el modelo activo.

Estados de Carga

Archivos: scripts/estados_carga/

Aplicación multi-tab para mapeo y verificación de estados de carga. Arquitectura completa con capa de modelo dedicada, verificación basada en fixtures y funciones de cálculo reutilizables.

Fundaciones

Archivos: scripts/fundaciones/

Generador paramétrico de fundaciones. Diseño automatizado con conexión directa a SAP2000 para crear geometría, asignar propiedades y aplicar cargas.

Registry de Funciones Verificadas

El framework mantiene un registro de 212 funciones API verificadas contra SAP2000 real. Cada entrada incluye:

• Firma completa con tipos de parámetros
• Layout ByRef — posición de cada parámetro de salida en el tuple retornado
• Wrapper script — código ejecutable que demuestra el uso
• Notas — particularidades, valores por defecto, errores comunes

Categorías cubiertas:

Estructura del Proyecto

Skills_SAP/
├── mcp_server/              # Servidor MCP (Python)
│   ├── server.py            #   Entry point — 12 herramientas MCP
│   ├── sap_bridge.py        #   Conexión COM singleton
│   ├── sap_executor.py      #   Sandbox de ejecución
│   ├── script_library.py    #   Persistencia de scripts
│   ├── doc_search.py        #   Buscador de documentación API
│   ├── function_registry.py #   Registry de funciones verificadas
│   └── tests/               #   Tests unitarios e integración
│
├── scripts/                 # Scripts y aplicaciones
│   ├── ejemplos/            #   7 scripts de ejemplo completos
│   ├── wrappers/            #   127 wrappers de funciones individuales
│   ├── templates/           #   Templates base (backend + GUI)
│   ├── mesh/                #   Backends de generación de malla
│   ├── modelo_base/         #   GUI: Modelo base estandarizado
│   ├── placabase/           #   GUI: Placa base paramétrica
│   ├── ring_areas/          #   GUI: Anillo circular
│   ├── database_tables/     #   GUI: Explorador de tablas
│   ├── post_proceso/        #   GUI: Estabilidad + shells
│   ├── comb_cargas/         #   GUI: Combinaciones de carga
│   ├── estados_carga/       #   GUI: Estados de carga
│   ├── fundaciones/         #   GUI: Fundaciones paramétricas
│   ├── columnas/            #   Generador de columnas
│   ├── steel_connections/   #   Conexiones de acero
│   ├── section_cut/         #   Section Cuts (en desarrollo)
│   └── registry.json        #   Registry de 212 funciones verificadas
│
├── API/                     # Documentación API SAP2000 (25 archivos .md)
│
└── .github/
    ├── copilot-instructions.md   # Instrucciones para Copilot
    ├── agents/                    # Agente SAP2000 Scripter
    └── skills/                    # Skill de referencia API

Herramientas MCP Disponibles

El servidor expone 12 herramientas que Copilot puede invocar:

Tecnologías

• Python 3.10+ — Lenguaje principal
• comtypes — Interfaz COM para SAP2000
• MCP (Model Context Protocol) — Protocolo de comunicación con Copilot
• FastMCP — SDK para servidor MCP
• PySide6 — Framework GUI (aplicaciones standalone)
• SAP2000 API — API COM de CSI para análisis estructural

Licencia

Este proyecto está bajo la licencia MIT. Ver LICENSE para más detalles.