MCP Civil Tools 伺服器

本專案是一個基於 MCP 協議的 Python 伺服器，提供經緯度與 UTM/TWD97 座標互轉，以及多種常用土木工程計算工具（目前主要針對水土保持技術規範提供如曼寧係數查詢、土壓力係數、排水溝流速、邊坡穩定、土壤侵蝕、逕流量、擋土牆檢核、植生建議、材料參數、坡面保護、滲水設施、IDF曲線等功能），適用於 LLM 工具、Claude Desktop 等 AI 應用整合。

---

目錄結構

MCP-civil-tools/
├── src/
│   ├── mcp_server.py         # MCP 伺服器主程式
│   ├── util.py              # 座標轉換與土木工程工具邏輯
│   └── utm_types/
│       └── __init__.py       # 型別定義
├── requirements.txt          # 依賴套件
├── README.md                 # 專案說明
└── .gitignore                # Git 忽略規則

---

安裝

1. 建議先建立虛擬環境：

   python -m venv .venv
   .venv\Scripts\activate  # Windows
   # 或 source .venv/bin/activate  # Linux/macOS
   

2. 安裝依賴：

   pip install -r requirements.txt
   

---

啟動方式

1. CLI (stdio) 模式

python src/mcp_server.py

2. HTTP 服務模式（建議用於 API 測試或 HTTP 整合）

uvicorn src.mcp_server:app --port 8000

---

mcp.json 設定範例

若要讓 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

---

參數預設行為說明

• 使用者只輸入緯度、經度時，沒有輸入其他資訊時，預設的 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曲線地點）等。
  • 查詢時若輸入錯誤或查無資料，會自動提示所有可查詢的支援項目，提升使用體驗。

---

個別工具使用範例

經緯度轉 UTM

• 輸入：緯度、經度（可選 datum，預設 TWD97）
• 回傳："X,Y" 字串，數值四捨五入到小數點下4位

範例

輸入：24.125193616011536, 120.64098341751337
回傳：203650.6040,2670482.4250

UTM 轉經緯度

• 輸入：X, Y（可選 zone, datum, south，預設 TWD97 北半球）
• 回傳："緯度,經度" 字串，數值四捨五入到小數點下15位

範例

輸入：203650.604, 2670482.425
回傳：24.125193616011536,120.64098341751337

曼寧係數查詢

• 輸入：材料名稱（如「混凝土」、「純細砂」、「全面密草生」等）
• 回傳：該材料的曼寧係數 n 及最大容許流速範圍

範例

輸入：全面密草生的曼寧係數?
回傳：全面密草生 的曼寧係數 n = 0.040，最大容許流速範圍：1.5~2.5 m/s
混凝土的曼寧係數?

主動土壓力係數計算

• 輸入：內摩擦角 phi（度）時，主動土壓力係數 Ka 是多少?
• 回傳：主動土壓力係數 Ka

範例

輸入：內摩擦角 phi（度）=30 時，主動土壓力係數 Ka 是多少?
回傳：主動土壓力係數 Ka = 0.3333

被動土壓力係數計算

• 輸入：內摩擦角 phi（度）=30 時，被動土壓力係數 Kp 是多少?
• 回傳：被動土壓力係數 Kp

範例

輸入：內摩擦角 phi（度）=30 時，被動土壓力係數 Kp 是多少?
回傳：被動土壓力係數 Kp = 3.0

排水溝流速計算（曼寧公式，含自動檢核）

• 輸入：n（曼寧係數）、r（水力半徑 m）、s（坡度），可選 material（材料名稱）
• 回傳：流速 v (m/s)，若超過最大容許流速會自動給出警告

範例

輸入：n=0.040, r=0.5, s=0.01, material="全面密草生"
回傳：流速 v = 1.3702 m/s

（若超過最大容許流速）
輸入：n=0.012, r=0.5, s=0.05, material="混凝土"
回傳：流速 v = 6.6000 m/s
警告：計算流速 v = 6.6000 m/s 已超過『混凝土』最大容許流速 6.1 m/s！

排水溝流量計算

• 輸入：v（流速 m/s）、a（斷面積 m2），計算排水溝流量
• 回傳：流量 Q (cms)

範例

輸入：v=2.0, a=0.8，計算排水溝流量
回傳：流量 Q = 1.6000 cms

邊坡穩定安全係數計算

• 輸入：坡度、單位重、摩擦角、凝聚力、地下水位、方法
• 回傳：安全係數、方法、是否合格、說明

範例

輸入：坡度=30, 單位重=18, 摩擦角=30, 凝聚力=10
回傳：安全係數 = 1.50，方法：簡化法，合格：True
預設安全係數1.5，僅為範例。

土壤侵蝕模數/流失量計算

