brick-bacnet-mcp

brick-bacnet-mcp

MCP 経由でビルオートメーションのポイントデータベースを LLM エージェントに公開する、読み取り専用の BACnet/IP ゲートウェイです。取り込み時に Brick と Project Haystack のセマンティックタグを付与します。

このプロジェクトの目的

この実装のもとになった調査ノートは https://habchy.dev/research/bacnet-msi-semantic-gap にあります。同じ記事は AutomatedBuildings.com にも掲載予定です（AB.com 版の公開後にリンクを追加します）。

要するに、ベンダーのエージェント型プラットフォーム（JCI OpenBlue、Honeywell Forge、Siemens Building X、Tridium Niagara 5）は、独自の制御製品群の中にセマンティック AI レイヤーを保持しています。複数ベンダーが混在する 5～50 棟のビルを運用する独立系 MSI は、BACnet のポイントデータベースを持っているものの、セマンティックタグ付きの形式で外部 LLM エージェントに公開する手段がありません。このゲートウェイは、そのギャップを埋める方法の 1 つです。

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 で拡張できます）。
• 4 つのツール（list_devices、list_objects、get_object_value、get_tagged_topology）を通じて、タグ付けされたトポロジーをあらゆる MCP ホストに公開します。

v0.1 の対象外

• 書き込みには対応していません。調査記事で述べたコンプライアンス対象範囲の理由から、WriteProperty は意図的に v0.1 の対象外としています。
• Niagara ステーションとの統合には対応していません。Fox プロトコル／Niagara モジュールによるラッピングは別途設計します。
• FDD や分析プラットフォームではありません。タグ付けされたトポロジーは、下流の FDD や LLM エージェントのワークフローで利用することを想定しています。このゲートウェイは取り込みレイヤーのみを担います。
• 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 では一度に 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 対応の LLM は次のように実行できます。

ユーザー：建物内のすべての空調機を一覧表示してください。

エージェント（MCP ツール経由）：get_tagged_topology(filter="brick:AHU") を呼び出します。

エージェントの応答：AHU が 3 台見つかりました。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

ネットワークに対して検出、列挙、タグ付けのサイクルを1回実行し、次の情報を出力します。

• 検出されたオブジェクトの総数
• Brick／Haystack の一致率
• どのルールにも一致しなかった、出現頻度の高いオブジェクト名の上位20件（件数を変更するには --top-unmatched N を使用します）
• 最も多く一致したルールの上位10件

一致しなかった項目の一覧を使用して、命名規則に合わせて YAML ルールファイルを拡張してください。まだ調整されていないポートフォリオで、初回実行時の一致率が30～50％なのは正常です。タグ付けされたトポロジーを LLM クエリに利用する前に、70％以上を目指してください。

タグ付けの仕組み

タグ付けツールは、YAML で定義されたルールを適用し、BACnet オブジェクト名と単位を Brick クラスおよび Haystack タグセットに対応付けます。デフォルトのルールセットは、一般的な HVAC、照明、計測器のオブジェクト名パターンを約50種類カバーしています。ユーザーはローカルで 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 経由で4つの MCP ツールを公開します

ロードマップ

v0.1 は研究用のツールです。以下のロードマップは、v0.1 が拡張を正当化するだけの継続的な利用状況を示した場合に、次に取り組む価値があると研究記事で指摘された項目です。そうした利用状況が確認されるまでは、いずれも実施を確約していません。

• v0.2：COV サブスクリプションのサポート、BACnet/SC、223P のスキーマ完全準拠、SkySpark／FIN の Haystack ストアへのパススルー
• v0.3 以降：明示的なオプトインを条件とする任意の書き込み経路、マルチサイト連携、ローカル以外へのデプロイ向けの認証レイヤー

謝辞

• 本プロジェクトと並行して構築されている、先行する MCP と BACnet の統合については ezhuk/bacnet-mcp に感謝します
• BACnet プロトコルライブラリについては bacpypes3 に感謝します
• Haystack のタグ付け語彙とコミュニティについては Project Haystack に感謝します
• Brick スキーマについては Brick consortium に感謝します
• 本研究の基盤となる見解を公表した、以下の 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 を提出する前に、まずイシューを作成して相談してください。