Qiao-MCP — Bridge Engineering (桥梁工程)

🌉 Qiao-MCP

英語 · 简体中文

橋梁结构分析の全生命周期をカバー — モデリング、施工段階、コード検査
桥梁全过程结构分析 MCP 服务器 — 建模、施工阶段、规范验算

Qiao-MCP は、AI アシスタントが橋梁構造解析ソフトウェアを操作できるようにする Model Context Protocol (MCP) サーバーです。橋梁モデルの作成、荷重の適用、構造解析の実行、結果の確認を行うツールを提供します。

特長

🔧 ツール（15 のドメインエントリーポイント、153 の操作）

バージョン 0.6.0 では、15 のドメインツールを公開しています。各ツールは、operation セレクターと対応するフィールドを含む request を受け取ります。スキーマには、各操作のすべてのパラメーターについて、詳細な説明、デフォルト値、制約が含まれています。従来の 153 個の名前はすべて、元の引数で引き続き直接呼び出せます。

ドメインツール	対象範囲
inspect_bridge	接続、モデルの状態、編集の準備状況
manage_model_files	プロジェクトの開く、保存、初期化
query_model	定義、エンティティ検索、形状チェック
edit_geometry	節点、要素、橋梁レイアウト
edit_properties	材料、断面、厚さ、時間効果
edit_boundaries	地盤支持、節点リンク、梁端解放
edit_construction	グループ、ステージ、有効化、無効化
edit_loads	静的荷重ケース、組み合わせ、物理荷重
analyze_model	ソルバー設定、動解析、構造解析
edit_prestress	テンドンのプロパティ、形状、プレストレス
edit_traffic	移動荷重、横方向荷重、国際活荷重
manage_checks	モデルチェックのスナップショット、現在のコード検査コンテキスト
query_results	構造、モード、活荷重、テンドンの結果
view_model	表示設定、ステージビュー、スクリーンショット、プロット
access_backend	ネイティブメソッドの検出、長尾 API 呼び出し

たとえば、{"request":{"operation":"get_model_status"}} を inspect_bridge に送信します。リクエスト例と互換性を参照してください。 元の 153 個の名前を一覧表示するには、QIAO_MCP_CATALOG_LAYOUT=flat を設定します。 バージョン 0.5.1 では、デフォルトでフラットカタログを使用していました。

画像以外の 151 個の操作では、出力スキーマと MCP の構造化コンテンツ （{status, message, ...}）が維持されています。接続診断では connection_status と connected も公開されます。橋梁テンプレートでは、解決済みの節点、要素、プロパティ ID が返されます。 get_model_status は QiaoTong の状態を status に保持します。画像に対応する 2 つのツールは、 表示可能な MCP 画像コンテンツまたはテキストの概要を返します。ドメインレベルでは、 14 のエントリーポイントが複合出力スキーマを公開し、view_model は画像とテキストの混在コンテンツに対応しています。 ツールの失敗時には型付き MCP エラーが使用され、読み取り専用、破壊的、オープンワールドの操作には MCP ツールアノテーションが付与されます。 サーバーの説明には、ツールグループの全体像が含まれています。ゲートウェイ経由で未対応のバックエンドメソッドを呼び出す前に、 list_qtmodel_api を使用してください。

入力スキーマには、パラメーターの説明、選択肢が限定されたセレクター、ページネーションの境界値、 固定サイズの座標／DOF 配列が含まれています。スキーマに無効な入力がある場合、バックエンド呼び出しの前に拒否されます。 梁端の release_i／release_j フラグは True = 解放 を意味します。 端の指定を省略すると、6 つの DOF すべてが接続された状態になります。 荷重組み合わせの成分には [case_type, case_name, factor] を使用し、 エンベロープには combine_type=3 を指定します。

支持条件の上書きでは、省略された座標／追加設定が維持されます。extra_parameters を指定すると、 extra_enabled=False で明示的に解除しない限り、それらが有効になります。この動作は、これらのオプションに対応する旧バージョンの SDK にも適用されます。

0.6.0：ドメインツールと qtmodel 2.9.3

