🌉 Qiao-MCP

English · 简体中文

Full-lifecycle bridge structural analysis — modeling, staging, code checks
桥梁全过程结构分析 MCP 服务器 — 建模、施工阶段、规范验算

Qiao-MCP es un servidor del Protocolo de Contexto de Modelo (MCP) que permite a los asistentes de IA interactuar con software de análisis estructural de puentes. Proporciona herramientas para crear modelos de puentes, aplicar cargas, ejecutar análisis estructurales y revisar resultados.

Características

🔧 Herramientas (132 herramientas, agrupadas)

Las herramientas están organizadas por área de flujo de trabajo. Destacados por grupo:

Las respuestas de las herramientas se normalizan a contenido estructurado ({status, ...}), mientras que las herramientas de imagen pueden devolver contenido de imagen MCP directamente. Los fallos de las herramientas utilizan errores MCP tipados, y las operaciones de solo lectura, destructivas y de mundo abierto llevan anotaciones de herramientas MCP. Las instrucciones del servidor incluyen la visión general completa del grupo de herramientas; use list_qtmodel_api antes de llamar a un método backend no cubierto a través de la puerta de enlace.

📦 Recursos (7 recursos)

💬 Prompts (4 flujos de trabajo)

Related MCP server: ETABS MCP Server

Arquitectura

qiao-mcp/
├── src/qiao_mcp/
│   ├── server.py              # MCP server entry point
│   ├── tools/                 # MCP Tools (envelope-wrapped)
│   ├── resources/             # MCP Resources
│   ├── prompts/               # MCP Prompts
│   └── providers/             # Backend adapters
│       ├── __init__.py        # BridgeProvider abstract base
│       └── qtmodel_provider.py  # QiaoTong adapter
├── tests/                     # Offline unit, integration, and API contract tests
└── reference-docs/            # Review notes and project documentation

El patrón de proveedor mantiene las 132 herramientas desacopladas de cualquier backend único. Seleccione uno con BRIDGE_PROVIDER; cada proveedor declara sus propias reglas específicas del software, por lo que el LLM se adapta sin cambios en el prompt. Actualmente es compatible con:

• QTModel (qtmodel, predeterminado) — Software de análisis de puentes QiaoTong (桥通) (manual de usuario)

Agregar un backend implica implementar BridgeProvider y registrar una línea, sin cambios en la capa de herramientas. Consulte Selección de Backend.

Inicio rápido

Requisitos previos

• Python >= 3.11

• Gestor de paquetes uv

• qtmodel 2.6.3 (instalado por uv sync)

• Software QiaoTong 2.6.3 en ejecución al llamar a operaciones de backend, modelo, análisis o visualización

El servidor MCP puede iniciarse sin QiaoTong. Use check_qiaotong_connection para distinguir entre un servidor conectado, una discrepancia de versión y un software que no se está ejecutando.

Instalar y ejecutar

# Install dependencies
uv sync

# Run the server
uv run qiao-mcp

Configurar en Claude Desktop

Agregue a su claude_desktop_config.json:

{
  "mcpServers": {
    "qiao-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/qiao-mcp", "run", "qiao-mcp"]
    }
  }
}

Configurar en Cursor

Agregue a .cursor/mcp.json:

{
  "mcpServers": {
    "qiao-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/qiao-mcp", "run", "qiao-mcp"]
    }
  }
}

Configurar en Reasonix (UI)

Abra Configuración → MCP y Herramientas, luego agregue un nuevo servidor MCP:

• Nombre: qiao-mcp

• Transporte: stdio (mantener predeterminado)

• Comando: uv --directory /ruta/a/qiao-mcp run qiao-mcp

  • Reemplace /ruta/a/qiao-mcp con la ruta real de su proyecto

  • Windows: use barras invertidas D:\ruta\a\qiao-mcp

  • macOS/Linux: use barras diagonales /ruta/a/qiao-mcp

