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 的绝对路径。

以 Windows 系统，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地點？
回傳：['台北市', '新北市', '台中市']

查询失败时自动提示

• 若查询时输入错误，会自动返回所有支持查询的项目：

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

使用示例

• 有一个集水区面积约为5公顷，农业区，位于新北市，重现期50年，降雨历时60分钟，该集水区的最大径流量是多少？
• 根据这个径流量，设计一条宽50厘米，深70厘米的混凝土沟，设计坡度允许范围是多少？
• 根据这个径流量，设计一条宽50厘米，沟深60厘米的混凝土沟，坡度2.5%，检查该设计是否可行，并出具一份完整的检查报告书。
• 有一个破碎岩盘的坡面，角度约60度，位于热带多雨地区，请提出坡面保护建议。

---

授权

本项目采用 MIT License 授权，欢迎自由使用与贡献。