バージョン 0.6.0 には、GitHub リリース 0.5.1 以降にローカルで行われた 0.5.2～0.5.9 の改善がまとめられています。 153 個すべての操作と従来の呼び出しを、15 個のドメインエントリーポイントから引き続き利用できます。 変更履歴に記載されている、ツールごとの修正も含まれています。 リリースおよびアップグレードに関する注意事項をご覧ください。 断面の作成／削除、ステージの削除、鉛直プレストレスの確認では、前提条件、選択範囲、書き込み動作について説明するようになりました。 add_custom_temperature では、ネイティブ形式の [reference, height, temperature] 行を受け付けます （reference は 1=上端、2=下端、方向は 1=ローカル Z、2=ローカル Y）。reference が省略される 2 値の行は 拒否されます。変更対象の選択では、空白、ブール値、小数の ID は拒否されます。番号の振り直しでは、両方のリストを完全に指定するか、 モデル全体の番号を意図的に振り直すために両方を省略する必要があります。

スクリーンショットとプロットでは、MCP ホストに保存するために PNG バイト列を取得するようになりました。部分更新には、一意かつ完全な読み戻しが必要です。確認クエリでは型付きフィールドが保持されます。 活荷重の結果には envelope_type=1（最大値）または 2（最小値）が表示されます。ソルバー、断面番号、グループクエリ、理想化のサポートに関する修正については、変更履歴をご覧ください。

ロックされたインストールでは、qtmodel 2.9.3 が使用されるようになりました。インスタンスコンテキストと model_instance_guard=1 を通知するデスクトップでは、分析ワーカースレッドを含め、変更とコミットに同じモデルインスタンス識別子が付与されます。ゲートウェイの undo_model でも、model_revision_schema=1 の場合はモデル／履歴のリビジョンが確認されます。保留中または不確かな編集があると、その取り消しはブロックされます。不一致が発生した場合は、別の操作を発行するかどうかを決める前に、アクティブなモデルとコマンド履歴を確認してください。旧バージョンのプロトコルでは、既存の状態確認が引き続き使われます。初期化／オープンと従来の raw-path ファイルルートは、既存の契約を維持しており、この新しいバインドには対応しません。この仕組みは、トランザクションのロールバックを提供するものでも、別々のクライアントリクエストを 1 つのレビュー済みプランにまとめるものでもありません。

操作の選び方

引数の全文はパラメータスキーマに公開されています。各ドメインには、受け付ける操作が記載されています。意図する効果に合った操作を選んでください。

ノードの絶対位置の編集には update_node、オフセットの適用には move_nodes、番号の変更には update_node_id／renumber_nodes を選んでください。断面については、 指定した形状を評価するには calc_section_property、保存済みのプロパティを読み取るには get_model_data、既存のすべての断面を書き換えるには calculate_section_property を使用します。 テンドンの定義、計算済みの損失、座標には、それぞれ別のクエリツールがあります。 自重の自動計算はステージで制御されます。自重という名前のケースを作成して制御するものではありません。

各タスクをどのエントリーポイントで扱うかについては、ドメインの境界をご覧ください。

0.5.0：クエリ、横断解析、確認用スナップショット、国際的な荷重

このバージョンでは B1～B4 を実装し、新しいツール 20 個とワークフロー用プロンプト 1 個が追加されました。 0.4.0 として以前にラベル付けされていた作業を含め、0.3.3 以降のすべての変更が含まれています。 リリースノート および0.3.3 からのアップグレードをご覧ください。 新しいコマンドには、対応する QiaoTong ビルドが必要です。ライブテストでは基本的な静力学と B1 の一部を確認しました。バックエンドの既知の制限をご覧ください。

get_model_edit_readiness は読み取り専用で、モデル操作がブロックされている場合も引き続き利用できます。その success ステータスは応答を受信したことを意味するもので、編集が安全であることを示すものではありません。生の readiness オブジェクトを確認してください。トークンは保持も再利用もされず、ステージや結果も変更されません。

query_model_data は型付きの request を受け取ります。たとえば、次のとおりです。

{"request": {"kind": "nodes", "structure_group_names": ["MainGirder"], "limit": 20, "offset": 0}}

種類：nodes、elements、boundaries、loads、node_local_axes、 section_summaries。名前はリストです。ID は正の整数または整数のリストで指定し、範囲文字列は使用できません。ノードには少なくとも1つのフィルターが必要です。near と tolerance は必ずセットで指定してください。Qiao-MCP ではフィルターリストとページの上限が500件です。断面サマリーでは、明示的に指定できるIDは100件、1ページあたりの項目数は100件までです。構造化された data フィールドは、合計を再計算したり、再度スライスしたりせずに、ネイティブのページメタデータを保持します。未対応のエンドポイントは、すべてをダウンロードしてローカルでフィルタリングするのではなく、明示的にエラーになります。

