建筑能耗模型管理工具

Honeybee-MCP

Bridge LLMs with the Ladybug Tools / Honeybee building-energy-modeling ecosystem via MCP.

中文文档 · GitHub · GPL-3.0

什么是蜜蜂MCP？

蜜蜂MCP是一种 模型上下文协议（MCP）服务器 建立在 FastMCP。它暴露了 瓢虫工具/蜜蜂 生态系统作为结构化工具调用，允许任何兼容MCP的IDE（游标、VS代码+副本、OpenCode等）中的AI代理 理解、查询和操作蜜蜂建筑能源模型 通过自然语言。

简而言之：你用简单的英语描述你想要什么，人工智能代理会为你驱动蜜蜂。

工具套件

蜜蜂MCP目前提供 27个MCP工具 分为以下模块。每个模块都被设计成一个“总线”——一个统一的入口点，在幕后调度到专门的服务功能。

型号I/O

load_model 和 save_model 处理蜜蜂模型的生命周期。

• 加载中 支持三个来源：本地HBJSON/HBpkl文件、Grasshopper共享内存模型和内存字典。当没有指定文件时，服务器会首先自动扫描Grasshopper模型。
• 储蓄 将当前内存中的模型导出到HBJSON文件，并可选择漂亮的打印缩进和属性过滤（例如仅能量或仅辐射导出）。

查询

query 是统一的读取接口。它接受a target_type （例如。 room, face, aperture, schedule, modifier, sensor_grid)并返回所请求的 fields 对于所有匹配的对象。

典型用例：

• 列出所有房间及其建筑面积
• 检查特定面上的边界条件和孔径比
• 检查当前定义了哪些能量计划或辐射修改器
• 计数对象而不获取完整数据(output_mode="count")

添加

add 在模型中创建新的子对象或资源。每 add 调用指定 operation 选择具体创建逻辑的字符串：

应用

apply 为现有对象分配属性和资源。这是附加房间程序、暖通空调系统、结构和负荷定义的地方：

移除

remove 删除具有引用完整性检查的对象。例如，删除仍被面引用的辐射修改器将返回 blocked 响应，而不是默默地破坏模型。

支持的操作： all_apertures, all_doors, all_shades, face_objects, room_shades, schedule, modifier, sensor_grid, view以及更多。

库搜索

search_properties 在蜜蜂标准库（ASHRAE、NECB等）中搜索预定义的构造、构造集、程序类型和修改器集。结果可以按年份、气候带、建筑类型和建筑方案进行过滤。

可视化

visualization 将模型或选定对象导出为VisualizationSet和可选文件（VTK、SVG）。支持自定义显示选项、SVG渲染和将文件导出到指定文件夹。

蚱蜢同步

一套共享内存工具，用于与Rhino/Grashopper进行实时双向通信：

• load_model_from_shared_memory --阅读Grasshopper通过HB MCP Writer编写的模型。
• save_model_to_shared_memory --将AI编辑的模型推回，以便Grasshopper通过HB MCP阅读器读取。
• check_shared_memory_status / clear_shared_memory_model --检查或重置共享内存通道。
• cleanup_shared_memory_cache --删除过时的缓存文件。

版本控制

version_control 提供内存中的撤消/重做堆栈，以及命名的快照管理：

• save / load --手动创建或还原命名快照。
• undo / redo --在编辑历史记录中后退或前进。
• compare --区分两个快照，看看发生了什么变化（添加/删除房间，修改属性）。
• info / delete / clear --检查、删除或擦除版本历史记录。

蚱蜢组件

包含两个自定义GHPython用户对象 grasshopper/:

• HB MCP编写器 --将蜜蜂模型从Grasshopper序列化到共享内存，供MCP服务器读取。
• HB MCP阅读器 --AI代理完成编辑后，从共享内存中读取模型。

安装 .ghuser 来自的文件 grasshopper/user_objects/ 放入Grasshopper用户对象文件夹（通常 %APPDATA%/Grasshopper/UserObjects/).共享内存传输使用内存映射文件，因此Grasshopper和MCP服务器必须在同一台机器上运行。

快速开始

1.克隆存储库

git clone https://github.com/LoftyTao/Honeybee-MCP.git
cd Honeybee-MCP

2.在人工智能协助下设置（推荐）

在兼容MCP的IDE（游标、VS代码、OpenCode等）中打开项目文件夹，然后简单地告诉AI：

Help me set up this project:
create a .venv, activate it, pip install -r requirements.txt,
then create the MCP config file for this IDE.

AI代理将自动处理虚拟环境创建、依赖关系安装和MCP配置。这是最快的开始方式。

