brick-bacnet-mcp

brick-bacnet-mcp

一个只读 BACnet/IP 网关，通过 MCP 向大模型 Agent 暴露楼宇自动化点位数据库，并在数据接入时添加 Brick + Project Haystack 语义标签。

为什么要做这个项目

本项目源自这篇研究文章：https://habchy.dev/research/bacnet-msi-semantic-gap。同一文章的另一个版本也将在 AutomatedBuildings.com 上发布（AB.com 版本上线后会添加链接）。

简而言之：供应商的 Agent 平台（JCI OpenBlue、Honeywell Forge、Siemens Building X、Tridium Niagara 5）将其语义 AI 层保留在自家的控制产品组合中。独立的 MSI 运营着 5-50 栋楼宇的混合品牌楼宇组合，拥有 BACnet 点位数据库，却没有简单的方法以带语义标签的形式将其暴露给外部大模型 Agent。这个网关是弥补这一缺口的一种方案。

ezhuk/bacnet-mcp 可在 BACnet 协议层进行读写，但不做语义规范化。本项目与之配合：在数据接入时增加 Brick + Haystack 标记步骤，并将 v0.1 限定为只读，以缩小合规范围。

功能（v0.1）

• 在本地广播域中发现 BACnet/IP 设备（Who-Is、I-Am）
• 枚举每台设备的对象（AI、AO、AV、BI、BO、BV、MSI、MSO、MSV、Schedule、Calendar）
• 读取每个对象的 present-value、units 和 description
• 使用基于规则的映射为每个对象添加 Brick 类和 Haystack 标签集（可通过 YAML 扩展规则）
• 通过四个工具向任意 MCP 宿主暴露带标签的拓扑：list_devices、list_objects、get_object_value、get_tagged_topology

不包含的功能（v0.1）

• 不支持写入。出于研究文章中所述的合规范围考虑，v0.1 特意不支持 WriteProperty。
• 不集成 Niagara 站点。Fox 协议 / Niagara 模块封装是独立的设计。
• 不是 FDD 或分析平台。带标签的拓扑旨在供下游 FDD 或大模型 Agent 工作流使用。本网关仅负责数据接入。
• 不是 UI。输出仅通过 MCP 提供。请搭配 Claude Desktop、Cursor 或其他 MCP 宿主使用。
• 不支持 BACnet/SC。v0.1 仅支持 BACnet/IP。Secure Connect 将在 v0.2 中考虑。
• 不具备 223P 完整架构的兼容性。v0.1 使用简化的 Brick + Haystack 映射。完整的 223P 实体模型是 v0.2 的候选功能。
• 不支持多站点联邦。v0.1 一次处理一个广播域。
• 未经过身份验证。v0.1 在可信的本地网络环境中运行。

安装

pip install brick-bacnet-mcp

或从源代码安装：

git clone https://github.com/Yveshby27/brick-bacnet-mcp
cd brick-bacnet-mcp
pip install -e .

需要 Python 3.11 或更高版本。

快速开始

创建配置文件 config.yaml：

bacnet:
  local_device_instance: 555001
  broadcast_address: 192.168.1.255
  polling_interval_seconds: 30
rules:
  brick: src/brick_bacnet_mcp/rules/brick_rules.yaml
  haystack: src/brick_bacnet_mcp/rules/haystack_rules.yaml
mcp:
  transport: stdio  # or "http" for a hosted MCP host
  http_port: 8080   # only if transport == http
log_level: INFO

运行 MCP 服务：

brick-bacnet-mcp --config config.yaml

或将其接入 Claude Desktop：

{
  "mcpServers": {
    "brick-bacnet": {
      "command": "brick-bacnet-mcp",
      "args": ["--config", "/path/to/config.yaml"]
    }
  }
}

交互示例

服务运行且模拟器已启动（或可访问真实 BACnet/IP 网络）时，支持 MCP 的大模型可以执行：

用户：列出楼宇中的所有空气处理机组。

