ESP-IDF FastMCP Server

# ESP-IDF MCP Server 设计文档 ## 1. 概述 ESP-IDF MCP Server 是一个基于 FastMCP 框架构建的服务，旨在为 ESP-IDF (Espressif IoT Development Framework) 开发者提供便捷的工具访问。该服务器通过 MCP (Model Control Protocol) 协议提供服务，允许客户端访问 ESP-IDF 的相关工具。 ## 2. 功能特性 ### 2.1 工具功能 - `get_esp_idf_version`: 获取当前安装的 ESP-IDF 版本信息 - `list_esp_targets`: 列出所有支持的 ESP 芯片型号 - `list_serial_ports`: 列出系统中的串口设备 - `select_serial_port`: 选择ESP-IDF操作的目标串口 - `get_selected_serial_port`: 获取当前选择的串口设备 - `compile_project`: 编译ESP-IDF项目 - `clean_project`: 清理ESP-IDF项目 ## 3. 架构设计 ### 3.1 系统架构 ``` +------------------+ MCP Protocol +------------------+ | MCP Client | <-----------------> | ESP-IDF MCP Server| +------------------+ +------------------+ | FastMCP Core | +------------------+ | Tool Functions | +------------------+ | ESP-IDF Tools | +------------------+ ``` ### 3.2 核心组件 #### 3.2.1 FastMCP Server 基于 FastMCP 框架构建的服务器实例，负责： - 注册和管理工具函数 - 处理 MCP 客户端请求 - 提供 HTTP 接口 #### 3.2.2 工具函数模块 实现各种 ESP-IDF 相关的工具函数，包括： - 系统信息查询工具 - 串口设备管理工具 - 项目编译和清理工具 ### 3.3 项目结构 ``` espidf-mcp/ ├── app.py # 主入口点 ├── core/ # 核心配置模块 │ ├── config.py # FastMCP实例和ESP-IDF环境初始化 ├── docs/ # 文档 ├── fastmcp.json # FastMCP配置文件 ├── requirements.txt # 依赖列表 ├── simple_server.py # 旧版服务器实现（已废弃） ├── tools/ # 工具函数模块 │ ├── esp_idf_tools.py # ESP-IDF相关工具 │ ├── serial_tools.py # 串口设备相关工具 └── tests/ # 测试文件 ``` ## 4. API 接口 ### 4.1 工具接口 #### get_esp_idf_version - **描述**: 获取当前安装的 ESP-IDF 版本信息 - **参数**: 无 - **返回值**: ESP-IDF 版本信息字符串 #### list_esp_targets - **描述**: 列出所有支持的 ESP 芯片型号 - **参数**: 无 - **返回值**: 支持的 ESP 芯片型号列表 #### list_serial_ports - **描述**: 列出系统中所有包含有效描述的串口设备（过滤掉描述为'n/a'的设备） - **参数**: 无 - **返回值**: 串口设备列表，每个设备包含设备路径、描述和硬件ID #### select_serial_port - **描述**: 选择ESP-IDF操作的目标串口设备，该选择将对所有需要串口操作的工具生效 - **参数**: `port_device` (str) - 要选择的串口设备路径 - **返回值**: 成功选择的确认消息 #### get_selected_serial_port - **描述**: 获取当前选择的串口设备 - **参数**: 无 - **返回值**: 当前选择的串口设备路径，如果没有选择则返回"No port selected" #### compile_project - **描述**: 编译指定路径的ESP-IDF项目，返回编译过程的标准输出和标准错误 - **参数**: `project_path` (str) - ESP-IDF项目的路径 - **返回值**: 包含返回码、标准输出和标准错误的字典 #### clean_project - **描述**: 清理指定路径的ESP-IDF项目 - **参数**: `project_path` (str) - ESP-IDF项目的路径 - **返回值**: 包含返回码、标准输出和标准错误的字典 ## 5. 部署与配置 ### 5.1 环境要求 - Python 3.8 或更高版本 - FastMCP 库 - ESP-IDF 开发环境 (位于 `~/esp/esp-idf`) ### 5.2 ESP-IDF 路径约定 ESP-IDF 必须安装在用户的主目录下的 `esp/esp-idf` 文件夹中，即： ``` ~/esp/esp-idf/ ``` ### 5.3 环境变量初始化 服务器在启动时会使用 ESP-IDF 提供的 `export.sh` 脚本来初始化环境变量，而不是在每次工具调用时重新初始化，以提高性能： - 脚本路径: `~/esp/esp-idf/export.sh` - 此脚本会设置所有必要的环境变量，包括 `IDF_PATH`、`PATH` 以及工具链相关的变量 - 环境变量在服务器启动时初始化一次，并在所有工具调用中复用 ### 5.4 安装步骤 1. 克隆项目代码: ```bash git clone <repository_url> cd espidf-mcp ``` 2. 安装依赖: ```bash pip install -r requirements.txt ``` 3. 确保 ESP-IDF 安装在正确路径: ``` ~/esp/esp-idf/ ``` 4. 确保 `~/esp/esp-idf/export.sh` 脚本存在且可执行 ### 5.5 运行服务器 有两种方式运行server： #### 方法1：直接运行Python文件 ```bash python app.py ``` 这将在`http://127.0.0.1:8080`上启动HTTP服务器。 #### 方法2：使用fastmcp配置文件（推荐） ```bash fastmcp run fastmcp.json ``` 这种方法使用声明式配置文件来定义服务器参数。 ### 5.6 自定义配置 可以通过以下方式自定义服务器配置： 1. 修改`app.py`文件中的`mcp.run()`参数： ```python mcp.run(transport="streamable-http", host="127.0.0.1", port=8080) ``` 2. 编辑`fastmcp.json`配置文件： ```json { "mcpServers": { "esp-idf-server": { "command": "python", "args": ["app.py"], "transport": "streamable-http", "url": "http://127.0.0.1:8080" } } } ``` 可以更改host、port或transport类型来满足具体需求。 ## 6. 使用说明 ### 6.1 连接服务器 MCP 客户端可以通过 `http://127.0.0.1:8080/mcp` 连接到服务器。 ### 6.2 调用工具 客户端可以列出并调用已注册的工具函数： - `get_esp_idf_version` - `list_esp_targets` - `list_serial_ports` - `select_serial_port` - `get_selected_serial_port` - `compile_project` - `clean_project` ## 7. 扩展与定制 ### 7.1 添加新工具 在 `app.py` 中使用 `@mcp.tool` 装饰器添加新的工具函数。 ## 8. 故障排除 ### 8.1 服务器无法启动 - 检查 Python 环境和依赖是否正确安装 - 确认端口 8080 未被占用 - 检查`fastmcp.json`配置文件是否正确 ### 8.2 工具调用失败 - 检查 ESP-IDF 是否正确安装在 `~/esp/esp-idf` 路径 - 确认 `~/esp/esp-idf/export.sh` 脚本存在且可执行 - 检查环境变量是否正确设置 ### 8.3 串口相关问题 - 确认用户具有访问串口设备的权限（通常需要将用户添加到`dialout`组） - 检查串口设备是否被其他程序占用 - 在某些系统上，可能需要安装额外的驱动程序 ### 8.4 编译项目失败 - 确认项目路径正确且包含有效的ESP-IDF项目结构 - 检查项目是否已正确配置目标芯片 - 确认有足够的磁盘空间和内存进行编译