3.AI Agent技能安装（更好地使用工具）

该项目包括专业“技能”（规则） agent/skills/ 指导AI代理如何更有效地使用Honeybee MCP工具的目录。

AI代理说明： 执行自动设置时，AI代理应将相关技能文档复制到用户特定AI IDE或CLI支持的相应技能目录中。标准路径请参考下表：

给代理人的示例说明：

“从以下位置复制所有技能文档 agent/skills/honeybee-mcp-use/ 并将其安装到此AI工具的自定义技能位置（例如。 .cursor/skills/)增强您的蜜蜂建模能力。"

4.手动设置（可选）

如果你更喜欢自己做：

python -m venv .venv

# Windows
.venv\Scripts\activate
# Linux / macOS
source .venv/bin/activate

pip install -r requirements.txt

然后将MCP服务器配置添加到IDE中。文件位置取决于IDE：

• 光标 -- .cursor/mcp.json
• VS Code -- .vscode/mcp.json
• 开源代码 -- .opencode/opencode.json

配置示例：

{
  "mcpServers": {
    "honeybee-mcp": {
      "command": "D:/Projects/Honeybee-MCP/.venv/Scripts/python",
      "args": ["server.py"],
      "cwd": "D:/Projects/Honeybee-MCP"
    }
  }
}

4.验证

python server.py

如果没有出现错误，则MCP服务器已准备就绪。

用法示例

以下每个示例由三个部分组成： 您的意见 （自然语言提示）， 蜜蜂MCP工具结果 （JSON在幕后返回），以及 AI响应 （代理人告诉你的）。

示例1——加载模型文件

你：

加载src\sample\Revit_sample.hbjson文件。

蜜蜂MCP返回：

{
  "success": true,
  "source": "file",
  "identifier": "Revit_Sample",
  "display_name": "Revit_Sample",
  "rooms": 15,
  "floor_area": 295.74,
  "outdoor_shades": 105,
  "orphaned_objects": 0
}

AI回应：

已成功从src\sample\Revit_sample.hbjson加载模型。

• 显示名称：Revit_Sample
• 建筑面积：295.74平方米
• 房间数量：15
• 室外遮阳帘：105
• 孤立对象：0（面、阴影、光圈、门）

示例2——查询房间并检查构造

你：

查询所有房间列表，并向我显示它们的建筑面积。还要检查气候区5有哪些可用的建筑。

蜜蜂MCP返回 （两次工具调用）：

// query -- rooms
{
  "success": true,
  "count": 15,
  "data": [
    {"identifier": "Bedroom_1_a3f2c", "display_name": "Bedroom 1", "floor_area": 18.2},
    {"identifier": "Bedroom_2_b7e1d", "display_name": "Bedroom 2", "floor_area": 15.6},
    {"identifier": "LivingRoom_1_c9a4e", "display_name": "Living Room", "floor_area": 32.1},
    ...
  ]
}

// search_properties -- opaque constructions
{
  "success": true,
  "category": "opaque_constructions",
  "results": [
    {"identifier": "Generic Exterior Wall R-19", "vintage": "2019", "climate_zone": "5"},
    {"identifier": "ASHRAE 189.1-2009 ExtWall Mass ClimateZone 5", "vintage": "2009"},
    ...
  ],
  "total": 12
}

AI回应：

该模型有15个房间。根据其显示名称，其中两间似乎是卧室：“卧室1”（18.2平方米）和“卧室2”（15.6平方米”）。其余的包括起居室、浴室和杂物间。

对于气候带5，标准库中有12个预定义的外墙结构。最常用的是“通用外墙R-19”。让我知道该申请哪一个，或者下一步该做什么。

示例3——添加具有方向比率的窗口

你：

清洁所有孔和门。 在所有卧室的垂直外墙上按比例添加窗户。四个方向（东、西、南和北）的比例分别为0.35、0.5、0.75和0.25。 关键的：仅向墙面添加窗。请勿触摸地板、屋顶或任何其他脸型。

蜜蜂MCP返回 （多个工具调用）：

// remove -- clear all apertures and doors
{"success": true, "removed_apertures": 24, "removed_doors": 6}

// add -- south-facing walls, ratio 0.75
{"success": true, "added": 3, "ratio": 0.75}

// add -- west-facing walls, ratio 0.5
{"success": true, "added": 2, "ratio": 0.5}

// add -- east-facing walls, ratio 0.35
{"success": true, "added": 2, "ratio": 0.35}

// add -- north-facing walls, ratio 0.25
{"success": true, "added": 2, "ratio": 0.25}

