thermal-mcp-server

Пакет Python и MCP-сервер, предоставляющий упрощённые тепловые модели жидкостного охлаждения ускорителей в виде инструментов, вызываемых ИИ, для анализа охлаждения на уровне стоек.

Что моделируется

• Стационарные одномерные сети тепловых сопротивлений для холодных пластин GPU.

• Нагрев теплоносителя из энергетического баланса.

• Перепад давления по Дарси-Вейсбаху с простой обработкой ламинарного, переходного и турбулентного режимов.

• Сравнение воды и 50/50 гликоля с фиксированными номинальными свойствами.

• Стойки с идентичными GPU в последовательной или параллельной топологии.

• Первичная оценка CDU: расход, перепад давления, температура возврата и температура переходов.

• Эталонные случаи для публичных ускорителей с явными метками источника и оценки.

Related MCP server: Foam-Agent

Что не моделируется

• Не является CFD-решателем или заменой проектирования тепловых систем производителем.

• Не валидировано на проприетарных тестовых данных.

• Не моделирует потери давления в коллекторах/трубопроводах, характеристики насосов, загрязнение, переходные/двухфазные процессы, двумерное растекание, детальную геометрию холодной пластины или неравномерность распределения потока.

• Не поддерживает гетерогенные стойки; каждый анализ стойки предполагает идентичные GPU и холодные пластины.

• Финансовое и ROI-моделирование выходит за рамки этого пакета.

Быстрый старт

git clone https://github.com/riccardovietri/thermal-mcp-server.git
cd thermal-mcp-server
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest
python examples/quickstart.py

Ожидаемый вывод от python examples/quickstart.py:

thermal-mcp-server quickstart

Single H100 SXM cold plate
  Heat load:        700 W
  Flow rate:        8.0 LPM water
  Inlet temp:       25.0 deg C
  Junction temp:    70.9 deg C
  Margin to 83 C:   12.1 deg C
  Pressure drop:    16.8 kPa
  Flow regime:      transitional

8-GPU rack, parallel topology
  Rack heat load:   5.6 kW
  Total CDU flow:   64.0 LPM
  Max junction:     70.9 deg C
  CDU return temp:  26.3 deg C
  Cold-plate dP:    16.8 kPa

Для сравнения последовательной и параллельной стоек:

python examples/rack_sizing_example.py

Использование MCP

Установите пакет:

pip install thermal-mcp-server

Добавьте сервер в MCP-клиент:

{
  "mcpServers": {
    "thermal": {
      "command": "python",
      "args": ["-m", "thermal_mcp_server"]
    }
  }
}

Если ваш MCP-клиент не наследует переменную PATH из оболочки, используйте абсолютный путь к исполняемому файлу Python в среде, где установлен thermal-mcp-server.

Пример запуска MCP-клиента:

Клиент вызывает analyze_coldplate через MCP-сервер, получает тепловой результат и интерпретирует вывод в диалоге.

Чтобы воспроизвести это локально без отдельного клиента, запустите демонстрацию в памяти — она запускает тот же MCP-сервер внутри процесса (без сети, без API-ключа) и выводит точные запросы/ответы, которые видит модель:

python examples/mcp_client_demo.py

Инструменты

См. docs/mcp.md для контрактов инструментов.

Физические допущения

Модель использует:

T_junction = T_inlet + 0.5 * coolant_rise + Q * R_total
R_total = R_jc + R_tim + R_base + R_conv
coolant_rise = Q / (m_dot * cp)

Теплопередача использует корреляцию Диттуса-Бёлтера для турбулентного потока, Nu = 4,36 для ламинарного потока и линейное смешивание в переходной области. Перепад давления рассчитывается по Дарси-Вейсбаху с тем же разделением режимов.

Прочитайте краткие заметки о модели в docs/model_overview.md и docs/assumptions.md. Подробный вывод и ссылки на ручные расчёты находятся в docs/physics.md.

Публичные эталонные случаи

Примеры включают случаи H100 SXM, B200 / GB200 NVL72, MI300X и Gaudi 3. В примерах по умолчанию только TDP и тепловой предел H100 считаются опубликованными производителем значениями. Другие пределы, сопротивления корпусов и геометрия холодных пластин для высокой мощности помечены как оценки или приближения там, где производители их не публикуют.

См. docs/public_specs.md и examples/real_chip_benchmarks.py.

Тесты

Текущий набор включает 75 тестов:

• Проверки физического поведения и ручных расчётов.

• Контракты MCP-обёртки и сообщения об ошибках.

• Поведение отчёта о решении, включая оценку осуществимости для стойки.

• Дымовые тесты для examples/quickstart.py, examples/rack_sizing_example.py и examples/mcp_client_demo.py.

Запуск:

pytest

Разработка

uv sync --group dev
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run mypy
uv build
uv run python examples/quickstart.py
uv run python examples/rack_sizing_example.py

Они повторяют CI-шлюз; все должны быть пройдены перед слиянием PR.

План развития

• Поддержка характеристик насоса как явного входного параметра вместо фиксированной оценки КПД насоса.

• Модель переходной тепловой ёмкости.

• Больше публичных эталонных случаев с чётко обозначенным качеством источника.

• Доработка интерактивного блокнота для использования в Colab.

• Оптимизация холодной пластины только как отдельный экспериментальный модуль или пакет.

Зачем это существует

Этот проект начался как способ исследовать, как ИИ-ассистенты могут напрямую вызывать лёгкие инженерные модели вместо того, чтобы только генерировать статический текст. Пакет предоставляет упрощённые расчёты жидкостного охлаждения через Python и MCP-инструменты, позволяя задавать вопросы о компромиссах в проектировании охлаждения ускорителей, оценке CDU на уровне стойки и топологии теплоносителя воспроизводимым образом.