yahboom-mcp

Yahboom Raspbot v2 (Boomy) — MCP サーバー、ウェブアプリ、ドキュメント

📖 インストールガイド — クイックスタート、手動セットアップ、トラブルシューティング

Windows版をダウンロード： yahboom-mcp-2.5.0-setup.exe — ウェブアプリと組み込みバックエンドが含まれるインストーラーです。ショートカットは1つです。インストーラーは署名されていません。SmartScreenの警告が表示された場合は、詳細情報 > 実行をクリックしてください。Claude Desktopユーザーは、代わりにMCPバンドルをインストールすることもできます（以下のワンライナーを参照）。

クイックスタート

Claude Desktopのみ（MCPBバンドル）：

irm https://github.com/sandraschi/yahboom-mcp/releases/latest/download/install.ps1 | iex

その他すべてのクライアント（Cursor、Windsurf、OpenCode、Claude Code）— uvx経由のstdio：

{
  "mcpServers": {
    "yahboom-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/sandraschi/yahboom-mcp", "yahboom-mcp", "--mode", "stdio"],
      "env": { "YAHBOOM_IP": "192.168.1.11" }
    }
  }
}

ソースから開発する場合：

git clone https://github.com/sandraschi/yahboom-mcp
cd yahboom-mcp
just

利用可能なコマンドをすべて表示する対話型ダッシュボードが開きます。just bootstrapを実行して依存関係をインストールし、その後just serveまたはjust devを実行して起動してください。

手動セットアップ

justがインストールされていない場合：

概要

Boomyは、Yahboom Raspbot v2（メカナムバージョン）のロボットカーです。重量は約1.0 kg、価格はおよそ300ドル（Raspberry Pi 5 16GBを搭載したフル構成）で、センサー統合、ROS 2オーケストレーション、エージェント型（AI駆動）ロボティクスのテストに使える統合プラットフォームを提供します。あらゆる年齢の子どもたちが楽しめるロボットでもあります。

メーカー：Yahboom

Yahboom は、中国のロボティクスおよびSTEM教育業界の主要企業です。幅広いハードウェアプラットフォームを提供しています。

• 市場展開：エントリーレベルの50ドルのDIYキットから、精密機械アームを備えた2,000ドル超の高度なSTEMロボットまでを取り扱っています。
• 業界での位置付け：教育やプロトタイピング向けの手頃なハードウェアを専門とし、UnitreeやNoetixなどのエンタープライズグレードのプラットフォームより下位に位置付けられています。
• 開発者エコシステム：Yahboomは**FOSS（フリーかつオープンソースのソフトウェア）**スタックへの強い取り組みを維持し、開発者向けに活発なGitHubサポートを提供しています。

---

🏗️ ハードウェアアーキテクチャ

Boomyは「デュアルスタック」コントローラーモデルを採用し、リアルタイムの物理的な信頼性と高度な認知タスクを両立します。

1. Rosmaster（ESP32 / Micro-ROS）：低遅延のモーター制御、超音波測距、ラインセンサー処理を行う小型のハードウェアコントローラーです。
2. Raspberry Pi 5（オプション／ゲートウェイ）：スタンドアロン動作時のメインブレインです。

🚀 「ゼロホスト」スウォーム構成

大規模なデプロイでは、BoomyをPiレススウォームモードで動作させることができます。

• セットアップ：Raspberry Piを取り外し、WiFiからEthernet／UARTへのブリッジ（15ドル）に置き換えます。
• 制御：リモートのマザーシップ（RTX 4090搭載PC）を介して集中オーケストレーションを行います。
• スケーリング：Pi搭載ロボット1台分の価格で、3台以上をデプロイできます。

---

🕹️ インターフェースの分離

このプロジェクトでは、人間が操作するコントロールと、機械に最適化されたインターフェースを明確に区別しています。

• 人間向けインターフェース：手動でのテレメトリー観察、周辺機器（ライト、OLED）の制御、人間とロボットのインタラクションを目的に設計された、ブラウザー上で動作するウェブダッシュボード（React/Vite）です。
• 機械向けインターフェース：AI エージェントやMCPクライアントが、より大きなフリート内でBoomyをツールとしてプログラムから制御するために設計された、標準準拠のMCP サーバー（Model Context Protocol）です。

---

フリート連携（コンパニオン）

yahboom-mcp は単独で完全に動作します。オプションで sandraschi フリート内のコンパニオンサーバーと接続し、拡張機能を利用できます。

コンパニオンサーバー	利用可能になる機能	ステータス	セットアップ
speech-mcp	音声フィードバック、音声合成	オプション	インストールガイド
reaper-mcp	オーディオ再生、サウンドボードFX	オプション	インストールガイド
virtualdj-mcp	デッキ制御、音楽再生	オプション	インストールガイド

自己完結型コンパニオン：フリートコンパニオンは独立して動作します。コンパニオンをインストールしても、推移的な依存関係の連鎖は発生しません。

---

📂 ドキュメントの柱

