Dual Water Tank MCP for Battery Aging Mechanism Identification

English | 中文

This project is an MCP server for fitting a lithium-ion full-cell dual-water-tank model from charge/discharge voltage-capacity data. It is designed for battery aging mechanism identification, including parameter fitting, charge/discharge sign handling, capacity-bound adaptation, and batch processing.

The project keeps a two-layer structure:

• dual_water_tank_mcp/: core model code, including data loading, column detection, charge/discharge detection, model calculation, GA fitting, batch output, and CLI.

• dual_water_tank_mcp/server.py: a thin MCP interface layer that exposes the core functions as MCP tools.

If you need to fix or improve the model later, edit the core code under dual_water_tank_mcp/, then restart the MCP server.

Features

• Reads .xlsx, .xls, .csv, .txt, and .tsv battery test data.

• Automatically detects voltage and capacity columns.

• Automatically detects charge or discharge from the voltage trend.

• Applies charge/discharge signs for electrode stoichiometry y and x.

• Automatically tests both +I*R and -I*R, then keeps the lower-RMSE result.

• Automatically adapts GA capacity bounds from the dataset capacity span.

• Supports single-file fitting and batch fitting.

• Writes final results to a desktop output folder by default.

• Runs as an MCP server with ready-to-call tools.

Related MCP server: COMSOL MCP Server

From GitHub To Installation

Clone the repository:

git clone <your GitHub repository URL>
cd dual-water-tank-mcp

If you already have the source code locally, enter the project root directly, for example:

cd "D:\desktop\PSG\1.1 github\dual-water-tank-mcp"

Python 3.10 or newer is required. Git is also recommended.

Check:

python --version
git --version

You can use the bundled one-click MCP launcher. On first run, it creates .venv and installs dependencies:

.\run_mcp.cmd

The same launcher is what MCP clients should call. Users do not need to edit model code, Python files, or MCP server code.

Command-line preview example:

.\dual-water-tank.cmd preview "test_cases\25C_0.1C\25C_0.1C.xlsx"

Command-line fitting example:

.\dual-water-tank.cmd fit "test_cases\25C_0.1C\25C_0.1C.xlsx"

Start MCP

Add this project as an MCP server in Codex, Claude Desktop, Claude Code, or another MCP client.

Windows MCP configuration:

{
  "mcpServers": {
    "dual-water-tank-model": {
      "command": "C:\\path\\to\\dual-water-tank-mcp\\run_mcp.cmd",
      "args": []
    }
  }
}

macOS/Linux MCP configuration:

{
  "mcpServers": {
    "dual-water-tank-model": {
      "command": "/path/to/dual-water-tank-mcp/run_mcp.sh",
      "args": []
    }
  }
}

On macOS/Linux, make the scripts executable once:

chmod +x run_mcp.sh dual-water-tank.sh

Reusable config examples are also provided:

• examples/mcp_config_windows.json

• examples/mcp_config_macos_linux.json

After configuring the client, refresh or restart the MCP connection. If dual-water-tank-model appears as an available MCP server, the connection is ready.

How To Use After MCP Is Connected

Once connected, you do not need to manually run Python or command-line scripts. Ask your MCP client to call the tools exposed by this project.

Recommended workflow:

1. If the input format is uncertain, call preview_dual_water_tank_data first.

2. For one file, call fit_dual_water_tank.

3. For many files, call batch_fit_dual_water_tank.

4. Open result.json, fitted_curve.csv, or batch_summary.csv in the desktop output folder.

By default, final results are written to the desktop:

Desktop/dual water tank output/run_YYYYMMDD_HHMMSS/

On this author's Windows machine, the default desktop path is usually:

D:\desktop\dual water tank output\

The MCP response also includes output paths such as output_dir, curve_csv, and result_json.

Example user requests:

Use the dual-water-tank MCP to preview test_cases/25C_0.1C/25C_0.1C.xlsx.

Use the dual-water-tank MCP to fit test_cases/25C_0.1C/25C_0.1C.xlsx and save the final result to the desktop.

Use the dual-water-tank MCP to batch fit all Excel files in D:\my_battery_data.
Write the final results to the desktop dual water tank output folder.

