Eclipse Ditto

Eclipse Ditto MCP サーバー

Eclipse Ditto（オープンソース（EPL-2.0）のデジタルツインフレームワーク）向けのModel Context Protocol（MCP）サーバーです。Ditto の HTTP API を MCP ツールとして公開し、AI エージェントがデバイス（「thing」）、その属性／機能、ポリシー、接続、クラスター管理を管理できるようにします。Ditto HTTP API の全機能を網羅しています。

Bosch IoT Thingsやその他の商用 IoT プラットフォームは Ditto のオープンプロトコルを基盤としているため、このサーバーはそうした環境でも動作します。コードにベンダー固有の要素はありません。

FastMCPで構築されています。

ツール

Things

ツール	説明
list_things(namespaces, filter, fields, limit)	thing を検索／一覧表示します。filter はDitto RQL 式です。例：eq(attributes/location,"lab-1")
count_things(namespaces, filter)	thing を取得せずに、フィルターに一致する件数を数えます。
get_things(thing_ids, fields)	1 回のリクエストで、ID を指定して複数の thing を一括取得します。
get_thing(thing_id, fields)	1 つの thing のデジタルツイン全体を取得します。
put_thing(thing_id, thing, overwrite=False)	thing を作成するか、overwrite=Trueを指定して置き換えます。
patch_thing(thing_id, patch)	RFC-7396 JSON Merge Patch を使用して、thing を部分的に更新します。
delete_thing(thing_id, confirm=False)	thing を削除します。元に戻せません。
get_thing_policy_id / set_thing_policy_id	thing を制御するポリシーを読み取る／再設定します。
get_thing_definition / set_thing_definition / delete_thing_definition	thing の WoT／モデル定義を管理します。
whoami()	このコネクターとして Ditto が認証した ID を返します。認証情報の確認に便利です。

属性と機能

ツール	説明
get_thing_attributes(thing_id, path=None)	すべての属性、または JSON ポインターパスで指定した属性を取得します。
set_thing_attributes(thing_id, value, path=None, overwrite=False)	属性オブジェクト全体、または 1 つの属性を設定します。
delete_thing_attributes(thing_id, path=None, confirm=False)	属性を削除します（オブジェクト全体または指定したパス）。
get_thing_features(thing_id)	すべての機能（センサー／アクチュエーターの状態）を取得します。
get_feature / put_feature / delete_feature	1 つの機能全体を読み取り／作成・置換／削除します。
get_feature_properties / set_feature_properties / delete_feature_properties	機能のプロパティまたはdesiredPropertiesを、全体またはパス単位で読み取り／書き込み／削除します。
get_feature_definition / set_feature_definition / delete_feature_definition	機能の定義を管理します。

メッセージ

ツール	説明
send_message(thing_id, subject, payload, feature_id=None, direction="inbox", timeout=10)	thing または機能との間でライブメッセージを送信します（例：デバイス操作の呼び出し）。
claim_thing(thing_id, payload=None, timeout=10)	thing へのアクセス権を得るため、claim メッセージを送信します。

ポリシー

ツール	説明
get_policy / put_policy / delete_policy	ポリシーを読み取り／作成・置換／削除します。
get_policy_entries(policy_id, label=None)	すべてのエントリー、またはラベルで指定したエントリーを読み取ります。
set_policy_entry / delete_policy_entry	1 つのポリシーエントリーを作成・置換／削除します。

接続と DevOps (DITTO_DEVOPS_USERNAME/DITTO_DEVOPS_PASSWORD が必要です)

Ditto の Connections API と DevOps API（ログレベル、クラスター設定、ピギーバックコマンド）は、ゲートウェイ上の独立した「devops」Basic 認証レルムの背後にあり、Things/Policies に使用されるポリシーベース認証とは別です。

ツール	説明
list_connections / get_connection	接続設定を一覧表示／取得します。
create_connection(connection, dry_run=False)	接続を作成します（ID は Ditto によって生成されます）。
update_connection(connection_id, connection)	既存の接続を更新します（存在しない場合は 404）。
delete_connection(connection_id, confirm=False)	接続を削除します。
get_connection_status / get_connection_metrics / get_connection_logs	接続の現在の状態を確認します。
send_connection_command(connection_id, command)	開く／閉じる／メトリクスをリセットする／ログを有効にする／ログをリセットします。
get_logging_config / set_logging_config	クラスターのログレベルを読み取り／設定します。
get_devops_config(path)	クラスター全体のランタイム設定を読み取ります。
send_devops_piggyback(command, service_name=None, instance_index=None)	低レベルの管理コマンドです。Ditto の API の中で最も強力で、最も保護が弱いものです。慎重に使用してください。

