三端物联网平台初步搭建（MCP-ready 架构）

项目地址

https://mcp-server.fuufhjn.link

一、阶段性概述

目前已完成一个前端—云端—终端三端稳定通信的物联网平台原型，支持：

• 前端与终端双向通信（控制 / 状态上报）
• 多终端同时在线
• 设备状态可视化与基础控制

现阶段的系统已经具备完整的工程闭环。后续工作的重点不是继续堆功能，而是对现有通信与控制逻辑进行抽象升级，使其满足 MCP（Model Context Protocol）对“可调用工具”的结构化要求，为后续引入大模型提供下层支撑。

二、技术栈说明

1. 前端

• 框架：React + TypeScript
• UI：Mantine 组件库
• 部署：Cloudflare Pages
• 访问地址：https://mcp-server.fuufhjn.link

前端当前定位为设备控制与状态展示界面。 每个设备拥有独立的功能页面，用于验证通信可靠性与控制正确性，后续将作为 MCP 上层的“人类交互入口”。

2. 后端（云端）

• 框架：Hono
• 部署：Cloudflare Workers
• 数据库：Cloudflare D1
• API Base：https://mcp-server.fuufhjn.link/api

后端按功能对接口与路由进行模块化封装。当前设计中，每新增一种设备类型，只需：

• 定义对应的 TypeScript 接口
• 注册对应路由即可完成扩展，具备良好的可维护性。

后续该层将演进为 MCP Server，用于向上暴露标准化的“设备控制工具”。

3. 终端

• 硬件：ESP32 / ESP32-C3（混合测试）
  • 在 WS2812 灯珠测试中，ESP32 老板子存在电压倒灌现象，临时使用 Seeed Studio ESP32-C3 替代
• 软件框架：Arduino

终端代码采用逻辑分离设计：

• WiFi 连接
• 心跳与通信
• 硬件驱动（屏幕 / 灯珠 / 传感器）

均封装为独立服务模块，主程序仅负责任务调度，便于后续扩展新硬件或统一控制接口。

三、已实现功能

目前接入了 3 个 ESP32 终端（主要用于通信与架构验证，非最终硬件选型）：

1. 温湿度采集终端

https://mcp-server.fuufhjn.link/function/telemetry

• 终端上电后每 5 秒上传一次温湿度数据
• 前端可实时显示当前值
• 支持查看历史趋势图（近一段时间的温湿度变化）

2. 屏幕显示终端

https://mcp-server.fuufhjn.link/function/screen

• 终端上下线状态可在前端实时显示
• 当前端输入字符串并发送后，终端 OLED 屏幕实时显示对应内容

3. LED 灯珠控制终端

https://mcp-server.fuufhjn.link/function/led

• 终端在线状态实时同步
• 前端通过色盘与亮度滑块输入参数
• 终端 LED 灯珠按输入值显示颜色与亮度

四、系统通信设计

1. 终端 → 云端（数据上报）

终端内部定义统一的 tick() 服务，用于：

• 检查 WiFi 联通性
• 校验时间戳
• 按固定周期向云端上传数据

以温湿度设备为例，上传数据格式如下：

export interface TelemetryData {
  deviceId: string;
  temperature: number;
  humidity: number;
}

后端通过 POST 接口接收数据并存入数据库。前端通过 /api/telemetry/latest 获取最新数据（时间字段在后端统一做 UTC → 本地时间修正）。

2. 云端 → 终端（控制与下发）

由于后端部署在云端而非局域网，采用终端主动轮询 + 云端缓冲的方式实现可靠通信。

（1）设备注册

终端在 setup 阶段连接 WiFi 后，调用注册接口，上传设备标识（当前使用 deviceId，后续可替换为 UUID）：

• 若设备不存在，则写入设备表并返回注册成功
• 若设备已存在，直接返回成功

（2）心跳与消息获取

终端按固定时间间隔向对应接口发送心跳请求，例如屏幕设备：

export interface ScreenHeartbeatRequest {
  deviceId: string;
}

后端处理逻辑：

• 更新设备表中的 last_heartbeat
• 查询“待发消息表”
• 若存在待发消息，则返回最早一条

前端判断设备是否在线的标准为：60 秒内是否收到心跳。

（3）缓冲区设计说明

当前端向设备发送控制指令时，该指令不会直接推送到终端，而是：

1. 写入“待发消息表”
2. 等待终端下次心跳轮询获取

这种设计的优势：

• 降低前端、后端、终端之间的耦合度
• 避免依赖云端内存状态
• 适合 Cloudflare Workers 这类无状态运行环境

当终端成功取走消息后，该消息即从表中删除。

（4）终端执行

终端收到待发消息后，调用本地显示或控制服务执行操作；若心跳响应为空，则维持当前状态不变。

五、面向 MCP 的设计思路（下层功能）

当前系统已经具备清晰的 “设备注册 → 状态上报 → 控制下发” 闭环。下一阶段的核心工作是：

将现有设备控制接口抽象为“语义明确、参数规范、可被模型调用的工具（Tool）”，以符合 MCP 协议对下层系统的要求。

重点包括：

• 将设备能力抽象为统一的 action + params 形式
• 在云端集中管理设备能力与状态
• 为 MCP Server 提供稳定、确定性的工具接口（本课题不涉及 agent、规划或自主决策层）

六、后续计划

1. 接入并测试更多终端设备（如电机、其他传感器），确定最终硬件方案并完善驱动代码；
2. 在现有后端基础上实现 MCP Server 的下层功能，对外暴露标准化设备控制工具；
3. 根据需要继续完善前端展示层（必要时考虑 React Native 作为移动端）；
4. 经过调研，决定不引入 MQTT 等消息中间件：在终端数量较少的前提下，引入中间件会增加系统复杂度，当前轮询 + 缓冲方案更符合课题目标。