Use the dual-water-tank MCP to fit D:\data\cell.xlsx.
Use D:\data\anode.txt as anode_path and D:\data\cathode.txt as cathode_path.
Automatically detect charge/discharge direction and I*R sign.

MCP Tools

The server exposes these tools:

• preview_dual_water_tank_data: preview one dataset and return inferred columns, charge/discharge direction, capacity span, voltage range, and current estimate.

• fit_dual_water_tank: fit one file or one workbook sheet and write result.json plus fitted_curve.csv.

• batch_fit_dual_water_tank: fit all supported files in a folder, or fit a supplied file list, and write per-file outputs plus batch summaries.

Tool Examples

Example MCP call for preview_dual_water_tank_data:

{
  "data_file": "test_cases/25C_0.1C/25C_0.1C.xlsx"
}

Example MCP call for fit_dual_water_tank:

{
  "data_file": "test_cases/25C_0.1C/25C_0.1C.xlsx",
  "direction": "auto",
  "resistance_sign": "auto"
}

Optional inputs for fit_dual_water_tank:

{
  "data_file": "D:/data/cell.xlsx",
  "anode_path": "D:/data/anode.txt",
  "cathode_path": "D:/data/cathode.txt",
  "current": 65,
  "direction": "auto",
  "resistance_sign": "auto",
  "voltage_col": "B",
  "capacity_col": "C",
  "output_dir": "D:/desktop/dual water tank output/my_run"
}

Example MCP call for batch_fit_dual_water_tank:

{
  "input_dir": "D:/my_battery_data",
  "direction": "auto",
  "resistance_sign": "auto"
}

Model Sign Convention

The model keeps the original five parameters:

[y0, Cp, x0, Cn, R]

Charge:

y = y0 - Q / Cp
x = x0 + Q / Cn
V = Upos(y) - Uneg(x) + I * R

Discharge:

y = y0 + Q / Cp
x = x0 - Q / Cn
V = Upos(y) - Uneg(x) - I * R

I is treated as a positive current magnitude. By default, resistance_sign is auto, so the tool fits both +I*R and -I*R for the detected direction and keeps the lower full-data RMSE. The selected sign and both candidate RMSE values are written to resistance_sign_selection in result.json.

Available resistance-sign modes:

auto | physics | positive | negative | matlab

• auto: fit both +I*R and -I*R, then choose the lower full-data RMSE.

• physics: charge uses +I*R; discharge uses -I*R.

• positive: force +I*R.

• negative: force -I*R.

• matlab: always use +I*R, matching the executed objective function in the original MATLAB file.

The original MATLAB target function uses +I*R for the provided charge example, while one MATLAB comment says charge should use -I*R. Because the code and comment conflict, the MCP default is data-driven sign selection.

Input Data Rules

Recommended full-cell data columns:

Headerless files are supported. The program scores numeric columns by whether they look like voltage and capacity:

• voltage-like columns usually have median values in a common battery voltage range and a reasonable voltage span;

• capacity-like columns usually have a meaningful span and are mostly monotonic;

• adjacent voltage/capacity columns get a bonus because this is common in cycler exports.

Charge/discharge detection normalizes capacity to move forward from zero, then compares the median voltage near the end against the median voltage near the beginning:

• voltage rising means charge;

• voltage falling means discharge;

• near-flat data falls back to a linear voltage-capacity slope.

The current magnitude can be provided explicitly with current. If it is omitted, the tool tries to parse C-rate from the file name. For example, 25C_0.1C.xlsx is interpreted as 0.1C; the temperature-like 25C is ignored when a more plausible C-rate is present.

Electrode OCV Files

The bundled test case includes matching electrode OCV files:

test_cases/25C_0.1C/anode.txt
test_cases/25C_0.1C/cathode.txt

By default, the MCP uses these test-case electrode files so that a new user can immediately run the demo. For real experiments, pass anode_path and cathode_path if you want to use a different pair of half-cell OCV curves.

Output Files

Each single-file fitting job outputs:

• result.json: fitted parameters, RMSE, sign selection, stoichiometry ranges, and derived values.

• fitted_curve.csv: capacity, measured voltage, modeled voltage, residual, electrode potentials, and x/y stoichiometry.

Batch jobs also output:

• batch_summary.csv: one-row summary for each fitted file.

• batch_summary.json: full batch summary with errors, if any.

If output_dir is not provided, final results are written to:

