MCP Prompts Server

{
  "id": "esp32-mcp-server-http-api-integration",
  "name": "ESP32 MCP Server HTTP API Integration",
  "description": "Expose ESP32 device capabilities via HTTP API compatible with mcp-prompts",
  "content": "# ESP32 MCP Server HTTP API Integration\n\n## Problem\nExpose ESP32 device capabilities (BPM detection, sensor data, device status) via HTTP API that can be consumed by MCP servers and web clients.\n\n## Solution: AsyncWebServer Setup\n\n### 1. Initialize HTTP Server\n```cpp\n#include <ESPAsyncWebServer.h>\n\nAsyncWebServer* httpServer = nullptr;\n\nvoid setup() {\n    // ... WiFi setup ...\n    \n    // Create server on port 80\n    httpServer = new AsyncWebServer(80);\n    \n    // Start server\n    httpServer->begin();\n    Serial.println(\"HTTP server started on port 80\");\n}\n```\n\n### 2. Basic Health Check Endpoint\n```cpp\nhttpServer->on(\"/api/v1/system/health\", HTTP_GET, [](AsyncWebServerRequest *request) {\n    String json = \"{\";\n    json += \"\\\"status\\\":\\\"ok\\\",\";\n    json += \"\\\"uptime\\\":\" + String(millis() / 1000) + \",\";\n    json += \"\\\"free_heap\\\":\" + String(ESP.getFreeHeap()) + \",\n    json += \"\\\"wifi_connected\\\":\" + String(WiFi.status() == WL_CONNECTED ? \"true\" : \"false\");\n    json += \"}\";\n    \n    request->send(200, \"application/json\", json);\n});\n```\n\n### 3. Device Status Endpoint\n```cpp\nhttpServer->on(\"/api/v1/system/status\", HTTP_GET, [](AsyncWebServerRequest *request) {\n    IPAddress apIP = WiFi.softAPIP();\n    int numClients = WiFi.softAPgetStationNum();\n    \n    String json = \"{\";\n    json += \"\\\"mode\\\":\\\"ap\\\",\";\n    json += \"\\\"ssid\\\":\\\"ESP32-BPM-Detector\\\",\";\n    json += \"\\\"ip\\\":\\\"\" + apIP.toString() + \"\\\",\";\n    json += \"\\\"clients\\\":\" + String(numClients) + \",\";\n    json += \"\\\"heap_free\\\":\" + String(ESP.getFreeHeap());\n    json += \"}\";\n    \n    request->send(200, \"application/json\", json);\n});\n```\n\n### 4. BPM Data Endpoint (with FlatBuffers)\n```cpp\n#include \"bpm_flatbuffers.h\"\n\nextern BPMDetector* bpmDetector;\n\nhttpServer->on(\"/api/v1/bpm/current\", HTTP_GET, [](AsyncWebServerRequest *request) {\n    if (!bpmDetector) {\n        request->send(500, \"application/json\", \n            \"{\\\"error\\\":\\\"BPM detector not initialized\\\"}\");\n        return;\n    }\n    \n    // Get current BPM reading\n    auto bpmData = bpmDetector->detect();\n    \n    // Create JSON response\n    String json = \"{\";\n    json += \"\\\"bpm\\\":\" + String(bpmData.bpm, 1) + \",\";\n    json += \"\\\"confidence\\\":\" + String(bpmData.confidence, 3) + \",\";\n    json += \"\\\"signal_level\\\":\" + String(bpmData.signal_level, 2) + \",\";\n    json += \"\\\"timestamp\\\":\" + String(millis());\n    json += \"}\";\n    \n    request->send(200, \"application/json\", json);\n});\n```\n\n### 5. CORS Headers for Web UI\n```cpp\n// Add CORS middleware\nhttpServer->on(\"*\", HTTP_OPTIONS, [](AsyncWebServerRequest *request) {\n    AsyncWebServerResponse *response = request->beginResponse(200);\n    response->addHeader(\"Access-Control-Allow-Origin\", \"*\");\n    response->addHeader(\"Access-Control-Allow-Methods\", \"GET, POST, OPTIONS\");\n    response->addHeader(\"Access-Control-Allow-Headers\", \"Content-Type\");\n    request->send(response);\n});\n\n// Apply CORS to all responses\nhttpServer->onNotFound([](AsyncWebServerRequest *request) {\n    AsyncWebServerResponse *response = request->beginResponse(404, \"text/plain\", \"Not Found\");\n    response->addHeader(\"Access-Control-Allow-Origin\", \"*\");\n    request->send(response);\n});\n```\n\n## API Endpoint Structure\n\n### Recommended Endpoints\n```\nGET  /api/v1/system/health      # Health check\nGET  /api/v1/system/status       # Device status\nGET  /api/v1/bpm/current        # Current BPM reading\nGET  /api/v1/bpm/history        # BPM history (if buffered)\nPOST /api/v1/config/update      # Update device configuration\nGET  /api/v1/sensors/list       # Available sensors\n```\n\n## Testing\n\n### From Command Line\n```bash\n# Health check\ncurl http://192.168.4.1/api/v1/system/health\n\n# Device status\ncurl http://192.168.4.1/api/v1/system/status | jq .\n\n# BPM data\ncurl http://192.168.4.1/api/v1/bpm/current | jq .\n\n# With verbose output\ncurl -v http://192.168.4.1/api/v1/system/health\n```\n\n### Expected Responses\n```json\n// GET /api/v1/system/health\n{\n  \"status\": \"ok\",\n  \"uptime\": 12345,\n  \"free_heap\": 245678,\n  \"wifi_connected\": true\n}\n\n// GET /api/v1/bpm/current\n{\n  \"bpm\": 120.5,\n  \"confidence\": 0.85,\n  \"signal_level\": 0.72,\n  \"timestamp\": 12345678\n}\n```\n\n## Error Handling\n\n### Standard Error Response Format\n```cpp\nvoid sendError(AsyncWebServerRequest *request, int code, const char* message) {\n    String json = \"{\";\n    json += \"\\\"error\\\":\\\"\" + String(message) + \"\\\",\";\n    json += \"\\\"code\\\":\" + String(code) + \",\";\n    json += \"\\\"timestamp\\\":\" + String(millis());\n    json += \"}\";\n    \n    request->send(code, \"application/json\", json);\n}\n\n// Usage\nif (!bpmDetector) {\n    sendError(request, 500, \"BPM detector not initialized\");\n    return;\n}\n```\n\n## Memory Considerations\n\n### AsyncWebServer Memory Usage\n- Base server: ~8KB RAM\n- Each connection: ~1KB RAM\n- Request buffers: ~2KB per active request\n- **Total**: ~15-20KB for typical usage\n\n### Optimization Tips\n```cpp\n// Limit concurrent connections\nhttpServer->begin();\n// Default: 5 connections\n// Can be adjusted in AsyncWebServer constructor\n\n// Use streaming for large responses\nrequest->beginResponse(\"application/json\", streamProvider);\n\n// Minimize JSON string concatenation\n// Use ArduinoJson library for better performance\n```\n\n## Security Considerations\n\n### Basic Authentication (Optional)\n```cpp\nhttpServer->on(\"/api/v1/config/update\", HTTP_POST, \n    [](AsyncWebServerRequest *request) {\n        // Check Authorization header\n        if (!request->hasHeader(\"Authorization\")) {\n            request->send(401, \"application/json\", \n                \"{\\\"error\\\":\\\"Unauthorized\\\"}\");\n            return;\n        }\n        // ... process request ...\n    });\n```\n\n### Rate Limiting (Future Enhancement)\n```cpp\n// Track request timestamps per IP\n// Limit to N requests per minute\n```\n\n## Integration with MCP Servers\n\n### Example MCP Tool Using ESP32 API\n```javascript\n// In MCP server code\ntools: [\n  {\n    name: 'get_esp32_bpm',\n    description: 'Get current BPM reading from ESP32 device',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        device_ip: { type: 'string', default: '192.168.4.1' }\n      }\n    }\n  }\n]\n\n// Implementation\nasync function get_esp32_bpm(device_ip) {\n  const response = await fetch(`http://${device_ip}/api/v1/bpm/current`);\n  return await response.json();\n}\n```\n\n## Related Patterns\n\n- Use with `esp32-network-ap-mode-configuration` for network setup\n- Combine with `esp32-flatbuffers-schema-sync-workflow` for data serialization\n- See `embedded-audio-fft-memory-constraints` for memory optimization\n\n## Success Metrics\n\n- **Response Time**: < 100ms for typical endpoints\n- **Concurrent Connections**: Support 5+ simultaneous clients\n- **Uptime**: Server remains responsive for > 24 hours\n- **Memory Stability**: Free heap stays > 50KB during operation",
  "isTemplate": false,
  "tags": ["embedded", "esp32", "mcp", "http-server", "api", "integration"],
  "category": "esp32",
  "version": 1,
  "createdAt": "2026-01-01T03:00:00.000Z",
  "updatedAt": "2026-01-01T03:00:00.000Z",
  "metadata": {
    "context": ["embedded", "esp32", "mcp", "http-server"],
    "problem": "Expose ESP32 device capabilities via HTTP API compatible with mcp-prompts",
    "success_count": 1,
    "confidence": "low",
    "related_prompts": [
      "esp32-network-ap-mode-configuration",
      "esp32-flatbuffers-schema-sync-workflow",
      "embedded-audio-fft-memory-constraints"
    ]
  }
}