能量加-MCP

Name: 能量加-MCP
Author: LBNL-ETA

作者：LBNL-ETA40 星标更新：2025-11-21

安装使用来源：spider==github.com

项目介绍

EnergyPlus MCP Server

这是一个基于模型上下文协议（MCP）的服务器，提供了35个全面工具，这些工具被组织成5个主要类别，用于处理EnergyPlus建筑能源模拟模型。该服务器使AI助手和其他MCP客户端能够通过标准化接口加载、验证、修改和分析EnergyPlus IDF（输入数据文件）模型。

版本: 0.1.0
EnergyPlus兼容性: 25.1.0
Python: 3.10+

这个仓库是关于什么的？

这个仓库包含了一个专门为EnergyPlus建筑能源模拟工作流程设计的MCP服务器。EnergyPlus是一个强大的建筑能源模拟引擎，而这个MCP服务器使其可以被AI助手和自动化工具访问。

关键特性：

🏗️ 完整模型生命周期：加载、验证、分析、修改和模拟EnergyPlus IDF文件
🔍 深度建筑分析：提取有关区域、表面、材料、构造和时间表的详细信息
⚙️ 灵活的模拟控制：配置模拟参数、运行周期和输出要求
🚀 自动化模拟：使用天气文件执行完整的EnergyPlus模拟并进行后处理
📊 高级可视化：创建交互式HTML图表和暖通空调系统图
🔧 暖通空调系统智能：全面发现、拓扑分析和可视化暖通空调循环
📈 智能输出管理：智能发现和配置输出变量和计量器
🎯 建筑修改：修改渗透率、添加窗户膜、表面涂层等工具
📋 时间表智能：深入分析和修改所有类型的EnergyPlus时间表
🖥️ 企业就绪：内置日志记录、错误跟踪、健康监控和调试功能
📁 智能文件管理：智能路径解析、模糊文件匹配和有序样本库

架构

EnergyPlus MCP服务器遵循分层架构，明确区分关注点：

MCP协议层：FastMCP服务器处理客户端通信
工具层：35个工具被组织成5个功能性类别
编排层：EnergyPlus Manager和核心配置模块用于工作流协调
EnergyPlus集成层：直接与EnergyPlus模拟引擎和文件系统接口

这种架构使得与AI助手、IDE和其他MCP客户端的可扩展集成成为可能，同时保持了强大的错误处理和企业级日志记录能力。

可用工具

EnergyPlus MCP服务器提供了35个全面工具，这些工具被组织成5个主要类别，如架构图所示：

🗂️ 模型配置与加载（9个工具）

copy_file - 智能文件复制，具有路径解析和模糊匹配功能
load_idf_model - 加载并验证EnergyPlus IDF文件，带有详细的错误报告
list_available_files - 浏览示例文件、示例文件和天气数据
get_model_summary - 提取基本模型信息（建筑物、站点、模拟控制、版本）
validate_idf - 全面的模型验证，带有警告和错误
check_simulation_settings - 查看当前模拟控制和运行周期设置
modify_simulation_control - 修改模拟控制参数（运行周期、尺寸等）
modify_run_period - 调整模拟时间段和日期
get_server_configuration - 获取详细的服务器配置和版本信息

🔍 模型检查（9个工具）

list_zones - 列出所有热区及其详细属性
get_surfaces - 获取全面的建筑表面信息和几何形状
get_materials - 提取材料和构造定义
inspect_schedules - 深入分析所有时间表对象，并支持值提取
inspect_people - 对People对象进行详细分析，包括占用计算和热舒适设置
inspect_lights - 对Lights对象进行全面分析，包括功率计算和热量分数
inspect_electric_equipment - 对ElectricEquipment对象进行全面分析，包括功率计算和热量分数
get_output_variables - 获取已配置的变量或发现所有可用的输出变量
get_output_meters - 获取已配置的计量器或发现所有可用的能量计量器

⚙️ 模型修改（8个工具）

modify_people - 使用灵活的目标修改People对象（全部、按区域或按名称）
modify_lights - 支持不同计算方法的Lights对象修改
modify_electric_equipment - 支持不同计算方法的ElectricEquipment对象修改
change_infiltration_by_mult - 通过乘数因子修改渗透率
add_window_film_outside - 向外部玻璃添加窗户膜，具有自定义属性
add_coating_outside - 应用外部表面涂层（墙壁/屋顶），具有热性能
add_output_variables - 添加输出变量，具有智能验证和格式化
add_output_meters - 添加输出计量器，具有灵活的指定格式

🚀 模拟与结果（4个工具）

run_energyplus_simulation - 使用天气文件执行完整的EnergyPlus模拟
create_interactive_plot - 从模拟结果生成交互式HTML图表
discover_hvac_loops - 发现模型中的所有暖通空调循环（植物、冷凝器、空气）
get_loop_topology - 获取特定暖通空调循环的详细拓扑结构，包括组件和连接