Desktop/dual water tank output/run_YYYYMMDD_HHMMSS/

The input data folder stays clean by default.

Test Case

The repository includes one test case:

test_cases/25C_0.1C/

Files:

• 25C_0.1C.xlsx: full-cell voltage-capacity test data.

• anode.txt: anode half-cell OCV curve.

• cathode.txt: cathode half-cell OCV curve.

Quick preview:

.\dual-water-tank.cmd preview "test_cases\25C_0.1C\25C_0.1C.xlsx"

Quick fit:

.\dual-water-tank.cmd fit "test_cases\25C_0.1C\25C_0.1C.xlsx"

Repository Layout

dual_water_tank_mcp/          Python package and MCP server
test_cases/25C_0.1C/          Example full-cell dataset plus anode/cathode OCV files
references/original_resource/ Original MATLAB scripts, notes, and source references
examples/                     MCP configuration examples
Desktop/dual water tank output/ Generated results outside the repository

Local Debugging

Run a quick preview:

.\dual-water-tank.cmd preview "test_cases\25C_0.1C\25C_0.1C.xlsx"

Run a quick fit without saving files:

.\dual-water-tank.cmd fit "test_cases\25C_0.1C\25C_0.1C.xlsx" --no-save --population-size 20 --generations 1 --max-points 100

Run the sign-diagnosis script:

python scripts\diagnose_parameter_gap.py

Developer installation, only if you want to modify the code:

python -m venv .venv
.\.venv\Scripts\activate
pip install -e .

License

The Python code in this repository is released under the Apache License 2.0. See LICENSE. Project attribution is listed in NOTICE.

Apache License 2.0 includes an explicit patent license and patent termination language. Reference materials under references/original_resource/ may have their own copyright, patent, or usage terms. The Apache License 2.0 for this repository code does not change the ownership or licensing of those external/reference files.

Dual Water Tank MCP for Battery Aging Mechanism Identification 中文

English | 中文

这是一个用于锂离子电池双水箱模型参数辨识的 MCP 服务。输入为充电/放电电压-容量数据，输出为双水箱模型参数、拟合曲线、误差、符号选择结果和批量汇总。它主要面向电池老化机理识别，例如容量损失、锂库存变化、正负极容量变化等参数分析。

项目保持两层结构：

• dual_water_tank_mcp/：核心模型代码，包括数据读取、列识别、充放电识别、模型计算、遗传算法拟合、批量输出和 CLI。

• dual_water_tank_mcp/server.py：MCP 薄接口层，只负责把核心函数暴露成 MCP 工具。

后续如果需要修正或改进模型，直接改 dual_water_tank_mcp/ 下的核心代码，然后重启 MCP 服务即可。

功能

• 读取 .xlsx、.xls、.csv、.txt、.tsv 电池测试数据。

• 自动识别电压列和容量列。

• 根据电压趋势自动识别充电或放电。

• 自动处理正负极化学计量比 y/x 的充放电符号。

• 自动分别尝试 +I*R 和 -I*R，选择全数据 RMSE 更低的结果。

• 根据数据容量范围自动适配遗传算法容量上下限。

• 支持单文件拟合和批量拟合。

• 默认把最终结果输出到桌面文件夹。

• 可以作为 MCP server 被 Codex、Claude 等 agent 调用。

从 GitHub 到安装

如果项目已经上传到 GitHub，先克隆仓库：

git clone <你的 GitHub 仓库地址>
cd dual-water-tank-mcp

如果已经有本地源码，直接进入项目根目录，例如：

cd "D:\desktop\PSG\1.1 github\dual-water-tank-mcp"

需要 Python 3.10 或更高版本，建议同时安装 Git。

检查版本：

python --version
git --version

可以直接使用仓库自带的一键 MCP 启动脚本。第一次运行会自动创建 .venv 并安装依赖：

.\run_mcp.cmd

MCP 客户端也应该调用这个脚本。用户不需要修改模型代码、Python 文件或 MCP server 文件。

命令行预览示例：

.\dual-water-tank.cmd preview "test_cases\25C_0.1C\25C_0.1C.xlsx"

命令行拟合示例：

.\dual-water-tank.cmd fit "test_cases\25C_0.1C\25C_0.1C.xlsx"

启动 MCP

