EdgeMCP 新手教程

← 返回使用指南
适用平台：OpenHarmony 标准系统（ZhihongOS）
上游依赖：EdgeComputer（须先跑通连云与插件加载）

章节	内容
一、开始之前	学什么、怎么读这份文档
二、连接开发板	hdc 连接、确认服务在跑
三、快速跑通	列出子设备、读第一条属性
四、查看状态与设备数据	health、设备列表、跨服务健康
五、逻辑原理	MCP 桥接、数据流、TSL 映射
六、功能一览	服务、CLI、五大工具
七、EdgeClaw 联调	mcp_service.json、对话验证
八、命令手册	子命令与参数说明
九、MCP 协议	HTTP 端点、JSON-RPC 握手
十、常见问题	连不上、无设备、会话耗尽
十一、附录	命令速查、相关文档

一、开始之前

1.1 这份文档帮你做什么

EdgeMCP 把 EdgeComputer 设备插件的物模型能力封装为 5 个 MCP Tool，供 EdgeClaw 等 MCP Client 通过 HTTP 调用。板端用 edgemcp CLI 可直接调试这些工具，无需经过大模型。

按下面顺序读，可以从零完成一次 MCP 设备控制：

第二章：hdc shell 进板子，确认 edgecomputer_service 和 edgemcp 在运行
第三章：跑通 list_devices 和 get_device_properties
第四章：掌握 health、设备状态、EdgeClaw MCP 状态等查看命令
第五章：理解 EdgeClaw → EdgeMCP → EdgeComputer 数据怎么走
第八章：需要查某个子命令或工具参数时当字典用

第三章跑通后，就可以边做边回头看第五章；不必一次读完。

前置：EdgeComputer 网关连云、子设备注册、插件加载见 edgecomputer.md 第三～四章。list_devices 返回空时，先完成 EdgeComputer 侧配置。

1.2 你需要准备

项目	说明
开发板	已烧录含 EdgeMCP 的 ZhihongOS 镜像（RK3588 已验证）
宿主机	已安装 `hdc`，能 `hdc shell` 进板子
EdgeComputer	`edgecomputer --format json service status` 中 `ipc_ok: true`
基础命令	会复制粘贴 Shell 命令；JSON 输出看得懂字段名更好
EdgeClaw（可选）	对话联调时需要；仅测 MCP 可不启动

1.3 CLI 用法

官方命令是 edgemcp。查命令用法：

bash

edgemcp --version          # 版本
edgemcp schema             # 全部子命令与参数
edgemcp schema tools.call  # 单个命令的参数说明

示例输出：

json

{
  "cli_version": "1.0.0",
  "schema_version": "1.0.0"
}

日常操作以 edgemcp 子命令为主，无需记忆配置文件路径（排障时可参考第十章）。

二、连接开发板

2.1 宿主机连接开发板

bash

# 【宿主机】列出已连接设备
hdc list targets

# 进入板端 Shell
hdc shell

2.2 确认 edgecomputer_service 已运行

EdgeMCP 强依赖 EdgeComputer。进入板端后先确认上游服务正常：

bash

# 【板端】
edgecomputer --format json service status

关注：ipc_ok 为 true 表示 IPC 可用；connected 为 true 表示网关 MQTT 已连上。EdgeComputer 未就绪时，edgemcp 的 bridge_connected 会为 false。

若 EdgeComputer 尚未配置，按 edgecomputer.md 第三章完成连云与插件加载。

2.3 确认 edgemcp 已运行

ZhihongOS 开机后 edgemcp 通常由系统自动拉起。进入板端后做一次确认：

bash

# 【板端】查看进程（可选）
ps -ef | grep edgemcp | grep -v grep

# 推荐：直接查健康状态
edgemcp health --format json

示例（进程列表）：

system         748     1 0 14:09:15 ?     00:00:00 edgemcp

若 health 中 reachable: true 且 mcp_listening: true，说明 MCP 服务正常。仅在排障时（第十章）才考虑 service_control restart edgemcp。

确认 MCP 端口监听：

bash

ss -tlnp | grep 9720

期望：

tcp   LISTEN   127.0.0.1:9720   ...   edgemcp

2.4 第一步验证

bash

edgemcp --version
edgemcp health --format json
edgemcp schema

三、快速跑通

目标：10 分钟内用 edgemcp CLI 列出子设备并读取一条属性。

3.1 前置条件

板端已 hdc shell 进入
edgecomputer --format json service status 显示 ipc_ok: true
已加载 linux_device 插件，且 edgecomputer device list 含 edge-linux-001（见 edgecomputer.md 第四章）

3.2 四步跑通

步骤	命令	看什么
1	`edgemcp health --format json`	`mcp_listening=true`，`tool_count=5`
2	`edgemcp tools list --format json`	返回 5 个工具及 `inputSchema`
3	`edgemcp tools call list_devices --format json`	列表含 `edge-linux-001`
4	见下方命令	`properties` 含 `cpu_usage` 等

步骤 1：确认 MCP 服务就绪