get_model_data はさらに、material_summaries、material_detail、 load_case_summaries、load_case_detail、load_combination_summaries、 load_combination_detail、construction_stage_summaries、element_section、spans に対応しています。新しい詳細データでは、ids に正の整数を1つ（または整数1つのリスト）指定します。element_section では position=0|1 を指定します。荷重ケース／組み合わせの詳細データのページネーションはサーバー側で行われます。それ以外のリスト種別では、従来どおりテキスト形式のページネーションが使用されます。サマリーは書き戻し用の完全なスナップショットではありません。また、施工ステージのIDはステージの順序に従います。

configure_live_load_system は、5種類のライブロードシステムから1つを明示的に選択します。既存の定義をクリアすると、デフォルトで無効になります。configure_operation_stage では4つすべてのケースリストが必須です。[] を指定すると、その種別が無効になります。これらのツールは解析を実行せずに設定を確定します。

横断方向の定義には、完全に型指定された request と action="add"|"update" を指定して、set_transversal_vehicle／set_transversal_lane を使用します。どちらも既存の定義を置き換えられます。最初に china_transversal を選択してください。表示単位にかかわらず、荷重の単位は kN、長さの単位は m です。レーンのノードは入力順を維持し、梁要素で直接接続されている必要があります。distribution_widths の単位はメートルです。参照には、返された data.index または get_transversal_data を使用してください。読み戻し時には、ネイティブのレーンフィールド load_factors が保持されます。編集時にはこれを distribution_widths に対応付けてください。

set_transversal_case は、参照先の車両IDとレーンIDを検証します。また、1～Nレーンに対する正の reduction_factors と、Nレーンを超える場合の greater_lane_factor を受け付けます。remove_transversal_data では対象を明示する必要があります。車両／レーンの削除では、デフォルトで cascade=False です。ケースの削除では cascade を指定できません。組み合わせと作業ステージの参照は、先に明示的に削除する必要があります。

ベースモデルの鉄筋には、UIからエクスポートした完全なスナップショットを指定して set_section_reinforcement を使用するか、完全な断面識別子（1、1-I、1-J、G7-2）を明示して remove_section_reinforcement を使用します。スナップショットのすべてのフィールドが必須です。空の配列を指定すると、その部分がクリアされます。外側／内側の6要素の行とモデルの長さ単位は、従来のパラメトリックツールとは異なります。現在のCSANクエリは、情報を損失なく復元できるモデルスナップショットではありません。新しいツールにはモデル書き込み権限が必要で、変更は1回で確定されます。

set_check_stirrup_snapshot はエクスポートされた定義全体を保持し、番号を振り直す場合は original_id を受け付けます。set_element_stirrups は、せん断（5要素）とねじり（3要素）の割り当て全体を、それぞれ独立して置き換えます。null はその種別を維持し、[] はクリアし、あばら筋ID 0 は未割り当てを意味します。これらは従来の現在のCSAN用あばら筋ツールとは別のものです。

manage_check_material はエクスポートされた完全な上書き設定を適用するか、明示したIDを基本材料にリセットします。manage_check_case_definition は、ネイティブの列挙値を使用して、コンクリート、耐震、補強に関するモデル定義を設定／削除します。既存の run_concrete_check は、これらの変更の確定後に、名前を指定したコンクリートケースをインポートします。耐震チェックや補強チェックは実行しません。部分的なスナップショットを作成するのではなく、エクスポートされた材料特性／パラメーター全体と保存された単位を保持してください。失敗、キャンセル、その他の正常終了ではない状態が報告された場合は、ツールエラーになります。待機処理が例外を発生させずにその状態を返す古いSDKでも同様です。 国際車両では、standard="AASHTO"|"BS"|"EN1991" で判別される request を指定して set_international_vehicle を使用します。まず、対応するモデルシステムを選択します。parameters と load_items は、値が {}／[] の場合でも明示的に指定する必要があります。追加と更新はいずれも定義全体を置き換えます。省略されたスカラー値や null のスカラー値には、新規定義のデフォルト値が使用されます。更新では元の名前で検索し、実際の ID と参照を維持します。書き込みは一度だけコミットされ、完全一致する名前で読み戻した定義を返します。