在 Codex、Claude Desktop、Claude Code 或其他 MCP 客户端中添加这个 MCP server。

Windows MCP 配置示例：

{
  "mcpServers": {
    "dual-water-tank-model": {
      "command": "C:\\path\\to\\dual-water-tank-mcp\\run_mcp.cmd",
      "args": []
    }
  }
}

macOS/Linux MCP 配置示例：

{
  "mcpServers": {
    "dual-water-tank-model": {
      "command": "/path/to/dual-water-tank-mcp/run_mcp.sh",
      "args": []
    }
  }
}

macOS/Linux 需要先给脚本执行权限：

chmod +x run_mcp.sh dual-water-tank.sh

仓库里也提供了可复制修改的配置文件：

• examples/mcp_config_windows.json

• examples/mcp_config_macos_linux.json

配置完成后，在 MCP 客户端中刷新或重启连接。看到 dual-water-tank-model 可用，就说明已经连上。

MCP 已连接后怎么用

连接成功以后，不需要手动运行 Python 或命令行脚本。你只需要在支持 MCP 的客户端里提出需求，客户端会调用本项目暴露的 MCP 工具。

推荐流程：

1. 如果不确定输入数据格式，先调用 preview_dual_water_tank_data。

2. 单文件拟合调用 fit_dual_water_tank。

3. 批量拟合调用 batch_fit_dual_water_tank。

4. 打开桌面输出目录里的 result.json、fitted_curve.csv 或 batch_summary.csv 查看结果。

最终结果默认输出到桌面：

Desktop/dual water tank output/run_YYYYMMDD_HHMMSS/

在作者的 Windows 电脑上，通常是：

D:\desktop\dual water tank output\

MCP 返回结果里也会包含 output_dir、curve_csv、result_json 等路径。

用户可以这样对 MCP 客户端说：

请使用 dual-water-tank MCP 预览 test_cases/25C_0.1C/25C_0.1C.xlsx。

请使用 dual-water-tank MCP 拟合 test_cases/25C_0.1C/25C_0.1C.xlsx，并把最终结果保存到桌面。

请使用 dual-water-tank MCP 批量拟合 D:\my_battery_data 里面的所有 Excel 文件。
最终结果输出到桌面的 dual water tank output 文件夹。

请使用 dual-water-tank MCP 拟合 D:\data\cell.xlsx。
anode_path 使用 D:\data\anode.txt，cathode_path 使用 D:\data\cathode.txt。
自动判断充放电方向和 I*R 符号。

MCP 工具

MCP server 暴露这些工具：

• preview_dual_water_tank_data：预览一个数据集，返回自动识别到的列、充放电方向、容量范围、电压范围和电流估计。

• fit_dual_water_tank：拟合一个文件或一个工作表，输出 result.json 和 fitted_curve.csv。

• batch_fit_dual_water_tank：拟合一个文件夹或文件列表，输出每个文件的结果和批量汇总。

工具调用示例

preview_dual_water_tank_data 示例：

{
  "data_file": "test_cases/25C_0.1C/25C_0.1C.xlsx"
}

fit_dual_water_tank 示例：

{
  "data_file": "test_cases/25C_0.1C/25C_0.1C.xlsx",
  "direction": "auto",
  "resistance_sign": "auto"
}

fit_dual_water_tank 可选参数示例：

{
  "data_file": "D:/data/cell.xlsx",
  "anode_path": "D:/data/anode.txt",
  "cathode_path": "D:/data/cathode.txt",
  "current": 65,
  "direction": "auto",
  "resistance_sign": "auto",
  "voltage_col": "B",
  "capacity_col": "C",
  "output_dir": "D:/desktop/dual water tank output/my_run"
}

batch_fit_dual_water_tank 示例：

{
  "input_dir": "D:/my_battery_data",
  "direction": "auto",
  "resistance_sign": "auto"
}

模型符号约定

模型保留原始五个参数：

[y0, Cp, x0, Cn, R]

充电：

y = y0 - Q / Cp
x = x0 + Q / Cn
V = Upos(y) - Uneg(x) + I * R

放电：

y = y0 + Q / Cp
x = x0 - Q / Cn
V = Upos(y) - Uneg(x) - I * R

