water2-chassis-mcp

ROSClaw Hardware MCP for the WATER2 （水滴2) robot chassis. 养志康复医院导诊机器人 · Phase 1：底盘接入。

导诊 Agent → ROSClaw (policy/permit/lease/receipt)
          → water2-chassis-mcp (本仓库)
          → TCP 192.168.10.10:31001 → WATER2 底盘

这是一个 southbound hardware adapter，不是 Agent。它把 WATER 私有 TCP API（长连接、类 URL 请求、response/callback/notification 多路 异步 JSON）变成 ROSClaw 可监管的标准 MCP 工具面。

关键设计

• persistent TCP transport：单长连接 + 增量 JSON 解码（半包/粘包/ 交错包/坏包恢复）+ uuid 请求关联 + 写串行化。

• 断线 fail-closed：重连后绝不重放运动命令；在途任务无法证明状态 时进入 unknown。

• 接受 ≠ 到达：/api/move 的 status=OK 只代表任务被接受； 完成判定以 2 Hz 轮询 robot_status 为准，notification 仅作事件增强。

• 停止分层：cancel_navigation（正常停）vs emergency_stop （软急停，电机失能）vs clear_soft_estop（operator 令牌）。

• 本地硬门控：raw joy_control、地图修改、定位矫正默认禁用； 即使上游误授权，MCP 侧 SafetyProfile 也会拒绝。

• 医院 profile：0.30 m/s / 0.60 rad/s 项目验收限速（非硬件极限）。

Related MCP server: Robot Navigation MCP Server

工具面

P0：get_chassis_status get_robot_info get_connection_info navigate_to_marker navigate_to_pose cancel_navigation get_navigation_task get_planned_path emergency_stop list_markers get_power_status get_diagnostics

P1 只读：get_current_map query_accessible_point probe_obstacle_distance make_plan

P2 维护（默认拒绝）：clear_soft_estop insert_marker delete_marker set_speed_limits position_adjust raw_joy_control

完整映射见 docs/API_MAPPING.md。

快速开始

uv sync --extra dev

# 无硬件冒烟（fake WATER server）
uv run python scripts/smoke_test.py

# 连接真机只读探测
uv run python scripts/probe_water2.py --host 192.168.10.10

# 启动 MCP server（stdio）
WATER2_HOST=192.168.10.10 WATER2_PROFILE=hospital uv run water2-chassis-mcp

测试

uv run pytest -m "not hardware" --cov     # CI：unit + protocol + integration + MCP
uv run pytest -m hardware tests/hardware/ # 真机验收（需要 WATER2_HW_ACK=1）

质量门：ruff + mypy + pytest，coverage ≥ 85%。

文档

• API 映射

• ROSClaw 集成

• 医院安全

• 真机验收 H0–H6

• 故障排查

• 来源与元数据

许可

代码部分待项目确定开源许可；厂商 API 文档为 Proprietary/Unknown， 不包含在本仓库中（见 docs/SOURCE_METADATA.md）。