Sparkplug B

Sparkplug B MCP サーバー

Sparkplug B 向けの Model Context Protocol（MCP）サーバーです。Sparkplug B は、産業用／SCADA データ向けの Eclipse 標準 MQTT トピック／ペイロード規約（出生／死亡証明、シーケンス付きメトリクス、protobuf ペイロード）です。Sparkplug B のトラフィックを扱うあらゆる MQTT ブローカーで動作します。使用するのはオープンな Sparkplug B 仕様のみで、ベンダー固有の拡張機能は使用しません。

このサーバーは Sparkplug B のプライマリホストアプリケーションとして機能します。spBv1.0 名前空間全体をサブスクライブし、NBIRTH／DBIRTH メッセージからエッジノードとデバイスを検出して、リアルタイムのメトリクスを追跡し、コマンド（NCMD／DCMD）を送信できます。これは、実際の導入環境で SCADA／ヒストリアンのホストアプリケーションが担う役割と同じです。

FastMCP と pysparkplug（paho-mqtt を基盤として構築）を使用しています。

ツール

ツール	説明
get_connection_status()	ブローカーへの接続状態と、このホストアプリケーションの識別情報を報告します。
set_host_online(online)	このコネクター自身の保持された Sparkplug STATE メッセージを公開します。
list_edge_nodes(group_id?)	NBIRTH／NDEATH を通じて検出されたエッジノードを一覧表示します。
list_devices(group_id?, edge_node_id?)	DBIRTH／DDEATH を通じて検出されたデバイスを一覧表示します。
get_node_metrics(group_id, edge_node_id)	エッジノードについて把握している最新のメトリクス値を取得します。
get_device_metrics(group_id, edge_node_id, device_id)	デバイスについて把握している最新のメトリクス値を取得します。
send_node_command(group_id, edge_node_id, metrics)	NCMD を送信し、ノードのメトリクスを1つ以上書き込みます。
send_device_command(group_id, edge_node_id, device_id, metrics)	DCMD を送信し、デバイスのメトリクスを1つ以上書き込みます。
request_node_rebirth(group_id, edge_node_id)	標準の Node Control/Rebirth コマンドを送信し、ノードに完全な NBIRTH の再公開を要求します。
start_watch(group_id?, edge_node_id?, device_id?, message_types?)	任意のフィルターに一致するデコード済み Sparkplug トラフィックのバッファリングを開始します。session_id を返します。
get_events(session_id, max_events, timeout_seconds)	ウォッチセッションからバッファリングされたイベントを取り出します。イベントが到着するまで短時間待機することもできます。
stop_watch(session_id)	ウォッチセッションを停止し、バッファリングされたイベントを破棄します。
list_watches()	アクティブなウォッチセッションをすべて一覧表示します。

ウォッチがセッションベースである理由

基盤となる MQTT ワイヤープロトコルと同様に、Sparkplug B は継続的なストリームであり、リクエスト／レスポンス API ではありません。MCP ツール呼び出し1回で、次の出生メッセージやデータメッセージを「永遠に待つ」ことはできません。start_watch は任意のフィルター（グループ／ノード／デバイス／メッセージタイプ）を登録し、一致するデコード済みメッセージをバックグラウンドでバッファリングします（このコネクターは常に spBv1.0 名前空間全体をサブスクライブしているため、ウォッチごとにブローカーへの追加のサブスクリプションは不要です）。get_events はそのバッファからイベントを取り出し、新しいデータを一定時間待機することもできます。処理が終わったら stop_watch を呼び出してください。

対応しているメトリクスのデータ型

INT8／INT16／INT32／INT64、UINT8／UINT16／UINT32／UINT64、FLOAT、DOUBLE、BOOLEAN、STRING、TEXT、UUID、DATETIME、BYTES、FILE と、それらの *_ARRAY バリアントに対応しています。DATASET、TEMPLATE、PROPERTYSET、PROPERTYSETLIST は Sparkplug B 仕様に含まれていますが、基盤の pysparkplug コーデックではサポートされていないため、黙って誤処理するのではなく、明確なエラーを返して拒否します。

send_node_command／send_device_command では、value の形式は datatype によって異なります。スカラー値には通常の int／float／bool／str、DATETIME には ISO 8601 形式の文字列、BYTES／FILE には base64 文字列、*_ARRAY 型には JSON リストを指定します。

Configuration

環境変数	必須	説明
SPARKPLUG_MQTT_HOST	はい	ブローカーのホスト名または IP アドレスです。
SPARKPLUG_HOST_ID	はい	このコネクターの Sparkplug ホストアプリケーション ID です（spBv1.0/STATE/{id} トピックで使用されます）。
SPARKPLUG_MQTT_PORT	いいえ	デフォルトは 1883 です。
SPARKPLUG_MQTT_USERNAME / SPARKPLUG_MQTT_PASSWORD	いいえ	ブローカーの認証情報です。
SPARKPLUG_MQTT_CLIENT_ID	いいえ	デフォルトではブローカーによって割り当てられる ID が使用されます。
SPARKPLUG_MQTT_KEEPALIVE	いいえ	秒単位です。デフォルトは 60 です。
SPARKPLUG_MQTT_CONNECT_TIMEOUT	いいえ	初回接続を待機する秒数です。デフォルトは 10 です。
SPARKPLUG_MQTT_USE_TLS	いいえ	true／false です。デフォルトは false です。
SPARKPLUG_MQTT_TLS_CA_CERTS	いいえ	CA バンドルへのパスです。省略すると、システムのトラストストアが使用されます。
SPARKPLUG_MQTT_TLS_CLIENT_CERT / SPARKPLUG_MQTT_TLS_CLIENT_KEY	いいえ	相互 TLS 用です。
SPARKPLUG_GROUP_ID	いいえ	検出／監視対象を単一の Sparkplug グループ ID に制限します。省略すると、すべてのグループ（spBv1.0/#）をサブスクライブします。

ローカルでの実行

uv sync
export SPARKPLUG_MQTT_HOST=localhost
export SPARKPLUG_MQTT_PORT=1883
export SPARKPLUG_HOST_ID=my-mcp-host
uv run sparkplugbmcpserver.py

すぐに使えるクライアント設定（stdio および Docker）については、mcp.json を参照してください。

実際のブローカーを使用したテスト

このリポジトリの設計原則では、モックではなく実際のインスタンスを使用したテストを求めています。docker-compose.yml は、ローカルテスト用に匿名リスナーを備えた Eclipse Mosquitto（2.x）を起動します。テストフィクスチャでは、pysparkplug 独自の EdgeNode／Device クラスを使用して、実際の PLC／デバイスをシミュレートします。これらは実際の NBIRTH／DBIRTH／NDATA／DDATA／NDEATH メッセージをパブリッシュし、ネットワーク経由で実際の NCMD／DCMD コマンドを受信するため、カバレッジは手作りのモックではなくプロトコルレベルです。テストに使える無償の実機 PLC／エッジノードハードウェアがないため、「物理」ノード／デバイスのみをシミュレートしています。両側での Sparkplug B プロトコル処理は実際のものです。

docker compose up -d       # start Mosquitto on localhost:1883 (anonymous, local testing only)
uv run pytest -v           # tests/conftest.py also starts/stops the stack automatically
docker compose down        # stop it manually if you started it yourself

ライセンスに関する注意

docker-compose.yml および docker/ 以下のファイルは、ローカルテスト専用にオープンソースの Eclipse Mosquitto ブローカー（EPL-2.0）を設定するものであり、MCP サーバー自体には含まれません。