pyBittle-mcp-server

pyBittle-mcp-server

一个通过蓝牙控制 Bittle 机器人的 Python MCP（Model Context Protocol）服务。此服务通过 MCP 协议提供一组命令，用于移动、摆姿势以及与 Bittle 互动。

功能

• 通过蓝牙连接 Bittle
• 提供移动和姿势命令（前进、后退、转向、坐下、休息等）
• 集成 MCP 工具，实现远程和程序化控制
• 将所有活动记录到 bittle_mcp.log

要求

• Python 3.10+
• 用于包管理的 uv
• 启用了蓝牙的 Bittle 机器人
• pyBittle 库
• mcp-server 库

安装与设置

1. 安装 uv（推荐用于快速、可靠的 Python 包管理）：

   curl -Ls https://astral.sh/uv/install.sh | sh
   

2. 安装 uvx（MCP 服务所需）：

   curl -Ls https://astral.sh/uvx/install.sh | sh
   

3. 安装依赖项：

   # Option 1: Using start_server.sh (recommended)
   chmod +x start_server.sh
   ./start_server.sh
   
   # Option 2: Manual installation
   uv pip install -r requirements.txt
   # or, if using pyproject.toml:
   uv pip install -r pyproject.toml
   

用法

1. 配置蓝牙： 确保 Bittle 机器人已开机并处于蓝牙配对模式。

2. 运行 MCP 服务：

   # Option 1: Using start_server.sh (recommended)
   ./start_server.sh
   
   # Option 2: Manual start
   uvx mcpo --port 8080 -- uv run --with 'mcp[cli]' --with git+https://github.com/cluesang/pyBittle.git mcp run ./server.py
   

   服务将尝试连接 Bittle，并将状态记录到 bittle_mcp.log。

3. 与 MCP 工具集成：

   • 此服务通过 MCP 协议提供命令，使任何兼容 MCP 的客户端或工具都可以使用这些命令。
   • 你可以使用 MCP CLI 或其他 MCP 工具，发现并调用 Bittle 机器人上可用的命令。
   • 示例（使用 MCP CLI）：

     mcp call move_forward
     mcp call sit
     mcp call rest
     

   • 所有可用命令均在 server.py 中通过 @mcp.tool() 装饰，并由 MCP 服务自动注册。

开发

• 主要逻辑位于 server.py。
• 日志配置为同时输出到控制台和 bittle_mcp.log。
• 命令通过 @mcp.tool() 装饰，以便通过 MCP 提供。
• 开发时使用 start_server.sh，它会处理环境设置和进程管理。

故障排除

• 如果服务无法连接，请检查蓝牙配对，并确保没有其他进程正在使用 Bittle 连接。
• 查看 bittle_mcp.log 以获取详细错误消息。
• 如果遇到端口冲突，start_server.sh 会自动处理并终止现有服务进程。
• 确保已安装 uv 和 uvx，并且它们在 PATH 中可用。

许可证

MIT 许可证