---
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

## 数据来源

## 部署方式

## 安全与脱敏

## 验证计划
```