🖥️ 服务器管理和日志（5个工具）

visualize_loop_diagram - 生成暖通空调系统拓扑和流路径的视觉图
get_server_status - 检查服务器健康状况、性能和系统信息
get_server_logs - 获取最近的服务器日志条目以供调试
get_error_logs - 获取最近的错误日志条目以供故障排除
clear_logs - 清除/轮换当前日志文件，自动备份

项目结构

sample_files/: 示例EnergyPlus IDF文件和天气数据
- 1ZoneUncontrolled.idf: 简单的单区模型
- 1ZoneEvapCooler.idf: 单区带蒸发冷却
- 5ZoneAirCooled.idf: 多区空气冷却模型
- USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw: 旧金山的天气文件
energyplus_mcp_server/: 服务器实现
- server.py: 包含所有可用工具的FastMCP服务器
- energyplus_tools.py: EnergyPlus文件操作实用程序
config.py: 配置管理
utils/: 高级实用模块
- schedules.py: 综合的时间表解析、分析和修改实用程序
- diagrams.py: 暖通空调图生成和可视化工具
pyproject.toml: 项目元数据和依赖项
outputs/: 模拟输出和修改文件的目录

设置说明

方案1：VS Code开发容器（推荐）

最简单的方法是使用VS Code开发容器，它提供了一个完全配置好的环境，其中预装了EnergyPlus。

前提条件：

步骤：

克隆仓库：

git clone https://github.com/tsbyq/EnergyPlus_MCP.git
cd EnergyPlus_MCP

在VS Code中打开：
```
code .
```
当提示时，点击“在容器中重新打开”或：
- 按 Ctrl+Shift+P
- 选择“Dev Containers: 在容器中重新打开”
容器会自动：
- 安装EnergyPlus 25.1.0
- 使用uv设置Python依赖项
- 配置开发环境
- 安装VS Code的Python和EnergyPlus扩展
- 运行uv sync --extra dev以安装所有依赖项

开发容器中包含的内容：

预配置环境：基于Ubuntu的容器，包含所有依赖项
EnergyPlus集成：预安装并配置了EnergyPlus 25.1.0
Python环境：带有uv包管理器的Python 3.11+
VS Code扩展：Python、Jupyter、EnergyPlus ModelKit和支持TOML
端口转发：自动转发MCP Inspector（6274）、HTTP服务器（8080, 3000）
工作区设置：正确的工作区文件夹配置和Python解释器路径

开发容器设置定义在.devcontainer/文件夹中：

Dockerfile: 包含EnergyPlus和Python设置的容器镜像
devcontainer.json: VS Code配置、扩展和端口转发

方案2：纯Docker

如果你更喜欢直接使用Docker而不使用VS Code：

前提条件：

Docker Desktop

步骤：

克隆仓库：

git clone https://github.com/tsbyq/EnergyPlus_MCP.git
cd EnergyPlus_MCP

构建开发容器：

docker build -t energyplus-mcp-dev -f .devcontainer/Dockerfile .

运行容器并挂载卷：

docker run -it --rm -v "%cd%":/workspace -w /workspace/energyplus-mcp-server energyplus-mcp-dev bash

在容器内安装依赖项：
```
uv sync --extra dev
```

方案3：本地开发

对于不使用容器的本地开发（需要手动安装EnergyPlus）：

前提条件：

Python 3.10或更高版本
uv包管理器
EnergyPlus 25.1.0（从NREL GitHub下载）

步骤：

克隆并导航到服务器目录：

git clone https://github.com/tsbyq/EnergyPlus_MCP.git
cd EnergyPlus_MCP\energyplus-mcp-server

安装依赖项：
```
uv sync --extra dev
```
在你的环境中或配置文件中配置EnergyPlus路径（服务器将在标准安装位置查找EnergyPlus）。

如何使用

根据需求，EnergyPlus MCP服务器可以有多种使用方式：

1. 作为AI助手的MCP服务器

主要用途是将服务器连接到兼容MCP的AI助手（如Claude Desktop、VS Code Copilot或其他MCP客户端）。

启动服务器：

cd energyplus-mcp-server
uv run python -m energyplus_mcp_server.server

服务器将以STDIO模式启动，并可以连接到MCP客户端。

示例MCP客户端配置（针对Claude Desktop）：

{
  "mcpServers": {
    "energyplus": {
      "command": "uv",
      "args": ["run", "python", "-m", "energyplus_mcp_server.server"],
      "cwd": "/path/to/energyplus-mcp-server"
    }
  }
}

2. 交互式开发和测试

使用MCP Inspector（如果可用）：

uv run mcp-inspector energyplus_mcp_server.server

这将打开一个Web界面，用于交互式测试MCP工具。

直接使用Python：

