关键词

机器人控制mBot2Spring AI自动化物理交互

使用说明

项目简介

MBot MCP Server 是一个基于 Spring Boot 框架构建的 MCP 服务器，旨在通过 Model Context Protocol (MCP) 协议，将 mBot2 机器人的控制能力以标准化的方式暴露给大型语言模型（LLM）。该项目允许开发者使用自然语言指令，通过支持 MCP 协议的客户端（如 Goose），远程控制 mBot2 机器人执行各种动作，例如移动、转向、发出声音等。

主要功能点

  • 工具注册与执行: 通过 Spring AI 的 '@Tool' 注解，将 mBot2 机器人的控制命令（如前进、后退、左转、右转、停止、探索、蜂鸣）注册为 MCP 工具，供 LLM 客户端调用。
  • MQTT 通信桥梁: 使用 MQTT 协议作为 MCP 服务器与 mBot2 机器人之间的通信桥梁。服务器接收到 LLM 客户端的工具调用请求后，通过 MQTT 协议向 mBot2 发送控制指令。
  • Stdio 传输协议: MCP 服务器默认使用 Stdio (标准输入输出) 作为与 MCP 客户端的通信协议，方便本地测试和部署。
  • Spring Boot 框架: 基于成熟的 Spring Boot 框架开发，易于配置、部署和扩展。
  • 示例客户端: 提供基于 Stdio 传输协议的 Java 客户端示例 (ClientStdioTest.java)，方便用户快速测试和理解 MCP 服务器的功能。

安装步骤

  1. 环境准备:

    • 确保已安装 Java 21 及以上版本。
    • 确保已安装 Maven 构建工具。
    • 准备 mBot2 机器人 和 mBlock IDE 开发环境。
    • 准备 MQTT Broker (消息队列服务器)，例如可以使用 Docker 快速部署，或者使用已有的 MQTT 服务。

  2. MQTT Broker 设置 (可选):

    • 如果您没有 MQTT Broker，可以使用仓库 assets 目录下的 'docker-compose.yml' 文件快速启动一个 MQTT Broker (Mosquitto)。 
      cd mbotmcp/assets
docker-compose up -d

  3. 配置 Spring Boot 应用:

    • 设置以下环境变量，配置 MCP 服务器连接 MQTT Broker 的信息。 
      MQTT_USERNAME=your_username  # MQTT Broker 用户名，如果不需要认证则留空
MQTT_PASSWORD=your_password  # MQTT Broker 密码，如果不需要认证则留空
MQTT_SERVER_URI=tcp://your_server:1883 # MQTT Broker 服务器地址，例如 tcp://localhost:1883 或 tcp://broker.example.com:1883
      注意: 请将 'your_username', 'your_password', 'your_server' 替换为您的 MQTT Broker 的实际配置信息。如果 MQTT Broker 运行在本地，'your_server' 可以设置为 'localhost' 或 '127.0.0.1'。

  4. mBot2 机器人设置:

    • 使用 USB 数据线连接 mBot2 机器人到电脑。
    • 打开 mBlock IDE 软件。
    • 在 mBlock IDE 中，点击 "文件" -> "打开"，导航到仓库的 '/assets' 目录。
    • 打开 'mbot-mqtt.py' 文件。
    • 修改 'mbot-mqtt.py' 文件中的 WiFi 和 MQTT 配置信息，替换为您自己的 WiFi 和 MQTT Broker 的信息。 
      ssid = "<your wifi ssid>"            # 您的 WiFi SSID