I 按正的电流大小输入。默认 resistance_sign 为 auto，工具会对检测到的方向分别拟合 +I*R 和 -I*R，选择全数据 RMSE 更低的结果。最终选择的符号和两个候选的 RMSE 会写入 result.json 的 resistance_sign_selection 字段。

可选的电阻符号模式：

auto | physics | positive | negative | matlab

• auto：同时拟合 +I*R 和 -I*R，选择全数据 RMSE 更低的结果。

• physics：充电用 +I*R，放电用 -I*R。

• positive：强制 +I*R。

• negative：强制 -I*R。

• matlab：始终使用 +I*R，对应原 MATLAB 目标函数实际执行的公式。

原 MATLAB 目标函数在给定充电示例中实际使用 +I*R，但脚本注释中有一处写成充电 -I*R。因为代码和注释冲突，所以本 MCP 默认使用数据驱动的符号选择。

输入数据规则

推荐全电池数据至少包含两列：

没有表头也可以。程序会根据数值特征识别电压列和容量列：

• 电压列通常在常见电池电压范围内，并且有合理电压跨度。

• 容量列通常有明显跨度，并且大体单调。

• 相邻的电压/容量列会获得额外评分，因为这符合常见测试设备导出格式。

充放电识别会先把容量归一化为从零向前增加，再比较末端电压和起始电压：

• 电压整体上升：charge

• 电压整体下降：discharge

• 近似平坦：退回到线性电压-容量斜率判断

电流大小可以通过 current 显式传入。如果不传，工具会尝试从文件名解析 C-rate。例如 25C_0.1C.xlsx 会识别为 0.1C，温度含义的 25C 不会被当成倍率。

半电池 OCV 文件

自带测试案例包含匹配的半电池 OCV 文件：

test_cases/25C_0.1C/anode.txt
test_cases/25C_0.1C/cathode.txt

默认情况下，MCP 使用这套测试案例里的电极文件，方便新用户下载后立刻跑通 demo。真实实验中，如果要使用自己的半电池 OCV 曲线，请传入 anode_path 和 cathode_path。

输出文件

单文件拟合会输出：

• result.json：拟合参数、RMSE、符号选择、化学计量比范围和派生参数。

• fitted_curve.csv：容量、实测电压、模型电压、残差、正负极电势和 x/y。

批量任务额外输出：

• batch_summary.csv：每个拟合文件一行摘要。

• batch_summary.json：完整批量结果和错误信息。

如果不传 output_dir，最终结果会写到：

Desktop/dual water tank output/run_YYYYMMDD_HHMMSS/

默认不会污染输入数据文件夹。

测试案例

仓库包含一个测试案例：

test_cases/25C_0.1C/

文件：

• 25C_0.1C.xlsx：全电池电压-容量测试数据。

• anode.txt：负极半电池 OCV 曲线。

• cathode.txt：正极半电池 OCV 曲线。

快速预览：

.\dual-water-tank.cmd preview "test_cases\25C_0.1C\25C_0.1C.xlsx"

快速拟合：

.\dual-water-tank.cmd fit "test_cases\25C_0.1C\25C_0.1C.xlsx"

仓库结构

dual_water_tank_mcp/          Python package and MCP server
test_cases/25C_0.1C/          Example full-cell dataset plus anode/cathode OCV files
references/original_resource/ Original MATLAB scripts, notes, and source references
examples/                     MCP configuration examples
Desktop/dual water tank output/ Generated results outside the repository

本地调试

快速预览：

.\dual-water-tank.cmd preview "test_cases\25C_0.1C\25C_0.1C.xlsx"

快速拟合但不保存文件：

.\dual-water-tank.cmd fit "test_cases\25C_0.1C\25C_0.1C.xlsx" --no-save --population-size 20 --generations 1 --max-points 100

运行符号诊断脚本：

python scripts\diagnose_parameter_gap.py

开发者安装方式，仅在需要修改代码时使用：

python -m venv .venv
.\.venv\Scripts\activate
pip install -e .

许可证

本仓库 Python 代码使用 Apache License 2.0，见 LICENSE。项目署名见 NOTICE。

Apache License 2.0 包含明确的专利授权和专利终止条款。references/original_resource/ 中的参考资料可能有其原始版权、专利或使用限制。本仓库代码使用 Apache License 2.0 不会改变这些外部参考资料的权属或许可状态。