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:

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:

   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

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:

   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 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