AI回应：

清除所有现有的孔（24）和门（6）。然后按方向在卧室外墙上添加窗户：

• 南侧：75%的窗墙比（3面）
• 西部：50%（2张脸）
• 东部：35%（2张脸）
• 北：25%（两面）

仅处理墙型面；地板、屋顶和其他面部类型被排除在外。

示例4——检查点和回滚

你：

先保存一个版本。我想尝试一些东西，可能需要撤销。

蜜蜂MCP返回：

{"success": true, "version_id": "v3", "description": "Manual save"}

AI回应：

检查点另存为版本v3。继续你的更改——你可以随时撤消回到这一点。

示例5——复杂的多步骤工作流

此示例在单个提示中演示了完整的端到端BEM工作流。AI代理会自动将其分解为连续的工具调用。

你：

加载src\sample\Revit_sample.hbjson文件。 查询所有房间列表并确定卧室。 清洁所有孔和门。 搜索可用的计划类型，并将适当的公寓计划应用于所有卧室。 在所有卧室的垂直外墙上按比例添加窗户。四个方向（东、西、南和北）的比例分别为0.35、0.5、0.75和0.25。 关键的：仅向墙面添加窗。请勿触摸地板、屋顶或任何其他脸型。 在朝南的窗户上添加百叶窗，您可以自定义属性。 在所有卧室安装PTAC系统进行供暖和制冷。 检查此模型的所有修改并生成流程报告.md。 将模型保存到项目文件夹中的“output”文件夹中，并将其命名为“demo”。

蜜蜂MCP工艺 （10+连续工具调用）：

1. load_model        --> Loaded Revit_Sample, 15 rooms, 295.74 m²
2. query (rooms)     --> Identified 2 bedrooms by display name
3. remove            --> Cleared all apertures and doors
4. search_properties --> Found matching apartment program types
5. apply (program)   --> Applied apartment program to 2 bedrooms
6. add (apertures)   --> Added directional windows (S:0.75, W:0.5, E:0.35, N:0.25)
7. add (louvers)     --> Added louver shading to south-facing windows
8. apply (hvac)      --> Applied PTAC system to 2 bedrooms
9. query (summary)   --> Collected all modification details
10. save_model       --> Saved as output/demo.hbjson

AI回应：

所有步骤均已完成。以下是流程总结：

1. 模型已加载 --Revit_Sample：15间客房，建筑面积295.74平方米。
2. 已确定的卧室 --卧室1（18.2平方米）和卧室2（15.6平方米。
3. 孔口和门已清理 --拆下24个孔和6个门。
4. 已应用程序 --“2019:：Midrise公寓：：公寓”分配给两间卧室。
5. Windows已添加 --南部75%，西部50%，东部35%，北部25%。仅处理了墙型面。
6. 百叶窗已添加 --朝南的窗户采用百叶窗遮阳（深度0.15米，每扇窗户6个百叶窗）。
7. 应用暖通空调 --PTAC（全空气类别）分配给两间卧室。
8. 模型已保存 --输出/demo.hbjson

详细的流程报告已保存到report.md。

项目结构

Honeybee-MCP/
├── server.py                    # Entry point
├── tools/
│   ├── mcp_context.py           # FastMCP instance
│   ├── load_model.py            # Model loading (file + shared memory)
│   ├── save_model.py            # Model saving (HBJSON export)
│   ├── operations/              # add / apply / query / remove buses
│   ├── library/                 # Standards library search
│   ├── visualization/           # VTK / SVG export
│   ├── sync/                    # Grasshopper shared-memory bridge
│   ├── versioning/              # Undo / redo / version snapshots
│   └── state/                   # In-memory model state manager
├── grasshopper/
│   ├── src/                     # GHPython source (Reader / Writer)
│   └── user_objects/            # Compiled .ghuser components
├── src/
│   ├── docs/                    # Tutorial slides, workflow docs
│   ├── resource/                # Images and demo assets
│   └── sample/                  # Sample HBJSON model
├── requirements.txt
└── LICENSE                      # GPL-3.0

需求

• Python 3.10+
• 核心： honeybee-core, honeybee-energy, honeybee-radiance, ladybug-core, ladybug-geometry, ladybug-vtk
• MCP运行时间： fastmcp >= 3.1.0
• 可视化： vtk >= 9.6.0

看 需求.txt 查看完整的固定依赖列表。

文档

许可证

该项目根据 GNU通用公共许可证v3.0.

联系

• 作者：陶
• 电子邮件: loftytao@foxmail.com
• GitHub: https://github.com/LoftyTao