ssid_password = "<your wifi password>"   # 您的 WiFi 密码
mqtt_ip = "<ip of the mqtt broker>"     # MQTT Broker IP 地址，例如 "192.168.1.100" 或 MQTT Broker 的域名
mqtt_port = 1883                      # MQTT Broker 端口，默认为 1883
mqtt_user = "<your mqtt username>"     # MQTT Broker 用户名，如果不需要认证则留空
mqtt_password = "<your mqtt password>" # MQTT Broker 密码，如果不需要认证则留空
    • 在 mBlock IDE 中，点击 "连接" -> "连接设备"，连接到 mBot2 机器人。
    • 点击 "上传" 按钮，将修改后的 'mbot-mqtt.py' 脚本上传到 mBot2 机器人。
    • 上传完成后，断开 USB 连接，并 打开 mBot2 机器人的电源。确保 mBot2 机器人已连接到配置的 WiFi 网络。

  5. 构建 Spring Boot 应用:

    • 在命令行终端中，进入 'mbotmcp' 仓库根目录。
    • 执行 Maven 命令构建 Spring Boot 应用。 
      mvn clean package
    • 构建成功后，会在 'target' 目录下生成 'mbotmcp-0.0.1-SNAPSHOT.jar' 文件。

服务器配置

MCP 客户端需要配置 MCP 服务器的启动命令和参数才能连接并使用其功能。对于 'mbotmcp' 项目，您可以使用以下 JSON 格式配置信息：

{
  "serverName": "mbotmcp-server",
  "command": "java",
  "args": [
    "-jar",
    "./target/mbotmcp-0.0.1-SNAPSHOT.jar"
  ],
  "transport": "stdio"
}

参数说明:

  • 'serverName': 服务器名称，可以自定义，用于标识该服务器连接配置。
  • 'command': 启动服务器的命令，这里是 'java'，假设您的 Java 环境已配置到 PATH 环境变量中。
  • 'args': 启动服务器命令的参数列表。
    • '"-jar"': 指定以 JAR 包方式运行 Java 应用。
    • '"./target/mbotmcp-0.0.1-SNAPSHOT.jar"': 指定要运行的 JAR 包文件路径，请确保该路径与您实际构建生成的 JAR 包文件路径一致。
  • 'transport': 指定 MCP 客户端与服务器之间的传输协议，这里是 'stdio'，表示使用标准输入输出进行通信。

MCP 客户端配置示例 (以 Goose 为例): 在 Goose 客户端的配置文件中，添加上述 JSON 配置信息到 'servers' 数组中。这样 Goose 客户端就能识别并连接到 'mbotmcp-server'。

基本使用方法

  1. 启动 MCP 服务器:

    • 在命令行终端中，进入 'mbotmcp' 仓库根目录。
    • 确保 MQTT Broker 已运行，mBot2 机器人已开机并连接到 WiFi。
    • 执行以下命令启动 Spring Boot MCP 服务器。 
      java -jar ./target/mbotmcp-0.0.1-SNAPSHOT.jar
    • 服务器成功启动后，会监听 Stdio 的输入，等待 MCP 客户端的请求。

  2. 运行测试客户端 (可选):

    • 在命令行终端中，进入 'mbotmcp' 仓库根目录。
    • 执行 Maven 命令运行测试客户端 'ClientStdioTest'。 
      mvn test -Dtest=ClientStdioTest
    • 测试客户端会连接到 MCP 服务器，列出可用的工具，并调用 'mbotBeep' 工具，您应该能看到 mBot2 机器人发出蜂鸣声并闪烁蓝色 LED 灯。

  3. 使用 MCP 客户端 (例如 Goose) 控制 mBot2:

    • 配置您的 MCP 客户端 (例如 Goose) 连接到 'mbotmcp-server' (使用上面提供的服务器配置 JSON)。
    • 在 MCP 客户端中，可以使用自然语言指令指示 mBot2 机器人执行动作，例如:
      • "让机器人探索房间"
      • "向右转弯并前进"
      • "发出哔哔声"
    • MCP 客户端会将自然语言指令转换为对 MCP 工具的调用，MCP 服务器接收到调用后，会通过 MQTT 协议控制 mBot2 机器人执行相应的动作。

注意: 请确保 MQTT Broker、MCP 服务器和 mBot2 机器人都运行在同一个网络环境中，并且网络通信正常。

信息

分类

桌面与硬件

访问项目