JinDaGe - ESP32MCPServer MCP Details

article

README

🚀 ESP32 MCP 服务器

ESP32 MCP 服务器是一个专为 ESP32 微控制器设计的模型上下文协议（MCP）实现方案。它借助基于 WebSocket 的接口，实现了资源发现和监控功能，为相关应用提供了有力支持。

🚀 快速开始

状态说明

当前项目处于无法编译的状态，初始提交内容保持不变。此 README 使用 Claude 3.5 Sonet 在提交日期创建（带有明显的修复，例如自动格式化等）。

架构图

✨ 主要特性

MCP 协议实现：支持 MCP 协议 v0.1.0 版本。
实时更新：基于 WebSocket 实现实时更新功能。
资源管理：可进行资源发现和监控。
WiFi 配置：能通过网页界面配置 WiFi。
线程安全：请求处理具备线程安全特性。
测试套件：拥有全面的测试套件。
服务器集成：集成了异步 Web 服务器。
存储支持：支持 LittleFS 用于配置存储。

📦 安装指南

先决条件

硬件

ESP32 S3 开发板（DevKitC - 1）
用于编程的 USB 电缆

软件

PlatformIO Core（CLI）或 PlatformIO IDE
Python 3.7 或更高版本
Git

安装步骤

克隆仓库：

git clone [仓库链接]
cd ESP32 - MCP - Server

安装依赖项：

运行`pio pkg install`

配置项目（可选）：
- 编辑平台配置文件（platformio.ini）
- 根据需要修改配置选项

💻 使用示例

网络配置

打开网页界面，访问：

http://[ESP32 IP地址]:8096

在“网络设置”部分输入以下信息：
- SSID：目标 WiFi 网络的名称
- 密码：目标 WiFi 网络的密码
点击“保存并重启”以应用更改。

MCP 连接

打开终端，连接到 ESP32 的串口：

串口工具 -> 选择正确的端口和波特率（通常为115200）

在 ESP32 启动后，通过 WebSocket 客户端或工具（如 wscat）连接到 ESP32：

wscat -H [ESP32 IP地址]:8096

发送以下命令以查询 MCP 状态：

{"id": 1, "method": "get_status"}

📚 详细文档

架构

flowchart TD
    Start[开始应用程序] --> Setup[设置]
    Setup -->|初始化文件系统| InitFS[初始化LittleFS]
    Setup -->|启动网络| StartNetwork[初始化网络管理器]
    Setup -->|创建任务| CreateTasks[创建和分配任务]

    subgraph 网络
        StartNetwork --> APCheck[检查AP或连接模式]
        APCheck -->|凭据存在| Connect[连接到WiFi]
        APCheck -->|无凭据| StartAP[启动访问点]
        Connect --> NetworkReady[网络准备就绪]
        StartAP --> NetworkReady
    end

    subgraph MCP_Server
        MCP[启动MCP服务器] --> HandleClient[处理客户端连接]
        HandleClient --> HandleRequest[处理请求]
        HandleRequest -->|WebSocket事件| WebSocket[处理WebSocket]
        HandleRequest -->|HTTP端点| HTTP[处理HTTP请求]
    end

    subgraph Metrics
        self[开始指标系统] --> InitMetrics[初始化系统指标]
        InitMetrics --> CollectMetrics[定期收集指标]
        CollectMetrics --> SaveMetrics[将指标保存到文件系统中]
    end

    subgraph Logger
        self[启动uLogger] --> LogMetrics[记录指标数据]
        LogMetrics --> CompactLogs[必要时合并日志]
        CompactLogs -->|生成报告| Report[生成报告]
    end

    CreateTasks --> InitMetrics
    CreateTasks --> StartNetwork

测试

基本测试

运行以下命令以启动测试套件：

pio test -e native

覆盖报告

生成覆盖报告：

pio test -e native -- --coverage

报告将保存在 .pio/coverageresults 文件夹中。

贡献指南

Fork 本仓库到您的账户。
创建一个新的分支用于您的功能或修复：

git checkout -b feature/[功能名称] 或 bugfix/[问题编号]

提交您的更改并添加详细的提交信息：

git add .
git commit -m "描述您的更改"

推送到您的仓库：

git push origin feature/[功能名称]

创建拉取请求到主分支。

📄 许可证

本项目受 MIT License 许可，详情请参阅 LICENSE 文件。

ESP32MCPServer