🌉 Qiao-MCP

English · 简体中文

全生命周期桥梁结构分析 — 建模、施工阶段、规范验算 桥梁全过程结构分析 MCP 服务器 — 建模、施工阶段、规范验算

Qiao-MCP 是一个 模型上下文协议 (MCP) 服务器，使 AI 助手能够与桥梁结构分析软件交互。它提供了创建桥梁模型、施加荷载、运行结构分析和查看结果的工具。

功能特性

🔧 工具（132 个工具，按组分类）

工具按工作流区域组织。每组亮点：

工具响应被规范化为结构化内容（{status, ...}），而图像工具可以直接返回 MCP 图像内容。工具失败使用类型化的 MCP 错误，只读、破坏性和开放世界操作带有 MCP 工具注释。服务器指令包含完整的工具组概览；在通过网关调用未覆盖的后端方法之前，请使用 list_qtmodel_api。

📦 资源（7 个资源）

💬 提示（4 个工作流）

Related MCP server: ETABS MCP Server

架构

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

提供者模式使 132 个工具与任何单一后端解耦。通过 BRIDGE_PROVIDER 选择一个；每个提供者声明自己的软件特定规则，因此 LLM 无需更改提示即可适应。目前支持：

• QTModel (qtmodel，默认) — 桥通 (QiaoTong) 桥梁分析软件（用户手册）

添加后端意味着实现 BridgeProvider 并注册一行 — 无需更改工具层。参见 后端选择。

快速开始

前提条件

• Python >= 3.11

• uv 包管理器

• qtmodel 2.6.3（由 uv sync 安装）

• 调用后端模型、分析或可视化操作时，桥通软件 2.6.3 正在运行

MCP 服务器可以在没有桥通的情况下启动。使用 check_qiaotong_connection 来区分已连接的服务器、版本不匹配以及软件未运行的情况。

安装与运行

# Install dependencies
uv sync

# Run the server
uv run qiao-mcp

在 Claude Desktop 中配置

添加到你的 claude_desktop_config.json：

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

在 Cursor 中配置

添加到 .cursor/mcp.json：

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

在 Reasonix（UI）中配置

打开 设置 → MCP & 工具，然后添加一个新的 MCP 服务器：

• 名称: qiao-mcp

• 传输方式: stdio（保持默认）

• 命令: uv --directory /path/to/qiao-mcp run qiao-mcp

  • 将 /path/to/qiao-mcp 替换为你的实际项目路径

  • Windows：使用反斜杠 D:\path\to\qiao-mcp

  • macOS/Linux：使用正斜杠 /path/to/qiao-mcp

• 环境变量（可选）：UV_PYTHON=3.11

点击 添加 保存。

在 Cherry Studio（UI）中配置

打开 设置 → 扩展 → MCP 服务器，然后添加一个新的服务器：

• 名称: qiao-mcp

• 描述: 可选描述

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

• 命令: uv

• 包管理器: 选择 默认

• 参数:

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

  （每行一个参数，不需要 --directory 前缀）

  • 将 /path/to/qiao-mcp 替换为你的实际项目路径

点击 保存 保存。

使用 MCP Inspector 测试

npx @modelcontextprotocol/inspector uv run qiao-mcp

局域网调试代理

对于跨机器调试，scripts/qiaotong_lan_proxy.py 将局域网端口转发到同一台机器上的桥通 API。它使用 45125 作为代理端口，并转发到选定的桥通进程（位于 127.0.0.1:55125）：

python scripts/qiaotong_lan_proxy.py

然后将客户端机器指向：

from qtmodel import mdb

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

代理会打印每个转发的请求和响应。当多个桥通进程运行时，将一个进程保持在 55125 上用于此固定代理，或者为不同进程使用单独的代理实例和端口。

SSH 隧道是一种替代方案，不会在局域网上暴露 API 端口：

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

在隧道运行时，在客户端机器上使用 http://127.0.0.1:45125/pythonForQt/。

开发

# 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

测试套件设计为离线运行 — 它不需要桥通软件。提供者/工具调用根据已安装的 qtmodel API 签名进行验证（契约测试），并针对进程内的假后端进行调度。

后端：QTModel（桥通）

此 MCP 服务器封装了 qtmodel Python API，该 API 提供对以下内容的访问：

• mdb — 模型数据库：构建和修改桥梁模型

• odb — 输出数据库：查询分析结果和可视化

• cdb — 验算数据库：结构验证和规范验算

版本管理

Qiao-MCP 独立于 qtmodel 进行版本管理 — 项目自行迭代（错误修复、新工具、文档），无需等待后端发布，后端发布也不会强制此处版本升级。后端需求在其所属位置表达：在依赖约束中。

兼容性

桥通软件 API 版本和已安装的 qtmodel 必须完全匹配 — qtmodel 2.6+ 会进行精确的版本握手，否则拒绝连接。运行 check_qiaotong_connection 查看两个版本以及当它们不同时该怎么做。

0.x 表示 API 仍可自由更改；这不是关于发布质量的声明。当迁移到新的 qtmodel 次要版本线时，提高依赖边界并在上表中添加一行。

许可证

版权所有 2026 Sorata (https://github.com/SorataYang)

根据 Apache 许可证 2.0 版授权。参见 LICENSE。 其他归属声明见 NOTICE。