bash

edgemcp health --format json

作用：检查 9720 端口、MCP 握手、工具注册、IPC 桥接是否正常。

示例输出：

json

{
  "service": "edgemcp",
  "mcp_host": "127.0.0.1",
  "mcp_port": 9720,
  "reachable": true,
  "mcp_listening": true,
  "bridge_connected": true,
  "device_count": 3,
  "tool_count": 5
}

步骤 2：查看工具列表

bash

edgemcp tools list --format json

作用：等价于 MCP 协议 tools/list，确认 5 个工具已注册。

步骤 3：列出子设备

bash

edgemcp tools call list_devices --format json

作用：获取 device_id。后续所有工具调用都须使用这里返回的 ID，不要手写猜测。

步骤 4：读取设备属性

bash

edgemcp tools call get_device_properties \
  --device-id edge-linux-001 \
  --args '{"property_ids":["cpu_usage","disk_usage"]}' \
  --format json

示例输出：

json

{
  "device_id": "edge-linux-001",
  "properties": {
    "cpu_usage": 12.5,
    "disk_usage": 2.49
  }
}

3.3 验收标准

检查项	期望
`health.mcp_listening`	`true`
`health.tool_count`	`5`
`health.bridge_connected`	`true`
`list_devices`	含目标 `device_id`
`get_device_properties`	含 `cpu_usage`、`disk_usage` 等

记忆口诀：health 看服务 → list 看工具 → list_devices 拿 ID → get_properties 读数据。

四、查看状态与设备数据

本章汇总「想看什么、跑哪条命令」。IoT 链路跨 edgecomputer、edgemcp、edgeclaw 三个服务，排障时按层往下看。

4.1 edgemcp 服务状态

`edgemcp health`

bash

edgemcp health --format json

一次性检查：TCP 9720 可达 → MCP initialize 握手 → tools/list 工具数 → list_devices 桥接探活。

字段	含义	正常值	异常时查什么
`reachable`	TCP 9720 可达	`true`	进程、端口
`mcp_listening`	MCP initialize 成功	`true`	配置、会话池（见 10.1）
`bridge_connected`	IPC 桥接 + list_devices 成功	`true`	`edgecomputer_service`
`tool_count`	已注册工具数	`5`	重启 edgemcp
`device_count`	子设备数量	≥ 0	插件、子设备配置
`init_error`	初始化失败原因	无此字段	常见 `"Too many sessions"`

bridge_connected=false 且 reachable=true 时，多半是 EdgeComputer 未就绪，不是 MCP 本身挂了。

`edgemcp dump`

bash

edgemcp dump              # 人类可读
edgemcp dump --format json

优先调用 edgemcp dump；若 dumpsys 不可用则回退到 health 输出。需要服务内部运行状态时用这个。

4.2 设备状态

设备数据来自 EdgeComputer，经 edgemcp 桥接后以 MCP 工具暴露。两条查看路径：

路径 A：EdgeComputer 直接查（底层）

bash

edgecomputer --format json service status
edgecomputer device list --format json
edgecomputer device get --device-id edge-linux-001 --format json

命令	看什么
`service status`	网关 MQTT 是否在线、IPC 是否可用
`device list`	所有设备 ID、产品 ID、在线状态
`device get`	单设备当前属性快照

路径 B：edgemcp 工具查（MCP 层）

bash

edgemcp tools call list_devices --format json

edgemcp tools call get_device_properties \
  --device-id edge-linux-001 \
  --args '{"property_ids":["cpu_usage","disk_usage","load_avg"]}' \
  --format json

edgemcp tools call get_device_capabilities \
  --device-id edge-linux-001 \
  --format json

命令	看什么
`list_devices`	子设备列表、在线状态、可写属性提示
`get_device_properties`	指定或全部可读属性当前值
`get_device_capabilities`	物模型结构：可读写属性、可调用服务、事件

对照排障：

现象	说明
`device list` 有数据，`list_devices` 为空	IPC 桥接问题，查 `health.bridge_connected`
两边都空	插件未加载或子设备未创建
`list_devices` 有设备，读属性超时	设备离线或插件异常，查 `edgecomputer.log`

list_devices 返回字段：

字段	说明
`device_id`	设备唯一 ID，后续工具必填
`device_name`	设备名称
`product_id`	产品 ID
`state`	`online` / `offline`
`capabilities_hint`	能力提示（来自 tool_metadata）
`writable_properties`	可写属性 ID 列表
`key_functions`	关键功能 ID 列表

4.3 EdgeClaw 侧 MCP 状态

从 EdgeClaw 客户端视角看 MCP 连接：

bash

edgeclaw --format json mcp list
edgeclaw --format json mcp status edge-device
edgeclaw --format json mcp tools edge-device

命令	作用
`mcp list`	读取 `mcp_service.json` 中注册的服务列表
`mcp status edge-device`	向配置的 URL 发起连接探测
`mcp tools edge-device`	客户端视角的工具目录（含限定名）

mcp status 示例输出：

json

