{
  "markdown": "# 🌉 Qiao-MCP\n\n<!-- mcp-name: io.github.SorataYang/qiao-mcp -->\n\n**English** · [简体中文](./README.zh-CN.md)\n\n> Full-lifecycle bridge structural analysis — modeling, staging, code checks  \n> 桥梁全过程结构分析 MCP 服务器 — 建模、施工阶段、规范验算\n\nQiao-MCP is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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.\n\n## Features\n\n### 🔧 Tools (132 tools, grouped)\n\nTools are organized by workflow area. Highlights per group:\n\n| Group | Representative tools |\n|-------|----------------------|\n| **Core modeling** | `create_nodes_linear`, `create_beam_elements_linear`, `create_material`, `create_section` (all parametric section types), `create_polygon_section` |\n| **Loads** | `create_load_group`, `create_load_case`, `set_self_weight_stage`, `set_gravity`, `apply_nodal_force`, `apply_beam_distributed_load`, temperature/settlement loads |\n| **Boundary** | `set_support`, `add_elastic_link`, `add_master_slave_link`, `add_elastic_support`, `add_beam_constraint` |\n| **Groups** | `create_structure_group`, `add_to_structure_group`, `merge_operation_stage` |\n| **Stages & analysis** | `add_construction_stage`, `merge_operation_stage`, `configure_analysis`, `run_analysis` (async, progress-reporting), `get_analysis_results` |\n| **Tendons** | `create_tendon_property`, `create_tendon_2d`, `apply_prestress`, `get_tendon_info` |\n| **Traffic (moving load)** | `add_node_tandem`, `add_influence_plane`, `add_traffic_lane`, `add_standard_vehicle`, `create_live_load_case` |\n| **Checking** | `setup_concrete_check`, `add_check_load_combination`, `add_parametric_reinforcement`, `run_concrete_check`, `get_check_data` |\n| **Queries** | `get_model_info`, `get_model_data` (by kind), `find_entities`, `calc_section_property`, `get_special_results` (paginated where applicable) |\n| **Modification** | `initialize_model`, `save_model_file`, `open_model_file`, `update_node`, `move_nodes`, `update_element`, `remove_nodes`, `remove_elements` |\n| **Visualization** | `save_model_screenshot`, `plot_analysis_result` (optionally return viewable images), `set_view_angle`, `display_ids` |\n| **Workflows** | `create_simple_beam_bridge`, `create_continuous_beam_bridge` |\n| **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 |\n\nTool responses are normalized to structured content (`{status, ...}`), while image\ntools can return MCP image content directly. Tool failures use typed MCP errors, and\nread-only, destructive, and open-world operations carry MCP tool annotations. The\nserver instructions include the full tool-group overview; use `list_qtmodel_api`\nbefore calling an uncovered backend method through the gateway.\n\n### 📦 Resources (7 resources)\n| URI | Description |\n|-----|-------------|\n| `bridge://model/summary` | Model overview |\n| `bridge://model/materials` | Material list |\n| `bridge://model/sections` | Section list |\n| `bridge://model/load-cases` | Load cases |\n| `bridge://model/stages` | Construction stages |\n| `bridge://model/structure-groups` | Structure groups |\n| `bridge://model/boundaries` | Boundary conditions |\n\n### 💬 Prompts (4 workflows)\n| Prompt | Description |\n|--------|-------------|\n| `design-simple-beam` | Simple beam bridge design workflow (简支梁设计) |\n| `design-continuous-beam` | Continuous beam bridge design (连续梁设计) |\n| `check-structure` | Structural code checking (结构检算) |\n| `construction-stage-analysis` | Construction stage analysis (施工阶段分析) |\n\n## Architecture\n\n```\nqiao-mcp/\n├── src/qiao_mcp/\n│   ├── server.py              # MCP server entry point\n│   ├── tools/                 # MCP Tools (envelope-wrapped)\n│   ├── resources/             # MCP Resources\n│   ├── prompts/               # MCP Prompts\n│   └── providers/             # Backend adapters\n│       ├── __init__.py        # BridgeProvider abstract base\n│       └── qtmodel_provider.py  # QiaoTong adapter\n├── tests/                     # Offline unit, integration, and API contract tests\n└── reference-docs/            # Review notes and project documentation\n```\n\nThe **Provider pattern** keeps the 132 tools decoupled from any single backend. Select one with\n`BRIDGE_PROVIDER`; each provider declares its own software-specific rules, so the LLM adapts\nwithout prompt changes. Currently supports:\n- **QTModel** (`qtmodel`, default) — [QiaoTong (桥通)](https://www.brdi.com.cn/Software.html) bridge analysis software ([user manual](https://soratayang.github.io/))\n\nAdding a backend means implementing `BridgeProvider` and registering one line — no tool-layer\nchanges. See [Backend Selection](./INTEGRATION_GUIDE.md#后端选择-backend-selection).\n\n## Quick Start\n\n### Prerequisites\n- Python >= 3.11\n- [uv](https://docs.astral.sh/uv/) package manager\n- `qtmodel` 2.6.3 (installed by `uv sync`)\n- QiaoTong software 2.6.3 running when calling backend model, analysis, or visualization operations\n\nThe MCP server can start without QiaoTong. Use `check_qiaotong_connection` to\ndistinguish a connected server, a version mismatch, and software that is not running.\n\n### Install & Run\n\n```bash\n# Install dependencies\nuv sync\n\n# Run the server\nuv run qiao-mcp\n```\n\n### Configure in Claude Desktop\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"qiao-mcp\": {\n      \"command\": \"uv\",\n      \"args\": [\"--directory\", \"/path/to/qiao-mcp\", \"run\", \"qiao-mcp\"]\n    }\n  }\n}\n```\n\n### Configure in Cursor\n\nAdd to `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"qiao-mcp\": {\n      \"command\": \"uv\",\n      \"args\": [\"--directory\", \"/path/to/qiao-mcp\", \"run\", \"qiao-mcp\"]\n    }\n  }\n}\n```\n\n### Configure in Reasonix (UI)\n\nOpen **Settings** → **MCP & Tools**, then add a new MCP server:\n\n- **Name**: `qiao-mcp`\n- **Transport**: `stdio` (keep default)\n- **Command**: `uv --directory /path/to/qiao-mcp run qiao-mcp`\n  - Replace `/path/to/qiao-mcp` with your actual project path\n  - Windows: use backslashes `D:\\path\\to\\qiao-mcp`\n  - macOS/Linux: use forward slashes `/path/to/qiao-mcp`\n- **Environment** (optional): `UV_PYTHON=3.11`\n\nClick **Add** to save.\n\n### Configure in Cherry Studio (UI)\n\nOpen **设置** → **扩展** → **MCP Servers**, then add a new server:\n\n- **名称 (Name)**: `qiao-mcp`\n- **描述 (Description)**: Optional description\n- **类型 (Type)**: `标准输入 / 输出 (stdio)`\n- **命令 (Command)**: `uv`\n- **包管理器 (Package Manager)**: Select `默认` (Default)\n- **参数 (Args)**: \n  ```\n  /path/to/qiao-mcp\n  run\n  qiao-mcp\n  ```\n  (Each line is one argument, no `--directory` prefix needed)\n  - Replace `/path/to/qiao-mcp` with your actual project path\n\nClick **保存** to save.\n\n### Test with MCP Inspector\n\n```bash\nnpx @modelcontextprotocol/inspector uv run qiao-mcp\n```\n\n### LAN debugging proxy\n\nFor cross-machine debugging, [`scripts/qiaotong_lan_proxy.py`](./scripts/qiaotong_lan_proxy.py)\nforwards a LAN-facing port to the QiaoTong API on the same machine. It uses\n`45125` for the proxy and forwards to the selected QiaoTong process on\n`127.0.0.1:55125`:\n\n```bash\npython scripts/qiaotong_lan_proxy.py\n```\n\nThen point the client machine at:\n\n```python\nfrom qtmodel import mdb\n\nmdb.set_url(\"http://<proxy-machine-LAN-IP>:45125/pythonForQt/\")\n```\n\nThe proxy prints each forwarded request and response. When several QiaoTong\nprocesses are running, keep one process on `55125` for this fixed proxy, or use\nseparate proxy instances and ports for separate processes.\n\nAn SSH tunnel is an alternative that does not expose the API port on the LAN:\n\n```bash\nssh -N -L 45125:127.0.0.1:55125 <user>@<qiaotong-machine-LAN-IP>\n```\n\nUse `http://127.0.0.1:45125/pythonForQt/` in the client machine while the tunnel\nis running.\n\n## Development\n\n```bash\n# Install in dev mode (includes ruff, mypy, pytest)\nuv sync\n\n# Run directly\nuv run python -m qiao_mcp.server\n\n# Quality gate (same checks as CI)\nuv run ruff check src/ tests/\nuv run mypy src/qiao_mcp/\nuv run pytest tests/ -q\n```\n\nThe test suite is designed to run offline — it does not require the QiaoTong software.\nProvider/tool calls are validated against the installed `qtmodel` API signatures\n(contract tests) and dispatched against an in-process fake backend.\n\n## Backend: QTModel (桥通)\n\nThis MCP server wraps the `qtmodel` Python API which provides access to:\n- **mdb** — Model database: building & modifying bridge models\n- **odb** — Output database: querying analysis results & visualization\n- **cdb** — Check database: structural verification & code checking\n\n## Versioning\n\nQiao-MCP versions independently from `qtmodel` — the project iterates on its own\n(bug fixes, new tools, docs) without waiting for a backend release, and a backend\nrelease does not force a version bump here. The backend requirement is expressed\nwhere it belongs: in the dependency constraint.\n\n### Compatibility\n\n| Qiao-MCP | qtmodel       | QiaoTong software |\n|----------|---------------|-------------------|\n| 0.3.x    | 2.6.3 – 2.6.x | 2.6.3             |\n| 0.2.x    | 2.5.0 – 2.5.x | 2.5.0             |\n\nThe QiaoTong software API version and the installed `qtmodel` must match\n**exactly** — qtmodel 2.6+ performs a precise version handshake and refuses to\nconnect otherwise. Run `check_qiaotong_connection` to see both versions and what\nto do when they differ.\n\n`0.x` signals the API is still free to change; it is not a statement about\nrelease quality. When moving to a new qtmodel minor line, raise the dependency\nbound and add a row to the table above.\n\n## License\n\nCopyright 2026 Sorata (https://github.com/SorataYang)\n\nLicensed under the Apache License, Version 2.0. See [LICENSE](./LICENSE).\nAdditional attribution notices are available in [NOTICE](./NOTICE).\n",
  "bytes": 9802,
  "sha": "41335c926d2ffa8c5241904d0c84164f67ebb069e21a23f5930edcd31ecea06f",
  "repo_slug": "soratayang/qiao-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_soratayang_qiao_mcp_b0c55fc3/readme"
}