内容
# UBEM-MCP
基于 EnergyPlus 的**城市建筑能耗建模(UBEM)**的模型上下文协议(MCP)服务器。 它提供了 **41 种工具**,用于加载、验证、修改、分析和模拟 EnergyPlus 建筑能耗模型 — 包括 **批量模拟整个建筑组合**,这是单模型 EnergyPlus 服务器的核心附加功能。
> **版本**: 0.1.0
> **EnergyPlus 兼容性**: 26.1.0(默认;参见 [针对不同 EnergyPlus 版本进行构建](#building-against-a-different-energyplus-version))
> **Python**: 3.10+
本项目源自 [EnergyPlus-MCP](https://github.com/LBNL-ETA/EnergyPlus-MCP)(LBNL)— 参见 [NOTICE.md](NOTICE.md) 以获取相关致谢和原始作品的引用信息。
<details open>
<summary><h2>📑 目录</h2></summary>
- [概述](#overview)
- [安装](#installation)
- [使用 MCP 服务器](#using-the-mcp-server)
- [Claude Desktop](#claude-desktop)
- [VS Code](#vs-code)
- [Cursor](#cursor)
- [开发设置](#development-setup)
- [VS Code 开发容器](#vs-code-dev-container)
- [Docker 设置](#docker-setup)
- [本地开发](#local-development)
- [可流式 HTTP 传输(本地测试)](#streamable-http-transport-local-testing)
- [针对不同 EnergyPlus 版本进行构建](#building-against-a-different-energyplus-version)
- [可用工具](#available-tools)
- [使用示例](#usage-examples)
- [批量模拟](#batch-simulation)
- [架构](#architecture)
- [配置](#configuration)
- [故障排除](#troubleshooting)
- [贡献](#contributing)
- [引用此作品](#cite-this-work)
- [许可证](#license)
</details>
## 概述
UBEM-MCP 通过模型上下文协议,使单个建筑或整个建筑组合的 EnergyPlus 建筑能耗模拟可被 AI 助手和自动化工具访问。
**关键功能:**
- 🏙️ **批量 / 投资组合模拟**:并发运行多个 EnergyPlus 模型作为后台作业;轮询状态和结果而不是阻塞单个长时间运行的调用
- 🏗️ **完整的模型生命周期**:加载、验证、分析、修改和模拟 IDF 文件
- 🔍 **深入的建筑分析**:提取有关区域、表面、材料和时间表的详细信息
- 🔧 **暖通空调智能**:发现、分析和可视化暖通空调系统拓扑
- 📈 **智能输出管理**:自动发现和配置输出变量/仪表
- 📊 **高级可视化**:创建交互式图表和暖通空调系统图
## 安装
### 使用 MCP 服务器
**先决条件(所有客户端):**
- [Docker Desktop](https://www.docker.com/products/docker-desktop/)(macOS / Windows)或 Docker 引擎(Linux),正在运行
- `git` 在您的 PATH 上
- 本地构建的 `ubem-mcp-dev` 镜像(以下步骤 1 — 执行此操作一次)
选择适合您的 AI 助手或 IDE 的设置:
#### Claude Desktop
1. **构建 Docker 镜像**(一次性设置):
```bash
git clone https://github.com/TensorBuildLab/UBEM-MCP.git
cd UBEM-MCP
docker build -t ubem-mcp-dev -f .devcontainer/Dockerfile .devcontainer
```
2. **找到 Claude Desktop 配置文件**,适用于您的操作系统:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: Claude Desktop 在 Linux 上不受官方支持。如果您使用社区构建,请查看其文档以获取配置路径(通常为 `~/.config/Claude/claude_desktop_config.json`)。
创建文件如果它不存在,然后添加:
```json
{
"mcpServers": {
"ubem": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-v", "/path/to/UBEM-MCP:/workspace",
"-w", "/workspace/ubem-mcp-server",
"ubem-mcp-dev",
"uv", "run", "python", "-m", "ubem_mcp_server.server"
]
}
}
}
```
**重要提示**:
- 将 `/path/to/UBEM-MCP` 替换为克隆存储库的绝对路径。
- macOS/Linux 示例:`/Users/yourname/code/UBEM-MCP`
- Windows 示例:`C:\\Users\\yourname\\code\\UBEM-MCP`(在 JSON 中使用双反斜杠)
- 添加到实际配置文件时删除所有注释(// 后的文本),因为 JSON 不支持注释。
3. **重启 Claude Desktop**。`ubem` MCP 服务器应该出现在 MCP 服务器面板中。
4. **验证**:在新的聊天中,询问 *"列出您有权访问的 UBEM-MCP 工具。"* 您应该看到 `load_idf_model`、`run_batch_simulation`、`get_server_status` 等工具。如果没有,请查看 [故障排除](#troubleshooting)。
#### VS Code
VS Code 1.102+ 自带原生 MCP 支持。配置位于工作区根目录的 `.vscode/mcp.json`(或在用户设置下的 `"mcp"`)。
1. **构建 Docker 镜像**(与 Claude Desktop 步骤 1 相同)。
2. **创建 `.vscode/mcp.json`** 在您的项目中:
```json
{
"servers": {
"ubem": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-v", "${workspaceFolder}:/workspace",
"-w", "/workspace/ubem-mcp-server",
"ubem-mcp-dev",
"uv", "run", "python", "-m", "ubem_mcp_server.server"
]
}
}
}
```
**重要提示**:保存时删除所有注释(// 后的文本)- JSON 不支持注释。
3. **重新加载 VS Code**(`Ctrl/Cmd+Shift+P` → *Developer: Reload Window*)。打开聊天视图并确认 `ubem` MCP 服务器显示为 *Running*。
4. **验证**:询问聊天 *"有哪些 UBEM-MCP 工具可用?"* — 您应该看到工具列表。
#### Cursor
1. **构建 Docker 镜像**(与 Claude Desktop 步骤 1 相同)。
2. **找到 Cursor MCP 配置文件**,适用于您的操作系统:
- **macOS/Linux**: `~/.cursor/mcp.json`
- **Windows**: `%USERPROFILE%\.cursor\mcp.json`
创建文件如果它不存在,然后添加:
```json
{
"mcpServers": {
"ubem": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-v", "/path/to/UBEM-MCP:/workspace",
"-w", "/workspace/ubem-mcp-server",
"ubem-mcp-dev",
"uv", "run", "python", "-m", "ubem_mcp_server.server"
]
}
}
}
```
**重要提示**:
- 将 `/path/to/UBEM-MCP` 替换为克隆存储库的绝对路径(Windows 用户:在 JSON 中使用双反斜杠,例如 `C:\\Users\\yourname\\code\\UBEM-MCP`)。
- 保存时删除所有注释(// 后的文本)- JSON 不支持注释。
3. **重启 Cursor**。打开 *Settings → MCP* 并确认 `ubem` 服务器已连接。
4. **验证**:询问 Cursor 聊天 *"有哪些 UBEM-MCP 工具可用?"* — 您应该看到工具列表。
### 开发设置
对于希望修改或扩展 MCP 服务器的贡献者:
#### VS Code 开发容器
最简单的开发设置,所有依赖项都已预先配置。
**先决条件:**
- [Visual Studio Code](https://code.visualstudio.com/)
- [Docker Desktop](https://www.docker.com/products/docker-desktop/)
- [Dev Containers 扩展](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
**步骤:**
1. 克隆并在 VS Code 中打开:
```bash
git clone https://github.com/TensorBuildLab/UBEM-MCP.git
cd UBEM-MCP
code .
```
2. 出现提示时点击“在容器中重新打开”(或按 `Ctrl+Shift+P` → “Dev Containers: Reopen in Container”)
3. 容器会自动安装 EnergyPlus 26.1.0 和所有依赖项(要固定其他版本,请参见 [针对不同 EnergyPlus 版本进行构建](#building-against-a-different-energyplus-version))
#### Docker 设置
适用于直接 Docker 开发,无需 VS Code:
```bash
# 克隆存储库
git clone https://github.com/TensorBuildLab/UBEM-MCP.git
cd UBEM-MCP
# 构建容器
docker build -t ubem-mcp-dev -f .devcontainer/Dockerfile .devcontainer
# 运行容器
docker run -it --rm -v "$(pwd)":/workspace -w /workspace/ubem-mcp-server ubem-mcp-dev bash
# 在容器中,安装依赖项
uv sync --extra dev
```
#### 本地开发
适用于本地开发(需要 EnergyPlus 安装):
**先决条件:**
- Python 3.10+
- [uv 包管理器](https://github.com/astral-sh/uv)
- [EnergyPlus 26.1.0](https://github.com/NREL/EnergyPlus/releases/tag/v26.1.0)(或固定其他版本 — 参见 [针对不同 EnergyPlus 版本进行构建](#building-against-a-different-energyplus-version))
```bash
# 克隆并安装
git clone https://github.com/TensorBuildLab/UBEM-MCP.git
cd UBEM-MCP/ubem-mcp-server
uv sync --extra dev
# 运行服务器进行测试
uv run python -m ubem_mcp_server.server
```
#### 流式 HTTP 传输(本地测试)
默认情况下,服务器运行在 **stdio** 上,这是本 README 中所有 MCP 客户端配置使用的内容。服务器也可以作为基于令牌验证的 **流式 HTTP** 服务运行 — 可用于测试远程样式部署、用 `curl` 进行烟雾测试,或连接期望 HTTP MCP 端点的客户端。
**先决条件 — 选择一种路径:**
- **Docker(推荐;无需本地 EnergyPlus 安装)**:构建 `ubem-mcp-dev` 镜像一次(按上面的 [Docker 设置](#docker-setup))。镜像中预安装了 EnergyPlus 26.1.0 和所有 Python 依赖项。
- **本地开发**:按照上面的 [本地开发](#local-development) 进行 — Python 3.10+、`uv` 和本地 EnergyPlus 安装。HTTP 模式会引入 `uvicorn` 和 `python-dotenv`,它们在 `pyproject.toml` 中声明 — `uv sync --extra dev` 将安装它们。
**1. 生成一个 bearer 令牌。** 令牌必须至少有 32 个字符:
```bash
openssl rand -hex 32
```
**2. 在 `ubem-mcp-server/` 中创建 `.env`(已忽略 git)。** 从 [.env.example](ubem-mcp-server/.env.example) 复制并填写您的值:
```bash
# EPLUS_IDD_PATH — 仅在本地变体中设置此项。
# 如果使用 Docker 变体,请注释掉/取消设置;镜像中有 EnergyPlus 26.1.0 内置并自动检测。
# EPLUS_IDD_PATH=/Applications/EnergyPlus-26-1-0/Energy+.idd
MCP_TRANSPORT=streamable-http
MCP_HTTP_HOST=0.0.0.0
MCP_HTTP_PORT=8000
MCP_HTTP_PATH=/mcp
# JSON 数组。MCP_TRANSPORT=streamable-http 时需要。
MCP_TOKENS=[{"label":"local-dev","token":"<在此处粘贴 32+ 个字符的十六进制>"}]
```
**3. 启动服务器。** 选择与您的设置匹配的变体:
*Docker(推荐):* 发布端口,挂载存储库,让容器通过 `--env-file` 拾取 `.env`。从 **存储库根目录** 运行:
```bash
docker run --rm \
-p 8000:8000 \
-v "$(pwd)":/workspace \
-w /workspace/ubem-mcp-server \
--env-file ubem-mcp-server/.env \
ubem-mcp-dev \
uv run python -m ubem_mcp_server.server
```
*本地:* (需要与 `.env` 中设置的 `EPLUS_IDD_PATH` 匹配的主机 EnergyPlus 安装)
```bash
cd ubem-mcp-server
uv run python -m ubem_mcp_server.server
```
无论哪种方式,您都应该会看到类似 `Listening on http://0.0.0.0:8000 (path=/mcp, 1 tokens)` 的日志行。
**4. 使用 curl 进行烟雾测试。** 服务器暴露了两个端点:
```bash
# 健康检查 — 不需要身份验证
curl -s http://localhost:8000/health
# 未身份验证的 MCP 请求 — 应该返回 401
curl -i -X POST http://localhost:8000/mcp
# 身份验证初始化握手
TOKEN=<粘贴您的令牌>
curl -i -X POST http://localhost:8000/mcp \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'
```
**5. 连接 MCP Inspector。** 运行 Inspector 并将其指向 `http://localhost:8000/mcp`,使用流式 HTTP 传输和 `Authorization: Bearer <your-token>` 头。
**测试** — 传输和身份验证行为由 `tests/test_config_transport.py` 和 `tests/test_auth.py` 覆盖;批量编排由 `tests/test_batch_manager.py` 覆盖。运行:
```bash
uv run pytest tests/
```
#### 构建针对不同 EnergyPlus 版本
Docker 镜像默认内置 EnergyPlus **26.1.0**。要固定其他版本,请在构建镜像时覆盖以下构建参数。您需要:
- `EPLUS_VER`:发布版本,例如 `25.1.0`
- `EPLUS_HASH`:NREL 在发布 tarball 文件名中嵌入的短提交字符串
- `EPLUS_PREFIX`:容器内的安装路径,例如 `/app/software/EnergyPlusV25-1-0`
- `EPLUS_DIST_SUFFIX`:`Ubuntu22.04` 用于 EnergyPlus ≤ 25.1.0,`Ubuntu24.04` 用于 ≥ 26.1.0
```bash
docker build \
--build-arg EPLUS_VER=25.1.0 \
--build-arg EPLUS_HASH=68a4a7c774 \
--build-arg EPLUS_PREFIX=/app/software/EnergyPlusV25-1-0 \
--build-arg EPLUS_DIST_SUFFIX=Ubuntu22.04 \
-t ubem-mcp-dev \
-f .devcontainer/Dockerfile .devcontainer
```
**注意 — 另外三个地方引用了安装路径**(`/app/software/EnergyPlusV26-1-0`)并且不读取 Dockerfile ARG,因此如果您覆盖 `EPLUS_PREFIX`,还需要更新:
- `ubem-mcp-server/ubem_mcp_server/config.py` — `version` 和 `default_installation`
- `ubem-mcp-server/.vscode/mcp.json` — 两个 `EnergyPlusV26-1-0` 字符串
- 您为 Claude Desktop / VS Code / Cursor 创建的客户端配置 JSON — 仅当它显式设置 `EPLUS_IDD_PATH` 时
## 可用工具
服务器提供 **41 种工具**,组织成 **6 类别**:
### 🏙️ 批量模拟(6 种工具)— UBEM-MCP 中的新增功能
- `discover_idf_files` - 浏览目录以查找 IDF 文件以构建批次的模型列表
- `run_batch_simulation` - 并发运行多个 EnergyPlus 模型作为后台作业;立即返回 `batch_id`
- `get_batch_status` - 轮询批次作业的整体/状态进度
- `get_batch_results` - 获取每个模型的运行结果(成功/失败、持续时间、输出路径)
- `list_batches` - 列出所有已知的批次作业(内存 + 持久化存储在磁盘上)
- `cancel_batch` - 取消批次作业(对已经运行的模型进行尽力而为)
### 🗂️ 模型配置和加载(9 种工具)
- `load_idf_model` - 加载和验证 IDF 文件
- `validate_idf` - 全面的模型验证
- `list_available_files` - 浏览示例文件和天气数据
- `copy_file` - 智能文件复制,具有路径解析功能
- `get_model_summary` - 提取基本模型信息
- `check_simulation_settings` - 审查模拟控制设置
- `modify_simulation_control` - 修改模拟参数
- `modify_run_period` - 调整模拟时间段
- `get_server_configuration` - 获取服务器配置信息
### 🔍 模型检查(9 种工具)
- `list_zones` - 列出具有属性的所有热区
- `get_surfaces` - 获取建筑表面信息
- `get_materials` - 提取材料定义
- `inspect_schedules` - 分析所有时间表对象
- `inspect_people` - 分析占用设置
- `inspect_lights` - 分析照明负载
- `inspect_electric_equipment` - 分析设备负载
- `get_output_variables` - 获取/发现输出变量
- `get_output_meters` - 获取/发现能源表
### ⚙️ 模型修改(8 种工具)
- `modify_people` - 更新占用设置
- `modify_lights` - 更新照明负载
- `modify_electric_equipment` - 更新设备负载
- `change_infiltration_by_mult` - 修改渗透率
- `add_window_film_outside` - 添加外部窗膜
- `add_coating_outside` - 应用表面涂层
- `add_output_variables` - 添加输出变量
- `add_output_meters` - 添加能源表
### 🚀 模拟和结果(4 种工具)
- `run_energyplus_simulation` - 执行单个模拟
- `create_interactive_plot` - 生成 HTML 可视化
- `discover_hvac_loops` - 查找所有 HVAC 环路
- `get_loop_topology` - 获取 HVAC 环路详细信息
### 🖥️ 服务器管理(5 种工具)
- `visualize_loop_diagram` - 生成 HVAC 图表
- `get_server_status` - 检查服务器状态
- `get_server_logs` - 查看最近的日志
- `get_error_logs` - 获取错误日志
- `clear_logs` - 清除/旋转日志文件
## 使用示例
### 基本工作流程
1. **加载模型**:
```json
{
"tool": "load_idf_model",
"arguments": {
"idf_path": "sample_files/1ZoneUncontrolled.idf"
}
}
```
2. **检查区域**:
```json
{
"tool": "list_zones",
"arguments": {
"idf_path": "sample_files/1ZoneUncontrolled.idf"
}
}
```
3. **运行单个模拟**:
```json
{
"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
}
}
```
### 与 MCP Inspector 一起使用
在 Node.js 18+ 上测试工具(需要 Node.js 18+):
```bash
# 从存储库根目录运行服务器,在检查器内使用 dev 镜像
npx @modelcontextprotocol/inspector \
docker run --rm -i \
-v "$(pwd):/workspace" \
-w /workspace/ubem-mcp-server \
ubem-mcp-dev \
uv run python -m ubem_mcp_server.server
```
## 批量模拟
这是与单模型 EnergyPlus MCP 服务器的关键区别:**运行整个建筑组合并查询结果**,而不是每个建筑的阻塞调用。
**为什么是轮询,而不是单个阻塞调用:** eppy's `IDF` 类持有模块级全局状态,因此并发模拟作为单独的工作进程运行,而不是进程内线程。 而且许多建筑的组合可能需要数分钟到数小时 —— 这远远超过了 MCP 客户端应该阻塞单个工具调用的时间。`run_batch_simulation` 立即返回一个 `batch_id`;您轮询 `get_batch_status` / `get_batch_results` 直到完成。
1. **在目录中发现模型:**
```json
{"tool": "discover_idf_files", "arguments": {"directory": "sample_files", "pattern": "*.idf"}}
```
2. **提交批次:**
```json
{
"tool": "run_batch_simulation",
"arguments": {
"models": ["sample_files/1ZoneUncontrolled.idf", "sample_files/1ZoneEvapCooler.idf"],
"weather_file": "sample_files/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw",
"continue_on_error": true
}
}
```
返回 `{"batch_id": "...", "status": "queued", ...}`.
3. **查询状态:**
```json
{"tool": "get_batch_status", "arguments": {"batch_id": "<batch_id>"}}
```
重复直到 `"is_complete": true`.
4. **获取每个模型的结果:**
```json
{"tool": "get_batch_results", "arguments": {"batch_id": "<batch_id>"}}
```
支持通过传递字典而不是普通路径字符串来重写每个模型:
```json
{
"tool": "run_batch_simulation",
"arguments": {
"models": [
{"idf_path": "bldg_001.idf", "label": "office_a"},
{"idf_path": "bldg_002.idf", "weather_file": "chicago.epw", "label": "office_b"}
],
"continue_on_error": false
}
}
```
如果 `continue_on_error` 为 `false`,则第一个模型的失败会取消批次中尚未启动的剩余模型(尽力而为 - 已经在工作进程中运行的 EnergyPlus 子进程无法被强制终止)。
## 架构
服务器遵循分层架构:
```
┌─────────────────────────┐
│ MCP 协议层 │ FastMCP 服务器处理客户端通信
├─────────────────────────┤
│ 工具层 │ 41 个工具,分为 6 类
├─────────────────────────┤
│ 业务流程层 │ EnergyPlus 管理器、批次管理器和配置模块
├─────────────────────────┤
│ EnergyPlus 集成 │ 直接接口到仿真引擎(每个模型,并发批次模型时每个模型一个工作进程)
└─────────────────────────┘
```
**项目结构:**
```
ubem-mcp-server/
├── ubem_mcp_server/
│ ├── server.py # FastMCP 服务器,含工具
│ ├── energyplus_tools.py # EnergyPlus 核心集成(单模型)
│ ├── batch_manager.py # 批次/投资组合业务流程(UBEM-MCP 新增)
│ ├── config.py # 配置管理
│ └── utils/ # 专用工具
├── sample_files/ # 示例 IDF 和天气文件
├── tests/ # 单元测试
└── pyproject.toml # 依赖项
```
## 配置
服务器自动检测 EnergyPlus 安装并使用合理的默认值。 可以通过环境变量自定义配置:
- `EPLUS_IDD_PATH`: EnergyPlus IDD 文件路径
- `EPLUS_SAMPLE_PATH`: 自定义示例文件目录
- `EPLUS_OUTPUT_PATH`: 结果输出目录
- `UBEM_BATCH_MAX_WORKERS`: 批次作业的最大并发模拟进程数(默认值:CPU 数量)
- `MCP_TRANSPORT`、`MCP_HTTP_HOST`、`MCP_HTTP_PORT`、`MCP_HTTP_PATH`、`MCP_TOKENS`: 流式 HTTP 传输设置(参见 [流式 HTTP 传输(本地测试)](#流式-http-传输-本地测试))
## 故障排除
**常见问题:**
1. **"未找到 IDD 文件"**:确保已安装 EnergyPlus
2. **"未找到模块"**:运行 `uv sync` 安装依赖项
3. **"权限被拒绝"**:检查文件权限
4. **"模拟失败"**:在模型的输出目录中检查 EnergyPlus 错误消息
5. **批次卡在 `"is_complete": false` 处**:检查 `get_batch_status` 的每个状态计数 - 非常大的批次且 `max_workers` 值较低时,可能会花费更长时间;检查 `get_server_logs` 中的单个模型错误
**调试:**
- 检查服务器状态:`get_server_status`
- 查看日志:`get_server_logs`
- 检查错误:`get_error_logs`
- 检查批次作业:`get_batch_status` / `get_batch_results`
## 贡献
1. 复刻仓库
2. 创建功能分支
3. 进行更改并添加测试
4. 运行检查:
```bash
uv run ruff check
uv run black .
uv run pytest
```
5. 提交拉取请求
## 引用此作品
UBEM-MCP 建立在 EnergyPlus-MCP 基础上。 如果您在研究中使用 UBEM-MCP,请引用原始的 EnergyPlus-MCP 论文 - 有关完整的引用和 BibTeX 条目,请参见 [NOTICE.md](NOTICE.md)。
## 许可证
该仓库同时使用两个 BSD-3-Clause 许可证:
- [LICENSE](LICENSE)(TensorBuildLab)涵盖 UBEM-MCP 的原始代码,包括批次模拟功能。
- [License.txt](License.txt) / [Copyright.txt](Copyright.txt)(LBNL)涵盖从 EnergyPlus-MCP 继承的代码。
有关每个许可证涵盖哪些文件以及该项目与 EnergyPlus-MCP 之间的关系的详细信息,请参见 [NOTICE.md](NOTICE.md)。
**政府权利声明:** 本软件的 EnergyPlus-MCP 部分是在美国能源部资助下开发的,因此美国政府保留 [License.txt](License.txt) 中描述的某些权利。
MCP 配置
以下是此 MCP Server 的配置信息,可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器