{
  "command": "mcp.status",
  "connected": true,
  "ok": true,
  "server_name": "edge-device",
  "tool_count": 5,
  "url": "http://edge-device-mcp.local:9720/mcp"
}

字段	含义	排障
`connected`	MCP 握手是否成功	`false` 时对照 `edgemcp health`
`tool_count`	客户端可见工具数	应为 5
`url`	实际连接地址	须为 `edge-device-mcp.local`

4.4 跨服务聚合健康

bash

edgecomputer edge health --format json
edgeclaw --format json health --all

edgecomputer edge health 聚合 edgecomputer、cloud、edgemcp、edgeclaw 四项状态。edgeclaw health --all 从 EdgeClaw 进程内探测，可发现「edgemcp 本机正常、EdgeClaw 连不上」这类跨进程问题。

4.5 常用查看命令

想看什么	命令
MCP 服务是否就绪	`edgemcp health --format json`
服务运行时	`edgemcp dump`
5 个工具定义	`edgemcp tools list --format json`
子设备列表（MCP 层）	`edgemcp tools call list_devices --format json`
单设备属性（MCP 层）	`edgemcp tools call get_device_properties --device-id <ID> --format json`
物模型能力摘要	`edgemcp tools call get_device_capabilities --device-id <ID> --format json`
子设备列表（底层）	`edgecomputer device list --format json`
单设备详情（底层）	`edgecomputer device get --device-id <ID> --format json`
EdgeClaw MCP 连接	`edgeclaw --format json mcp status edge-device`
四服务整体	`edgecomputer edge health --format json`

4.6 分层诊断

建议调试顺序：

1. edgecomputer device list     → EdgeComputer 是否有设备
2. edgemcp health               → MCP 服务与桥接
3. edgemcp tools call list_devices → MCP 层能否列出设备
4. edgeclaw mcp status edge-device → 客户端能否连 MCP
5. edgeclaw chat ...             → 全链路

现象	优先检查	处理
`device list` 为空	插件、子设备	`plugin load` + `config apply`
`health` 正常，`list_devices` 为空	桥接	重启 edgecomputer → edgemcp
`edgemcp` 正常，`mcp status connected=false`	`mcp_service.json`	改 URL 后 `service_control restart edgeclaw_service`
`tool_count` 不是 5	MCP 初始化	重启 edgemcp

五、逻辑原理

读完前三章并跑通 MCP 调用后，用本章把概念串起来：EdgeMCP 在链路中的位置、数据怎么走、物模型怎么映射到 MCP Tool。

5.1 为什么需要 EdgeMCP

问题	EdgeMCP 的解法
EdgeComputer 提供 IPC 设备 API，LLM 无法直接调用	封装为 MCP Tool Schema
每个设备物模型不同，难以猜参数	`get_device_capabilities` 返回结构化能力摘要
MCP 是 LLM 生态标准工具协议	充当翻译层：TSL → MCP

5.2 数据流

链路：

EdgeClaw → EdgeMCP (:9720) → EdgeComputer → 设备插件

5.3 TSL 到 MCP 映射

物模型元素	MCP 映射
设备实例列表	`list_devices` 返回
properties（读）	`get_device_properties` 的 `property_ids`
properties（写）	`set_device_properties` 的 `properties` 对象
functions	`invoke_device_function` 的 `function_id` + `inputs`
完整 TSL / 能力摘要	`get_device_capabilities`
events	在 capabilities 摘要中列出（只读参考）

推荐调用顺序（控制设备前）：

list_devices → get_device_capabilities → set/invoke → get_device_properties（确认）

5.4 设备目录轮询

DeviceCatalog 默认每 10 秒轮询 edgecomputer，发现新子设备后自动更新 MCP 能力。修改轮询间隔（edgemcp_config.json）：

json

"catalog": { "poll_interval_seconds": 5 }

5.5 IPC 与 REST 双路径

模式	`bridge.type`	说明
IPC（默认）	`ipc`	Binder 调用 `edgecomputer_service`，板端生产环境
REST	`rest`	HTTP 调用 EdgeComputer REST API，Linux standalone 调试

5.6 mcp_service.json 的 URL 约束

EdgeClaw 侧配置必须使用 edge-device-mcp.local，禁止 127.0.0.1：

URL	结果
`http://edge-device-mcp.local:9720/mcp`	EdgeClaw 内置 DNS 解析到 127.0.0.1，通过 URL 安全策略
`http://127.0.0.1:9720/mcp`	被 EdgeClaw `url_policy` 拦截

edgemcp 服务本身监听 127.0.0.1:9720 正常；仅 EdgeClaw 客户端配置须用 edge-device-mcp.local。

六、功能一览

EdgeMCP 由 系统服务 + CLI 工具 + MCP Host 三部分组成。

6.1 模块总览

6.2 核心模块

