内容
# 水TAP引擎MCP
> **⚠️ 开发状态：本项目正在积极开发中，尚未达到生产就绪状态。API、接口和功能可能会在未通知的情况下发生变化。请自行承担风险，仅用于评估和测试目的，不建议用于生产部署。**
水处理过程模拟引擎，通过双适配器将WaterTAP功能暴露给AI代理集成。
## 动机
WaterTAP提供复杂的水处理过程方程导向模型（RO、NF、结晶器、蒸发器、生物处理），但建模工作流程需要大量的领域专业知识：自由度管理、适当的缩放、顺序初始化和求解器诊断。
WaterTAP引擎MCP通过使**自然语言成为主要接口**来颠倒这一范式。工程师可以与配套技能合作，后者协调这些操作：
> "在ZLD流程图中评估RO上游的硬度去除（IX或石灰/苏打软化）：比较再生剂和化学品成本与减少蒸发器热负荷的天然气节省，并计算增量预处理CAPEX的IRR。"
这使得：
- **迭代周期缩短**：构建 -> 求解 -> 诊断 -> 修补 -> 重新求解，无需手动跟踪自由度
- **显式卫生操作**：每个修复、缩放和初始化操作都可见且可控
- **结构化诊断**：直接向代理提供自由度建议、缩放问题和故障解释
- **可复制的会话**：版本控制的流程图定义，带有确定性元数据
目标不是取代领域专业知识，而是**减少摩擦**，让工程师可以专注于设计决策，而不是求解器机制。
## WaterTAP vs QSDsan：求解器范式
该服务器是[qsdsan-engine-mcp](../qsdsan-engine-mcp/)的 sibling，但使用根本不同的求解器方法：
| 方面 | WaterTAP（此服务器） | QSDsan |
|--------|------------------------|--------|
| **求解器类型** | 方程导向NLP（IPOPT） | ODE积分（solve_ivp） |
| **建模框架** | Pyomo + IDAES | BioSTEAM |
| **仿真模式** | 稳态代数 | 动态ODE时间步长 |
| **仿真速度** | ~秒到分钟每次求解 | ~毫秒到秒每次运行 |
| **优化** | 原生基于梯度的（pyomo.environ.SolverFactory） | 需要外部优化器 |
| **自由度管理** | 显式 - 需要自由度=0才能求解 | 隐式 - 前馈顺序 |
| **缩放** | 对收敛至关重要 | 不需要 |
| **灵敏度** | 通过NLP求解器自动 | 有限差分近似 |
### 稳态 vs 动态仿真
**WaterTAP（方程导向，稳态）**
- 求解非线性代数方程组：`F(x) = 0`
- 所有变量同时求解，直接找到稳态
- 需要自由度=0（方程数量=未知数数量）
- 理想用于**设计优化**："什么膜面积能最小化LCOW？"
- 支持原生**灵敏度分析**和**基于梯度的优化**
- 每次求解速度较慢，但优化速度更快（精确梯度）
**QSDsan（ODE积分，动态）**
- 积分微分方程随时间变化：`dx/dt = f(x,t)`
- 模拟从t=0到t=T的瞬态行为
- 变量顺序更新；无自由度约束
- 理想用于**动态行为**："启动期间废水质量如何变化？"
- 支持**蒙特卡罗采样**和**场景枚举**（每次运行速度快）
- 每次运行速度较快，但需要多次运行才能优化（有限差分）
### 何时使用WaterTAP
- **膜过程优化**：RO/NF，详细浓度极化，结垢模型
- **基于梯度的优化**：最小化LCOW，最大化回收率，最佳压力
- **严格的热力学**：多组分相平衡，结晶
- **设计决策**：最佳膜面积，阶段配置，压力设定点
- **灵敏度分析**：回收率如何随进水盐度变化？
### 何时使用QSDsan
- **生物处理动态**：活性污泥瞬态，消化器启动/中断
- **快速场景枚举**：蒙特卡罗不确定性量化，DOE
- **时间序列分析**：昼夜模式，风暴事件，过程扰动
- **简单物料平衡**：当稳态足够但动态信息丰富时
- **培训模拟器**：交互式"假设"探索，快速反馈
## 架构：双适配器
引擎通过两个适配器暴露相同的功能：
```
+-------------------------------------+
| 水TAP引擎核心 |
| （注册表、管道、会话） |
+-----------------+-------------------+
|
+-----------------------+---------------------+
| | |
v v v
+----------------+ +----------------+ +----------------+
| MCP适配器 | | CLI适配器 | | Python API |
| （server.py） | | （cli.py） | | 直接使用 |
+----------------+ +----------------+ +----------------+
| |
v v
+----------------+ +----------------+
| MCP客户端 | | 代理技能 |
| （Claude等） | | （Claude代码） |
+----------------+ +----------------+
```
### MCP适配器（`server.py`）
适用于MCP兼容客户端（Claude Desktop，Cline等）：
```bash
python server.py
```
### CLI适配器（`cli.py`）
适用于基于CLI的代理运行时和代理技能：
```bash
python cli.py --help
```
## 工具表面
### 会话管理工具
| 工具 | MCP | CLI | 描述 |
|------|-----|-----|-------------|
| `create_session` | `create_session` | `session new` | 创建新的流程图会话 |
| `get_session` | `get_session` | `session show` | 获取会话详情 |
| `list_sessions` | `list_sessions` | `session list` | 列出所有会话 |
| `delete_session` | `delete_session` | `session delete` | 删除会话 |
### 注册表和发现工具
| 工具 | MCP | CLI | 描述 |
|------|-----|-----|-------------|
| `list_units` | `list_units` | `units list` | 列出可用单元类型 |
| `list_property_packages` | `list_property_packages` | `packages list` | 列出属性包 |
| `list_translators` | `list_translators` | `translators list` | 列出ASM/ADM翻译器 |
| `get_unit_spec` | `get_unit_spec` | `units spec` | 获取自由度、缩放、初始化提示 |
### 流程图构造工具
| 工具 | MCP | CLI | 描述 |
|------|-----|-----|-------------|
| `create_feed` | `create_feed` | `flowsheet add-feed` | 添加具有状态的进料 |
| `create_unit` | `create_unit` | `flowsheet add-unit` | 添加单元操作 |
| `create_translator` | `create_translator` | `flowsheet add-translator` | 添加ASM/ADM翻译器 |
| `connect_ports` | `connect_ports` | `flowsheet connect` | 连接单元 |
| `update_unit` | `update_unit` | `flowsheet update-unit` | 修改单元参数 |
| `delete_unit` | `delete_unit` | `flowsheet delete-unit` | 删除单元 |
| `validate_flowsheet` | `validate_flowsheet` | `flowsheet validate` | 预建验证 |
### 自由度管理工具
| 工具 | MCP | CLI | 描述 |
|------|-----|-----|-------------|
| `get_dof_status` | `get_dof_status` | `dof status` | 获取每个单元的自由度计数 |
| `fix_variable` | `fix_variable` | `dof fix` | 将变量固定为值 |
| `unfix_variable` | `unfix_variable` | `dof unfix` | 释放变量 |
| `list_unfixed_vars` | `list_unfixed_vars` | `dof unfixed` | 显示未固定的变量 |
### 缩放工具
| 工具 | MCP | CLI | 描述 |
|------|-----|-----|-------------|
| `set_scaling_factor` | `set_scaling_factor` | `scale set` | 设置显式缩放 |
| `calculate_scaling_factors` | `calculate_scaling_factors` | `scale calculate` | 运行IDAES缩放 |
| `report_scaling_issues` | `report_scaling_issues` | `scale report` | 查找缩放问题 |
### 求解器操作工具
| 工具 | MCP | CLI | 描述 |
|------|-----|-----|-------------|
| `initialize_unit` | `initialize_unit` | `init unit` | 初始化单个单元 |
| `initialize_flowsheet` | `initialize_flowsheet` | `init flowsheet` | 顺序初始化 |
| `propagate_state` | `propagate_state` | `init propagate` | 端口间状态 |
| `build_and_solve` | `build_and_solve` | `solve` | 完整的卫生管道 |
| `get_solve_status` | `get_solve_status` | `status` | 作业状态 |
| `run_diagnostics` | `run_diagnostics` | `diagnose` | 诊断工具箱 |
### 零阶工具
| 工具 | MCP | CLI | 描述 |
|------|-----|-----|-------------|
| `load_zo_parameters` | `load_zo_parameters` | `zo load` | 从数据库加载 |
| `list_zo_databases` | `list_zo_databases` | `zo databases` | 可用数据库 |
| `get_zo_unit_parameters` | `get_zo_unit_parameters` | `zo params` | 单元参数 |
### 成本工具
| 工具 | MCP | CLI | 描述 |
|------|-----|-----|-------------|
| `enable_costing` | `enable_costing` | `costing enable` | 启用成本块 |
| `add_unit_costing` | `add_unit_costing` | `costing add-unit` | 为单元启用成本 |
| `disable_unit_costing` | `disable_unit_costing` | `costing disable-unit` | 禁用单元成本 |
| `set_costing_parameters` | `set_costing_parameters` | `costing set-params` | 设置成本参数 |
| `list_costed_units` | `list_costed_units` | `costing list` | 显示成本状态 |
| `compute_costing` | `compute_costing` | `costing compute` | 计算LCOW、CapEx、OpEx |
| `get_costing` | `get_costing` | `costing results` | 获取成本结果 |
### 结果工具
| 工具 | MCP | CLI | 描述 |
|------|-----|-----|-------------|
| `get_results` | `get_results` | `results` | 整体求解结果 |
| `get_stream_results` | `get_stream_results` | `results streams` | 流表 |
| `get_unit_results` | `get_unit_results` | `results units` | 单元性能 |
## 属性包
13个支持的属性包：
| 包 | 组件 | 用例 |
|---------|------------|----------|
| **海水** | H2O + TDS | 海水RO/NF，质量基准 |
| **NACL** | H2O + NaCl | 淡水RO，质量基准 |
| **NACL_T_DEP** | H2O + NaCl | 温度依赖热力学 |
| **水** | H2O | 纯水，液+气 |
| **MCAS** | 多离子 | 离子特定NF，摩尔基准 |
| **零阶** | 数据库驱动 | 简单零阶模型 |
| **ASM1** | 13 | 活性污泥（基本） |
| **ASM2D** | 19 | 活性污泥带生物P |
| **ASM3** | - | 活性污泥扩展 |
| **修改ASM2D** | - | 修改ASM2d |
| **ADM1** | 63 | 厌氧消化 |
| **修改ADM1** | - | 修改ADM1 |
| **ADM1_VAPOR** | - | ADM1气相 |
**警告 - 类名冲突：**
- `NaClParameterBlock`存在于`NaCl_prop_pack.py`和`NaCl_T_dep_prop_pack.py`中
- `WaterParameterBlock`存在于`water_prop_pack.py`和`zero_order_properties.py`中
始终使用注册表的完整模块路径，而不是类名。
## 翻译器
**只有WaterTAP中有ASM↔ADM翻译器！** 注册表包括8个翻译器：
**核心翻译器（4）：**
| 源 | 目的地 | 翻译器 |
|--------|-------------|------------|
| ASM1 | ADM1 | Translator_ASM1_ADM1 |
| ADM1 | ASM1 | Translator_ADM1_ASM1 |
| ASM2D | ADM1 | Translator_ASM2d_ADM1 |
| ADM1 | ASM2D | Translator_ADM1_ASM2d |
**修改模型翻译器（4）：**
| 源 | 目的地 | 翻译器 |
|--------|-------------|------------|
| 修改ASM2D | ADM1 | Translator_ModifiedASM2d_ADM1 |
| ADM1 | 修改ASM2D | Translator_ADM1_ModifiedASM2d |
| ASM2D | 修改ADM1 | Translator_ASM2d_ModifiedADM1 |
| 修改ADM1 | ASM2D | Translator_ModifiedADM1_ASM2d |
对于非生物流程图，在整个流程图中**使用相同的属性包**。
## 单元注册表
21+个单元操作，可跨类别使用：
- **膜：** ReverseOsmosis0D, ReverseOsmosis1D, Nanofiltration0D, NanofiltrationDSPMDE0D
- **零阶：** NanofiltrationZO, UltraFiltrationZO, PumpZO, FeedZO
- **热力学：** Evaporator, Condenser, Compressor, Crystallization
- **泵/ERD：** Pump, EnergyRecoveryDevice, PressureExchanger
- **实用工具：** Feed, Product, Mixer, Separator（来自IDAES）
- **生物：** （使用属性包兼容性用于ASM/ADM）
```bash
# 列出所有单元
python cli.py units list --json-out
# 按类别筛选
python cli.py units list --category membrane
```
## 求解器卫生管道
`build_and_solve`工具运行完整的卫生管道：
```
IDLE -> DOF_CHECK -> SCALING -> INITIALIZATION -> PRE_SOLVE_DIAGNOSTICS -> SOLVING
|
COMPLETED <-- POST_SOLVE_DIAGNOSTICS <----------------------------------------+
^ | （如果失败） |
+------- RELAXED_SOLVE ---------------------------------------------------+
| （如果仍然失败）
FAILED
```
每个阶段提供结构化输出用于诊断：
- **DOF_CHECK:** 不指定/过度指定分析，建议
- **SCALING:** 未缩放变量和约束警告
- **INITIALIZATION:** 单元初始化状态和初始化后自由度
- **DIAGNOSTICS:** 约束残差，边界违规
## 快速入门
### 使用CLI
```bash
# 创建会话
python cli.py session new --property-package SEAWATER --id my_ro
# 添加进料和单元
python cli.py flowsheet add-feed --session my_ro --flow 100 \
--tds 35000 --temp 25 --pressure 1.01
python cli.py flowsheet add-unit --session my_ro --type ReverseOsmosis0D \
--id RO1 --config '{"has_pressure_change": true}'
# 修复自由度
python cli.py dof fix --session my_ro --unit RO1 --var "A_comp[0, H2O]" --value 4.2e-12
python cli.py dof fix --session my_ro --unit RO1 --var "B_comp[0, TDS]" --value 3.5e-8
python cli.py dof fix --session my_ro --unit RO1 --var area --value 50
python cli.py dof fix --session my_ro --unit RO1 --var "permeate.pressure[0]" --value 101325
# 检查自由度
python cli.py dof status --session my_ro
# 求解
python cli.py solve --session my_ro --run-full-pipeline
### 使用MCP
在MCP客户端配置（例如Claude Desktop `config.json`）：
```json
{
"mcpServers": {
"watertap-engine": {
"command": "python",
"args": ["/path/to/watertap-engine-mcp/server.py"]
}
}
```
然后使用自然语言配合配套技能：
> "评估RO上游的硬度去除（IX或石灰/苏打软化）并计算增量预处理CAPEX基于减少蒸发器热负荷的IRR。"
## 安装
```bash
# 克隆存储库
git clone https://github.com/paturn-water/watertap-engine-mcp.git
cd watertap-engine-mcp
# 创建虚拟环境
python -m venv venv
source venv/bin/activate # 或在Windows上使用venv\Scripts\activate
# 安装依赖项
pip install -r requirements.txt
# 适用于完整WaterTAP支持（可选，用于求解操作）：
pip install watertap idaes-pse pyomo
```
### 依赖项
- Python 3.10+
- WaterTAP 1.0+（可选，用于求解）
- IDAES-PSE 2.0+（可选，用于求解）
- FastMCP（用于MCP适配器）
- Typer（用于CLI适配器）
## 文件结构
```
watertap-engine-mcp/
├── server.py # MCP适配器（FastMCP）- 57种工具
├── cli.py # CLI适配器（typer）
├── worker.py # 后台作业工作器
├── core/
│ ├── property_registry.py # 13种属性包
│ ├── translator_registry.py # ASM/ADM翻译器
│ ├── unit_registry.py # 单元规格，带自由度，缩放
│ ├── water_state.py # 进料状态抽象
│ └── session.py # 会话管理
├── solver/
│ ├── pipeline.py # 卫生管道状态机
│ ├── dof_resolver.py # 自由度分析
│ ├── scaler.py # 缩放工具
│ ├── initializer.py # 顺序初始化
│ ├── diagnostics.py # DiagnosticsToolbox包装器
│ └── recovery.py # 故障恢复
├── utils/
│ ├── model_builder.py # 会话 -> Pyomo 模型
│ ├── auto_translator.py # 翻译器插入
│ ├── job_manager.py # 后台作业
│ ├── state_translator.py # 进料状态转换
│ └── topo_sort.py # 拓扑排序
├── templates/ # 预建流程图模板
│ ├── ro_train.py
│ ├── nf_softening.py
│ └── mvc_crystallizer.py
├── jobs/ # 会话/作业持久性（运行时）
└── tests/ # 373个测试
```
## 配套技能
`watertap-flowsheet-builder`技能（位于`~/skills/watertap-skill/`）：提供领域智能：
- 自由度建议，每个单元类型有典型值
- 属性包选择指导
- 生物链翻译器选择
- 故障诊断模式
- 常见流程图的流程编排
该技能编排原子服务器工具 - 服务器提供显式操作，技能提供智能。
## 测试
```bash
# 运行所有测试
pytest tests/ -v
# 跳过慢速测试
pytest tests/ -v -m "not slow"
```
## 许可证
MIT
## 致谢
在国家水创新联盟（NAWI）的支持下，基于WaterTAP构建。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器