規格	固有の単位と規約
AASHTO	車軸 [N, m]、w N/m、長さ m、r パーセント（90 = 90%）
BS	pa／pb kN、w3 kN/m、長さ m、w1／w2 は式の係数、指数は無次元
EN1991	車軸 [kN, m]、等分布荷重 kN/m、集中荷重 kN、長さ m。載荷長と間隔は別個の値です

SDK では BS の車軸力の単位が指定されていません。検証済みのネイティブな BS の車軸エクスポート／クエリ値を変更せずに使用し、別の規格から単位を推測しないでください。 get_international_live_load_data(kind="vehicles"|"cases") は、完全なネイティブフィールドを保持します。選択とページネーションは、ネイティブの全リスト応答を対象にローカルで実行されます。車両エクスポートには、他の規格向けの非アクティブなパラメーターが含まれる場合があります。型付きツールには説明されているフィールドを選択するか、既存のゲートウェイを使って、変更していない完全なネイティブ定義を再適用してください。全体的な単位変換は行われません。

create_en1991_vehicle は、明示的な名前とともに、ネイティブの source="standard"|"user" ファクトリーを選択します。標準車両で指定できるのは、有効なファクトリー制御値のみです。コードで生成される等分布荷重／長さ／間隔は上書きできません。ユーザー車両では、これらのフィールドに加えて、p／dis、load_length、num、point_load を指定できます。p／dis が両方とも null の場合、LM71 は 250 kN の車軸を 4 つ使用します。ファクトリーへの書き込みでも、実際の車両 ID が読み戻されます。たとえば、en1991 を選択した後は次のようになります。

{"request": {"source": "standard", "name": "LM71", "load_type": "LM71"}}

set_planned_lane では、平面、基準タンデム、幅、車両数、符号付きオフセット、方向を指定する必要があります。これは add_traffic_lane(optimize=True) とは異なる専用エンドポイントを使用します。計画車線専用のゲッターはありません。応答でコミットを確認でき、モデルのエクスポート／UI の確認で定義を検証できます。ゲートウェイから削除する場合は、remove_lane_line に lane_kind="planned" を渡す必要があります。

set_international_live_load_case は、書き込み前に各車両の名前と期待される standard が完全一致するかを検証します。サブケースでは、optimized=False|True によって通常車線／計画車線を選択します。EN1991 では、重複する車線割り当ては拒否されます。QiaoTong は、車線の存在、車線の種類、影響平面への所属を確認します。係数オブジェクトでは、ネイティブの完全なフィールド名と値を使用します。null は、更新時も含めてサーバーのデフォルト値を意味します。configure_operation_stage で live_load_cases を明示的に設定してから、run_analysis と、QiaoTong で検証済みの結果識別子を使用する get_analysis_results(case_name_mode="full") を実行してください。定義によって解析が開始されることはありません。車両／ケースの削除には、既存のゲートウェイにある remove_international_vehicle と remove_live_load_case を引き続き使用できます。

0.5.0 では、質量／剛性係数、フランジ／有効幅の定義、統計、構造物の統合について、既存のゲートウェイを通じて上流の 0687ffe も追跡します。モデルの重量クエリでは、表示単位に関係なく固定の N を使用します。

📦 リソース（7 件）

URI	説明
bridge://model/summary	モデルの概要
bridge://model/materials	材料リスト
bridge://model/sections	断面リスト
bridge://model/load-cases	荷重ケース
bridge://model/stages	施工段階
bridge://model/structure-groups	構造グループ
bridge://model/boundaries	境界条件

💬 プロンプト（5 つのワークフロー）

プロンプト	説明
design_simple_beam	単純梁橋の設計ワークフロー
design_continuous_beam	連続梁橋の設計
check_structure	構造物の基準照査
construction_stage_analysis	施工段階の解析
analyze_transversal	横方向の定義、設定、解析、および検証済み結果識別子の明示

通常の静的ケースでは、get_analysis_results は自動的に ST: プレフィックスを付加します。 それ以外の結果ファミリーには、QiaoTong の結果/UI で確認した完全な識別子を指定して case_name_mode="full" を使用してください。指定した識別子は変更されずに渡されます。TV/MV の組み合わせコードは、結果エンドポイントの命名規則を示すものではありません。

