DTS CloudMaster MCP 能力分析与使用说明

适用程序：DTS Cloud 7.0 20260915以上版本 CloudMaster.McpHost.exe

1. 概述

CloudMaster.McpHost.exe 是一个本地 STDIO MCP 服务，用于把 CloudMaster 的管理能力开放给 Codex 等 MCP 客户端。

它的定位是“CloudMaster 运维与工程发布入口”，不是完整的 DTS 场景二次开发 SDK。提供 9 个工具，覆盖：

查询服务状态、查询本机授权；
启动、停止、重启整套 Cloud 服务；
添加和删除 CloudMaster 工程；
打开本机视频流测试页和 API 示例页。

它不直接提供 fdapi.camera、fdapi.marker、fdapi.customObject 等场景内控制能力。场景内相机、标注、模型、图层等操作仍应通过 DigitalTwinPlayer 获取的 fdapi 调用；实例、节点、连接等更细粒度运行信息，需要 CloudServer MCP 的相应工具，而不是本程序。

获取fdapi以及更多AI技能

2. 审计对象与验证结果

2.1 程序信息

项目	实测结果
路径	`C:\Users\freedo\AppData\Roaming\DTS Cloud\7.1\CloudMaster\CloudMaster.McpHost.exe`
文件大小	35,950,048 字节
文件版本	1.0.0.0
产品版本	1.0.0
数字签名	有效
签名者	Beijing Feidu Technology Co., Ltd.
SHA-256	`25118EFE3CC3C90DC189AE25CEDF68B538604C75D4AF63FB2F00CBFC4FC227EB`

升级或重新安装 DTS Cloud 后，建议重新核对版本、签名和哈希；路径中的 7.1 也可能随版本变化。

2.2 MCP 兼容性

已完成实际握手和工具枚举：

项目	实测结果
传输方式	本地 STDIO，由 MCP 客户端启动子进程
MCP 协议版本	`2025-06-18`
服务名	`CloudMaster.McpHost`
服务版本	`1.0.0.0`
能力	`logging`、`tools`
工具清单变化通知	支持，`tools.listChanged=true`
Resources / Prompts	本次握手未声明

只读调用 cloudmaster_get_service_status 已成功。审计时返回：整体服务、受管服务、CloudServer 和 NodeService 正在运行；RelayServer 与 3DT 文件服务未运行；启动类型为 Normal。

本次审计没有调用启动、停止、重启、增删工程或打开页面工具，因此没有改变现有 CloudMaster 服务和工程配置。

3. 工具能力清单

3.1 只读查询

`cloudmaster_get_service_status`

查看 CloudMaster 编排的完整服务及主要子服务的进程生命周期状态。

输入：无。
主要输出：running、managedServiceRunning、cloudServerRunning、nodeServiceRunning、relayServerRunning、fileServerRunning、startupType。
风险：低，工具声明为只读。
边界：不返回工程、实例、节点或客户端连接的业务详情。若已连接 CloudServer MCP，应使用其 dts_get_status 查询运行时详情。

`cloudmaster_get_license_info`

查看 CloudMaster 当前加载、并用于判断服务能否启动的本机授权。

输入：无。
主要输出：授权状态、产品类型、授权用户、序列号、有效期、剩余天数、节点数、授权服务器及特性支持情况。
风险：低，但输出中可能包含序列号和授权主体等敏感信息，不宜原样粘贴到公开日志或工单。
边界：若要确认正在运行的 CloudServer 实际识别到的授权，应使用 CloudServer MCP 的 dts_get_license_info。

3.2 服务生命周期

`cloudmaster_start_service`

启动由本机 CloudMaster 编排的完整云服务。服务已经运行时不会重复启动。

输入：无。
幂等性：声明为幂等。
风险：中，会改变本机运行状态并启动多个服务进程。

`cloudmaster_stop_service`

停止由本机 CloudMaster 编排的完整云服务。服务未运行时直接返回成功。

输入：无。
幂等性：声明为幂等。
风险：高，工具标记为破坏性；会中断现有实例和客户端连接。
手册对应：CloudMaster 的“停止”会结束其启动的实例及相关服务进程。

`cloudmaster_restart_service`

先停止、再启动 CloudMaster 编排的完整云服务。