模块	职责
McpHost	监听 9720 端口，处理 MCP Streamable HTTP 请求
ToolRegistry	注册 5 个 MCP Tool，分发 `tools/call`
TslMcpTranslator	物模型 TSL → MCP Tool Schema / 能力摘要
DeviceCatalog	轮询 edgecomputer 设备目录，发现新设备
IEdgeComputerBridge	IPC 桥接（默认）或 REST 回退

6.3 五大 MCP 工具

工具名	只读	写/调用	EdgeClaw 限定名	作用
`list_devices`	✓	—	`mcp__edge-device__list_devices`	列出网关下子设备
`get_device_properties`	✓	—	`mcp__edge-device__get_device_properties`	读设备属性
`set_device_properties`	—	✓	`mcp__edge-device__set_device_properties`	写设备属性
`invoke_device_function`	—	✓	`mcp__edge-device__invoke_device_function`	调用设备服务/功能
`get_device_capabilities`	✓	—	`mcp__edge-device__get_device_capabilities`	物模型能力摘要

6.4 与其他服务的关系

| 服务 | 关系 | |------|-----|------| | edgecomputer | 必须先运行；edgemcp 经 IPC 读取设备与物模型 | | edgeclaw | MCP Client；经 HTTP 调用 edgemcp | | JetLinks | — | 间接；edgecomputer 连云，edgemcp 读本地物模型 |

推荐启动顺序：

edgecomputer_service → edgemcp → edgeclaw_service

6.5 配置文件

文件	路径	说明
EdgeMCP 主配置	`/system/etc/edgemcp/edgemcp_config.json`	端口、桥接、轮询间隔
工具元数据	`/system/etc/edgemcp/tool_metadata.json`	中文描述、产品 hints
EdgeClaw MCP 配置	`/system/etc/edgeclaw/mcp_service.json`	客户端连接 URL

edgemcp_config.json 默认要点：

json

{
  "mcp": {
    "host": "127.0.0.1",
    "port": 9720,
    "endpoint": "/mcp",
    "name": "edge-device-mcp",
    "version": "1.0.0"
  },
  "bridge": {
    "type": "ipc",
    "rest_fallback_url": "http://127.0.0.1:8080",
    "connect_retry_seconds": 180
  },
  "catalog": {
    "poll_interval_seconds": 10,
    "enable_event_subscription": true
  }
}

七、EdgeClaw 联调

目标：让 EdgeClaw 通过 MCP 调用 edgemcp 的 5 个工具，在对话中控制 IoT 设备。

7.1 配置 mcp_service.json

编辑 /system/etc/edgeclaw/mcp_service.json：

json

{
  "servers": [
    {
      "name": "edge-device",
      "url": "http://edge-device-mcp.local:9720/mcp",
      "transport": "streamable_http",
      "timeout": 30
    }
  ]
}

url 必须是 http://edge-device-mcp.local:9720/mcp，不能写 127.0.0.1。详见 5.6 节。

7.2 启动与验证

bash

# 【板端】按依赖顺序启动
service_control start edgecomputer_service
service_control start edgemcp
service_control start edgeclaw_service

# 确认配置
cat /system/etc/edgeclaw/mcp_service.json

# 逐层验证
edgeclaw --format json health --all
edgeclaw --format json mcp list
edgeclaw --format json mcp status edge-device
edgeclaw --format json mcp tools edge-device

验收：mcp status 中 connected: true，tool_count: 5。

7.3 对话控制设备

bash

# 【板端】点名工具（步骤清晰，便于对照日志）
edgeclaw chat -s iot-demo -m \
  '请调用 mcp__edge-device__list_devices 列出所有子设备'

edgeclaw chat -s iot-demo -m \
  '请读取 edge-linux-001 的 cpu_usage 和 disk_usage 属性'

7.4 工具名映射

MCP 工具	EdgeClaw 调用名
`list_devices`	`mcp__edge-device__list_devices`
`get_device_properties`	`mcp__edge-device__get_device_properties`
`set_device_properties`	`mcp__edge-device__set_device_properties`
`invoke_device_function`	`mcp__edge-device__invoke_device_function`
`get_device_capabilities`	`mcp__edge-device__get_device_capabilities`

set_device_properties、invoke_device_function 会改设备状态，生产环境注意 settings.json 中的 permission_mode。

7.5 与 edgemcp CLI 的分工

命令	视角	作用
`edgeclaw mcp status`	EdgeClaw 客户端	看 EdgeClaw 能否连上 MCP
`edgeclaw mcp tools`	EdgeClaw 客户端	看客户端视角的工具列表
`edgemcp health`	EdgeMCP 服务端	看 9720 监听、桥接、工具注册
`edgemcp tools call`	EdgeMCP 服务端	直接执行一次 tools/call

edgemcp tools call 成功而 edgeclaw chat 失败时，问题多半在 EdgeClaw 侧（mcp_service.json、LLM、会话配置）。

八、命令手册

需要查某个子命令或参数时，用本章当字典。各工具参数与 edgemcp tools list 返回的 inputSchema 一致。

8.1 命令树