アーキテクチャ

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/            # Local reference material (not committed)

プロバイダーパターンにより、153 の操作を特定のバックエンドに依存しない形にしています。 BRIDGE_PROVIDER でプロバイダーを選択します。各プロバイダーがソフトウェア固有のルールを定義するため、LLM は プロンプトを変更することなく適応できます。現在、以下をサポートしています。

• QTModel（qtmodel、デフォルト）— ブリッジ解析ソフトウェアのQiaoTong（桥通）（ユーザーマニュアル）

バックエンドを追加するには、BridgeProvider を実装して 1 行登録するだけで済みます。ツール層の 変更は不要です。バックエンドの選択を参照してください。

クイックスタート

前提条件

• Python >= 3.11
• uv パッケージマネージャー
• qtmodel 2.6.3～2.9.x（2.9.0 を除く。uv sync でインストールされます。現在のロックバージョンは 2.9.3 です）
• バックエンドのモデル、解析、または可視化操作を呼び出す際は、QiaoTong ソフトウェアが起動していること （各バージョンの対応関係については互換性を参照してください）

MCP サーバーは QiaoTong が起動していなくても開始できます。check_qiaotong_connection を使用して サーバーに接続できているか、ソフトウェアが起動していないかを確認し、 get_model_status を使用してモデルが開いているか、現在の QiaoTong の状態でどの操作が 可能かを確認してください。

インストールと実行

# 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 & Tools を開き、新しい 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 Servers を開き、新しいサーバーを追加します。

• 名前（Name）：qiao-mcp
• 説明（Description）：任意の説明
• タイプ（Type）：標準入力 / 出力 (stdio)
• コマンド（Command）：uv
• パッケージマネージャー（Package Manager）：デフォルト（Default）を選択します
• 引数（Args）：

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

  （各行が 1 つの引数です。--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 プロセスが実行されている場合、この固定プロキシでは 1 つのプロセスを 55125 で実行し続けるか、 プロセスごとに別のプロキシインスタンスとポートを使用してください。

SSH トンネルを使えば、API ポートを LAN に公開せずに接続できます。

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

トンネルの実行中は、クライアントマシンで http://localhost:45125/pythonForQt/ を使用してください。 この設定では、Windows HTTP.sys が Host ヘッダーを検証し、127.0.0.1 を 400 Invalid Hostname で拒否します。

開発

# Install in dev mode (includes ruff, mypy, pytest)
uv sync

# Run directly
uv run python -m qiao_mcp.server

# Quality checks and offline regression tests
uv run ruff check src/ tests/
uv run mypy src/qiao_mcp/
uv run pytest tests/ --ignore=tests/test_end_to_end.py -q

上記のコマンドはオフラインで実行され、QiaoTong ソフトウェアは不要です。 プロバイダー／ツールの呼び出しは、インストール済みの qtmodel API シグネチャに対して検証され （コントラクトテスト）、プロセス内のフェイクバックエンドにディスパッチされます。 除外されているエンドツーエンドテストには、使い捨ての QiaoTong モデルが必要です。ソルブの前に、 アクティブなモデルをクリアして再構築します。

バックエンド：QTModel（桥通）

この MCP サーバーは、以下へのアクセスを提供する qtmodel Python API をラップします。

• mdb — モデルデータベース：橋梁モデルの照会、構築、変更
• odb — 出力データベース：解析結果の照会と可視化
• cdb — 照査データベース：構造検証とコードチェック

バージョン管理

Qiao-MCP は qtmodel とは独立してバージョン管理されています。バックエンドのリリースを待たずに、プロジェクト独自で 更新（バグ修正、新しいツール、ドキュメント）を進められます。また、バックエンドのリリースによって、こちらの バージョンを上げる必要もありません。バックエンドの要件は、依存関係の制約という適切な場所で指定します。

互換性

Qiao-MCP	qtmodel	QiaoTong ソフトウェア
0.6.0	2.6.3 – 2.9.x、2.9.0 を除く	同じバックエンド要件。153 件すべてのレガシー操作を備えた 15 個のドメインツール
0.5.1	2.6.3 – 2.9.x、2.9.0 を除く	2.9.x では、QiaoTong がモデル状態を報告する必要があります。新しいコマンドにはサーバー側のサポートが必要です
0.5.0	2.6.3 – 2.9.x、2.9.0 を除く	2.9.x では、QiaoTong がモデル状態を報告する必要があります。新しいコマンドにはサーバー側のサポートが必要です
0.3.2 – 0.3.3	2.6.3 – 2.8.x	2.6.3 以降。2.8.x の組み合わせは固定されなくなりました
0.3.0 – 0.3.1	2.6.3 – 2.6.x	2.6.3（qtmodel により完全一致が必須）
0.2.x	2.5.0 – 2.5.x	2.5.0