Agent（通过 MCP 工具）：调用 get_tagged_topology(filter="brick:AHU")

Agent 回复：找到 3 台 AHU。AHU-1 有 5 个子点（discharge_air_temp、return_air_temp、supply_fan_status、mixed_air_damper_position、outside_air_temp）。AHU-2……AHU-3……

完整的可运行脚本请参阅 examples/。

检查楼宇的覆盖率

入门规则库针对常见的美式对象名称约定（OAT、DAT、ZNT、CHWS、AHU-1 等）。实际使用中，混合多家供应商的设备组合会采用千差万别的命名方式。在判断工具是否正常工作之前，请先运行：

brick-bacnet-mcp --coverage-report --config config.yaml

这会针对你的网络执行一次发现 + 枚举 + 标记流程，并输出：

• 发现的对象总数
• Brick / Haystack 匹配百分比
• 最常见的 20 个未匹配对象名称（使用 --top-unmatched N 可更改数量）
• 最热门的 10 条规则

使用未匹配列表扩展 YAML 规则文件，以适配你的命名约定。对于尚未校准的设备组合，首次运行的匹配率达到 30-50% 属于正常情况；在依赖已标记拓扑进行大模型查询之前，匹配率应达到 70% 以上。

标记工作原理

标记器应用 YAML 定义的规则，将 BACnet 对象名称和单位映射到 Brick 类和 Haystack 标签集。默认规则集涵盖约 50 种常见的 HVAC、照明和计量对象名称模式。用户可在本地编辑 src/brick_bacnet_mcp/rules/brick_rules.yaml 和 haystack_rules.yaml 来覆盖或扩展规则。

Brick 规则示例：

- pattern: '(?i)^(oat|outside_air_temp|outsideair)$'
  units: ['degF', 'degC', '°F', '°C']
  brick_class: 'Outside_Air_Temperature_Sensor'

规则语法和覆盖约定请参阅 docs/RULES.md。

架构

请参阅 docs/ARCHITECTURE.md。简而言之：

• discovery.py 运行 Who-Is 广播，捕获 I-Am 响应，并缓存设备元数据
• reader.py 枚举每台设备的对象列表，并按配置的间隔轮询 present-value
• tagger.py 将 Brick + Haystack 规则应用于每个已枚举对象
• topology.py 将已标记对象组装成可查询的图
• server.py 通过 stdio 或可流式传输的 HTTP 暴露四个 MCP 工具

路线图

v0.1 是一个研究工具。下方路线图列出研究文章指出的后续工作，前提是 v0.1 获得足够持续使用的信号，足以证明继续扩展是合理的。获得信号之前，这些工作都尚未承诺。

• v0.2：支持 COV 订阅、BACnet/SC、完整的 223P 架构 parity、SkySpark / FIN Haystack-store 直通
• v0.3+：仅在明确选择启用后提供可选写入路径、多站点联邦、面向非本地部署的身份验证层

致谢

• ezhuk/bacnet-mcp：提供了本项目在其基础上进一步构建的 MCP + BACnet 集成先例
• bacpypes3：提供 BACnet 协议库
• Project Haystack：提供 Haystack 标记词汇和社区
• Brick consortium：提供 Brick 架构
• 本研究所借鉴其已发表观点的 MSI 相关人士：Brian Turner（Adaptive Buildings）、Marc Petock（Lynxspring）、Tom Shircliff 和 Rob Murchison（Intelligent Buildings LLC）、Jim Meacham（Altura Associates）、Therese Sullivan（BuildingContext）、Alper Üzmezler（BASSG）

许可证

MIT。请参阅 LICENSE。

贡献

请参阅 CONTRIBUTING.md。欢迎提交 PR，扩展规则库、完善文档、添加示例和测试覆盖。较大的改动（写入路径、支持非 BACnet 协议、UI、FDD 逻辑）不在 v0.1 范围内。提交 PR 前，请先创建 issue 讨论。