• Entorno (opcional): UV_PYTHON=3.11

Haga clic en Agregar para guardar.

Configurar en Cherry Studio (UI)

Abra 设置 → 扩展 → MCP Servers, luego agregue un nuevo servidor:

• 名称 (Nombre): qiao-mcp

• 描述 (Descripción): Descripción opcional

• 类型 (Tipo): 标准输入 / 输出 (stdio)

• 命令 (Comando): uv

• 包管理器 (Gestor de paquetes): Seleccione 默认 (Predeterminado)

• 参数 (Args):

  /path/to/qiao-mcp
  run
  qiao-mcp

  (Cada línea es un argumento, no se necesita el prefijo --directory)

  • Reemplace /ruta/a/qiao-mcp con la ruta real de su proyecto

Haga clic en 保存 para guardar.

Probar con MCP Inspector

npx @modelcontextprotocol/inspector uv run qiao-mcp

Proxy de depuración LAN

Para depuración entre máquinas, scripts/qiaotong_lan_proxy.py reenvía un puerto orientado a LAN a la API de QiaoTong en la misma máquina. Utiliza 45125 para el proxy y reenvía al proceso de QiaoTong seleccionado en 127.0.0.1:55125:

python scripts/qiaotong_lan_proxy.py

Luego apunte la máquina cliente a:

from qtmodel import mdb

mdb.set_url("http://<proxy-machine-LAN-IP>:45125/pythonForQt/")

El proxy imprime cada solicitud y respuesta reenviada. Cuando se ejecutan varios procesos de QiaoTong, mantenga un proceso en 55125 para este proxy fijo, o use instancias de proxy y puertos separados para procesos separados.

Un túnel SSH es una alternativa que no expone el puerto de la API en la LAN:

ssh -N -L 45125:127.0.0.1:55125 <user>@<qiaotong-machine-LAN-IP>

Use http://127.0.0.1:45125/pythonForQt/ en la máquina cliente mientras el túnel está activo.

Desarrollo

# Install in dev mode (includes ruff, mypy, pytest)
uv sync

# Run directly
uv run python -m qiao_mcp.server

# Quality gate (same checks as CI)
uv run ruff check src/ tests/
uv run mypy src/qiao_mcp/
uv run pytest tests/ -q

El conjunto de pruebas está diseñado para ejecutarse sin conexión — no requiere el software QiaoTong. Las llamadas a proveedores/herramientas se validan con las firmas de la API qtmodel instalada (pruebas de contrato) y se envían a un backend simulado en proceso.

Backend: QTModel (桥通)

Este servidor MCP envuelve la API de Python qtmodel que proporciona acceso a:

• mdb — Base de datos del modelo: creación y modificación de modelos de puentes

• odb — Base de datos de salida: consulta de resultados de análisis y visualización

• cdb — Base de datos de verificación: verificación estructural y comprobación de normativas

Versionado

Qiao-MCP tiene versiones independientes de qtmodel — el proyecto itera por su cuenta (correcciones de errores, nuevas herramientas, documentación) sin esperar una versión del backend, y una versión del backend no fuerza un cambio de versión aquí. El requisito del backend se expresa donde corresponde: en la restricción de dependencia.

Compatibilidad

La versión de la API del software QiaoTong y el qtmodel instalado deben coincidir exactamente — qtmodel 2.6+ realiza un protocolo de enlace de versión preciso y se niega a conectarse de lo contrario. Ejecute check_qiaotong_connection para ver ambas versiones y qué hacer cuando difieran.

0.x indica que la API aún es libre de cambiar; no es una declaración sobre la calidad de la versión. Al pasar a una nueva línea menor de qtmodel, aumente el límite de dependencia y agregue una fila a la tabla anterior.

Licencia

Copyright 2026 Sorata (https://github.com/SorataYang)

Licenciado bajo la Licencia Apache, Versión 2.0. Consulte LICENSE. Los avisos de atribución adicionales están disponibles en NOTICE.