AI导哈

机器人控制服务器

通过模型上下文协议控制Parrot Jumping Sumo机器人，实现运动控制、跳跃、踢球、姿势变换、动画播放及实时摄像头流功能。

  • by zapat0s
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 zapat0s/sumo-mcp-server

使用说明

鹦鹉跳跃Sumo MCP服务器

通过模型上下文协议控制你的鹦鹉跳跃相扑机器人！这个MCP服务器使像克劳德这样的人工智能助手能够驾驶你的机器人，并通过它的车载摄像头进行观察。

🤖 特性

  • 机器人运动控制 -以精确的速度和持续时间控制前进/后退、左转/右转
  • 高级跳跃 -完整的跳跃控制，包括弹簧加载、长/高跳跃和取消
  • 踢球 -启用踢球模式并使用前部附件进行踢球
  • 姿势变化 -在站立、跳投和踢球姿势之间切换
  • 10个内置动画 -旋转、踢踏、舞蹈、跳台、螺旋、障碍赛等，展现个性
  • 实时摄像头流媒体 -查看您的机器人实时看到的内容
  • 照片拍摄 -拍摄照片并将其保存到机器人的内部存储中
  • 连接管理 -通过状态监控轻松连接/断开
  • 安全特性 -紧急停机、参数验证、自动停机

📋 先决条件

硬件

  • 鹦鹉跳相扑 机器人（充满电）
  • 具有WiFi功能的计算机

软件

  • Python 3.8-3.11 （Python 3.12+可能与opencv-Python存在兼容性问题）
  • 点 包管理器
  • Git （用于克隆存储库）

🚀 安装

步骤1：克隆所需的存储库

MCP服务器需要此存储库和python sumo库：

# Navigate to your working directory
# The python-sumo repository should already be cloned
# If not, clone it:
git clone https://github.com/faturita/python-sumo.git

# Navigate to the MCP server directory
cd sumo-mcp-server

步骤2：安装Python依赖项

安装所需的Python包：

# Install the MCP server and its dependencies
pip install -r requirements.txt

# Install the MCP server in editable mode (for development)
pip install -e .

备注：如果您在Windows上遇到opencv-python问题，您可能需要安装Visual C++可再分发文件。

步骤3：连接到您的机器人

  1. 开机 你的鹦鹉跳跃相扑机器人
  2. 等待机器人启动（灯将稳定）
  3. 在您的计算机上，打开WiFi设置
  4. 查找名为的网络 “JumpingSumo-XXXXXX” （XXXXXX是唯一标识符）
  5. 连接到此网络（默认密码：无，这是一个开放网络）
  6. 通过打开PowerShell并运行以下命令来验证连接：
    ping 192.168.2.1
    您应该看到成功的ping响应。

🎮 用法

启动MCP服务器

有两种方法可以运行服务器：

选项1：直接执行

python server.py

选项2：使用已安装的命令

sumo-mcp-server

服务器将启动并等待MCP客户端通过stdio连接。

配置您的MCP客户端

要将此服务器与Claude Desktop或其他MCP客户端一起使用，请将其添加到MCP配置文件中。

添加此配置：

{
  "mcpServers": {
    "sumo-robot": {
      "command": "python",
      "args": [
        "~/sumo-mcp-server/server.py"
      ]
    }
  }
}

更改后重新启动Claude Desktop。

可用工具

连接后，以下内容 12工具 将提供给您的AI助手：

连接和状态

1. connect_robot 建立与机器人的连接。

  • 参数:
    • sumo_ip （可选）：机器人IP地址（默认：“192.168.2.1”）
  • 用法：“连接到我的相扑机器人”

2. disconnect_robot 安全地与机器人断开连接。

  • 参数：无
  • 用法：“与机器人断开连接”

3. get_connection_status 检查机器人连接状态。

  • 参数：无
  • 退货：连接状态和IP地址
  • 用法：“机器人还连接着吗？”

运动

