Provides civil engineering tools via Model Context Protocol for natural language queries and calculations including Manning's coefficient, soil pressure, runoff, slope stability, erosion, retaining wall checks, vegetation recommendations, material parameters, coordinate conversions, and more, based on 2023 soil and water conservation standards.
Unlock the full potential of MCP Civil Tools through LangDB's AI Gateway. Get enterprise-grade security, analytics, and seamless integration with zero configuration.
Free tier available • No credit card required
本專案是一個基於 MCP 協議的 Python 伺服器,主要是將水土保持技術規範(2023.05.04)透過 MCP Server 的方式提供給支援 MCP 的 client 調用,實現以自然語言與大模型對話的方式來進行查詢及計算,提供如曼寧係數查詢、土壓力係數、排水溝流速、邊坡穩定、土壤侵蝕、逕流量、擋土牆檢核、植生建議、材料參數、坡面保護、滲水設施、IDF曲線等查詢及計算功能。另外還提供台灣地區經緯度與 UTM/TWD97 座標的轉換。適用於 LLM 工具、Claude Desktop 等 AI 應用整合。
MCP-civil-tools/
├── src/
│ ├── mcp_server.py # MCP 伺服器主程式
│ ├── util.py # 座標轉換與土木工程工具邏輯
│ └── utm_types/
│ └── __init__.py # 型別定義
├── requirements.txt # 依賴套件
├── README.md # 專案說明
└── .gitignore # Git 忽略規則
python -m venv .venv .venv\Scripts\activate # Windows # 或 source .venv/bin/activate # Linux/macOS
pip install -r requirements.txt
python src/mcp_server.py
uvicorn src.mcp_server:app --port 8000
若要讓 Claude Desktop 或其他 MCP 客戶端自動偵測並啟動本伺服器,MCP setting JSON 內容如下(請依實際路徑調整):
{ "mcpServers": { "MCP-civil-tools": { "command": "path/.venv/Scripts/python.exe", "args": [ "path/src/mcp_server.py" ] } } } 或是 "MCP-civil-tools": { "command": "C:/TOMO/MCP-civil-tools/.venv/Scripts/python.exe", "args": [ "C:/TOMO/MCP-civil-tools/src/mcp_server.py" ], "disabled": true, "autoApprove": [] },
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
所有查表型工具皆支援「支援清單查詢」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
功能,現在可正確返回所有支援的常用材料設計參數材料名稱清單,包括:一般黏土、砂土、礫石、混凝土、花崗岩、石灰岩、頁岩、砂岩等。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
功能,新增地震情況下的安全係數檢核:
"X,Y"
字串,數值四捨五入到小數點下4位輸入:請將緯度24.125193616011536、經度120.64098341751337轉換為UTM座標
回傳:203650.6040,2670482.4250
"緯度,經度"
字串,數值四捨五入到小數點下15位輸入:請將 UTM 座標 X=203650.604、Y=2670482.425 轉換為經緯度
回傳:24.125193616011536,120.64098341751337
輸入:全面密草生的曼寧係數是多少?
回傳:全面密草生 的曼寧係數 n = 0.040,最大容許流速範圍:1.5~2.5 m/s
依據:水土保持技術規範第18條及附件曼寧係數表
輸入:請查詢混凝土的曼寧係數
回傳:混凝土 的曼寧係數 n = 0.013,最大容許流速範圍:3.0~6.0 m/s
依據:水土保持技術規範第18條及附件曼寧係數表
輸入:內摩擦角30度的主動土壓力係數Ka是多少?
回傳:主動土壓力係數 Ka = 0.3333
依據:水土保持技術規範第117條及附件土壓力計算公式
說明:主動土壓力係數用於計算擋土結構所承受的水平推力,是擋土牆設計的重要參數。
輸入:內摩擦角30度的被動土壓力係數Kp是多少?
回傳:被動土壓力係數 Kp = 3.0
依據:水土保持技術規範第117條及附件土壓力計算公式
說明:被動土壓力係數用於計算擋土結構的抵抗力,是擋土牆穩定分析的重要參數。
輸入:計算寬50公分,高70cm的鋼筋混凝土矩形溝,流量1cms,坡度5%,流速和流深? 輸出完整報告,含計算過程及計算式。
回傳:
流速: 7.20 m/s,流深: 0.250 m。警告:計算流速 v = 7.2000 m/s 已超過『鋼筋混凝土』最大容許流速 12.0 m/s,應於適當位置設置消能設施。
輸入:計算寬50公分,高70cm的混凝土矩形溝,流量0.2cms,坡度0.5%,流速和流深?
回傳:
流速: 0.65 m/s,流深: 0.120 m。警告:計算流速 v = 0.6500 m/s 低於『混凝土』最小容許流速 0.8 m/s,可能導致泥砂淤積。
【排水斷面流速/流深/流量計算報告】
斷面型式:矩形
矩形底寬 b=50.0cm, 高度 h=70.0cm
流量 Q = 1.000 cms
坡度 S = 5.000%
曼寧係數 n = 0.013
渠道材質:鋼筋混凝土
【計算公式】
Q = A × V, V = (1/n) × R^(2/3) × S^(1/2)
【計算步驟】
A = b×y, P = b+2y, R = A/P, V = (1/n)R^(2/3)S^(1/2), Q = A×V
【計算結果】
流速 V = 2.340 m/s
流深 y = 0.210 m
斷面積 A = 0.1050 m²
水力半徑 R = 0.0700 m
周長 P = 1.0000 m
計算結果符合安全流速規範。
【檢核警告】計算流深 y = 0.210 m 不符第86條規範,應≧max(0.2m, 設計水深25%)=0.250 m。請調整設計。
輸入:請計算坡度30度、土壤單位重18kN/m³、摩擦角30度、凝聚力10kPa的邊坡穩定安全係數
回傳:安全係數 = 1.50,方法:簡化法,合格:True
依據:水土保持技術規範第31條及附件安全係數表
說明:邊坡穩定安全係數應大於1.5,本案例符合規範要求。
輸入:計算坡長100公尺、坡度10%、年降雨量1200mm、砂土、草地、等高耕作的土壤流失量
回傳:土壤侵蝕模數/流失量 = 42.75 公噸/公頃/年
依據:水土保持技術規範第35條及附件USLE公式、參數表
說明:USLE公式為國際通用土壤流失量推估方法,台灣水保規範明定可用於坡地土壤侵蝕評估。
輸入:計算一個面積2公頃、降雨強度100mm/hr、逕流係數0.6的集水區最大逕流量
回傳:最大逕流量 Q = 0.33 cms,方法:Rational
依據:水土保持技術規範第16、17、18條及附件降雨強度、逕流係數表
說明:集水區面積小於1000公頃時,無實測資料可採Rational公式計算洪峰流量。
輸入:檢核一座高2公尺、厚1公尺的擋土牆,土壤單位重18kN/m³、摩擦角30度、凝聚力10kPa、背填坡度10度,地震係數0.15,土層基礎
回傳:
【常時情況】
滑動SF=1.65(≧1.5 合格),傾倒SF=2.30(≧2.0 合格),承載SF=3.10(≧3.0 合格),合力作用點位置合格
【地震情況】
滑動SF=1.25(≧1.2 合格),傾倒SF=1.60(≧1.5 合格),合力作用點位置合格
依據:水土保持技術規範第117、118、120、164條及附件最小安全係數表
說明:擋土牆設計須同時檢核常時與地震情況下的滑動、傾倒安全係數及合力作用點位置,並符合規範建議標準。
輸入:檢核一座高2公尺、頂寬0.5公尺、底寬1公尺的梯形擋土牆,土壤單位重18kN/m³、摩擦角30度、凝聚力10kPa,地震係數0.15,土層基礎
回傳:
【牆體幾何與重量】
梯形斷面:高度 = 2.00 m,頂寬 = 0.50 m,底寬 = 1.00 m,牆體單位重 = 24.00 kN/m³
牆體重量 W = 24.00 × (1.00 + 0.50) × 2.00 / 2 = 36.00 kN/m
重心位置 x_g = 0.56 m
【常時情況】
滑動SF=1.78(≧1.5 合格),傾倒SF=2.45(≧2.0 合格),承載SF=3.25(≧3.0 合格),合力作用點位置合格
【地震情況】
滑動SF=1.32(≧1.2 合格),傾倒SF=1.75(≧1.5 合格),合力作用點位置合格
依據:水土保持技術規範第117、118、120、164條及附件最小安全係數表
說明:擋土牆設計須同時檢核常時與地震情況下的滑動、傾倒安全係數及合力作用點位置,並符合規範建議標準。
輸入:請針對坡度30度、壤土、亞熱帶氣候的邊坡提供植生護坡設計建議
回傳:建議工法:噴播草皮+格框或土工網,分區分期施工
草種:百慕達草、狗牙根、地毯草等耐旱耐沖蝕草種
覆蓋率:90.0%
依據:水土保持技術規範第8、167、172條及附件坡度分級、樣區面積、覆蓋率等規定
輸入:請提供一般黏土的設計參數
回傳:材料:一般黏土,單位重:18.0kN/m³,凝聚力:20.0kPa,摩擦角:25.0°,強度:200.0kPa
依據:常用土壤工程手冊
輸入:坡度30%、砂土、年降雨量1200mm的坡面,建議採用什麼保護工法?
回傳:建議工法:噴播草皮+格框或土工網
說明:坡度較大時應加強排水設施與坡面穩定措施
依據:水土保持技術規範第8、167、172條及附件坡度分級表
輸入:請設計一個滲水井,土壤滲透係數k=0.001cm/s,集水面積100平方公尺,年降雨量1200mm
回傳:設施型式:滲水井,設計流量:0.033cms,建議尺寸:直徑1.2m,深度1.8m
依據:水土保持技術規範第94條及附件滲透設施設計準則
說明:滲水井設計需考慮土壤滲透性、集水面積及當地降雨特性,並定期維護以確保功能。
輸入:請查詢台中市10年重現期、60分鐘歷時的降雨強度
回傳:地點:台中市,重現期:10年,歷時:60分鐘,強度:78.5 mm/hr
依據:水土保持技術規範第15條及附件IDF曲線公式
說明:IDF曲線反映不同重現期與歷時下的降雨強度,用於水文分析與水利設施設計。
查詢:有哪些常用材料?
回傳:['一般黏土', '砂土', '礫石', '混凝土', ...]
查詢:可以查詢哪些水溝鋪面的曼寧係數?
回傳:['純細砂', '混凝土', '全面密草生', ...]
查詢:有哪些坡面保護工法?
回傳:['草皮或直接播種', '噴播草皮+格框/土工網', ...]
查詢:有哪些IDF地點?
回傳:['台北市', '新北市', '台中市']
輸入:查詢不存在的材料名稱
回傳:查無此材料,支援查詢的材料有:一般黏土, 砂土, 礫石, 混凝土, ...
此功能用於分析土石籠擋土牆的穩定性,包括主動和被動土壓力計算。
result = check_gabion_stability( height=3.0, # 土石籠高度 (m) width=2.0, # 土石籠寬度 (m) wall_weight=100, # 擋土牆總重 (kN/m) phi=30, # 土壤內摩擦角 (°) delta=20, # 牆背摩擦角 (°),預設 0 theta=0, # 牆背傾斜角 (°),預設 0 i=0, # 地表傾斜角 (°),預設 0 gamma=18, # 土壤飽和單位重 (kN/m³),預設 18 friction_coef=0.5, # 摩擦係數,預設 0.5 pressure_mode="active" # 土壓力模式 ("active" 或 "passive"),預設 "active" )
函數回傳一個字典,包含以下內容:
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 格式)報告書包含以下章節:
輸入:混凝土溝,height=1.5, wall_slope=0.5, soil_slope=15, soil_angle=30, effective_depth=0.2,計算水溝所需的鋼筋量,建議的配筋?
回傳:
{
"success": true,
"data": {
"earth_pressure_coef": 0.3333,
"earth_pressure": 6.750,
"moment": 3.375,
"rebar_area": 13.780
},
"message": "土壓力係數 Ka = 0.3333, 土壓力 P = 6.750 kN/m, 彎矩 M = 3.375 kN·m/m, 鋼筋量 As = 13.780 cm²/m",
"report": "【U型溝鋼筋量計算報告】
輸入參數:
- 溝高 H = 1.500 m
- 溝壁傾角 m = 0.500
- 土方傾角 i = 15.00°
- 安息角 ψ = 30.00°
- 有效厚度 d = 0.200 m
- 土重 γ = 18.0 kN/m³
計算公式:
1. 土壓力係數 Ka = cos²(ψ+m) / [cos²m·(1+√Q)²]
其中 Q = [sinψ·sin(ψ-i)] / [cos(m+i)·cosm]
2. 土壓力 P = γ·H²·Ka / (2·cosm)
3. 彎矩 M = γ·H³·Ka / (6·cosm)
4. 鋼筋量 As = M / (fs·d) × 10⁶ / 1000
計算結果:
- 土壓力係數 Ka = 0.3333
- 土壓力 P = 6.750 kN/m
- 彎矩 M = 3.375 kN·m/m
- 鋼筋量 As = 13.780 cm²/m"
}
本工具提供以下鋼筋資料查詢功能:
列出所有可用的鋼筋編號
list_rebar_numbers()
查詢特定鋼筋編號的規格資料
get_rebar_specs(rebar_number="#3")
計算鋼筋重量
calculate_rebar_weight(rebar_number="#3", length=10.0)
可用的鋼筋編號包括:#3、#4、#5、#6、#7、#8、#9、#10、#11,每個編號對應的規格資料包括:
輸入「鋼筋規格 #3」或「鋼筋資料 #3」可查詢特定鋼筋的詳細資料,包括:
輸入「鋼筋重量 長度 6 #3」可計算指定長度的鋼筋重量,例如:
輸入「鋼筋截面積 #3」可查詢特定鋼筋的截面積,例如:
輸入「所有鋼筋」可列出所有可用的鋼筋編號,包括:
輸入「U型溝配筋 面積 10cm2」可查詢建議的配筋方式,系統會:
逕流係數查詢工具可依據水土保持技術規範第18條,查詢不同土地利用類型或集水區狀況的逕流係數C值。
輸入:請查詢農業區的逕流係數
回傳:逕流係數 C = 0.53
來源:農業區逕流係數範圍:0.45~0.60,採用平均值0.53
依據:水土保持技術規範第18條及附件逕流係數表
說明:逕流係數C值反映集水區地表特性對降雨逕流之影響,開發中狀態C值以1.0計算。
輸入:開發中的平坦耕地逕流係數是多少?
回傳:逕流係數 C = 0.85
來源:開發中狀態,平坦耕地
依據:水土保持技術規範第18條及附件逕流係數表
說明:逕流係數C值反映集水區地表特性對降雨逕流之影響,開發中狀態C值較高。
查詢結果包含:
USLE 因子查詢工具可依據水土保持技術規範第35條,查詢土壤流失量計算所需的各項因子值。
輸入:請查詢台北市的降雨沖蝕指數R值
回傳:地區 台北市 的降雨沖蝕指數 R = 350,單位:百萬焦耳·公釐/公頃·小時·年
輸入:年平均降雨量2000mm的降雨沖蝕指數R值是多少?
回傳:年平均降雨量 2000 mm 推估的降雨沖蝕指數 R = 600,單位:百萬焦耳·公釐/公頃·小時·年
輸入:砂土的沖蝕指數K值是多少?
回傳:土壤類型 砂土 的沖蝕指數 K = 0.30,單位:公噸·公頃·年/公頃·百萬焦耳·公釐
輸入:請查詢黏土的K值
回傳:土壤類型 黏土 的沖蝕指數 K = 0.20,單位:公噸·公頃·年/公頃·百萬焦耳·公釐
輸入:草地的覆蓋與管理因子C值是多少?
回傳:土地利用類型 草地 的覆蓋與管理因子 C = 0.05,單位:無因次
輸入:請查詢農地的C值
回傳:土地利用類型 農地 的覆蓋與管理因子 C = 0.30,單位:無因次
輸入:等高耕作的水土保持處理因子P值是多少?
回傳:水土保持措施 等高耕作 的處理因子 P = 0.50,單位:無因次
輸入:請查詢梯田的P值
回傳:水土保持措施 梯田 的處理因子 P = 0.20,單位:無因次
查詢結果包含:
本報告旨在檢核所設計之混凝土溝斷面,是否能安全容納上游集水區於特定重現期下所產生之最大逕流量。
使用曼寧公式,針對設計流量 (Q = 1.03 cms) 及上述溝渠參數進行水理計算:
計算公式:
計算結果:
檢核項目:
本專案採用 MIT License 授權,歡迎自由使用與貢獻。
Discover shared experiences
Shared threads will appear here, showcasing real-world applications and insights from the community. Check back soon for updates!