stamplc-mcp-server-io

M5StamPLC MCP Server with OpenAI Voice Assistant

A Model Context Protocol (MCP) server implementation for M5StamPLC that enables AI-powered voice conversations using OpenAI's Realtime API.

Features

• 🤖 MCP Server: Full Model Context Protocol implementation
• 🎤 Voice Assistant: Natural voice conversations with OpenAI GPT-4o Mini Realtime
• 🔊 Speech-to-Text: Audio transcription using OpenAI Whisper
• 🗣️ Text-to-Speech: Natural voice responses using OpenAI TTS
• 🔌 PLC Control: Complete control over inputs, relays, and sensors
• 📊 Real-time Dashboard: Live status display on device screen
• 🌐 RESTful API: HTTP endpoints for device control
• 📡 Server-Sent Events: Real-time state updates via SSE

Hardware Requirements

• M5StamPLC device
• USB-C cable for programming
• WiFi network access
• OpenAI API key

Software Requirements

• PlatformIO IDE or CLI
• Python 3.x (for esptool)
• Git

Installation

1. Clone the Repository

git clone https://github.com/moecr7/stamplc-mcp-server-io.git
cd stamplc-mcp-server-io

2. Configure WiFi and API Keys

Copy the example configuration file:

cp wifi_config.h.example wifi_config.h

Edit wifi_config.h with your credentials:

const char* WIFI_SSID = "YourWiFiSSID";
const char* WIFI_PASSWORD = "YourWiFiPassword";
const char* OPENAI_API_KEY = "sk-your-openai-api-key";

Important: wifi_config.h is gitignored to protect your credentials. Never commit this file!

3. Install Dependencies

PlatformIO will automatically install required libraries:

• M5StamPLC library
• ArduinoJson
• ESPAsyncWebServer
• AsyncTCP

4. Build and Upload

Connect your M5StamPLC via USB and upload the firmware:

pio run --target upload

Monitor the serial output:

pio device monitor

Configuration

WiFi Setup

The device will automatically connect to WiFi on startup. The status LED will show:

• 🔴 Red: WiFi disconnected
• 🟢 Green: Time synchronized successfully
• ⚪ White: Normal operation
• 🔵 Blue: Incoming command

OpenAI API Key

Get your API key from OpenAI Platform and add it to wifi_config.h.

Note: The OpenAI Realtime API requires a paid account. Make sure you have sufficient credits.

Usage

MCP API Endpoints

Base URL

http://<device-ip>/mcp

Available Methods

Read Input

{
  "jsonrpc": "2.0",
  "method": "readInput",
  "params": {"inputNumber": 0},
  "id": 1
}

Write Relay

{
  "jsonrpc": "2.0",
  "method": "writeRelay",
  "params": {"relayNumber": 1, "state": true},
  "id": 2
}

Read Relay

{
  "jsonrpc": "2.0",
  "method": "readRelay",
  "params": {"relayNumber": 1},
  "id": 3
}

Get IO State

{
  "jsonrpc": "2.0",
  "method": "getIOState",
  "params": {},
  "id": 4
}

Get System Info

{
  "jsonrpc": "2.0",
  "method": "getSystemInfo",
  "params": {},
  "id": 5
}

Play Tone

{
  "jsonrpc": "2.0",
  "method": "tone",
  "params": {"frequency": 1000, "duration": 500},
  "id": 6
}

Voice Conversation API

Endpoint: POST /voice/chat

Request:

• Content-Type: audio/wav
• Body: Audio file (WAV format, 16kHz recommended)

Response:

{
  "success": true,
  "transcribed": "User's speech transcribed to text",
  "text": "AI assistant response",
  "audio": "base64-encoded MP3 audio response"
}

Example using curl:

curl -X POST http://192.168.100.97/voice/chat \
  -H "Content-Type: audio/wav" \
  --data-binary @audio.wav

Server-Sent Events

Connect to real-time updates:

curl http://192.168.100.97/events

Events include:

• Input states (8 inputs)
• Relay states (4 relays)
• Sensor data (temperature, voltage, current)
• Timestamp

Capabilities Endpoint

List all available MCP capabilities:

curl http://192.168.100.97/capabilities

Project Structure

stamplc-mcp-server-io/
├── src/
│   ├── stamplc-mcp-server.cpp    # Main application
│   ├── mcp_server.h/cpp           # MCP server implementation
│   ├── dashboard_ui.h/cpp         # Display UI
│   ├── openai_realtime.h/cpp      # OpenAI API integration
│   └── wifi_config-def.h          # Configuration template
├── examples/                      # Example code
├── platformio.ini                 # PlatformIO configuration
├── wifi_config.h.example         # Configuration template
└── README.md                      # This file

Relay Numbering

Relays are numbered from 0:

• relayNumber: 0 = Relay 1
• relayNumber: 1 = Relay 2
• relayNumber: 2 = Relay 3
• relayNumber: 3 = Relay 4

Input Numbering

Inputs are numbered from 0:

• inputNumber: 0 = Input 1
• inputNumber: 1 = Input 2
• ... up to inputNumber: 7 = Input 8

Troubleshooting

WiFi Connection Failed

• Check SSID and password in wifi_config.h
• Ensure WiFi is 2.4GHz (ESP32 doesn't support 5GHz)
• Check signal strength

OpenAI API Errors

• Verify API key is correct
• Check account has sufficient credits
• Ensure API key has access to Realtime API

Upload Failed

• Put device in bootloader mode (hold BOOT button, press RESET)
• Check USB cable connection
• Verify correct port in platformio.ini

Device Not Responding

• Check IP address on device display
• Verify device and computer are on same network
• Check firewall settings

Development

Building

pio run

Uploading

pio run --target upload

Monitoring

pio device monitor

Cleaning

pio run --target clean

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Author

Moein (moecr7)

Acknowledgments

• M5Stack for the M5StamPLC hardware
• OpenAI for the Realtime API
• PlatformIO for the development platform

Support

For issues and questions:

• Open an issue on GitHub
• Check the examples directory for usage examples
• Review the MCP protocol documentation

Changelog

v1.0.0

• Initial release
• MCP server implementation
• OpenAI voice assistant integration
• Real-time dashboard UI
• Complete PLC control capabilities