Eclipse Ditto

Eclipse Ditto MCP 服务

一个适用于 Eclipse Ditto 的 Model Context Protocol（MCP）服务。Eclipse Ditto 是一个开源（EPL-2.0）数字孪生框架。它将 Ditto 的 HTTP API 暴露为 MCP 工具，使 AI Agent 能够管理设备（“things”）及其属性/功能、策略、连接和集群管理功能，涵盖 Ditto HTTP API 的完整范围。

由于 Bosch IoT Things 和其他商业 IoT 平台基于 Ditto 的开放协议构建，此服务也适用于这些部署——代码中没有任何针对特定供应商的内容。

使用 FastMCP 构建。

工具

Things

工具	描述
list_things(namespaces, filter, fields, limit)	搜索/列出 things。filter 是 Ditto RQL 表达式，例如 eq(attributes/location,"lab-1")。
count_things(namespaces, filter)	统计符合筛选条件的 things 数量，不获取其内容。
get_things(thing_ids, fields)	在一次请求中按 ID 批量获取多个 things。
get_thing(thing_id, fields)	获取单个 thing 的完整数字孪生。
put_thing(thing_id, thing, overwrite=False)	创建 thing，或在 overwrite=True 时替换现有 thing。
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 验证此连接器身份时使用的身份信息——可用于检查凭据是否正常。

属性与功能

工具	描述
get_thing_attributes(thing_id, path=None)	获取所有属性，或通过 JSON 指针路径获取单个属性。
set_thing_attributes(thing_id, value, path=None, overwrite=False)	设置整个属性对象，或设置单个属性。
delete_thing_attributes(thing_id, path=None, confirm=False)	删除属性（整个对象或指定路径）。
get_thing_features(thing_id)	获取所有功能（传感器/执行器状态）。
get_feature / put_feature / delete_feature	读取/创建并替换/删除整个功能。
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 的访问权限。

策略

工具	描述
get_policy / put_policy / delete_policy	读取/创建并替换/删除策略。
get_policy_entries(policy_id, label=None)	读取所有条目，或按标签读取单个条目。
set_policy_entry / delete_policy_entry	创建并替换/删除单个策略条目。

连接与 DevOps （需要 DITTO_DEVOPS_USERNAME/DITTO_DEVOPS_PASSWORD）

Ditto 的 Connections API 和 DevOps API（日志级别、集群配置、附带命令）位于网关上独立的“devops” Basic Auth 领域中，与用于事物/策略的基于策略的身份验证相互独立。

工具	描述
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 连接并收集实时事物变更事件。这是对 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 Auth 凭据。通常用于可自托管的 Ditto（nginx 演示配置使用 ditto/ditto）。
DITTO_BEARER_TOKEN	否	Bearer 令牌，用于替代同一 API 的 Basic Auth。通常用于由 OAuth2 提供前置身份验证的部署（例如 Bosch IoT Things）。
DITTO_DEVOPS_USERNAME / DITTO_DEVOPS_PASSWORD	否	独立 DevOps/Connections 领域的 Basic Auth 凭据（可自托管实例的默认值：devops/foobar）。仅 Connectivity 和 DevOps 工具需要。

如果同时设置了 DITTO_BEARER_TOKEN 和 Basic Auth 凭据，则优先使用 Bearer 令牌。如果两者都未设置，请求将以未身份验证的方式发送（仅当 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

请参阅 mcp.json 获取可直接使用的客户端配置（stdio 和 Docker）。

针对真实 Ditto 实例进行测试

本仓库的设计原则要求针对真实实例进行测试，而不是使用模拟对象。docker-compose.yml（基于 Ditto 官方示例改编，并精简为此连接器所需的服务）会启动完整的本地 Ditto 堆栈，包括 MongoDB、Ditto 微服务，以及带有 Basic auth 的 nginx 入口。

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 项测试针对真实堆栈覆盖了所有工具组（事物、属性/功能、消息、策略、连接、运维、实时事件），其中包括删除/确认门控和创建/覆盖门控。

关于实时事件近似实现的说明

poll_thing_changes 会在有界时间窗口内打开 Ditto 的 SSE 变更流，而不是维持持久订阅（这种方式无法很好地映射到单次 MCP 工具调用）。即使没有任何变更，Ditto 的 SSE 流也会定期发送空的 data: 保活行——该工具会在收到的每一行（包括保活行）上检查截止时间，因此无论流有多活跃或多安静，都能确保在 duration_seconds 内返回。

许可证说明

docker-compose.yml 和 docker/ 下的文件基于 Eclipse Ditto 项目（EPL-2.0）改编，仅用于启动本地测试实例；它们并非 MCP 服务本身的一部分。