🌉 Qiao-MCP

English · 简体中文

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:

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)

💬 Prompts (4 workflows)

Architecture

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

# Install dependencies
uv sync

# Run the server
uv run qiao-mcp

Configure in Claude Desktop

Add to your claude_desktop_config.json:

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

Configure in Cursor

Add to .cursor/mcp.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

  Copy

  /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

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:

python scripts/qiaotong_lan_proxy.py

Then point the client machine at:

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:

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

# 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

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

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

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