# water2-chassis-mcp

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

```text
导诊 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 项目验收限速（非硬件极限）。

## 工具面

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](docs/API_MAPPING.md)。

## 快速开始

```bash
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
```

## 测试

```bash
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 映射](docs/API_MAPPING.md)
- [ROSClaw 集成](docs/ROSCLAW_INTEGRATION.md)
- [医院安全](docs/HOSPITAL_SAFETY.md)
- [真机验收 H0–H6](docs/HARDWARE_ACCEPTANCE.md)
- [故障排查](docs/TROUBLESHOOTING.md)
- [来源与元数据](docs/SOURCE_METADATA.md)

## 许可

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