既知の下限バージョンの制約：qtmodel 2.6.3 には get_load_group_names がないため、 ワンショットの橋梁ワークフローツールはこのバージョンでは実行できません。これは既存の 制約です。これらのワークフローには 2.6.4 以降を使用してください（2.9.0 は引き続き対象外です）。 依存関係のバージョン範囲は、すべてのビルドですべての新しいツールが利用できることを保証するものではありません。メソッドの欠落や 互換性のないパラメーターがある場合、書き込みを行う前に明示的に失敗します。オフライン テストスイートは、PyPI 版の 2.6.3、2.6.4、2.8.2、2.9.1、2.9.2、2.9.3 に加え、参照用の 0687ffe に対して実行されます。 これらのテストではソフトウェアのコントラクトを検証します。エンジニアリング面での完全な受け入れは、引き続き保留中です。 qtmodel 2.9.3 は、履歴チェック・スナップショットおよび計画済みレーンの追加／更新ルートを API_NOT_OPEN で明示的に拒否します。 SDK カタログにメソッドが掲載されていても、デスクトップ側にそのルートが存在するとは限りません。

両者の照合方法は、qtmodel 2.8.2 で変更されました。

• qtmodel 2.6 / 2.7 では、厳密なバージョンハンドシェイクが行われます。QiaoTong API バージョンとインストール済みの qtmodel が完全に一致しない場合、 check_qiaotong_connection は version_mismatch を報告して接続を拒否します。
• qtmodel 2.8.2 では、このハンドシェイクが削除されました。Python API を公開する QiaoTong であれば接続できるため、version_mismatch は発生しなくなりました。代わりに、 古い QiaoTong には新しいコマンドがない場合があります。get_model_status は、モデル状態のハンドシェイクより ソフトウェアが古いことを示す state_unknown として、その状況を表します。そのためツールは、 状態を確認せずに書き込むことなく、安全側に停止します。

ビルドによって、qtmodel 2.8.2 の報告内容は異なります。PyPI のホイール（2026-08-20）には QtServer.get_model_state が含まれていませんが、同じバージョンの上流ソースには含まれています。 Qiao-MCP はバージョンではなく機能の有無を検出します。この機能がなければ、モデル状態のガードはスキップされ （guard_unavailable）、ツールは 0.3.1 と同様に動作します。機能があれば、すべてのツールは QiaoTong が報告する状態によって制御されます。qtmodel 2.9.0 は、この機能を含む最初の PyPI リリースであるため、2.9.x ではガードが常に有効です。

ライブテストで確認されたバックエンドの制限

2026-10-12 のライブテストでは、qtmodel 2.9.2 を使用して QiaoTong 26.1.116.1010 をテストしました。 独立した片持ちモデルでは、反力、曲げモーメント、変位のチェックに合格しました。 先端変位は、せん断を含む手計算の結果と約 0.00125% 異なりました。 同じテストで、以下のバックエンドの制限も確認されました。

• GET-DEFORMATION は誤った rz を返します。テストしたケースでは ry と同じ値です。 ソルバーデータベースには正しい Rz が含まれています。このビルドの API が返す Rz に依存しないでください。Qiao-MCP が代わりの値を生成することはありません。
• configure_live_load_system は 未知参数：clear_existing により拒否されます。 横方向ワークフローはシステム選択の段階で停止します。国際ワークフローも同じ前提条件を共有するため実行していません。このテストでは、個々の国際インターフェースがサポートされていないとは確認できていません。
• SET-SECTION-REINFORCEMENT、SET-CHECK-STIRRUP、SET-CHECK-CASE は不明なコマンドとして拒否されます。鉄筋およびチェック状態のスナップショットを完全に受け入れるかどうかは、引き続き未確認です。

connected や compatible は、これらの機能を保証するものではありません。対応する QiaoTong ビルドを使用し、使い捨てモデルでこれらの機能を確認してください。 BS の車軸力の単位も、上流ではまだ確認されていません。