edgemcp [--global-flags]
├── health                    # MCP 监听 + IPC 桥接健康
├── schema [command]          # CLI 参数自省
├── tools
│   ├── list                  # MCP tools/list
│   └── call <tool> [options] # MCP tools/call
└── dump                      # edgemcp dump 或 health 回退

8.2 全局标志

标志	说明
`--config <path>`	配置文件（默认 `/system/etc/edgemcp/edgemcp_config.json`）
`--format json\|table`	输出格式
`--dry-run`	预览，不实际调用 MCP
`--yes`	跳过确认
`--quiet` / `--verbose`	日志级别
`--version`	CLI 版本

8.3 退出码

码	含义
0	成功
1	一般错误
2	参数错误
3	资源未找到（如配置文件）
10	dry-run 成功

8.4 health — 服务健康检查

bash

edgemcp health --format json

作用：检查 MCP HTTP 是否在 9720 监听、能否完成 MCP 握手、与 EdgeComputer 的 IPC 桥是否连通、5 个工具是否已注册。

返回字段	含义
`reachable`	TCP 9720 可达
`mcp_listening`	MCP 协议 initialize 成功
`bridge_connected`	已连 EdgeComputer 且 list_devices 探活成功
`tool_count`	注册工具数，正常为 5
`device_count`	子设备数量
`init_error`	初始化失败原因（如 `"Too many sessions"`）

详见第四章。

8.5 schema — 命令自省

bash

edgemcp schema                          # 全部命令
edgemcp schema tools.call --format json # 单命令参数

8.6 tools list — 工具定义

bash

edgemcp tools list --format json

作用：等价于 MCP tools/list，返回每个工具的 name、description、inputSchema、annotations。

8.7 tools call — 调用工具

bash

edgemcp tools call <tool_name> [options] --format json

传参方式：

方式	适用	示例
独立标志	单参数	`--device-id edge-linux-001`
`--args` JSON	复杂/嵌套参数	`--args '{"device_id":"...","property_ids":["cpu_usage"]}'`

专用标志：

标志	映射 MCP 参数	说明
`--device-id`	`device_id`	设备 ID
`--property-id`	`property_id`	单个属性
`--property-ids`	`property_ids`	JSON 数组字符串
`--properties`	`properties`	JSON 对象
`--function` / `--function-id`	`function_id`	功能/服务 ID
`--inputs`	`inputs`	JSON 对象
`--include-current-values`	`include_current_values`	true/false/1/yes
`--args`	完整 arguments	覆盖上述独立标志

dry-run 预览：

bash

edgemcp tools call set_device_properties \
  --device-id edge-linux-001 \
  --properties '{"threshold":90}' \
  --dry-run --format json

8.8 dump — 服务运行时摘要

bash

edgemcp dump
edgemcp dump --format json

优先 edgemcp dump；不可用时回退 health。

8.9 list_devices — 列出子设备

控制任何设备前必须先调用。

参数	类型	必填	说明
`filter`	object	否	过滤条件
`filter.product_id`	string	否	按产品 ID
`filter.state`	enum	否	`online` / `offline`
`filter.device_type`	enum	否	`gateway` / `childrenDevice` / `device`

bash

edgemcp tools call list_devices --format json

edgemcp tools call list_devices \
  --args '{"filter":{"state":"online"}}' \
  --format json

8.10 get_device_properties — 读属性

省略 property_ids 时返回全部可读属性。

参数	类型	必填	说明
`device_id`	string	是	来自 `list_devices`
`property_ids`	string[]	否	指定属性 ID 列表

bash

edgemcp tools call get_device_properties \
  --device-id edge-linux-001 \
  --args '{"property_ids":["cpu_usage","disk_usage","load_avg"]}' \
  --format json

edgemcp tools call get_device_properties \
  --device-id edge-linux-001 \
  --format json

示例输出：

json

{
  "device_id": "edge-linux-001",
  "properties": {
    "disk_usage": 2.49,
    "load_avg": 0.79,
    "temp": 35.06
  }
}

8.11 set_device_properties — 写属性

properties 的 key 须为 get_device_capabilities 返回的可写 property_id。

参数	类型	必填	说明
`device_id`	string	是	来自 `list_devices`
`properties`	object	是	key=property_id，value 类型与物模型一致

bash

edgemcp tools call set_device_properties \
  --device-id edge-linux-001 \
  --properties '{"threshold":90}' \
  --format json

edgemcp tools call set_device_properties \
  --device-id fan-living-01 \
  --args '{"properties":{"power":true,"speed":3}}' \
  --format json

写入后建议 get_device_properties 确认。报 Property not writable 时先查 get_device_capabilities。

8.12 invoke_device_function — 调功能

适用于多参数或复合逻辑的服务调用。

参数	类型	必填	说明
`device_id`	string	是	来自 `list_devices`
`function_id`	string	是	来自 `get_device_capabilities`
`inputs`	object	否	服务输入参数

bash

edgemcp tools call invoke_device_function \
  --device-id edge-linux-001 \
  --function self_check \
  --inputs '{"mode":"quick"}' \
  --format json

