cloud
183 lines
4.9 KiB
Markdown
183 lines
4.9 KiB
Markdown
---
|
||
name: edge-mcp-tools
|
||
description: edge_collector 边缘侧本地模型与 MCP 工具接入规范。用于在鲁班猫/RK3566/RK3576/RK3588 等边缘设备部署本地模型后，设计或实现 MCP 工具服务，让模型安全调用网关状态、设备点位、历史数据、诊断、配置查询和运维只读能力。
|
||
---
|
||
|
||
# edge_collector MCP 工具接入
|
||
|
||
## 目标
|
||
|
||
让边缘侧本地模型可以通过受控工具访问网关能力，而不是直接读取任意文件、执行任意命令或绕过现有服务。
|
||
|
||
典型链路：
|
||
|
||
```text
|
||
本地模型
|
||
-> MCP Client
|
||
-> edge MCP tools
|
||
-> configurator / collector / 本地数据库 / 只读诊断命令
|
||
```
|
||
|
||
## 适用场景
|
||
|
||
- 在 RK3566/RK3576/RK3588 鲁班猫上部署 Qwen 等本地模型。
|
||
- 给本地模型增加“查询设备状态”“分析点位趋势”“解释报警”“读取网关状态”等工具。
|
||
- 把边缘侧诊断能力封装成 AI 可调用工具。
|
||
- 设计 MCP 工具权限、输入输出和安全边界。
|
||
|
||
## 设计原则
|
||
|
||
- 默认只读。
|
||
- 工具服务独立运行，不耦合 `edge` 主服务。
|
||
- 本地模型不直接访问数据库文件、配置文件和 shell。
|
||
- 所有工具必须有明确输入 schema、输出 schema 和错误语义。
|
||
- 写配置、重启服务、删除数据等高风险动作第一版不开放。
|
||
- 工具返回用户可理解信息，不泄露密钥、路径、Token、内部模型配置。
|
||
|
||
## 推荐第一版工具
|
||
|
||
优先做只读工具：
|
||
|
||
- `edge_get_gateway_status`：读取网关状态、版本、运行时间。
|
||
- `edge_list_devices`：列出设备名称、协议、在线状态。
|
||
- `edge_list_points`：列出某设备点位名称、类型、单位。
|
||
- `edge_read_latest_values`：读取指定设备/点位最新值。
|
||
- `edge_query_history_summary`：查询历史数据摘要，不返回超大原始数据。
|
||
- `edge_get_alarm_summary`：读取报警或异常摘要。
|
||
- `edge_get_network_status`：读取网络、WiFi、4G、端口转发只读状态。
|
||
- `edge_get_service_health`：读取 `edge`、独立 agent 状态。
|
||
|
||
暂不开放：
|
||
|
||
- 修改协议配置。
|
||
- 保存 AI Key。
|
||
- 重启服务。
|
||
- 删除缓存或历史数据。
|
||
- 执行任意 shell。
|
||
- 读取任意文件。
|
||
|
||
## 工具命名
|
||
|
||
- 使用 `edge_` 前缀。
|
||
- 动词清晰：`get`、`list`、`query`、`analyze`。
|
||
- 避免泛化工具名，例如 `run_command`、`read_file`。
|
||
|
||
## 输入输出
|
||
|
||
输入必须限制范围：
|
||
|
||
```text
|
||
gateway_id
|
||
device_id 或 device_name
|
||
point_id 或 point_name
|
||
time_range
|
||
limit
|
||
```
|
||
|
||
输出建议结构：
|
||
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"data": {},
|
||
"warnings": [],
|
||
"source": "configurator",
|
||
"timestamp": "2026-06-16T00:00:00+08:00"
|
||
}
|
||
```
|
||
|
||
错误要可行动：
|
||
|
||
```json
|
||
{
|
||
"ok": false,
|
||
"error_code": "DEVICE_NOT_FOUND",
|
||
"message": "未找到指定设备，请确认设备名称或 ID",
|
||
"suggestion": "可先调用 edge_list_devices 查看可用设备"
|
||
}
|
||
```
|
||
|
||
## 与现有服务集成
|
||
|
||
优先通过现有 API 或受控本地接口访问：
|
||
|
||
- `configurator` API。
|
||
- `collector` 状态接口或已有数据接口。
|
||
- 本地只读数据库查询。
|
||
- systemd 只读状态命令。
|
||
|
||
不要绕过业务逻辑直接修改配置文件。
|
||
|
||
## 本地模型注意
|
||
|
||
参考已有本地模型文档：
|
||
|
||
- `docs/本地模型/Qwen2.5-0.6B-Instruct在RK3566本地部署方案.md`
|
||
- `docs/本地模型/Qwen2.5-VL-3B-Instruct在RK3576鲁班猫3边缘图文模型部署方案.md`
|
||
- `docs/本地模型/Qwen2.5-14B-Instruct在16G_RK3588鲁班猫5部署方案.md`
|
||
|
||
设计工具时必须考虑：
|
||
|
||
- 模型上下文有限，工具返回要摘要化。
|
||
- RK3566/RK3576 资源有限，工具查询要分页、限流。
|
||
- 大历史数据先聚合摘要，再按需返回异常片段。
|
||
- 离线运行时不要依赖云端 AI Provider。
|
||
|
||
## 安全边界
|
||
|
||
结合 `edge-security-secrets`：
|
||
|
||
- 不返回 API Key、JWT、MQTT 密码、SSH 密码。
|
||
- 不暴露真实配置文件完整内容。
|
||
- 不开放任意命令执行。
|
||
- 日志中记录工具名、参数摘要、耗时、结果状态，不记录敏感值。
|
||
- 对外接口只监听本机或受控内网，默认不暴露公网。
|
||
|
||
## 部署方式
|
||
|
||
第一版建议使用 Python 独立 agent：
|
||
|
||
- 遵循 `edge-python-agent`。
|
||
- 使用 systemd 独立托管。
|
||
- 配置文件动态生成但不覆盖已有配置。
|
||
- 打包和同步遵循 `edge-config-lifecycle`。
|
||
|
||
服务名建议：
|
||
|
||
```text
|
||
edge-mcp-tools
|
||
```
|
||
|
||
## 验证计划
|
||
|
||
至少验证：
|
||
|
||
- 工具列表可发现。
|
||
- 每个工具 schema 正确。
|
||
- 正常查询返回结构化数据。
|
||
- 设备不存在、点位不存在、时间范围过大时错误可理解。
|
||
- 返回内容脱敏。
|
||
- 大数据查询有 limit 或摘要。
|
||
- 服务重启后配置保留。
|
||
- 本地模型能完成一个端到端问题，例如“分析最近 1 小时某设备是否异常”。
|
||
|
||
## 文档输出
|
||
|
||
设计 MCP 工具时输出：
|
||
|
||
```markdown
|
||
## 工具清单
|
||
|
||
## 权限边界
|
||
|
||
## 输入输出 schema
|
||
|
||
## 数据来源
|
||
|
||
## 部署方式
|
||
|
||
## 安全与脱敏
|
||
|
||
## 验证计划
|
||
```
|