# 在Python环境或Jupyter笔记本中
from energyplus_mcp_server.energyplus_tools import EnergyPlusManager

ep_manager = EnergyPlusManager()

# 加载示例模型
result = ep_manager.load_idf("1ZoneUncontrolled.idf")
print(result)

# 获取模型摘要
summary = ep_manager.get_model_basics("1ZoneUncontrolled.idf")
print(summary)

3. 常见使用示例

加载并验证IDF文件：

{
  "tool": "load_idf_model",
  "arguments": {
    "idf_path": "sample_files/1ZoneUncontrolled.idf"
  }
}

修改模拟设置：

{
  "tool": "modify_simulation_control",
  "arguments": {
    "idf_path": "sample_files/1ZoneUncontrolled.idf",
    "field_updates": {
      "Run_Simulation_for_Weather_File_Run_Periods": "Yes",
      "Do_Zone_Sizing_Calculation": "Yes"
    },
    "output_path": "outputs/modified_model.idf"
  }
}

列出模型中的区域：

{
  "tool": "list_zones",
  "arguments": {
    "idf_path": "sample_files/5ZoneAirCooled.idf"
  }
}

检查模型中的时间表：

{
  "tool": "inspect_schedules",
  "arguments": {
    "idf_path": "sample_files/5ZoneAirCooled.idf",
    "include_values": true
  }
}

修改渗透率：

{
  "tool": "change_infiltration_by_mult",
  "arguments": {
    "idf_path": "sample_files/1ZoneUncontrolled.idf",
    "mult": 0.5,
    "output_path": "outputs/reduced_infiltration.idf"
  }
}

向外部表面添加窗户膜：

{
  "tool": "add_window_film_outside",
  "arguments": {
    "idf_path": "sample_files/5ZoneAirCooled.idf",
    "u_value": 3.5,
    "shgc": 0.35,
    "visible_transmittance": 0.60,
    "output_path": "outputs/with_window_film.idf"
  }
}

向外部表面添加涂层：

{
  "tool": "add_coating_outside",
  "arguments": {
    "idf_path": "sample_files/1ZoneUncontrolled.idf",
    "location": "Wall",
    "solar_abs": 0.3,
    "thermal_abs": 0.8,
    "output_path": "outputs/with_coating.idf"
  }
}

获取可用的示例文件：

{
  "tool": "list_sample_files",
  "arguments": {}
}

获取已配置的输出变量：

{
  "tool": "get_output_variables",
  "arguments": {
    "idf_path": "sample_files/5ZoneAirCooled.idf"
  }
}

发现所有可用的输出变量：

{
  "tool": "get_output_variables",
  "arguments": {
    "idf_path": "sample_files/5ZoneAirCooled.idf",
    "discover_available": true,
    "run_days": 1
  }
}

获取已配置的输出计量器：

{
  "tool": "get_output_meters",
  "arguments": {
    "idf_path": "sample_files/5ZoneAirCooled.idf"
  }
}

发现所有可用的输出计量器：

{
  "tool": "get_output_meters",
  "arguments": {
    "idf_path": "sample_files/5ZoneAirCooled.idf",
    "discover_available": true,
    "run_days": 1
  }
}

发现暖通空调循环：

{
  "tool": "discover_hvac_loops",
  "arguments": {
    "idf_path": "sample_files/5ZoneAirCooled.idf"
  }
}

可视化暖通空调循环图：

{
  "tool": "visualize_loop_diagram",
  "arguments": {
    "idf_path": "sample_files/5ZoneAirCooled.idf",
    "loop_name": "Hot Water Loop",
    "output_path": "outputs/hvac_diagram.png",
    "format": "png"
  }
}

运行EnergyPlus模拟：

{
  "tool": "run_energyplus_simulation",
  "arguments": {
    "idf_path": "sample_files/1ZoneUncontrolled.idf",
    "weather_file": "sample_files/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw",
    "annual": true,
    "readvars": true
  }
}

从模拟结果生成交互式图表：

{
  "tool": "create_interactive_plot",
  "arguments": {
    "output_directory": "outputs/1ZoneUncontrolled",
    "file_type": "auto",
    "custom_title": "区域温度分析"
  }
}

获取服务器日志以供调试：

{
  "tool": "get_server_logs",
  "arguments": {
    "lines": 100
  }
}

4. 暖通空调系统分析与可视化

服务器提供了高级的暖通空调系统分析能力，包括拓扑检测和可视化图生成：

暖通空调分析功能：

循环发现：自动发现所有暖通空调循环（植物、冷凝器、空气循环）
拓扑映射：提取详细的组件级别拓扑，包括供应/需求侧分析
组件检测：识别风扇、线圈、泵、空气终端、区域设备和连接
可视化图：生成PNG/SVG格式的暖通空调系统流路径和连接图
节点追踪：