0.3.3 からのアップグレード

0.5.0 では、add_nodal_mass に互換性のない修正が含まれています。

• X、Y、Z 方向に等しい並進質量を指定するには、mass を使用します。たとえば {"node_id": 1, "mass": 10} のように指定します。省略可能な mass_x／mass_y／mass_z で各方向を個別に上書きできます。省略した方向には mass が使用され、そのデフォルト値はゼロです。
• mass_rm は削除されました。意図する回転慣性の軸は rot_x、rot_y、rot_z のいずれかで指定してください。古いパラメーター名を機械的に変更しないでください。
• 方向ごとに異なる質量を指定するには、mass_xyz に対応した SDK が必要です（サポート対象の PyPI 2.9 ビルドは 2.9.1 と 2.9.2 です）。古いビルドでは、書き込み前に拒否されます。

以前のバージョンでは、一部の並進質量引数が回転フィールドに書き込まれていました。パッケージをアップグレードしても、既存モデルは修正されません。以前に書き込んだ節点質量を読み戻し、意図した工学的な値と照合してください。また、より厳格なクリープ／材料の検証、小数のステージ期間、および上記のモデル状態要件について、変更履歴 も確認してください。

Upstream qtmodel 2.9 との整合

現在の参照先は 0687ffe で、2.9.2 とラベル付けされていますが、PyPI の 2.9.2 ホイールとは異なります。それ以前のローカルベースラインは 8ae651e で、バージョンラベルが古い点を除けば、そのパッケージは同じホイールと一致していました。

• 書き込みの安全性。 書き込みへの応答が失われると、CommandOutcomeUnknownError が発生し、再送されなくなりました。Qiao-MCP は結果不明として報告し、それ以上の操作を行う前にクライアントへモデルを読み戻すよう指示します。
• クライアント側の検証。 多くの書き込みで、不正な値が送信前に拒否されるようになりました。Qiao-MCP のスキーマもこれに対応しています。空でないクリープ／収縮曲線、26 または 29 個の値を持つ断面特性テーブル、コードごとのクリープパラメーター数、カスタム材料の data_info が対象です。
• 節点質量のレイアウト。 add_nodal_mass では mass_info が (mass, inertia X, Y, Z) として記載され、方向別の質量に対応する mass_xyz が追加されました。Qiao-MCP はこのレイアウトで送信するようになりました（修正されたフィールドについては変更履歴を参照してください）。
• 既存ツールに新しいパラメーターを追加。 施工ステージで小数の期間と sub_steps がサポートされるようになりました。create_material には is_orthotropic／ey、set_support と add_elastic_support には coordinate、extra_enabled、8 個の値を持つ extra_parameters が追加されています。一方向の弾性支承では、符号付きの axis_direction も受け付けます。add_influence_plane には always_divided_by_beam_shape が、create_live_load_case にはサブケースごとのブール値リスト sub_case_optimized が追加されています。オプションを省略すると従来の動作が維持され、明示したオプションは書き込み前にインストール済みのシグネチャと照合されます。小数のステージ作成は、値が切り捨てられるビルドでは拒否されます。これらの追加機能は 0.5.0 に含まれており、そのカタログには 153 個のツールがあります。
• 操作設定と連鎖削除。 configure_operation_stage では、横断ケースを含む 4 つすべてのケースリストを指定できます。ゲートウェイメソッドの update_operation_stage_setting も引き続き利用できます。省略または空のリストは解析を無効にするため、意図するケースリストをすべて指定してください。 remove_material の既定値は cascade=True です（関連するテンドン特性とテンドンも削除されます）。remove_tendon_property の既定値は False です。True を指定すると、確認ダイアログなしで参照しているテンドンとその荷重が削除されます。まず削除範囲を確認してください。名前とインデックスの両方を省略すると、すべてのオブジェクトが対象になります。
• 専用ツールとロングテール API。 0.5.0 では、横断、国際基準／計画車線、鉄筋／チェック用スナップショット、編集準備状態に対応する専用ツールが追加されました。オブジェクトの正確な削除（delete_model_object）、係数、有効幅、統計、構造物のマージは、引き続きゲートウェイから利用できます。すべての MDB 書き込みと、明示的な CDB モデルスナップショットメソッドは、update_model でコミットされます。
• ゲートウェイでブロックされている機能。 post_python_file（ローカルファイルを読み取り、実行のため任意の URL に送信）、prepare_model_edit（結果を取り消し不可能な形で削除する可能性があるため、ユーザーの承認後にホストアプリケーションで使用）、export_api_help（SDK ヘルプを任意のローカルパスに書き込み）、既存の ensure_running、set_url、set_version、export_qt_helper、wait_solve（時間制限なしでポーリングするため、run_analysis を使用してください）。