• 輸入：坡長、坡度、降雨、土壤因子、植生因子、保護措施因子、方法
• 回傳：侵蝕模數、流失量、方法、說明

範例

輸入：坡長=100, 坡度=10, 降雨=1200, 土壤因子=0.3, 植生因子=0.5, 保護因子=0.8
回傳：侵蝕模數 = 100.00，流失量 = 10.00，方法：USLE
預設侵蝕模數100，流失量10，僅為範例。

集水區最大逕流量計算

• 輸入：面積、降雨強度、逕流係數、方法
• 回傳：最大逕流量、方法、說明

範例

輸入：面積=2, 強度=100, 逕流係數=0.6
回傳：最大逕流量 Q = 5.00 cms，方法：Rational
預設逕流量5cms，僅為範例。

護岸/擋土牆穩定檢核

• 輸入：牆高、厚度、單位重、摩擦角、凝聚力、背填坡度、地下水位
• 回傳：滑動、傾倒、承載安全係數、是否合格、說明

範例

輸入：牆高=3, 厚=1, 單位重=18, 摩擦角=30, 凝聚力=10, 背填坡度=10
回傳：滑動SF=2.00，傾倒SF=2.50，承載SF=3.00，合格：True
預設安全係數均合格，僅為範例。

植生護坡設計建議

• 輸入：坡度、土壤類型、氣候
• 回傳：建議工法、草種、覆蓋率、說明

範例

輸入：坡度=30, 土壤=壤土, 氣候=亞熱帶
回傳：建議工法：噴播草皮，草種：百慕達草，覆蓋率：90.0%
預設建議，僅為範例。

常用材料設計參數查詢

• 輸入：材料名稱
• 回傳：單位重、凝聚力、摩擦角、強度、說明

範例

輸入：材料=壤土
回傳：材料：壤土，單位重：18.0kN/m3，凝聚力：10.0kPa，摩擦角：30.0°，強度：200.0kPa
預設參數，僅為範例。

坡面保護工法建議

• 輸入：坡度、土壤、降雨
• 回傳：建議工法、說明

範例

輸入：坡度=30, 土壤=砂土, 降雨=1200
回傳：建議工法：格框+草皮
預設建議，僅為範例。

滲水設施設計

• 輸入：設施型式、土壤滲透係數、集水面積、降雨
• 回傳：設計流量、建議尺寸、說明

範例

輸入：型式=滲水井, k=0.001, 面積=100, 降雨=1200
回傳：設施型式：滲水井，設計流量：1.0cms，建議尺寸：直徑1m,深1.5m
預設建議，僅為範例。

IDF曲線查詢

• 輸入：地點、重現期、歷時
• 回傳：降雨強度、說明

範例

輸入：地點=台中, 重現期=10, 歷時=60
回傳：地點：台中，重現期：10年，歷時：60分鐘，強度：100.0 mm/hr
預設強度100mm/hr，僅為範例。

查詢支援清單

• 你可以直接查詢有哪些可用的材料、地區、工法等：

查詢：有哪些常用材料？
回傳：['一般黏土', '砂土', '礫石', '混凝土', ...]

查詢：可以查詢哪些水溝鋪面的曼寧係數？
回傳：['純細砂', '混凝土', '全面密草生', ...]

查詢：有哪些坡面保護工法？
回傳：['草皮或直接播種', '噴播草皮+格框/土工網', ...]

查詢：有哪些IDF地點？
回傳：['台北市', '新北市', '台中市']

查詢失敗時自動提示

• 若查詢時輸入錯誤，會自動回傳所有支援查詢的項目：

輸入：查詢不存在的材料名稱
回傳：查無此材料，支援查詢的材料有：一般黏土, 砂土, 礫石, 混凝土, ...

使用範例(功能導向，讓大模型自動調用相關工具來求解)

• 有一集水區面積約5ha，農業區，新北市，重現期50年，降雨延時60min，該集水區最大逕流量?
• 依據這個逕流量，設計一條寬50cm，深70cm的混凝土溝，設計坡度容許範圍?
• 依據這個逕流量，設計一條寬50cm，溝深60cm的混凝土溝，坡度2.5%，檢核該設計是否OK，並出具一份完整的檢核報告書。
• 有一個破碎岩盤的坡面，角度約60度，位於熱帶多雨地區，請提出坡面保護建議。
• 無基礎的混凝土重力式擋土牆，全高2.3M，牆頂寬50cm，牆底寬100cm，土壤單位重18kN/m3，摩擦角30度，凝聚力10kPa，地下水位在牆頂以下2M，請調用MCP工具，檢核其穩定性，並輸出完整計算報告書。

---

授權

本專案採用 MIT License 授權，歡迎自由使用與貢獻。