robot-mcp-server

robot-mcp-server

中国語ドキュメント

LLM、エージェントシステム、自動化プラットフォーム向けの、より充実したロボット制御 MCP サーバーです。Unitree ロボットと DJI Tello ドローンを統一的に制御できます。

改善点

元のバージョンと比べて、本プロジェクトは最小限のプロトタイプではなく、より実用的なエンジニアリングの基盤となりました。

• mock と hardware の両方のバックエンドに対応し、実機なしでワークフローを検証できます
• 環境変数や CLI による上書きが可能な、統一設定レイヤーを追加しました
• ヘルスチェック、ステータスの確認、機能の検出、グローバルな緊急停止ツールを追加しました
• 一般的なロボットのワークフロー向けに、組み込みルーチンテンプレートを追加しました
• クライアントが複数の組み込みルーチンを 1 回のリクエストで実行できる、軽量なシーケンス実行機能を追加しました
• より厳格なパラメーター検証と接続状態の保護により、アダプターを強化しました
• 依存関係の宣言漏れ、不安定な起動フロー、不安定な相対インポートを修正しました
• 検証や回帰チェックを容易にするため、ユニットテストとローカルデモを追加しました

プロジェクト構成

.
├── examples/
│   └── demo.py
├── src/
│   ├── __init__.py
│   ├── config.py
│   ├── dji_adapter.py
│   ├── exceptions.py
│   ├── main.py
│   ├── service.py
│   └── unitree_adapter.py
├── tests/
│   └── test_service.py
├── README.md
├── README.zh-CN.md
├── requirements.txt
└── run.ps1

インストール

要件：

• Python 3.10+
• Python を実行できる Windows PowerShell または任意のターミナル

依存関係をインストールします：

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

デフォルトで含まれるもの：

• mcp
• djitellopy

実際の Unitree ハードウェアに接続する場合は、対応する SDK もインストールしてください：

python -m pip install git+https://github.com/unitreerobotics/unitree_sdk2_python.git

クイックスタート

推奨する mock モードでの起動方法：

.\run.ps1

または：

python -m src.main --backend mock --transport stdio

HTTP トランスポートで起動します：

.\run.ps1 -Backend mock -Transport streamable-http -Host 127.0.0.1 -Port 8000

実際のハードウェアに接続します：

python -m src.main --backend hardware --transport stdio

hardware に切り替える前に、mock モードでワークフローを検証することをおすすめします。

環境変数

変数	デフォルト	説明
ROBOT_MCP_BACKEND	mock	バックエンドモード：mock / hardware
ROBOT_MCP_TRANSPORT	stdio	トランスポート：stdio / streamable-http
ROBOT_MCP_HTTP_HOST	127.0.0.1	HTTP バインドホスト
ROBOT_MCP_HTTP_PORT	8000	HTTP ポート
ROBOT_MCP_LOG_LEVEL	INFO	ログレベル
ROBOT_MCP_UNITREE_TIMEOUT_SECONDS	10	Unitree の接続タイムアウト
ROBOT_MCP_DEFAULT_TAKEOFF_HEIGHT	1.2	DJI のデフォルト離陸高度（メートル）
ROBOT_MCP_TELLO_HOST	empty	特定の Tello ホスト

利用可能な MCP ツール

共通ツール：

• server_status
• list_robot_capabilities
• list_robot_routines
• run_routine_sequence
• health_check
• emergency_stop_all

Unitree ツール：

• unitree_connect
• unitree_move(velocity, duration=1.0)
• unitree_stop
• unitree_status
• unitree_disconnect
• unitree_move_and_stop(velocity, duration=1.0)
• unitree_out_and_back(velocity, forward_duration=1.0, return_duration=None)
• unitree_pulse_patrol(velocity, pulse_duration=0.8, pause_duration=0.3, cycles=3)
• unitree_inspection_sweep(velocity=1.0, forward_duration=1.0, checkpoint_pause=0.5, cycles=2)

注：

• velocity の範囲：-3.0 ~ 3.0 m/s
• duration の範囲：0.1 ~ 30.0 秒

DJI ツール：

• dji_connect
• dji_takeoff(height=None)
• dji_land
• dji_emergency_stop
• dji_status
• dji_disconnect
• dji_takeoff_hover_land(height=None, hover_seconds=3.0)
• dji_quick_observe(height=None, hover_seconds=5.0)
• dji_perimeter_scan(height=None, hover_seconds=2.0, checkpoints=3)

注：

• height の範囲：0.2 ~ 10.0 メートル
• height を省略すると、設定済みのデフォルト値が使われます

組み込みルーティン

クライアント側の開発時間を短縮するため、サーバーにはいくつかの組み合わせ済みアクションが含まれています。

• unitree_move_and_stop 必要に応じて接続し、1 回移動してから自動的に停止します
• unitree_out_and_back 前進し、戻ってから停止する、シンプルな往復パトロールを行います
• unitree_pulse_patrol 短い移動と一時停止を繰り返す、軽量なパトロールシナリオを実行します
• unitree_inspection_sweep 前進、チェックポイントでの停止、復路の移動を含む、簡潔な点検ルーティンを実行します
• dji_takeoff_hover_land 離陸し、設定可能な時間ホバリングしてから、自動的に着陸します
• dji_quick_observe 離陸、ホバリング、着陸を行う、手軽な観察ルーティンです
• dji_perimeter_scan 複数のホバリングチェックポイントを含む、軽量な空中スキャンルーティンです

シーケンス実行

run_routine_sequence を使うと、クライアントは複数の組み込みルーティンと pause ステップを 1 回のリクエストで送信できます。

例：

[
  {
    "action": "unitree_move_and_stop",
    "params": {
      "velocity": 1.0,
      "duration": 1.2
    }
  },
  {
    "action": "pause",
    "params": {
      "duration": 1
    }
  },
  {
    "action": "dji_takeoff_hover_land",
    "params": {
      "height": 1.5,
      "hover_seconds": 3
    }
  }
]

サポートされているシーケンスアクション：

• pause
• unitree_move_and_stop
• unitree_out_and_back
• unitree_pulse_patrol
• unitree_inspection_sweep
• dji_takeoff_hover_land
• dji_quick_observe
• dji_perimeter_scan

リソースとプロンプト

ツールに加えて、サーバーは次も公開します。

• リソース：robot://status/summary
• プロンプト：safe_operation_checklist(device)

ローカルデモ

python examples\demo.py

テスト

python -m unittest discover -s tests -v

使用上のヒント

• 開発中は mock モードを優先してください
• 実機に接続する前に health_check を呼び出してください
• 移動または離陸のコマンドを実行する前に server_status を確認してください
• 問題が発生した場合は、まず emergency_stop_all を使用してください

既知の制限事項

• Unitree ハードウェアの制御は、拡張の出発点として設計された軽量な SDK 統合レイヤーです
• 現在のテストは主に mock モードを対象としており、実機の動作には現地での統合テストが必要です
• streamable-http の正確な動作は、インストールされている mcp パッケージのバージョンによって異なります

ライセンス

MIT ライセンス