🌉 Qiao-MCP

English · 简体中文

전 생애주기 교량 구조 해석 — 모델링, 시공 단계, 규정 검토 桥梁全过程结构分析 MCP 服务器 — 建模、施工阶段、规范验算

Qiao-MCP는 Model Context Protocol (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로 설치)

• 백엔드 모델, 해석 또는 시각화 작업 호출 시 QiaoTong 소프트웨어 2.6.3 실행 중

MCP 서버는 QiaoTong 없이 시작할 수 있습니다. 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)에서 구성

Settings → MCP & Tools를 열고 새 MCP 서버 추가:

• Name: qiao-mcp

• Transport: stdio (기본값 유지)

• Command: 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

• Environment (선택 사항): UV_PYTHON=3.11

Add를 클릭하여 저장.

Cherry Studio (UI)에서 구성

设置 → 扩展 → MCP Servers를 열고 새 서버 추가:

• 名称 (Name): qiao-mcp

• 描述 (Description): 선택적 설명

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

• 命令 (Command): uv

• 包管理器 (Package Manager): 默认 (기본값) 선택

• 参数 (Args):

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

  (각 줄은 하나의 인수이며 --directory 접두사 불필요)

  • /path/to/qiao-mcp를 실제 프로젝트 경로로 바꾸세요.

保存을 클릭하여 저장.

MCP Inspector로 테스트

npx @modelcontextprotocol/inspector uv run qiao-mcp

LAN 디버깅 프록시

크로스 머신 디버깅을 위해 scripts/qiaotong_lan_proxy.py는 LAN 포트를 동일한 머신의 QiaoTong API로 전달합니다. 프록시에 45125를 사용하고 선택한 QiaoTong 프로세스의 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/")

프록시는 각 전달된 요청과 응답을 출력합니다. 여러 QiaoTong 프로세스가 실행 중인 경우, 이 고정 프록시를 위해 하나의 프로세스를 55125에 유지하거나 별도의 프록시 인스턴스와 포트를 사용하여 별도의 프로세스를 처리하세요.

SSH 터널은 LAN에 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

테스트 스위트는 오프라인에서 실행되도록 설계되었습니다. QiaoTong 소프트웨어가 필요하지 않습니다. 제공자/도구 호출은 설치된 qtmodel API 시그니처(계약 테스트)에 대해 검증되고 인-프로세스 가짜 백엔드에 디스패치됩니다.

백엔드: QTModel (桥通)

이 MCP 서버는 qtmodel Python API를 래핑하며, 다음에 대한 액세스를 제공합니다:

• mdb — 모델 데이터베이스: 교량 모델 구축 및 수정

• odb — 출력 데이터베이스: 해석 결과 조회 및 시각화

• cdb — 검토 데이터베이스: 구조 검증 및 규정 검토

버전 관리

Qiao-MCP는 qtmodel과 독립적으로 버전 관리됩니다. 프로젝트는 백엔드 릴리스를 기다리지 않고 자체적으로 반복(버그 수정, 새 도구, 문서)하며, 백엔드 릴리스가 여기서 버전 범프를 강제하지 않습니다. 백엔드 요구 사항은 종속성 제약 조건에 명시됩니다.

호환성

QiaoTong 소프트웨어 API 버전과 설치된 qtmodel은 정확히 일치해야 합니다. qtmodel 2.6+는 정확한 버전 핸드셰이크를 수행하며 그렇지 않으면 연결을 거부합니다. check_qiaotong_connection을 실행하여 두 버전을 확인하고 차이가 있을 때 수행할 작업을 확인하세요.

0.x는 API가 여전히 변경될 수 있음을 나타냅니다. 릴리스 품질에 대한 진술이 아닙니다. 새 qtmodel 마이너 라인으로 이동할 때 종속성 경계를 올리고 위 표에 행을 추가하세요.

라이선스

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

Apache License, Version 2.0에 따라 라이선스가 부여됩니다. LICENSE를 참조하세요. 추가 저작권 표시는 NOTICE에서 확인할 수 있습니다.