mbotmcp

# MBotMcp https://github.com/user-attachments/assets/a11d68c5-dc52-4dab-9741-bc1cf47e2ec9 This project demonstrates how to control an mBot2 robot using Spring AI and Model Context Protocol (MCP). With this setup, AI models can control a physical robot through simple natural language commands like "explore" or "turn left". ## Overview The system consists of: 1. A Spring Boot application that implements the Model Context Protocol 2. An MQTT broker for message passing 3. Python code running on the mBot2 robot 4. AI client integration capabilities The Spring application exposes robot control commands as AI-callable functions, allowing AI models to control the physical robot through natural language. ## Prerequisites - Java 21 - Maven - mBot2 robot and mBlock IDE - MQTT broker (can run in Docker) - Basic Java knowledge ## Setup Instructions ### 1. MQTT Broker Setup (Optional, if you don't have one) Run the included Docker Compose file to set up the MQTT broker: ```bash cd mbotmcp/assets docker-compose up -d ``` This creates a message queue that will relay commands between your app and robot. ### 2. Configure Spring Boot Application Set the following environment variables: ``` MQTT_USERNAME=your_username # leave blank if not configured MQTT_PASSWORD=your_password # leave blank if not configured MQTT_SERVER_URI=tcp://your_server:1883 ``` These tell your app how to connect to the MQTT broker. ### 3. mBot2 Setup To upload the Python script to your mBot2: 1. Connect your mBot2 to your computer via USB 2. Open the mBlock IDE on your computer 3. Click on the "File" menu and select "Open" 4. Navigate to the `/assets` directory in the repository 5. Open the `mbot-mqtt.py` file 6. Modify the script to include your personal WiFi and MQTT configurations: ```python ssid = "<your wifi ssid>" ssid_password = "<your wifi password>" mqtt_ip = "<ip of the mqtt broker>" mqtt_port = 1883 mqtt_user = "<your mqtt username>" mqtt_password = "<your mqtt password>" ``` 7. Upload the script to your mBot2 8. Power on your mBot2 ### 4. Build the Spring Boot App ```bash mvn clean package ``` ## Testing the Setup 1. Ensure your MQTT broker is running 2. Power on your mBot2 and ensure it's connected to WiFi 3. Run the test client: ```bash mvn test -Dtest=ClientStdioTest ``` 4. Watch your robot perform the "beep" command with blue LED lights! ## Available Robot Commands The BotService class defines all the MCP tools, your robot can understand: - `mbotExplore()` - Execute the 'explore' routine - `mbotStop()` - Stop the robot - `mbotBeep()` - Make the robot beep - `mbotLeft()` - Turn the robot left - `mbotRight()` - Turn the robot right - `mbotForward()` - Move the robot forward - `mbotBackward()` - Move the robot backward ## Integration with AI Models Once everything is working, you can integrate with LLM clients that support MCP. Personally, I would recommend [Goose](https://block.github.io/goose/) for this purpose. Just point these clients to your server, and they can autonomously control your robot based on natural language requests. Example natural language commands: - "Explore the room" - "Turn right and go forward" - "Make a beep sound" ## How It Works 1. The Spring application exposes robot commands as tools using the `@Tool` annotation 2. The MCP server in Spring connects these tools to the outside world 3. When an AI wants to control your robot, it calls these methods through the protocol 4. Commands are sent via MQTT to the robot 5. The robot executes the commands based on the received message ## Disclaimer If your robot starts planning world domination, the author accepts no responsibility. Just unplug it and run! 😂 ## License [MIT License](https://opensource.org/licenses/MIT)