lab-robot

基于 MCP 的实验室视觉机器人助手：语音交互、云端 VLM 图像问答与 Opentrons 设备接入。

演示

观看完整演示视频（约 57 秒，MP4） · 版本与下载

Related MCP server: Webcam MCP

功能与架构

• 将“看看当前画面”等自然语言请求交给 MCP 摄像头工具，获取现场图像并调用云端 VLM 返回文字回答。

• 使用 ONVIF 连接网络摄像头、获取 RTSP 地址；支持本地截图与可选 PTZ 云台控制。

• 通过已固定版本的 opentrons-mcp 接入协议上传、运行查询与执行控制工具。

• 使用小智客户端桥接工具与语音终端；Python 和 Node.js 服务可通过单个 Docker 镜像部署。

flowchart LR
    ESP[ESP32 语音终端\nESP-IDF / C] <--> Cloud[小智云端对话服务]
    Cloud <--> Bridge[小智 MCP 桥接客户端]
    Bridge <--> Camera[MCP 摄像头工具\nNode.js / Python]
    Camera <--> IP[ONVIF / RTSP 网络摄像头]
    Camera --> VLM[OpenAI GPT-4o 直连\n或小智 VLM 网关]
    Bridge <--> OT[Opentrons MCP]
    OT <--> Robot[Opentrons 实验设备]

VLM 负责图像理解；OpenCV 仅用于取帧、JPEG 编码等图像处理，不在本地加载模型权重。支持两种视觉通道：

• VISION_PROVIDER=xiaozhi（默认）：沿用小智 /vision/explain 网关，以 multipart 表单提交 file 和 question，读取返回的 text。源码没有指定网关背后的模型，不能由此确认使用了 GPT-4o。

• VISION_PROVIDER=openai：通过 OpenAI Responses API 直连，默认模型 gpt-4o；将 JPEG 编码为 Base64 data URL，与文字问题一起发送，读取返回消息中的 output_text，统一返回 {success, text}。

视觉通道的切换不改变 MCP 工具接口。使用语音终端时，小智仍承担语音对话和 MCP 桥接；选择 OpenAI 后，图片识别请求由 Python 直接发送给 OpenAI。

本仓库整理的是机器人设备接入与视觉工具部分。ESP32 固件、机械结构和接线图尚未包含；BinderAgent 的蛋白设计、RAG 和 LangGraph 编排也不在此仓库中。

硬件与运行条件

容器需能访问摄像头和机器人所在网络。摄像头是网络设备，不需要映射 USB 摄像头。开发板具体型号、外壳结构与固件工程需另外准备。

Docker 快速开始

git clone https://github.com/zbbio/lab-robot.git
cd lab-robot
cp .env.example .env
# 编辑 .env，填写小智接入点、摄像头参数，并选择视觉通道与认证信息。
docker compose pull
docker compose up -d
docker compose logs -f

Windows PowerShell 使用 Copy-Item .env.example .env 复制模板。

首次配置需要填写 XIAOZHI_MCP_ENDPOINT；摄像头功能需要 ONVIF_CAMERA_IP、用户名和密码。

直连 GPT-4o：在本机 .env 中设置：

VISION_PROVIDER=openai
OPENAI_API_KEY=你的OpenAI_API密钥
OPENAI_MODEL=gpt-4o

请求固定发送到 https://api.openai.com/v1/responses，不使用 VISION_API_URL、VISION_API_TOKEN 或 VISION_DEVICE_ID。实现使用现有 requests，无需新增 SDK；包含连接/读取超时、缺少密钥检查、HTTP/JSON 错误处理、未完成/拒绝/空回答检查及错误日志密钥脱敏。设置 store=false，不启用 Responses 的响应存储；这不等于服务端无任何日志。API 密钥与模型权限需在 OpenAI 平台开通，ChatGPT 订阅不替代 API 认证。

使用小智视觉网关：保持 VISION_PROVIDER=xiaozhi；若网关需要认证，填写 VISION_API_TOKEN。VISION_DEVICE_ID 可固定设备身份，避免容器重建后 MAC 地址变化影响服务端绑定。

更新已有部署的 .env 后，执行 docker compose up -d --force-recreate 使环境变量生效；本地运行时重启 MCP 进程。图像输入与模型接口依据 OpenAI 官方视觉文档 和 GPT-4o 模型文档。

打开 http://127.0.0.1:9999 查看上游小智客户端管理界面。该界面管理工具与连接配置；端口默认只绑定本机。接入点和缓存写入 Docker 数据卷，截图位于数据卷的 captures/ 下。

也可以本地构建：

docker compose up --build -d

健康检查验证管理界面已启动；摄像头连接、VLM 服务和实验设备需在配置完成后分别联调。

本地开发

需要 Node.js 22+、Python 3.11+ 与 uv。建议使用 Python 3.12。

npm ci
uv sync --frozen --python 3.12
cp .env.example .env
# 在 .env 中设置 Python 路径：Windows 为 .venv/Scripts/python.exe，Linux 为 .venv/bin/python。
npm start

如果只想将摄像头工具接入其他 MCP 客户端，将其启动命令配置为：

{
  "mcpServers": {
    "lab-robot-camera": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--env-file", "/absolute/path/to/.env", "ghcr.io/zbbio/lab-robot:v0.2.0", "node", "camera/node/camera.js"]
    }
  }
}

stdio 需要保留输入连接；使用 -i，不要加 -t。此模式不会启动小智桥接或管理页面。

工具

PTZ 默认关闭，设置 ONVIF_CAMERA_PTZ_ENABLED=true 后注册。设置 OPENTRONS_ENABLED=false 可只运行摄像头接入。Docker 使用 headless 图像依赖，不暴露本地 GUI 实时预览工具。

验证与发布

uv run python -m unittest discover -s tests -p 'test_*.py' -v
# 运行 npm test 前，保证 PYTHON_VENV_PATH 指向上述虚拟环境中的 Python。
npm test
npm run smoke
python scripts/check_release.py

CI 验证小智网关与 OpenAI 直连的请求格式、模型、图片、问题、认证与超时设置，缺失配置、异常响应和密钥脱敏，本地截图，MCP 初始化和工具发现；然后构建镜像，运行容器 MCP 测试与管理界面启动检查。测试使用模拟响应，不连接真实摄像头、云端 VLM 或机器人，也不执行实验协议。

与 MedAgent 的发布方式一致：推送版本标签后重跑验证，全部通过再发布 ghcr.io/zbbio/lab-robot:<版本>。普通代码推送只运行 CI。

git tag v0.2.0
git push origin v0.2.0

升级或回退时，在 .env 修改 LAB_ROBOT_IMAGE 为目标版本，再执行 docker compose pull && docker compose up -d --no-build。保留同一个数据卷即可保留运行数据。

来源与许可

本项目基于小智客户端生态整理实验室设备接入，相关来源及保留的许可见 NOTICE 和 LICENSE。演示媒体用于展示项目效果；不包含生产认证信息或实验原始数据。