操作类型	用哪个工具
开关、数值设置	`set_device_properties`
多参数服务（模式切换、重启等）	`invoke_device_function`

8.13 get_device_capabilities — 查能力

写操作或调功能前建议先调用。

参数	类型	必填	默认	说明
`device_id`	string	是	—	来自 `list_devices`
`include_current_values`	boolean	否	`true`	是否含属性当前值

bash

edgemcp tools call get_device_capabilities \
  --device-id edge-linux-001 \
  --format json

edgemcp tools call get_device_capabilities \
  --device-id edge-linux-001 \
  --include-current-values false \
  --format json

返回含 Properties（读写权限、类型、枚举/范围）、Functions（输入 schema）、Events 三段。

九、MCP 协议

需要直接用 curl 或脚本调试 MCP 时参考本章。日常板端操作优先用 edgemcp CLI（第八章）。

9.1 端点

项目	值
URL（板内 CLI）	`http://127.0.0.1:9720/mcp`
URL（EdgeClaw 配置）	`http://edge-device-mcp.local:9720/mcp`
方法	POST
Content-Type	application/json
协议版本	`2024-11-05`

9.2 握手序列

9.3 initialize 请求

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": { "name": "curl-debug", "version": "1.0" }
  }
}

9.4 tools/call 示例

json

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "list_devices",
    "arguments": {}
  }
}

json

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "get_device_properties",
    "arguments": {
      "device_id": "edge-linux-001",
      "property_ids": ["cpu_usage", "disk_usage"]
    }
  }
}

9.5 MCP Resources（可选）

URI 模板	等价工具
`edge://devices`	`list_devices`
`edge://device/{device_id}/metadata`	`get_device_capabilities`（原始 TSL）
`edge://device/{device_id}/properties`	`get_device_properties`
`edge://products/{product_id}/metadata`	产品级 TSL

9.6 宿主机 curl 调试

bash

# 【宿主机】
hdc fport tcp:9720 tcp:9720

curl -X POST http://127.0.0.1:9720/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

宿主机 curl 可用 127.0.0.1；EdgeClaw 配置仍须 edge-device-mcp.local。

9.7 Python 调试脚本

bash

# 【宿主机】端口转发后执行
python3 -c "
import requests, json
base = 'http://127.0.0.1:9720/mcp'
h = {'Content-Type': 'application/json'}

r1 = requests.post(base, json={
    'jsonrpc':'2.0','id':1,'method':'initialize',
    'params':{'protocolVersion':'2024-11-05','capabilities':{},
              'clientInfo':{'name':'debug','version':'1.0'}}
}, headers=h)
print('initialize:', json.dumps(r1.json(), indent=2, ensure_ascii=False))

requests.post(base, json={'jsonrpc':'2.0','method':'notifications/initialized'}, headers=h)

r3 = requests.post(base, json={'jsonrpc':'2.0','id':2,'method':'tools/list'}, headers=h)
print('tools:', json.dumps(r3.json(), indent=2, ensure_ascii=False))

r4 = requests.post(base, json={
    'jsonrpc':'2.0','id':3,'method':'tools/call',
    'params':{'name':'list_devices','arguments':{}}
}, headers=h)
print('call:', json.dumps(r4.json(), indent=2, ensure_ascii=False))
"

十、常见问题

10.1 Too many sessions

现象：

json

{
  "error": "mcp_unreachable",
  "message": "MCP initialize failed: \"Too many sessions\"",
  "retryable": true,
  "suggestion": "run 'service_control start edgemcp_service'"
}

edgemcp health 显示 mcp_listening=false、init_error="Too many sessions"、tool_count=0。

原因：EdgeMCP 维护有限会话池。频繁 CLI 调用、EdgeClaw 回归测试、未正常关闭的 MCP Client 会占满会话。

处理：

bash

service_control stop edgemcp
service_control start edgemcp

edgemcp health --format json
edgemcp tools list --format json

重启后期望：mcp_listening=true、tool_count=5、bridge_connected=true。

10.2 bridge_connected=false

检查项	命令/操作
EdgeComputer 进程	`ps -ef \| grep edgecomputer_service`
IPC 可用	`edgecomputer --format json service status` 看 `ipc_ok`
设备数据	`edgecomputer device list --format json`

先确认 EdgeComputer 正常，再重启 edgemcp：

bash

service_control restart edgecomputer_service
service_control restart edgemcp
edgemcp health --format json

10.3 list_devices 为空

edgecomputer plugin list --format json 确认插件已加载
edgecomputer device list --format json 确认子设备已注册
若 EdgeComputer 有设备而 MCP 层为空，查 health.bridge_connected

bash

edgecomputer plugin load linux_device --format json
edgecomputer config apply

10.4 EdgeClaw MCP not connected

检查项	处理
URL 用了 `127.0.0.1`	改为 `edge-device-mcp.local`
启动顺序错误	edgecomputer → edgemcp → edgeclaw
edgemcp 正常但客户端连不上	对照出厂 `mcp_service.json`，`service_control restart edgeclaw_service`

