pyBittle-mcp-server

pyBittle-mcp-server

Bluetooth 経由で Bittle ロボットを制御する Python 製 MCP（Model Context Protocol）サーバーです。このサーバーは、MCP プロトコルを使用して Bittle を動かしたり、ポーズを取らせたり、操作したりするための一連のコマンドを公開します。

特長

• Bluetooth 経由で Bittle に接続します
• 移動やポーズのコマンド（前進、後退、旋回、おすわり、休憩など）を公開します
• リモートおよびプログラムによる制御に MCP ツールを活用します
• すべてのアクティビティを bittle_mcp.log に記録します

必要条件

• Python 3.10+
• パッケージ管理用の uv
• Bluetooth が有効な 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. Bluetooth を設定します： Bittle ロボットの電源が入っており、Bluetooth のペアリングモードになっていることを確認してください。

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 で公開するコマンドには @mcp.tool() が付与されています。
• 開発には start_server.sh を使用してください。環境設定とプロセス管理が処理されます。

トラブルシューティング

• サーバーが接続に失敗する場合は、Bluetooth のペアリングを確認し、ほかのプロセスが Bittle への接続を使用していないことを確認してください。
• 詳細なエラーメッセージは bittle_mcp.log を確認してください。
• ポートの競合が発生した場合、start_server.sh が既存のサーバープロセスを自動的に終了します。
• uv と uvx の両方がインストールされ、PATH から利用できることを確認してください。

ライセンス

MIT ライセンス