# ESP-IDF MCP over MQTT SDK [English](README.md) | [中文](README_CN.md) An implementation of Model Context Protocol (MCP) over MQTT 5.0 for ESP32 platform, developed based on the ESP-IDF framework. ## What is MCP? **Model Context Protocol (MCP)** is an open protocol for secure, structured communication between AI assistants and external data sources and tools. MCP allows AI assistants to: - Access external data sources and knowledge bases - Invoke external tools and services - Operate within secure boundaries - Interact with multiple data sources in a standardized way MCP defines clear interfaces and protocols, enabling AI assistants to safely extend their capabilities while maintaining control over data access. ## Why MCP over MQTT?  MQTT is a lightweight messaging protocol designed for IoT and edge computing. Combining MCP with MQTT brings the following advantages: ### Core Features - **Lightweight Transport**: Suitable for bandwidth-constrained network environments - **Reliable Message Delivery**: Supports QoS levels and message persistence - **Built-in Service Discovery**: MCP clients can automatically discover available MCP servers - **Load Balancing and Scalability**: Supports horizontal scaling of MCP server instances - **Flexible Access Control**: Implements fine-grained authorization through MQTT topic permissions ### Use Cases - **Edge Computing**: Deploy MCP servers on resource-constrained devices - **IoT Applications**: Provide AI capabilities for smart devices - **Cloud-Edge Collaboration**: Seamless integration between cloud AI and edge devices - **Real-time Communication**: Support low-latency AI tool invocation ## SDK Features ### Core Functionality - **MCP Server**: Complete MCP protocol implementation - **MQTT 5.0 Support**: Based on ESP-IDF MQTT client - **Tool Registration**: Support dynamic registration and invocation of MCP tools - **Resource Management**: Provide data resource access capabilities - **JSON-RPC**: Communication protocol based on JSON-RPC 2.0 ### Tool System ```c typedef struct { char *name; // Tool name char *description; // Tool description int property_count; // Number of parameters property_t *properties; // Parameter definitions const char *(*call)(int n_args, property_t *args); // Execution function } mcp_tool_t; ``` ### Resource Management ```c typedef struct { char *uri; // Resource URI char *name; // Resource name char *description; // Resource description char *mime_type; // MIME type char *title; // Resource title } mcp_resource_t; ``` ### Security Features - **TLS/SSL Support**: Support for MQTTS secure connections - **User Authentication**: Username/password authentication - **Certificate Verification**: Client certificate support - **Access Control**: Permission management based on MQTT topics ## Installation and Dependencies ### System Requirements - ESP-IDF v5.0 or higher - ESP32 series chips - MQTT Broker supporting MQTT 5.0 ### Dependencies ```yaml REQUIRES: - mqtt # ESP-IDF MQTT client - json # JSON parsing library ``` ### Installation Steps 1. Add this component to your ESP-IDF project 2. Add dependencies in `CMakeLists.txt` 3. Configure MQTT Broker connection parameters ## Quick Start ### Basic Usage Example ```c #include "mcp_server.h" // Define MCP tools mcp_tool_t my_tools[] = { { .name = "get_temperature", .description = "Get device temperature", .property_count = 0, .properties = NULL, .call = get_temperature_callback } }; // Initialize MCP server mcp_server_t *server = mcp_server_init( "esp32_sensor", // Server name "ESP32 Sensor MCP Server", // Description "mqtt://broker.example.com", // MQTT Broker URI "esp32_client_001", // Client ID "username", // Username "password", // Password NULL // Certificate (optional) ); // Register tools mcp_server_register_tool(server, 1, my_tools); // Start server mcp_server_run(server); ``` ### Tool Callback Function Example ```c const char* get_temperature_callback(int n_args, property_t *args) { // Read sensor data float temp = read_temperature_sensor(); // Return JSON formatted result static char result[64]; snprintf(result, sizeof(result), "{\"temperature\": %.2f}", temp); return result; } ``` ## Protocol Specification This SDK implements the [MCP over MQTT protocol specification](https://github.com/mqtt-ai/mcp-over-mqtt), supporting: - **Service Discovery**: Automatic discovery and registration of MCP servers - **Load Balancing**: Support for multi-instance deployment - **State Management**: Maintain MCP server state - **Access Control**: Permission control based on MQTT topics ## License This project is licensed under the [LICENSE](LICENSE) license. ## Related Links - [MCP Official Documentation](https://modelcontextprotocol.io/) - [MCP over MQTT Specification](https://github.com/mqtt-ai/mcp-over-mqtt) - [ESP-IDF Documentation](https://docs.espressif.com/projects/esp-idf/) - [MQTT Protocol Specification](https://mqtt.org/specification/) - [MCP over MQTT Python SDK](https://github.com/emqx/mcp-python-sdk)
aa5a40fbba04878bcbeb383c3e03b5943ee4973e
idf.py add-dependency "mqtt-ai/esp-mcp-over-mqtt^0.0.1"