Integrations
Implements MCP protocol using Python to provide civil engineering tools that can be integrated with AI applications.
MCP Civil Tools 伺服器
本專案是一個基於 MCP 協議的 Python 伺服器,主要是將水土保持技術規範(2023.05.04)透過 MCP Server 的方式提供給支援 MCP 的 client 調用,實現以自然語言與大模型對話的方式來進行查詢及計算,提供如曼寧係數查詢、土壓力係數、排水溝流速、邊坡穩定、土壤侵蝕、逕流量、擋土牆檢核、植生建議、材料參數、坡面保護、滲水設施、IDF曲線等查詢及計算功能。另外還提供台灣地區經緯度與 UTM/TWD97 座標的轉換。適用於 LLM 工具、Claude Desktop 等 AI 應用整合。
注意! 程式尚未完整,且每個大模型智力不等,輸出結果使用者務必再次核實,若有錯誤,歡迎反饋~
目錄結構
安裝
- 建議先建立虛擬環境:Copy
- 安裝依賴:Copy
啟動方式
1. CLI (stdio) 模式
2. HTTP 服務模式(建議用於 API 測試或 HTTP 整合)
mcp.json 設定範例
若要讓 Claude Desktop 或其他 MCP 客戶端自動偵測並啟動本伺服器,MCP setting JSON 內容如下(請依實際路徑調整):
command
請填入你虛擬環境的 python.exe 絕對路徑。args
請填入 mcp_server.py 的絕對路徑。
以 Windowss 系統,Command args,輸入格式如下: C:\TOMO\MCP-civil-tools.venv\Scripts\python.exe C:\TOMO\MCP-civil-tools\src\mcp_server.py
以 MAC 系統,Command args,輸入格式如下: /Users/tuchengshin/Documents/MCP/MCP-civil-tools/.venv/bin/python3 /Users/tuchengshin/Documents/MCP/MCP-civil-tools/src/mcp_server.py
參數預設行為說明
- 使用者只輸入緯度、經度時,沒有輸入其他資訊時,預設的 UTM/TM2 Zone 就是 TM2-121,預設的半球就是北半球。
- 當使用者只輸入平面座標 X, Y 時,預設的 UTM Zone 是 TWD97,半球是北半球。
主要功能更新
- 所有查表型工具皆支援「支援清單查詢」API:
- 例如:
list_supported_materials
(常用材料)、list_supported_manning_materials
(曼寧係數材料)、list_supported_max_velocity_materials
(最大流速材料)、list_supported_regions
(地區/IDF/年雨量)、list_supported_soil_types
(土壤類型)、list_supported_land_uses
(土地利用)、list_supported_practices
(水保措施)、list_supported_runoff_land_uses
(逕流係數土地利用)、list_supported_slope_protection_methods
(坡面保護工法)、list_supported_soil_k_types
(滲透係數土壤)、list_supported_idf_locations
(IDF曲線地點)等。 - 查詢時若輸入錯誤或查無資料,會自動提示所有可查詢的支援項目,提升使用體驗。
- 例如:
- 2023/04/23 更新:
- 修正
list_supported_materials
功能,現在可正確返回所有支援的常用材料設計參數材料名稱清單,包括:一般黏土、砂土、礫石、混凝土、花崗岩、石灰岩、頁岩、砂岩等。 - 新增四個 USLE 因子查詢工具:
query_r_factor_tool
:查詢降雨沖蝕指數 R 值(依據水土保持技術規範第35條)query_k_factor_tool
:查詢土壤沖蝕指數 K 值(依據水土保持技術規範第35條)query_c_factor_tool
:查詢覆蓋與管理因子 C 值(依據水土保持技術規範第35條)query_p_factor_tool
:查詢水土保持處理因子 P 值(依據水土保持技術規範第35條)
- 修正
calc_catchment_runoff
功能,增強參數處理能力,現在可以正確處理自然語言輸入,例如「計算一個面積2公頃、降雨強度100mm/hr、逕流係數0.6的集水區最大逕流量」。 - 擴充
check_retaining_wall
功能,新增地震情況下的安全係數檢核:- 依據水土保持技術規範第120條,增加地震時滑動安全係數(≧1.2)和傾倒安全係數(≧1.5)的檢核
- 增加合力作用點位置檢核,支援岩盤基礎和土層基礎兩種情況
- 修正承載力安全係數要求為3.0,符合規範要求
- 輸出報表中明確區分常時情況和地震情況的安全係數
- 修正
個別工具使用範例
經緯度轉 UTM
- 輸入:自然語言描述經緯度,如「將緯度24.125、經度120.641轉換為UTM座標」
- 回傳:
"X,Y"
字串,數值四捨五入到小數點下4位
範例
UTM 轉經緯度
- 輸入:X, Y 座標(可選 zone, datum, south,預設 TWD97 北半球)
- 回傳:
"緯度,經度"
字串,數值四捨五入到小數點下15位
範例
曼寧係數查詢
- 輸入:材料名稱(如「混凝土」、「純細砂」、「全面密草生」等)
- 回傳:該材料的曼寧係數 n 及最大容許流速範圍
範例
主動土壓力係數計算
- 輸入:內摩擦角等資訊
- 回傳:主動土壓力係數 Ka、計算公式、依據等
範例
被動土壓力係數計算
- 輸入:內摩擦角等資訊
- 回傳:被動土壓力係數 Kp、計算公式、依據等
範例
排水斷面流速/流深/流量計算(多斷面支援)
- 輸入:斷面型式、流量、坡度、曼寧係數、渠道材質、尺寸等資訊
- 回傳:流速、流深、斷面積、水力半徑等計算結果,以及完整報告書
計算邏輯與警告說明(2024/06修正版)
- 若輸入流量超過該斷面滿流時的最大流量,系統會直接回傳錯誤訊息,提示「所需流量已超過滿流最大流量,請加大尺寸或坡度」。
- 只要流量未超過滿流,計算會自動求得一個合理的流深(小於溝高),不會誤報滿流。
- 滿流警告僅在流深極接近高度且流量極接近滿流時才會出現。
- 計算精度與收斂條件已優化,避免工程常用情境下出現誤判。
最大/最小容許流速規則
- 最大容許流速:
- 僅檢核最大值(如混凝土6.1m/s、鋼筋混凝土12.0m/s、粗砂及細砂0.61m/s等),超過時系統將警告並建議設置消能設施。
- 表格中無"鋼筋混凝土"之最大容許流速,系統已新增最大值12.0m/s。
- 最小容許流速:
- 僅混凝土與鋼筋混凝土排水設施明確規定最小容許流速為0.8 m/s,低於時系統將警告可能導致泥砂淤積。
- 其餘材質未見明確規定,系統不檢核最小值。
- 檢核建議:設計排水之流速超過其最大容許流速者,應於適當位置設置消能設施。
出水高(流深)規範檢核(第86條)
- 矩形、梯形排水溝之出水高(流深)應符合:
- 不得小於設計水深的25%
- 最小值為20公分
- L型、拋物線型排水溝不在此限
- 若計算流深低於上述標準,系統將於回傳結果與報告書中給予明確警告,請調整設計參數。
範例
邊坡穩定安全係數計算
- 輸入:坡度、單位重、摩擦角、凝聚力、地下水位、方法等資訊
- 回傳:安全係數、方法、是否合格、說明
範例
土壤侵蝕模數/流失量計算
- 輸入:坡長、坡度、降雨、土壤類型、土地利用、水保措施等資訊
- 回傳:侵蝕模數、流失量、方法、說明
範例
集水區最大逕流量計算
- 輸入:集水區面積、降雨強度、逕流係數等資訊
- 回傳:最大逕流量、方法、說明
範例
護岸/擋土牆穩定檢核
- 輸入:牆高、厚度(矩形斷面)或頂寬/底寬(梯形斷面)、單位重、摩擦角、凝聚力、背填坡度、地下水位、地震係數、基礎類型等資訊
- 回傳:常時與地震情況下的滑動、傾倒安全係數、合力作用點位置、是否合格、說明
範例(矩形斷面)
範例(梯形斷面)
植生護坡設計建議
- 輸入:坡度、土壤類型、氣候等資訊
- 回傳:建議工法、草種、覆蓋率、說明
範例
常用材料設計參數查詢
- 輸入:材料名稱
- 回傳:單位重、凝聚力、摩擦角、強度、說明
範例
坡面保護工法建議
- 輸入:坡度、土壤類型、降雨量等資訊
- 回傳:建議工法、說明
範例
滲水設施設計
- 輸入:設施型式、土壤滲透係數、集水面積、降雨量等資訊
- 回傳:設計流量、建議尺寸、說明
範例
IDF曲線查詢
- 輸入:地點、重現期、歷時等資訊
- 回傳:降雨強度、說明
範例
查詢支援清單
- 你可以直接查詢有哪些可用的材料、地區、工法等:
查詢失敗時自動提示
- 若查詢時輸入錯誤,會自動回傳所有支援查詢的項目:
土石籠擋土牆穩定分析
此功能用於分析土石籠擋土牆的穩定性,包括主動和被動土壓力計算。
使用方法
回傳結果
函數回傳一個字典,包含以下內容:
success
: 布林值,表示計算是否成功data
: 計算結果數據,包含:earth_pressure_coef
: 土壓力係數total_pressure
: 總土壓力 (kN/m)vertical_force
: 垂直力分量 (kN/m)horizontal_force
: 水平力分量 (kN/m)restoring_moment
: 抗傾覆力矩 (kN·m/m)overturning_moment
: 傾覆力矩 (kN·m/m)overturning_safety_factor
: 抗傾覆安全係數sliding_safety_factor
: 抗滑動安全係數
message
: 計算結果摘要report
: 完整的計算報告書(Markdown 格式)
計算報告書內容
報告書包含以下章節:
- 輸入參數
- 計算公式
- 計算結果
- 穩定評估
U型溝鋼筋量計算
- 輸入:
- height: 溝高 (m)
- wall_slope: 溝壁傾角 (m)
- soil_slope: 土方傾角 (°)
- soil_angle: 安息角 (°)
- effective_depth: 有效厚度 (m)
- soil_weight: 土重 (kN/m³),預設 18.0
- 回傳:dict,含計算結果與報告書
範例
鋼筋查詢功能
本工具提供以下鋼筋資料查詢功能:
- 列出所有可用的鋼筋編號Copy
- 查詢特定鋼筋編號的規格資料Copy
- 計算鋼筋重量Copy
可用的鋼筋編號包括:#3、#4、#5、#6、#7、#8、#9、#10、#11,每個編號對應的規格資料包括:
- 直徑(mm)
- 截面積(cm²)
- 單位重量(kg/m)
- 周長(mm)
鋼筋規格查詢
輸入「鋼筋規格 #3」或「鋼筋資料 #3」可查詢特定鋼筋的詳細資料,包括:
- 鋼筋編號
- 直徑 (mm)
- 截面積 (cm²)
- 單位重量 (kg/m)
- 周長 (mm)
鋼筋重量計算
輸入「鋼筋重量 長度 6 #3」可計算指定長度的鋼筋重量,例如:
- 長度:6m
- 鋼筋:#3
- 重量:2.04 kg
鋼筋截面積查詢
輸入「鋼筋截面積 #3」可查詢特定鋼筋的截面積,例如:
- #3 鋼筋截面積:0.71 cm²
所有鋼筋列表
輸入「所有鋼筋」可列出所有可用的鋼筋編號,包括:
- #3 至 #11 鋼筋
- 各鋼筋的基本規格
U 型溝配筋建議
輸入「U型溝配筋 面積 10cm2」可查詢建議的配筋方式,系統會:
- 根據輸入的鋼筋斷面積 (cm²/m)
- 自動計算並建議主筋與副筋的配筋方式
- 間距會取整到最接近的 5cm
- 提供完整的配筋建議報告
逕流係數查詢
逕流係數查詢工具可依據水土保持技術規範第18條,查詢不同土地利用類型或集水區狀況的逕流係數C值。
範例
查詢結果包含:
- 逕流係數值
- 來源說明
- 規範依據
- 土地利用類型
- 開發狀態
- 數值範圍(如適用)
USLE 因子查詢工具
USLE 因子查詢工具可依據水土保持技術規範第35條,查詢土壤流失量計算所需的各項因子值。
降雨沖蝕指數 R 值查詢
土壤沖蝕指數 K 值查詢
覆蓋與管理因子 C 值查詢
水土保持處理因子 P 值查詢
查詢結果包含:
- 因子值
- 單位
- 來源說明
- 規範依據
使用範例(功能導向,使用自然語言對話,讓大模型自動調用相關工具來求解)
- 有一集水區面積約5ha,平坦耕地,新北市,重現期50年,降雨延時60min,調用工具取得該地區的降雨強度值,計算該集水區最大逕流量?
- 有一集水區面積約5ha,平坦耕地,新北市,降雨延時60min,調用工具取得該地區的降雨強度值,請分別計算重現期25年、50年該集水區最大逕流量? 並輸出完整計算式的報告書。
- 依據25年的逕流量,設計一條寬50cm,深70cm的混凝土溝,設計坡度容許範圍?
- 依據這個逕流量,設計一條寬50cm,溝深60cm的混凝土溝,坡度2.5%,檢核該設計是否OK,並出具一份完整的檢核報告書。
- 水溝編號,B(cm),H(cm),坡度(%),流量(CMS),水溝鋪面型式 1-1,40,60,1.5,0.25,鋼筋混凝土矩形溝 1-2,40,70,1.5,0.30,鋼筋混凝土矩形溝 檢核上列水溝設計,以markdown表格型式輸出結果。
- 有一個破碎岩盤的坡面,角度約60度,位於熱帶多雨地區,請提出坡面保護建議。
- 無基礎的混凝土重力式擋土牆,全高2.3M,牆頂寬50cm,牆底寬100cm,土壤單位重18kN/m3,摩擦角30度,凝聚力10kPa,地下水位在牆頂以下2M,地震係數0.15,土層基礎,請調用MCP工具,檢核其常時與地震情況下的穩定性,並輸出完整計算報告書。
- 混凝土溝,height=1.5, wall_slope=0.5, soil_slope=15, soil_angle=30, effective_depth=0.2,調用工具,計算水溝所需的鋼筋量及建議配筋?
- 台中的 "年平均土壤流失量"如何估算? 需提供哪些參數?
- 請計算一條直徑60公分的混凝土圓形管渠,流量0.5cms,坡度1.2%,曼寧係數0.013的流速和流深
- 計算寬30公分,高50cm的鋼筋混凝土矩形溝,流量0.5cms,坡度1.2%,流速和流深?
- 計算寬50公分,高70cm的鋼筋混凝土矩形溝,流量1cms,坡度5%,流速和流深? 輸出完整報告,含計算過程及計算式。
- 計算底寬50公分,頂寬100cm,高70cm的"平常砂土梯形溝",流量0.2cms,坡度0.7%,流速和流深? 輸出完整報告,含計算過程及計算式。
- 有一集水區面積約5ha,平坦耕地,新北市,重現期50年,降雨延時60min,調用工具取得該地區的降雨強度值,計算該集水區最大逕流量?
- 依據這個逕流量,設計一條寬50cm,溝深60cm的混凝土溝,坡度2.5%,檢核該設計是否OK,並出具一份完整的檢核報告書(含集水區最大逕流量)。
- 使用 Gemini 2.5 Pro 的輸出結果如下:調用工具:query_idf_curve(降雨強度-歷時-頻率(IDF)曲線查詢)、query_runoff_coeff(逕流係數C值查詢工具)、calc_catchment_runoff(集水區最大逕流量計算)、get_manning_n(常見材料的曼寧係數查詢)、calc_channel_section_flow(排水斷面流速/流深/流量計算)
混凝土溝設計檢核報告書
1. 設計目標
本報告旨在檢核所設計之混凝土溝斷面,是否能安全容納上游集水區於特定重現期下所產生之最大逕流量。
2. 集水區最大逕流量計算摘要
- 集水區條件:
- 面積 (A): 5.0 公頃 (ha)
- 土地利用: 平坦耕地
- 地點: 新北市
- 設計條件:
- 重現期 (T): 50 年
- 降雨延時 (D): 60 分鐘
- 計算參數:
- 降雨強度 (I): 140.0 mm/hr (依據新北市50年60分鐘IDF曲線)
- 逕流係數 (C): 0.53 (平坦耕地,取規範平均值)
- 計算公式 (合理化公式): Q = (C × I × A) / 360
- 計算結果 (設計流量 Q_design):
- Q_design = (0.53 × 140.0 × 5.0) / 360 ≈ 1.03 cms
3. 混凝土溝設計參數
- 斷面型式: 矩形
- 渠道材質: 混凝土
- 曼寧糙度係數 (n): 0.012
- 溝渠寬度 (b): 50 cm (0.5 m)
- 溝渠深度 (H): 60 cm (0.6 m)
- 渠道坡度 (S): 2.5 % (0.025 m/m)
4. 水理計算與檢核
使用曼寧公式,針對設計流量 (Q = 1.03 cms) 及上述溝渠參數進行水理計算:
- 計算公式:
- Q = A × V
- V = (1/n) × R^(2/3) × S^(1/2)
- A = b × y
- P = b + 2y
- R = A / P
- 計算結果:
- 實際流速 (V): 4.014 m/s
- 實際水深 (y): 0.513 m (51.3 cm)
- 檢核項目:
- 通水能力 (Capacity Check):
- 計算水深 (y) = 51.3 cm
- 設計溝深 (H) = 60.0 cm
- 出水高 (Freeboard) = H - y = 60.0 - 51.3 = 8.7 cm
- 評估: 溝渠斷面可容納設計流量,尚有 8.7 cm 的出水高。一般工程設計建議保留約10-20%溝深或至少10-15cm的出水高作為安全餘裕,此處出水高略顯不足,建議可考慮加大溝深以增加安全係數。
- 流速檢核 (Velocity Check):
- 計算流速 (V) = 4.014 m/s
- 混凝土容許流速範圍 (V_allowable): 4.57 ~ 6.1 m/s (依據水保技術規範常見值)
- 評估: 計算流速 4.014 m/s 低於混凝土的容許流速下限 (4.57 m/s),表示此流速對混凝土渠道本身是安全的,不會造成渠道沖刷。
- 通水能力 (Capacity Check):
5. 結論與建議
- 通水能力: 設計之混凝土溝斷面 (寬50cm, 深60cm) 可以容納 1.03 cms 的設計流量。
- 流速: 計算流速 4.014 m/s 在混凝土的安全容許範圍內。
- 出水高: 計算所得的出水高為 8.7 cm,相對偏低。
- 建議: 雖然此斷面在計算上可通過設計流量,但考量到實際施工誤差、泥砂淤積、或未來流量增加的可能性,建議將溝渠深度適度加大 (例如增加至 70 cm 或以上),以提供更充足的出水高,增加整體設計的安全性與韌性。
授權
本專案採用 MIT License 授權,歡迎自由使用與貢獻。
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
A Python-based MCP server that provides coordinate conversion between latitude/longitude and UTM/TWD97, along with various civil engineering calculation tools for LLM and AI application integration.
Related MCP Servers
- -securityAlicense-qualityMCP server for toolhouse.ai. This does not rely on an external llm unlike the official server.Last updated -1PythonMIT License
- -securityFlicense-qualityAn MCP server providing timezone conversions and time-related operations via RESTful API endpoints, featuring comprehensive error handling and timezone database integration.Last updated -Python
- -securityAlicense-qualityAn MCP server implementation that integrates AI assistants with Langfuse workspaces, allowing models to query LLM metrics by time range.Last updated -9JavaScriptApache 2.0
- -security-license-qualityAn MCP server that integrates various penetration testing tools, enabling security professionals to perform reconnaissance, vulnerability scanning, and API testing through natural language commands in compatible LLM clients like Claude Desktop.Last updated -1Python