🌉 Qiao-MCP

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

Qiao-MCP is a Model Context Protocol (MCP) server that enables AI assistants to interact with bridge structural analysis software. It provides tools for creating bridge models, applying loads, running structural analysis, and reviewing results.

Features

🔧 Tools (132 tools, grouped)

Tools are organized by workflow area. Highlights per group:

Group	Representative tools
Core modeling	`create_nodes_linear`, `create_beam_elements_linear`, `create_material`, `create_section` (all parametric section types), `create_polygon_section`
Loads	`create_load_group`, `create_load_case`, `set_self_weight_stage`, `set_gravity`, `apply_nodal_force`, `apply_beam_distributed_load`, temperature/settlement loads
Boundary	`set_support`, `add_elastic_link`, `add_master_slave_link`, `add_elastic_support`, `add_beam_constraint`
Groups	`create_structure_group`, `add_to_structure_group`, `merge_operation_stage`
Stages & analysis	`add_construction_stage`, `merge_operation_stage`, `configure_analysis`, `run_analysis` (async, progress-reporting), `get_analysis_results`
Tendons	`create_tendon_property`, `create_tendon_2d`, `apply_prestress`, `get_tendon_info`
Traffic (moving load)	`add_node_tandem`, `add_influence_plane`, `add_traffic_lane`, `add_standard_vehicle`, `create_live_load_case`
Checking	`setup_concrete_check`, `add_check_load_combination`, `add_parametric_reinforcement`, `run_concrete_check`, `get_check_data`
Queries	`get_model_info`, `get_model_data` (by kind), `find_entities`, `calc_section_property`, `get_special_results` (paginated where applicable)
Modification	`initialize_model`, `save_model_file`, `open_model_file`, `update_node`, `move_nodes`, `update_element`, `remove_nodes`, `remove_elements`
Visualization	`save_model_screenshot`, `plot_analysis_result` (optionally return viewable images), `set_view_angle`, `display_ids`
Workflows	`create_simple_beam_bridge`, `create_continuous_beam_bridge`
Gateway & diagnostics	`check_qiaotong_connection`, `list_qtmodel_api`, `call_qtmodel_api` — diagnose the bridge connection or discover and call long-tail qtmodel methods with signature validation

Tool responses are normalized to structured content ({status, ...}), while image tools can return MCP image content directly. Tool failures use typed MCP errors, and read-only, destructive, and open-world operations carry MCP tool annotations. The server instructions include the full tool-group overview; use list_qtmodel_api before calling an uncovered backend method through the gateway.

📦 Resources (7 resources)

URI	Description
`bridge://model/summary`	Model overview
`bridge://model/materials`	Material list
`bridge://model/sections`	Section list
`bridge://model/load-cases`	Load cases
`bridge://model/stages`	Construction stages
`bridge://model/structure-groups`	Structure groups
`bridge://model/boundaries`	Boundary conditions

💬 Prompts (4 workflows)

Prompt	Description
`design-simple-beam`	Simple beam bridge design workflow (简支梁设计)
`design-continuous-beam`	Continuous beam bridge design (连续梁设计)
`check-structure`	Structural code checking (结构检算)
`construction-stage-analysis`	Construction stage analysis (施工阶段分析)

Architecture

Code

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

The Provider pattern keeps the 132 tools decoupled from any single backend. Select one with BRIDGE_PROVIDER; each provider declares its own software-specific rules, so the LLM adapts without prompt changes. Currently supports:

QTModel (qtmodel, default) — QiaoTong (桥通) bridge analysis software (user manual)

Adding a backend means implementing BridgeProvider and registering one line — no tool-layer changes. See Backend Selection.

Quick Start

Prerequisites

Python >= 3.11
uv package manager
qtmodel 2.6.3 (installed by uv sync)
QiaoTong software 2.6.3 running when calling backend model, analysis, or visualization operations

The MCP server can start without QiaoTong. Use check_qiaotong_connection to distinguish a connected server, a version mismatch, and software that is not running.

Install & Run

bash

# Install dependencies
uv sync

# Run the server
uv run qiao-mcp

Configure in Claude Desktop

Add to your claude_desktop_config.json:

config.json

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

Configure in Cursor

Add to .cursor/mcp.json:

config.json

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

Configure in Reasonix (UI)

Open Settings → MCP & Tools, then add a new MCP server:

Name: qiao-mcp
Transport: stdio (keep default)
Command: uv --directory /path/to/qiao-mcp run qiao-mcp
- Replace /path/to/qiao-mcp with your actual project path
- Windows: use backslashes D:\path\to\qiao-mcp
- macOS/Linux: use forward slashes /path/to/qiao-mcp
Environment (optional): UV_PYTHON=3.11

Click Add to save.

Configure in Cherry Studio (UI)

Open 设置 → 扩展 → MCP Servers, then add a new server:

名称 (Name): qiao-mcp
描述 (Description): Optional description
类型 (Type): 标准输入 / 输出 (stdio)
命令 (Command): uv
包管理器 (Package Manager): Select 默认 (Default)
参数 (Args):
Code
```
/path/to/qiao-mcp
run
qiao-mcp
```
(Each line is one argument, no --directory prefix needed)
- Replace /path/to/qiao-mcp with your actual project path

Click 保存 to save.

Test with MCP Inspector

Terminal

npx @modelcontextprotocol/inspector uv run qiao-mcp

LAN debugging proxy

For cross-machine debugging, scripts/qiaotong_lan_proxy.py forwards a LAN-facing port to the QiaoTong API on the same machine. It uses 45125 for the proxy and forwards to the selected QiaoTong process on 127.0.0.1:55125:

bash

python scripts/qiaotong_lan_proxy.py

Then point the client machine at:

server.ts

from qtmodel import mdb

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

The proxy prints each forwarded request and response. When several QiaoTong processes are running, keep one process on 55125 for this fixed proxy, or use separate proxy instances and ports for separate processes.

An SSH tunnel is an alternative that does not expose the API port on the LAN:

bash

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

Use http://127.0.0.1:45125/pythonForQt/ in the client machine while the tunnel is running.

Development

bash

# 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

The test suite is designed to run offline — it does not require the QiaoTong software. Provider/tool calls are validated against the installed qtmodel API signatures (contract tests) and dispatched against an in-process fake backend.

Backend: QTModel (桥通)

This MCP server wraps the qtmodel Python API which provides access to:

mdb — Model database: building & modifying bridge models
odb — Output database: querying analysis results & visualization
cdb — Check database: structural verification & code checking

Versioning

Qiao-MCP versions independently from qtmodel — the project iterates on its own (bug fixes, new tools, docs) without waiting for a backend release, and a backend release does not force a version bump here. The backend requirement is expressed where it belongs: in the dependency constraint.

Compatibility

Qiao-MCP	qtmodel	QiaoTong software
0.3.x	2.6.3 – 2.6.x	2.6.3
0.2.x	2.5.0 – 2.5.x	2.5.0

The QiaoTong software API version and the installed qtmodel must match exactly — qtmodel 2.6+ performs a precise version handshake and refuses to connect otherwise. Run check_qiaotong_connection to see both versions and what to do when they differ.

0.x signals the API is still free to change; it is not a statement about release quality. When moving to a new qtmodel minor line, raise the dependency bound and add a row to the table above.

License

Licensed under the Apache License, Version 2.0. See LICENSE. Additional attribution notices are available in NOTICE.