输入：无。
幂等性：未声明为幂等。
风险：高，工具标记为破坏性；会造成服务中断。
建议：仅在明确维护窗口、确认当前连接和任务可中断后执行。

3.3 工程管理

`cloudmaster_add_project`

把本机工程加入 CloudMaster，并同步 CloudMaster 界面、配置、本机节点和 CloudServer。

必填输入：projectPath。
路径要求：绝对路径。
文件格式：仅 .acp 或 .dtml。
风险：中，会修改 CloudMaster 工程列表和相关配置。

调用前必须检查：

工程文件真实存在且可读；
Explorer 工程版本与 Cloud 兼容；
多节点部署时，所有节点都能访问工程，且本地工程路径保持完全一致；
工程名没有与列表中的现有工程重复；
DTML 工程所引用的资源路径在节点上同样有效。

`cloudmaster_delete_project`

按工程名称从 CloudMaster 工程列表和配置中移除工程，并同步界面、节点和 CloudServer。

必填输入：projectName，不含 .acp 或 .dtml 扩展名。
磁盘文件：不会删除工程文件本身。
引用处理：引用该工程的实例会先停止，并重置工程设置。
限制：默认 demo 工程不能删除。
风险：高，工具标记为破坏性；虽然不删磁盘文件，但会影响正在引用该工程的实例。

删除前应先确认目标工程名、引用数和相关实例状态，并取得明确授权。

3.4 本机测试页面

`cloudmaster_open_player_page`

使用 CloudMaster 当前服务配置，在本机桌面打开视频流测试页面。

输入：无。
影响：仅打开本机 UI，不修改工程文件；可能建立视频流连接并占用实例/并发资源。
手册对应：视频流测试页面用于进入云渲染三维界面。

`cloudmaster_open_api_page`

使用 CloudMaster 当前服务配置，在本机桌面打开 API 示例页面。

输入：无。
影响：仅打开本机 UI；在页面中实际执行代码时会改变场景状态。
手册对应：API 示例页包含接口列表、实时日志、三维窗口和可即时运行的 JavaScript 编辑区。

4. 与 DTS Cloud V7.0 手册的对应关系

MCP 能力	CloudMaster 手册功能	重要注意事项
启动服务	启动 / 常规启动	服务设置、工程、节点和实例应先配置完成
停止服务	停止	会结束已启动的实例和相关服务进程
重启服务	停止后重新启动	MCP 是整套服务级重启，不是单实例重启
添加工程	工程管理 → 添加	支持 ACP、DTML；工程与 Cloud 版本需兼容
删除工程	工程管理 → 删除	demo 不可删除；MCP 不删除磁盘文件
打开视频流页	接口测试页面 → 视频流测试	可能占用实例和授权并发
打开 API 页	接口测试页面 → API 示例	页面可编辑并运行 JavaScript
查看状态	CloudMaster 服务与运行状态	MCP 仅返回进程级摘要
查看授权	安装授权 / 服务启动前置条件	本机加载授权与 CloudServer 实际授权要区分

参考手册：

用户提供的本地源文件 D:\Work\dts\_documents\_202605\app\docs\7.0\cloud\_V7.0.md 在本次运行环境中不存在，因此本说明采用飞渡官网当前可访问的 V7.0 在线页面作为手册依据。若本地 Markdown 后续可用，应再做一次逐节差异核对。

5. 在 Codex 中接入

5.1 推荐方式：桌面设置

打开 Codex/ChatGPT 桌面端的设置。
进入 “MCP servers”。
选择添加服务器，类型选 STDIO。
名称填写 dts-cloudmaster。
命令填写：
C:\Users\freedo\AppData\Roaming\DTS Cloud\7.1\CloudMaster\CloudMaster.McpHost.exe
不需要参数、URL 或 OAuth。
保存并重启客户端，然后用 /mcp 检查连接状态和工具列表。

5.2 命令行添加

powershell

codex mcp add dts-cloudmaster -- "C:\Users\freedo\AppData\Roaming\DTS Cloud\7.1\CloudMaster\CloudMaster.McpHost.exe"
codex mcp list

5.3 直接编辑 `config.toml`

Codex 用户级配置通常位于 C:\Users\freedo\.codex\config.toml。也可以在可信工程下使用 .codex\config.toml 做工程级配置。

推荐先启用完整工具集，但让所有非只读工具都请求确认：