bash

edgeclaw --format json mcp status edge-device
edgemcp health --format json

10.5 属性读取超时 / Device not found

现象	处理
属性读取超时	查 `edgecomputer.log`，确认设备在线
`Device not found`	先 `list_devices`，不要编造 `device_id`
`Property not writable`	查 `get_device_capabilities`

10.6 netstat TIME_WAIT

ss -tlnp | grep 9720 可见大量 TIME_WAIT——CLI 每次 tools call 建立短连接后的正常 TCP 行为。若同时出现 Too many sessions，应重启 edgemcp，而非仅等待超时。

10.7 分层诊断命令汇总

bash

edgecomputer --format json service status
edgecomputer device list --format json
edgemcp health --format json
edgemcp dump
edgemcp tools call list_devices --format json
edgeclaw --format json mcp status edge-device
edgecomputer edge health --format json

十一、附录

附录 A：命令速查表

场景	命令
版本	`edgemcp --version`
MCP 服务健康	`edgemcp health --format json`
服务运行时	`edgemcp dump`
工具列表	`edgemcp tools list --format json`
列出设备	`edgemcp tools call list_devices --format json`
读属性	`edgemcp tools call get_device_properties --device-id <ID> --format json`
写属性	`edgemcp tools call set_device_properties --device-id <ID> --properties '{...}'`
调功能	`edgemcp tools call invoke_device_function --device-id <ID> --function <FN>`
查能力	`edgemcp tools call get_device_capabilities --device-id <ID> --format json`
EdgeComputer 设备	`edgecomputer device list --format json`
聚合健康	`edgecomputer edge health --format json`
EdgeClaw MCP 状态	`edgeclaw --format json mcp status edge-device`
重启服务	`service_control stop edgemcp && service_control start edgemcp`
命令自省	`edgemcp schema`

附录 B：练手 checklist

步骤	做什么	怎么确认
1	板子能 `hdc shell`	能执行 `edgemcp --version`
2	EdgeComputer 已就绪	`service status` 中 `ipc_ok: true`
3	MCP 服务正常	`health` 中 `mcp_listening: true`，`tool_count: 5`
4	列出子设备	`list_devices` 含 `edge-linux-001`
5	读取属性	`get_device_properties` 含 `cpu_usage`
6	EdgeClaw 联调（可选）	`mcp status` 中 `connected: true`

附录 C：五服务教程体系导航

顺序	服务	本地教程	角色	依赖
1	EdgeComputer	edgecomputer.md	JetLinks 网关	—
2	EdgeMCP	edgemcp.md（本文）	物模型 → MCP Tool	EdgeComputer
3	EdgeClaw	edgeclaw.md	AI 编排、自然语言控制 IoT	EdgeComputer + EdgeMCP
4	Edge Engine	edgeengine.md	端侧 CV/语音推理	NPU（RK3588）
5	EdgePipe	edgepipe.md	视觉流水线 YAML	Edge Engine

推荐路径：IoT 开发者 1→2→3；视觉 AI 开发者 4→5。

文档	路径
使用指南总览	/training/
EdgeMCP 架构设计	`extension/edge/edge_mcp/docs/edge-mcp-architecture-design.md`
EdgeClaw 集成指南	`extension/edge/edge_mcp/docs/edgeclaw-integration-guide.md`

附录 D：错误 JSON 格式

json

{
  "error": "mcp_unreachable",
  "message": "MCP initialize failed: \"Too many sessions\"",
  "retryable": true,
  "suggestion": "run 'service_control start edgemcp_service'"
}

附录 E：tool_metadata.json 结构

json

{
  "tools": {
    "list_devices": {
      "description_zh": "列出网关下所有子设备，返回 device_id、device_name、product_id、state。"
    },
    "get_device_capabilities": {
      "description_zh": "获取指定设备的物模型能力摘要，包括可读写属性、可调用服务、事件。"
    },
    "set_device_properties": {
      "description_zh": "向设备写入一个或多个属性，key 必须来自 get_device_capabilities。"
    }
  },
  "product_hints": {
    "zhimi.fan.v3": {
      "capabilities_hint": "风扇：开关/风速/摆头",
      "common_commands": [
        {"intent": "打开", "tool": "set_device_properties", "args": {"properties": {"power": true}}},
        {"intent": "关闭", "tool": "set_device_properties", "args": {"properties": {"power": false}}}
      ]
    }
  }
}

EdgeMCP 新手教程 ​

目录 ​

一、开始之前 ​

1.1 这份文档帮你做什么 ​

1.2 你需要准备 ​

1.3 CLI 用法 ​

二、连接开发板 ​

2.1 宿主机连接开发板 ​

2.2 确认 edgecomputer_service 已运行 ​

2.3 确认 edgemcp 已运行 ​

2.4 第一步验证 ​

三、快速跑通 ​

3.1 前置条件 ​

3.2 四步跑通 ​

步骤 1：确认 MCP 服务就绪 ​

步骤 2：查看工具列表 ​

步骤 3：列出子设备 ​