4. move_robot 控制机器人运动。

  • 参数:
    • speed （必填）：-100到100（负=向后，正=向前）
    • turn （可选）：-100到100（负=左，正=右）
    • duration （可选）：时间（秒）（默认值：1.0）
  • 使用示例:
    • “以50%的速度前进2秒”
    • “原地左转”
    • “向后行驶并右转”

跳跃和踢腿

5. jump_robot 执行跳转（简单的一步命令）。

  • 参数:
    • jump_type （可选）：“长”或“高”（默认值：“long”）
  • 用法：“让机器人跳”或“做跳高”

6. load_jump 加载/压缩弹簧（高级控制）。

  • 参数：无
  • 用法：“加载跳簧”
  • 备注：允许手动控制跳跃时间

7. cancel_jump 取消加载的跳跃。

  • 参数：无
  • 用法：“取消跳跃”

8. stop_jump 跳跃电机紧急停止。

  • 参数：无
  • 用法：“立即停止跳跃电机”
  • 安全：高优先级应急指挥

姿势

9. change_posture 改变机器人的物理姿态。

  • 参数:
    • posture_type （可选）：“站立”、“跳跃”或“踢球”
  • 姿势:
    • 站立：正常驾驶模式
    • 跳线：跳跃准备姿势
    • 踢球者：使用前部附件进行踢腿
  • 用法：“改变踢球姿势”

动画

10. play_animation 播放内置动画。

  • 参数:
    • animation （可选）：动画名称
  • 可用动画:
    • stop -停止正在进行的动画
    • spin -原地旋转
    • tap -轻敲动作
    • slowshake -缓慢摇晃
    • metronome -像节拍器一样来回摆动
    • ondulation -站立舞
    • spinjump -旋转与跳跃相结合
    • spintoposture -以不同姿势结束旋转
    • spiral -螺旋运动
    • slalom -障碍赛风格之字形
  • 用法：“制作旋转动画”或“让机器人跳舞”

相机

11. get_camera_frame 检索当前摄像头视图。

  • 参数：无
  • 退货：机器人看到的JPEG图像
  • 用法：“让我看看机器人的摄像头看到了什么”

12. capture_photo 给机器人的仓库拍张照片。

  • 参数：无
  • 备注：照片存储在机器人上，需要FTP才能检索
  • 用法：“拍摄照片”

💡 示例使用场景

基本动作测试

You: "Connect to my robot and make it move forward slowly"
AI: *connects and moves robot at 30% speed for 1 second*

相机探索

You: "Show me what the robot sees, then turn right and show me again"
AI: *captures frame, rotates robot, captures another frame*

受控导航

You: "Move the robot forward for 3 seconds, then rotate 90 degrees to the left"
AI: *executes forward movement, then executes turn command*

跳跃动作

You: "Make the robot do a high jump"
AI: *executes high jump command*

You: "Do a long jump to clear that obstacle"
AI: *executes long jump for maximum distance*

高级跳跃控制（手动计时）

You: "Load the jump spring and wait for my signal"
AI: *compresses spring, robot ready*

You: "Now jump high!"
AI: *executes high jump from loaded state*

踢腿顺序

You: "Switch to kicker mode"
AI: *changes posture to kicker stance*

You: "Load the kicker and kick that ball"
AI: *loads mechanism, executes kick*

You: "Return to normal driving mode"
AI: *changes posture back to standing*

有趣的动画

You: "Make the robot dance"
AI: *plays ondulation (dance) animation*

You: "Do a spin jump!"
AI: *plays spinjump animation*

You: "Make it do a slalom pattern"
AI: *plays slalom zigzag animation*

You: "Make it tap"
AI: *plays tap animation*

复杂序列（组合特征）

You: "Move forward, do a spin, then jump high"
AI: *drives forward, spins 360 degrees, performs high jump*

🌐 网络部署（Raspberry Pi）

您可以在Raspberry Pi上部署此服务器，并通过网络远程控制机器人！

看 部署.md 获取完整的设置指南。