上流ソースの変更（2026-09-04–08）

これらの変更は、まだ 2.8.2 と表示されていた時点で 2316654 に初めて同期されましたが、2.9.0 の一部です。

• ac4dbad はモデルクエリの参照先を odb から mdb に変更します。Qiao-MCP は新しい名前空間を優先し、メソッドがない場合は odb にフォールバックします。既存モデルの断面形状には mdb.get_model_section_shape を使用し、mdb.get_section_shape はローカルで形状を生成するために引き続き使用します。解析結果とビューは引き続き odb を使用します。
• bc1ee99 は、to_dict() と Mapping をサポートする型付きモデルレコードを返します。プロバイダーは、元のサーバーフィールドを保持したまま、それらをツール、リソース、API ゲートウェイ向けのプレーンな JSON データに再帰的に変換します。MDB クエリ呼び出しに必要なのは読み取り権限であり、モデル書き込み権限ではありません。また、モデルが更新されることもありません。calculate_section_property のような状態を変更する呼び出しには、引き続きモデル書き込み権限が必要です。
• 6821413 はモデルオブジェクトをドメインモジュールに分割し、互換性のために core.model_db をエクスポートとして維持します。アダプターは、これらの内部パスに依存しません。
• 9月7日～8日の更新では、厚さ定義に t_out、解析の実行に show_view、12種類の解析設定リセット API、3種類の一括厚さ API が追加されました。Qiao-MCP は既存のツールで新しい2つのオプションを公開します。15種類の管理 API は、検出してから呼び出すゲートウェイ経由で利用できます。

ビルドの互換性： これらのオプションと管理 API は PyPI 2.9.x リリースに含まれています。PyPI 2.8.2 ビルド（8月20日）には含まれていません。デフォルトのツール呼び出しはどちらでも引き続き動作しますが、明示的な t_out または show_view=True のリクエストは、インストール済み API がそれらを受け付けない場合、書き込みや解析の開始前に失敗します。バージョン表示が一致しているだけでは、機能がサポートされているとは限りません。

対応する qtmodel ビルドでの MCP ツール呼び出しの例：

add_thickness(name="Deck", t=0.20, t_out=0.30, thick_type=0)
run_analysis(read_timeout=3600, show_view=True)
list_qtmodel_api(api_object="mdb", pattern="thickness")
call_qtmodel_api(api_object="mdb", method="copy_thicknesses", kwargs={"ids": [1, 2]})
list_qtmodel_api(api_object="mdb", pattern="reset_")

thick_type の意味は 0 = 通常のプレート、1 = リブ付きプレート であり、面内と面外の厚さが等しいか異なるかを示すものではありません。t_out を省略すると、両方に t が使用されます。 show_view が制御するのは QiaoTong の進捗ウィンドウのみです。解析では引き続きバックグラウンド実行、ポーリング、MCP 進捗ハートビートが使用されます。

一括厚さ API には、範囲文字列ではなく、正の整数 ID または ID のリストを指定します。 remove_thicknesses([]) は何も削除しません。解析設定のリセットでは設定が削除され、arrange_thickness_ids では ID と参照が変更されます。これらの書き込み API を呼び出す前に、意図したメソッドを検出し、変更内容が意図どおりであることを確認してください。

インストール済みパッケージを置き換えずに参照ソースをテストするには（macOS/Linux）：

PYTHONPATH=reference_codes/qtmodel-release/packages/qtmodel/src:src uv run pytest tests/ --ignore=tests/test_end_to_end.py -q

0.x は API が引き続き変更される可能性があることを示します。リリース品質について述べたものではありません。新しい qtmodel のマイナー系列に移行する際は、依存関係の下限を引き上げ、上の表に行を追加してください。

ライセンス

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

Apache License, Version 2.0 の下でライセンスされています。LICENSE を参照してください。 追加の帰属表示は NOTICE で確認できます。