toml

[mcp_servers.dts-cloudmaster]
command = 'C:\Users\freedo\AppData\Roaming\DTS Cloud\7.1\CloudMaster\CloudMaster.McpHost.exe'
enabled = true
startup_timeout_sec = 15
tool_timeout_sec = 120
default_tools_approval_mode = "writes"

如果只希望审计，不允许任何状态改变，可使用只读白名单：

toml

[mcp_servers.dts-cloudmaster]
command = 'C:\Users\freedo\AppData\Roaming\DTS Cloud\7.1\CloudMaster\CloudMaster.McpHost.exe'
enabled = true
enabled_tools = [
  "cloudmaster_get_service_status",
  "cloudmaster_get_license_info",
]

配置方法参考 OpenAI 官方 MCP 文档。桌面端、Codex CLI 和 IDE 扩展会共享同一 Codex 主机上的 MCP 配置。

本说明没有修改现有 config.toml。如需实际安装，建议先备份配置并在重启后验证 /mcp，不要把“配置已写入”当作“握手已成功”。

6. 推荐对话用法

6.1 查询状态

text

请只读检查 DTS CloudMaster 服务状态，不要启动、停止或重启任何服务。

预期使用：cloudmaster_get_service_status。

6.2 查询授权

text

请只读检查 CloudMaster 当前加载的授权是否有效，只汇报产品类型、有效期、剩余天数和节点数，隐藏完整序列号。

预期使用：cloudmaster_get_license_info。

6.3 添加工程

text

请先检查这个 DTS 工程文件是否存在、扩展名和版本是否合适，并确认它是否已在 CloudMaster 中；只向我展示检查结果，不要添加。工程路径：E:\项目\示例.dtml

检查确认后，再单独发出：

text

确认把 E:\项目\示例.dtml 添加到 CloudMaster。添加后只读检查服务状态并汇报结果，不要重启服务。

6.4 删除工程

text

请先检查 CloudMaster 中名为“示例”的工程及其引用情况，不要删除。告诉我删除会影响哪些实例。

只有确认影响后再明确授权删除。注意：当前 CloudMaster MCP 自身不提供工程列表或引用详情查询，必要时需要 CloudServer MCP 或 CloudMaster UI 补充确认。

6.5 打开测试页面

text

请打开 DTS Cloud 视频流测试页面，不要修改服务或工程配置。

或：

text

请打开 DTS Cloud API 示例页面，页面打开后不要自动执行示例代码。

6.6 服务维护

text

先只读检查 CloudMaster 服务状态。若已经运行，不执行任何操作；若未运行，向我汇报并等待确认，不要自动启动。

需要执行时，再明确说“确认启动”“确认停止”或“确认重启”。

7. 建议的安全工作流

text

只读检查状态
  → 核对 CloudMaster 进程路径与当前服务状态
  → 对工程操作先核对绝对路径、版本、同名和节点可达性
  → 展示拟执行动作及影响范围
  → 用户明确确认
  → 执行一个写操作
  → 再次只读检查状态
  → 必要时打开播放器/API 页面做人工验收

专业使用建议：

默认把本 MCP 配成 writes 审批模式，避免模型自动执行非只读工具。
停止、重启和删除工程始终逐次确认，不做批量隐式执行。
在调用生命周期工具前，同时确认 CloudMaster 主程序路径、进程身份和服务状态；不要仅凭端口或 PID 判断归属。
添加工程前保留工程文件和 CloudMaster 配置的可恢复副本。
多节点环境重点核对“所有节点可访问”和“本地路径完全一致”。
预览工程、视频流测试可能占用授权和并发数，测试完成后应确认连接是否释放。
授权序列号、授权用户、服务地址和访问密码不应进入公开日志。
“工具调用成功”只表示 CloudMaster 接受了操作；关键变更仍应结合状态复查和实际页面验收。

8. 能力边界与缺口

当前 9 个工具没有覆盖以下 CloudMaster 手册功能：

工程列表查询、工程引用详情、工程预览；
单个实例的启动、停止、重启、参数设置与工程锁定；
节点、空间群组、客户端连接和并发管理；
服务地址、HTTP/HTTPS、中继、编码、帧率和管理员认证配置；
日志目录、日志读取和故障诊断；
场景内相机、标注、图层、模型、天气、量算等 fdapi 能力。

