yahboom-mcp

Yahboom Raspbot v2 (Boomy) — MCP 服务、Web 应用与文档

📖 安装指南 — 快速入门、手动设置与故障排除

Windows 下载： yahboom-mcp-2.5.0-setup.exe — 安装程序包含 Web 应用和内嵌后端，并提供一个快捷方式。安装程序未经签名：SmartScreen 会发出警告，请点击 More info > Run anyway。Claude Desktop 用户也可以改为安装 MCP bundle（见下方的一行命令）。

快速入门

仅限 Claude Desktop（MCPB bundle）：

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 转以太网/UART 网桥（15 美元）。
• 控制：通过远程 母舰（配备 RTX 4090 的 PC）进行集中编排。
• 扩展：以单台由 Pi 托管的机器人所需的成本，部署 3 台或更多设备。

---

🕹️ 接口分离

本项目明确区分供人操作的控制方式与针对机器优化的接口：

• 人机界面：基于浏览器的 Web 控制面板（React/Vite），用于手动查看遥测数据、控制外围设备（灯光、OLED）以及进行人机交互。
• 机器接口：符合标准的 MCP 服务（Model Context Protocol），供 AI Agent 和 MCP 客户端以编程方式将 Boomy 作为工具集成到更大的设备群中。

---

设备群交叉连接（伴随服务）

yahboom-mcp 可完全独立运行。你也可以选择将其与 sandraschi 设备群中的伴随服务连接，以解锁扩展功能：

伴随服务	解锁的功能	状态	设置
speech-mcp	语音反馈、语音合成	可选	安装指南
reaper-mcp	音频播放、音效板效果	可选	安装指南
virtualdj-mcp	音轨控制、音乐播放	可选	安装指南

独立伴随服务：设备群中的伴随服务彼此独立运行。安装伴随服务不会触发传递依赖链。

---

📂 文档支柱

支柱	重点	主要主题
自主任务	v2.4.0 — Ollama → ROS	自然语言目标 → 大模型规划 → ROS 执行；视觉检测（SSD MobileNet v2）；超声波避障；“找到我们的狗”演练。
启动与 bringup	从这里开始（机器人 + Goliath）	ROS 2 与 rosbridge_suite（软件）以及 Pi 下方 USB 控制器层的区别；启动顺序；Pi 上的 Docker/systemd；Web 应用可以重启的内容；仪表板与诊断。
Agent 任务与 MCP	大模型 → 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；生命周期（从未启动 vs 已退出 vs 重启循环）；可选的 docker logs 预览（已脱敏）。
设置与安装	开发安装	uv、模式、基准环境变量。
软件与逻辑	架构	系统设计、ROS 2 节点图和状态管理。
硬件与引脚定义	物理层	接线图、I2C 地址和传感器技术规格。
Raspbot v2 硬件栈	Boomy 底盘	底盘、麦克纳姆轮、电机、灯带、PTZ、摄像头、IMU、超声波、循线/悬崖检测、扩展板与 rosbridge 软件的区别、Pi 接口、I2C、电池、开关。
ROS 2 Bridge	连接	Bridge 架构、主题映射、状态缓存、环境变量、已知错误。
语音与音频	声音系统	CSK4002 模块协议、espeak-ng TTS、聊天机器人架构，以及内置 17 种音效的音频音效板。
多机器人集成	生态系统	联邦式机群标准和跨机器人通信协议。
配置	参考	环境变量、端口、传输模式、大模型提供商。
开发	参考	开发环境设置、目录布局、测试命令、五道关卡。
工具	参考	MCP 工具、yahboom_tool 操作、REST 端点。
故障排查	参考	常见问题及解决方法。
入门指南	首次设置	Boomy 硬件启动（机器人供电、IP、基本检查）。

---

Web 应用状态界面

• 仪表板（/dashboard） — 首页：基本的机器人连接（网关、目标 IP、ROS · SSH · 视频），以及 Raspbot 关机或 Goliath 没有 AP/以太网连接路径时的操作提示。
• 诊断中心（/diagnostics） — 详情：ROS 主题浏览器、节点列表、重新同步/硬重置、SSH Shell、栈健康状态表格（可用时与仪表板使用相同的 stack 负载）。
• 服务器日志（/logs） — Goliath 上实时的 yahboom-mcp 日志流（SSE）。

---

历史状态日志和旧版研究资料保存在 docs/archive/ 目录中。

技术栈

层级	技术
MCP	FastMCP 3.4（统一网关：stdio + HTTP/SSE）
后端	FastAPI + uvicorn、Pydantic v2、structlog
机器人连接	roslibpy（rosbridge）/ 直连 ESP32 TCP / mock bridge、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 sidecar 后端）
质量	ruff + pyright + pytest（+coverage）/ tsc + Biome / Playwright
大模型	Ollama（:11434）+ LM Studio（:1234）自动发现、Gemini 任务规划

🛡️ 工业级质量栈

本项目遵循 SOTA 2026 工业标准，实现高保真 Agentic 编排：

• Python（核心）：Ruff 用于代码检查和格式化。核心处理器中对 print 语句（T201）实行零容忍。
• Webapp（UI）：Biome 用于亚毫秒级代码检查。
• MCP：FastMCP 3.4，支持统一网关、复合工具、技能和 Agentic 采样。
• 大模型提供商：自动发现 Ollama（:11434）和 LM Studio（:1234）。通过 nvidia-smi 获取 GPU 指标。
• 自动化：使用 Justfile 提供所有设备群操作的配方（just lint、just fix、just dev）。