网络模式的主要特征：

  • 苏格兰和南方能源公司运输：使用MCP的服务器发送事件标准
  • 远程访问：从网络上的任何计算机驱动机器人
  • 双连接：Pi连接到机器人（WiFi）+您的网络（以太网）

基本命令：

python server.py --transport sse --host 0.0.0.0

⚠️ 安全指南

  1. 净空间：确保机器人有足够的移动空间（至少2m x 2m）
  2. 跳跃间隙：跳跃时，确保机器人上方至少有50cm的间隙
  3. 监督：切勿让机器人在无人看管的情况下运行
  4. 速度限制：测试时从低速（20-30%）开始
  5. 紧急停止：使用 stop_jump 如果需要，命令或关闭电源
  6. 表面：仅适用于平坦光滑的表面
  7. 障碍：保持该区域无障碍物、楼梯和边缘
  8. 踢球：在踢球模式下，保持手和物体远离前部附件

🔧 故障排除

“无法连接到Sumo机器人”

可能的原因：

  • 机器人已关闭或未完全启动→ 开机后等待30秒
  • 未连接到机器人的WiFi→ 检查WiFi连接
  • 另一台设备已连接→ 一次只允许一个连接
  • Windows防火墙阻止→ 允许Python通过防火墙

解决方案：

# Test network connectivity
ping 192.168.2.1

# If ping fails, reconnect to robot's WiFi

“还没有可用的相机框架”

原因： 视频流仍在初始化

解决方案： 连接后等待2-3秒，然后重试

“机器人未连接”错误

原因： 连接丢失或从未建立

解决方案：

  1. 检查 get_connection_status
  2. 如果断开连接，请使用 connect_robot 再次
  3. 验证机器人是否仍处于通电状态

Python/OpenCV问题

cv2的导入错误：

# Reinstall opencv-python
pip uninstall opencv-python
pip install opencv-python

Python版本问题：

  • 使用Python 3.8-3.11以获得最佳兼容性
  • Python 3.12+可能需要从源代码中获取opencv Python

📁 项目结构

sumo-mcp-server/
├── server.py              # Main MCP server implementation
├── sumopy_wrapper.py      # Wrapper for python-sumo library
├── requirements.txt       # Python dependencies
├── pyproject.toml        # Package configuration
└── README.md             # This file

python-sumo/              # Separate repository
├── sumopy/
│   ├── interface.py      # SumoController class
│   └── commands.py       # Command definitions
└── ...

🛠️ 发展

以开发模式运行

# Install in editable mode with dependencies
pip install -e .

# Run the server with logging
python server.py

修改服务器

  • 添加新工具：添加新 @app.tool(...) 函数 server.py
  • 更改机器人行为：修改 sumopy_wrapper.py
  • 调整连接设置：在中编辑默认参数 SumoWrapper.__init__()

📝 技术细节

通信协议

  • 连接：WiFi、TCP/UDP套接字
  • 默认IP: 192.168.2.1
  • 港口：44444（初始化）、54321（设备到控制器）、动态（控制器到设备）
  • 命令频率：40 Hz用于保持连接
  • 视频格式：通过UDP传输JPEG帧

摄像头流

机器人通过UDP流式传输JPEG编码的帧。MCP服务器：

  1. 连接时自动启动视频流
  2. 缓冲最新帧
  3. 在以下情况下返回JPEG数据 get_camera_frame 被称为
  4. 将帧保存到工件目录以进行持久化

部队移动控制

移动命令指定：

  • 速度：-100（完全倒车）至+100（完全前进）
  • 转：-100（硬左）到+100（硬右）
  • 持续时间：最小0.025秒（40Hz时为1帧）

命令以40Hz的频率发送。在显式命令之间，服务器发送“停止”命令以保持连接。

📚 参考文献

📄 许可证

此MCP服务器包装器按原样提供，用于教育和个人用途。底层python sumo库有自己的许可证（检查存储库）。

🤝 贡献

请随时提交问题、建议或改进！

机器人驾驶快乐！ 🚗🤖

相关 MCP