ライブイベント

ツール	説明
poll_thing_changes(thing_ids, namespaces, filter, fields, duration_seconds=10, max_events=50)	短時間の SSE 接続を開き、ライブの Thing 変更イベントを収集します。Ditto の永続的な変更フィードをリクエスト／レスポンス方式で近似したものです。下記の注意事項を参照してください。

安全性に関する規約

• 作成と置き換え： すべての put_*／set_*／create_* ツールは、デフォルトで overwrite=False を使用し、Ditto の If-None-Match: * ヘッダーによって、作成のみの操作を競合状態なく実行します（確認してから設定する方式ではありません）。既存のデータを置き換えるには overwrite=True を渡します。
• 削除には確認が必要です： すべての delete_* ツールには confirm=True が必要です。一括削除やカスケード削除はありません。
• 対象外（意図的）： WoT Web-of-Things ディスクリプターのエンドポイント（/.well-known/wot、/devops/wot/*）と、きめ細かなポリシーのサブリソース（subjects/{id}、resources/{path}、imports、トークン統合アクション）は対象外です。一般的なケースはエントリー全体を扱う set_policy_entry／get_policy_entries でカバーできます。必要であれば後から追加してください。

設定

環境変数	必須	説明
DITTO_BASE_URL	はい	Ditto HTTP API のベース URL です。例：http://localhost:8080、またはゲートウェイの公開 URL。
DITTO_USERNAME / DITTO_PASSWORD	いいえ	Things/Policies/Messages/Search API 用の Basic 認証です。セルフホスト型の Ditto で一般的です（nginx のデモ設定では ditto/ditto を使用します）。
DITTO_BEARER_TOKEN	いいえ	同じ API で Basic 認証の代わりに使用するベアラートークンです。OAuth2 を前段に置いたデプロイ（例：Bosch IoT Things）で一般的です。
DITTO_DEVOPS_USERNAME / DITTO_DEVOPS_PASSWORD	いいえ	独立した DevOps/Connections レルム用の Basic 認証です（セルフホスト時のデフォルト：devops/foobar）。Connectivity と DevOps のツールでのみ必要です。

DITTO_BEARER_TOKEN と Basic 認証の認証情報の両方が設定されている場合は、ベアラートークンが優先されます。どちらも設定されていない場合、リクエストは認証なしで送信されます（Ditto インスタンスが匿名アクセスまたは事前認証済みアクセスを許可している場合にのみ機能します）。

ローカルでの実行

uv sync
export DITTO_BASE_URL=http://localhost:8080
export DITTO_USERNAME=ditto
export DITTO_PASSWORD=ditto
export DITTO_DEVOPS_USERNAME=devops    # only needed for connectivity/devops tools
export DITTO_DEVOPS_PASSWORD=foobar
uv run dittomcpserver.py

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

実際の Ditto インスタンスを使用したテスト

このリポジトリの設計原則では、モックではなく実際のインスタンスを使用したテストが求められています。docker-compose.yml（Ditto の公式サンプルを基に、このコネクターに必要なサービスに絞って調整したもの）を使うと、MongoDB、Ditto のマイクロサービス、Basic 認証を備えた nginx のフロントエンドを含む、完全なローカル Ditto スタックが起動します。

docker compose up -d       # start Ditto on http://localhost:8080 (user: ditto / pass: ditto; devops: devops / foobar)
uv run pytest -v           # tests/conftest.py also starts/stops the stack automatically
docker compose down        # stop it manually if you started it yourself

47 件のテストでは、削除／確認のゲーティングや作成／上書きのゲーティングも含め、すべてのツールグループ（things、属性／features、メッセージ、ポリシー、接続、devops、ライブイベント）をこの実際のスタックに対してテストします。

ライブイベントの近似実装に関する注意

poll_thing_changes は、永続的なサブスクリプションを維持するのではなく、Ditto の SSE 変更フィードを時間制限付きで開きます。永続的なサブスクリプションは、単一の MCP ツール呼び出しにはうまく対応しないためです。Ditto の SSE ストリームは、変更がない場合でも定期的に空の data: キープアライブ行を送信します。このツールは、キープアライブを含む受信したすべての行で期限を確認するため、ストリームの通信頻度にかかわらず、duration_seconds 以内に確実に戻ります。

ライセンスに関する注意

docker-compose.yml と docker/ 配下のファイルは、Eclipse Ditto プロジェクト（EPL-2.0）を基に調整したもので、ローカルテストインスタンスの起動にのみ使用します。これらは MCP サーバー自体の一部ではありません。