步骤 4：读取设备属性 ​

3.3 验收标准 ​

四、查看状态与设备数据 ​

4.1 edgemcp 服务状态 ​

edgemcp health ​

edgemcp dump ​

4.2 设备状态 ​

路径 A：EdgeComputer 直接查（底层） ​

路径 B：edgemcp 工具查（MCP 层） ​

4.3 EdgeClaw 侧 MCP 状态 ​

4.4 跨服务聚合健康 ​

4.5 常用查看命令 ​

4.6 分层诊断 ​

五、逻辑原理 ​

5.1 为什么需要 EdgeMCP ​

5.2 数据流 ​

5.3 TSL 到 MCP 映射 ​

5.4 设备目录轮询 ​

5.5 IPC 与 REST 双路径 ​

5.6 mcp_service.json 的 URL 约束 ​

六、功能一览 ​

6.1 模块总览 ​

6.2 核心模块 ​

6.3 五大 MCP 工具 ​

6.4 与其他服务的关系 ​

6.5 配置文件 ​

七、EdgeClaw 联调 ​

7.1 配置 mcp_service.json ​

7.2 启动与验证 ​

7.3 对话控制设备 ​

7.4 工具名映射 ​

7.5 与 edgemcp CLI 的分工 ​

八、命令手册 ​

8.1 命令树 ​

8.2 全局标志 ​

8.3 退出码 ​

8.4 health — 服务健康检查 ​

8.5 schema — 命令自省 ​

8.6 tools list — 工具定义 ​

8.7 tools call — 调用工具 ​

8.8 dump — 服务运行时摘要 ​

8.9 list_devices — 列出子设备 ​

8.10 get_device_properties — 读属性 ​

8.11 set_device_properties — 写属性 ​

8.12 invoke_device_function — 调功能 ​

8.13 get_device_capabilities — 查能力 ​

九、MCP 协议 ​

9.1 端点 ​

9.2 握手序列 ​

9.3 initialize 请求 ​

9.4 tools/call 示例 ​

9.5 MCP Resources（可选） ​

9.6 宿主机 curl 调试 ​

9.7 Python 调试脚本 ​

十、常见问题 ​

10.1 Too many sessions ​

10.2 bridge_connected=false ​

10.3 list_devices 为空 ​

10.4 EdgeClaw MCP not connected ​

10.5 属性读取超时 / Device not found ​

10.6 netstat TIME_WAIT ​

10.7 分层诊断命令汇总 ​

十一、附录 ​

EdgeMCP 新手教程

目录

一、开始之前

1.1 这份文档帮你做什么

1.2 你需要准备

1.3 CLI 用法

二、连接开发板

2.1 宿主机连接开发板

2.2 确认 edgecomputer_service 已运行

2.3 确认 edgemcp 已运行

2.4 第一步验证

三、快速跑通

3.1 前置条件

3.2 四步跑通

步骤 1：确认 MCP 服务就绪

步骤 2：查看工具列表

步骤 3：列出子设备

步骤 4：读取设备属性

3.3 验收标准

四、查看状态与设备数据

4.1 edgemcp 服务状态

`edgemcp health`

`edgemcp dump`

4.2 设备状态

路径 A：EdgeComputer 直接查（底层）

路径 B：edgemcp 工具查（MCP 层）

4.3 EdgeClaw 侧 MCP 状态

4.4 跨服务聚合健康

4.5 常用查看命令

4.6 分层诊断

五、逻辑原理

5.1 为什么需要 EdgeMCP

5.2 数据流

5.3 TSL 到 MCP 映射

5.4 设备目录轮询

5.5 IPC 与 REST 双路径

5.6 mcp_service.json 的 URL 约束

六、功能一览

6.1 模块总览

6.2 核心模块

6.3 五大 MCP 工具

6.4 与其他服务的关系

6.5 配置文件

七、EdgeClaw 联调

7.1 配置 mcp_service.json

7.2 启动与验证

7.3 对话控制设备

7.4 工具名映射

7.5 与 edgemcp CLI 的分工

八、命令手册

8.1 命令树

8.2 全局标志

8.3 退出码

8.4 health — 服务健康检查

8.5 schema — 命令自省

8.6 tools list — 工具定义

8.7 tools call — 调用工具

8.8 dump — 服务运行时摘要

8.9 list_devices — 列出子设备

8.10 get_device_properties — 读属性

8.11 set_device_properties — 写属性

8.12 invoke_device_function — 调功能

8.13 get_device_capabilities — 查能力

九、MCP 协议

9.1 端点

9.2 握手序列

9.3 initialize 请求

9.4 tools/call 示例

9.5 MCP Resources（可选）

9.6 宿主机 curl 调试

9.7 Python 调试脚本

十、常见问题

10.1 Too many sessions

10.2 bridge_connected=false

10.3 list_devices 为空

10.4 EdgeClaw MCP not connected

10.5 属性读取超时 / Device not found

10.6 netstat TIME_WAIT

10.7 分层诊断命令汇总

十一、附录