MCP 工具说明

更新时间：2026-06-30

本文件记录 DTS MCP 服务的连接方式和当前可用工具清单。工具清单通过 MCP tools/list 获取，服务端返回的服务信息为 bv-ai-gateway，版本 1.0.0。

基本信息

真实 API Key 属于敏感凭证，文档和前端代码中建议只保留占位符，通过服务端配置、环境变量或密钥管理系统注入。

连接流程

MCP Streamable HTTP 客户端通常按以下顺序连接：

1. 向 MCP 地址发送 initialize 请求。
2. 从响应头读取 Mcp-Session-Id，后续请求都带上该会话 ID。
3. 发送 notifications/initialized 通知。
4. 调用 tools/list 获取工具列表。
5. 调用 tools/call 执行具体工具。

通用请求头

Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2025-03-26
bv-api-key: <YOUR_API_KEY>
Mcp-Session-Id: <初始化响应返回的会话ID>

初始化请求第一次发送时不需要 Mcp-Session-Id。服务端可能返回普通 JSON，也可能返回 text/event-stream，客户端需要支持解析 SSE 中的 data: JSON 数据。

初始化示例

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "clientInfo": {
      "name": "dts-mcp-client",
      "version": "1.0.0"
    }
  }
}

初始化成功后，服务端返回能力信息：

{
  "protocolVersion": "2025-03-26",
  "capabilities": {
    "completions": {},
    "logging": {},
    "prompts": {
      "listChanged": true
    },
    "resources": {
      "subscribe": false,
      "listChanged": true
    },
    "tools": {
      "listChanged": true
    }
  },
  "serverInfo": {
    "name": "bv-ai-gateway",
    "version": "1.0.0"
  }
}

获取工具列表示例

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

如果响应中包含 nextCursor，需要继续带上该游标分页拉取。本次查询未返回 nextCursor。

调用工具示例

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "devicePage",
    "arguments": {
      "currentPage": 1,
      "pageSize": 10,
      "productId": "产品编号"
    }
  }
}

所有工具的 inputSchema 均设置了 additionalProperties: false，调用时不要传入 schema 未声明的字段。

工具总览

工具明细

场景与大屏操作

项目、图层、节点、巡逻

产品、实体、产品Profile、服务

通知消息

孪生体、任务、时序

通用辅助

常见调用路径

查询并调用产品服务

1. 用 productPage 或已知产品编号确定 productId。
2. 用 productFindFunctionList 查询服务列表，取服务标识符 serviceIdentifier。
3. 用 devicePage 查询实体，确定 deviceId。
4. 如需补齐入参，用 deviceAttribute 查询实体属性。
5. 用 productServiceExecute 执行服务。

查询通知并评论

1. 用 find_notice_message 按项目和时间范围查询通知列表。
2. 用 find_message_detail 查看通知详情。
3. 用 send_comment 对通知发送评论。

控制大屏场景

1. 用 get_the_project_list 确定项目。
2. 用 switch_map 切换地图或场景。
3. 用 execute_label、execute_node、execute_layout、execute_patrol 等工具执行具体动作。
4. 复杂自然语言命令可统一走 executeCommand，由服务端按 intent、executeAction、commandParams 解释执行。

对接注意事项

• 所有时间字段建议使用服务端要求的格式；通知消息列表中的 startTime、endTime 为 yyyy-MM-dd HH:mm:ss。
• 分页接口未传 currentPage、pageSize 时，按工具说明使用默认第一页和默认 10 条。
• 枚举值请按工具描述传入，避免传中文说明文本代替枚举数字。
• inputData、commandParams 等对象型参数应传 JSON 对象，不要传 JSON 字符串。
• 执行型工具会改变大屏、任务或设备服务状态，生产环境接入前建议先做权限隔离和操作确认。