柱	焦点	主なトピック
自律ミッション	v2.4.0 — Ollama → ROS	自然言語による目標 → LLM による計画 → ROS による実行；ビジョン検出（SSD MobileNet v2）；超音波による障害物回避；「犬を探す」ウォークスルー。
起動と立ち上げ	まずはこちら（ロボット + Goliath）	ROS 2 と rosbridge_suite（ソフトウェア）、Pi 配下の USB コントローラーレイヤーとの違い；起動順序；Pi 上の Docker/systemd；Web アプリから再起動できるもの；ダッシュボードと診断機能の違い。
エージェントのミッションと MCP	LLM → Pi のミッション	yahboom_agent_mission（MCP）と POST /api/v1/agent/mission（HTTP）；MissionPlanV1；環境変数；boomy_mission_executor；Nav2 と /boomy/detections_json；yahboom_agentic_workflow との違いを含むトラブルシューティング。
Rosmaster アーキテクチャ	デュアルバスの分析	モーター／センサー用 I2C（0x2b）、IMU／バッテリー用 UART；レジスターマップ；コンテナーレイアウト；micro-ROS の分析。
スタックのヘルスプローブ	health.stack	TTL SSH/TCP プローブ、YAHBOOM_ROS2_CONTAINER、ライフサイクル（未起動／終了／再起動ループ）、任意の docker logs プレビュー（機密情報を削除）。
セットアップとインストール	開発環境のインストール	uv、モード、基本環境変数。
ソフトウェアとロジック	アーキテクチャ	システム設計、ROS 2 ノードグラフ、状態管理。
ハードウェアとピン配置	物理レイヤー	配線図、I2C アドレス、センサーの技術仕様。
Raspbot v2 ハードウェアスタック	Boomy シャーシ	シャーシ、メカナム、モーター、ライトストリップ、PTZ、カメラ、IMU、超音波、ライン／段差検出、拡張ボードと rosbridge ソフトウェアの違い、Pi ポート、I2C、バッテリー、スイッチ。
ROS 2 ブリッジ	接続性	ブリッジアーキテクチャ、トピックマップ、状態キャッシュ、環境変数、既知のバグ。
音声とオーディオ	サウンドシステム	CSK4002 モジュールのプロトコル、espeak-ng TTS、チャットロボットのアーキテクチャ、17 種類の効果音を内蔵したオーディオサウンドボード。
マルチロボット統合	エコシステム	フェデレーション型フリートの標準と、ロボット間通信プロトコル。
設定	リファレンス	環境変数、ポート、トランスポートモード、LLM プロバイダー。
開発	リファレンス	開発環境のセットアップ、構成、テストコマンド、5 つのゲート。
ツール	リファレンス	MCP ツール、yahboom_tool の操作、REST エンドポイント。
トラブルシューティング	リファレンス	よくある問題と解決方法。
オンボーディング	初回セットアップ	Boomy のハードウェア立ち上げ（ロボットの電源、IP、動作確認）。

---

Web アプリのステータス画面

• ダッシュボード（/dashboard） — 最初に表示されるページ：基本的なロボット接続（ゲートウェイ、接続先 IP、ROS・SSH・ビデオ）と、Raspbot の電源がオフの場合や Goliath に AP／イーサネット経由の接続経路がない場合のオペレーター向けヒント。
• 診断ハブ（/diagnostics） — 詳細情報：ROS トピックエクスプローラー、ノード一覧、再同期／ハードリセット、SSH シェル、スタックヘルステーブル（利用可能な場合、ダッシュボードと同じ stack ペイロード）。
• サーバーログ（/logs） — Goliath 上の yahboom-mcp のライブログストリーム（SSE）。

---

過去のステータスログと旧来の調査資料は、docs/archive/ ディレクトリに保存されています。

スタック

レイヤー	技術
MCP	FastMCP 3.4（統合ゲートウェイ：stdio + HTTP/SSE）
バックエンド	FastAPI + uvicorn、Pydantic v2、structlog
ロボット接続	roslibpy（rosbridge） / ESP32 TCP への直接接続 / モックブリッジ、paramiko SSH
ビジョン／音声	OpenCV、faster-whisper、edge-tts、pytapo
フロントエンド	React 19 + Vite 5 + TailwindCSS 3 + Lucide + Framer Motion + Zustand + Three.js
パッケージマネージャー	uv（Python）、bun（webapp）
デスクトップ	Tauri 2 + NSIS（PyInstaller サイドカーバックエンド）
品質	ruff + pyright + pytest（+coverage） / tsc + Biome / Playwright
LLM	Ollama（:11434）+ LM Studio（:1234）の自動検出、Gemini によるミッション計画

🛡️ 産業品質スタック

このプロジェクトは、高忠実度のエージェント型オーケストレーションにおける SOTA 2026 の産業標準に準拠しています。

• Python（コア）：Ruff による lint とフォーマット。コアハンドラーでは print 文（T201）を一切許容しません。
• Webapp（UI）：Biome によるサブミリ秒の lint。
• MCP：統合ゲートウェイ、ポートマントーツール、スキル、エージェント型サンプリングを備えた FastMCP 3.4。
• LLM プロバイダー：Ollama（:11434）と LM Studio（:1234）を自動検出。nvidia-smi 経由で GPU メトリクスを取得します。
• 自動化：フリート運用全般に対応する Justfile のレシピ（just lint、just fix、just dev）。