因此，比较稳妥的组合是：

CloudMaster MCP：负责服务生命周期、工程注册、授权与入口页面；
CloudServer MCP：负责运行时工程、实例、节点、连接等详情；
DTS JavaScript SDK（DigitalTwinPlayer + fdapi）：负责场景内业务控制；
CloudMaster UI：负责复杂配置、影响确认和最终人工验收。

9. 常见问题

MCP 能连接，但状态查询失败

先确认 CloudMaster 主程序正在运行，而且运行路径与 MCP Host 所属版本一致。本次成功验证是在 CloudMaster.exe 正在运行时完成的，尚未验证主程序退出时的行为。

`/mcp` 中看不到工具

检查：

路径是否存在，尤其是版本目录是否仍为 7.1；
配置是否保存到当前 Codex 主机实际使用的 config.toml；
是否已重启桌面端或 IDE 扩展；
enabled 是否为 true；
enabled_tools 是否误删了需要的工具；
安全软件是否阻止子进程或标准输入/输出通信。

添加工程失败

重点检查绝对路径、扩展名、文件权限、工程与 Cloud 版本、同名工程，以及多节点路径一致性。.dtml 中引用的资源路径也必须在渲染节点上有效。

为什么不能直接让 MCP 控制相机或添加标注

因为当前 CloudMaster.McpHost.exe 只暴露 CloudMaster 管理工具，没有暴露 fdapi。应先打开 API 示例页，或在 Web 应用中通过 DigitalTwinPlayer.getAPI() 获得 fdapi，并在 onReady 后调用场景接口。

更新日志

Cloud

新内容

DTS CloudMaster MCP 能力分析与使用说明 ​

1. 概述 ​

2. 审计对象与验证结果 ​

2.1 程序信息 ​

2.2 MCP 兼容性 ​

3. 工具能力清单 ​

3.1 只读查询 ​

cloudmaster_get_service_status ​

cloudmaster_get_license_info ​

3.2 服务生命周期 ​

cloudmaster_start_service ​

cloudmaster_stop_service ​

cloudmaster_restart_service ​

3.3 工程管理 ​

cloudmaster_add_project ​

cloudmaster_delete_project ​

3.4 本机测试页面 ​

cloudmaster_open_player_page ​

cloudmaster_open_api_page ​

4. 与 DTS Cloud V7.0 手册的对应关系 ​

5. 在 Codex 中接入 ​

5.1 推荐方式：桌面设置 ​

5.2 命令行添加 ​

5.3 直接编辑 config.toml ​

6. 推荐对话用法 ​

6.1 查询状态 ​

6.2 查询授权 ​

6.3 添加工程 ​

6.4 删除工程 ​

6.5 打开测试页面 ​

6.6 服务维护 ​

7. 建议的安全工作流 ​

8. 能力边界与缺口 ​

9. 常见问题 ​

MCP 能连接，但状态查询失败 ​

/mcp 中看不到工具 ​

添加工程失败 ​

为什么不能直接让 MCP 控制相机或添加标注 ​

DTS CloudMaster MCP 能力分析与使用说明

1. 概述

2. 审计对象与验证结果

2.1 程序信息

2.2 MCP 兼容性

3. 工具能力清单

3.1 只读查询

`cloudmaster_get_service_status`

`cloudmaster_get_license_info`

3.2 服务生命周期

`cloudmaster_start_service`

`cloudmaster_stop_service`

`cloudmaster_restart_service`

3.3 工程管理

`cloudmaster_add_project`

`cloudmaster_delete_project`

3.4 本机测试页面

`cloudmaster_open_player_page`

`cloudmaster_open_api_page`

4. 与 DTS Cloud V7.0 手册的对应关系

5. 在 Codex 中接入

5.1 推荐方式：桌面设置

5.2 命令行添加

5.3 直接编辑 `config.toml`

6. 推荐对话用法

6.1 查询状态

6.2 查询授权

6.3 添加工程

6.4 删除工程

6.5 打开测试页面

6.6 服务维护

7. 建议的安全工作流

8. 能力边界与缺口

9. 常见问题

MCP 能连接，但状态查询失败

`/mcp` 中看不到工具

添加工程失败

为什么不能直接让 MCP 控制相机或添加标注