Show HN: SharkClean MCP 深度解读

背景

随着智能家居生态的碎片化，许多用户发现主流机器人吸尘器（如 SharkClean 和 SharkNinja 系列）的官方 App 与第三方自动化平台（如 Home Assistant）或 AI 代理工具之间的连接存在断层。长期以来，社区依赖基于 sharkiq SDK 的集成方案，该方案通过 SharkNinja 的遗留物联网云平台（Ayla cloud）与设备通信。

然而，随着产品迭代，SharkNinja 已将较新的机器人型号（如 Matrix、AI Ultra、Mach 2 以及 RV2500+ 系列）迁移至新的后端云服务（代号 "skegox"）。这一迁移导致旧有的集成方案失效：在新后端上，这些机器人往往在第三方平台中显示为“离线”，且房间地图冻结过时，尽管它们在官方 App 中工作正常。

在此背景下，开发者发布了 SharkClean MCP，这是一个基于 Model Context Protocol (MCP) 标准的服务器实现。它旨在通过逆向工程 Skegox 云 API，为任何支持 MCP 的客户端（如 Claude Code、Claude Desktop 等）提供对 SharkClean 机器人的原生控制能力，从而实现通过自然语言指令进行智能代理操作。

核心内容

SharkClean MCP 是一个非官方项目，未获得 SharkNinja 的赞助或认可，但其底层逻辑直接对接 SharkNinja 当前使用的云端后端（skegox），因此其行为与官方 App 完全一致，无需对硬件进行任何修改。

技术架构与兼容性

该项目的核心突破在于解决了新旧云平台的兼容性问题：

• 旧方案局限：广泛使用的 sharkiq SDK 及其衍生的 Home Assistant 集成仅能访问 Ayla 云。对于已迁移至 skegox 的新款机器人，Ayla 云无法获取实时状态，导致设备显示离线。
• 新方案优势：SharkClean MCP 直接通过 Skegox API 通信。这一逆向工程工作主要归功于 shark2mqtt 项目。因此，它能够正确识别并控制那些被旧方案遗弃的新型号机器人。

功能特性

该 MCP 服务器允许 AI 代理以自然语言执行以下操作：

• 启动清洁：开始最大功率的全屋清洁。
• 房间清洁：指定特定房间（如厨房、客厅）进行清洁。
• 状态查询：检查机器人是否在线、电池电量及清洁进度。
• 回充指令：发送机器人返回基站。

此外，项目还提供了一个命令行工具 shark-mcp-rc，便于在脚本或 Cron 任务中直接驱动机器人。

安全与认证机制

由于 SharkNinja 的 Auth0 租户启用了反机器人检测，直接通过密码进行无头（headless）登录会被阻止。因此，该项目采用了一种基于 PKCE 流程的浏览器认证机制：

1. 运行 shark-mcp-auth 会在浏览器中打开真实的 SharkClean 登录页面。
2. 用户登录后，浏览器会尝试重定向到 com.sharkninja.shark://... 协议链接（通常会显示错误或空白页，属正常现象）。
3. 用户需复制该完整 URL 并粘贴回终端。
4. 系统获取 Auth0 刷新令牌并缓存至 ~/.config/shark-mcp/tokens.json（权限设置为 600）。
5. 服务器利用该刷新令牌生成短期的 Skegox ID 令牌，并在每次刷新时持久化旋转后的令牌，以应对 Auth0 的令牌轮换策略。

多机器人支持

系统支持多机器人账户。每个工具函数均接受一个可选的 robot 参数（名称或设备 ID）。若账户中仅有一台机器人，可省略此参数。在发送指令前，服务器会先检查机器人是否在线，若离线则拒绝执行，防止指令静默丢失。

安装与配置

• 环境要求：需要 uv 包管理器和 Python ≥ 3.10。
• 安装步骤：
  1. 克隆仓库并同步依赖。
  2. 配置 .env 文件，填入 SharkClean 应用的邮箱和密码。
  3. 执行浏览器认证流程。
  4. 运行 shark-mcp-doctor 验证机器人状态和房间地图。
• 集成方式：
  • Claude Code：可通过 claude mcp add 命令添加，或复制 .mcp.json.example 配置文件。
  • Claude Desktop：在 claude_desktop_config.json 中配置 MCP 服务器路径。

关键要点

• 解决“离线”痛点：直接对接 Skegox 后端，解决了新款 Shark 机器人在第三方平台显示离线、地图冻结的问题，这是旧版 sharkiq 集成无法做到的。
• 非官方但功能完整：项目基于社区逆向工程（主要依赖 shark2mqtt），未经 SharkNinja 官方背书，但功能覆盖全面，包括启动、分区清洁、状态查询和回充。
• 认证流程特殊：由于 Auth0 的安全限制，不支持纯命令行密码登录。必须通过浏览器完成一次 PKCE 流程获取令牌，之后令牌会自动刷新，无需重复浏览器操作。
• 安全性考量：令牌缓存文件权限严格限制（600），且服务器会自动处理 Auth0 的令牌轮换。若出现 invalid_grant 错误，需重新运行认证流程。
• 房间地图依赖：clean_rooms 功能要求机器人已完成地图构建。不支持房间划分的旧型号将报告无可用房间。
• 易用性提升：通过 MCP 标准，用户可以使用自然语言（如“开始最大功率清洁”、“把机器人送回基站”）与 AI 代理交互，实现了从“手动操作”到“代理控制”的转变。
• 社区驱动：项目鼓励用户确认其机器人型号并更新 CONFIRMED_MODELS.md，同时提供了单元测试（使用模拟机器人，无云端调用）以确保代码质量。

意义与影响

SharkClean MCP 的发布标志着智能家居自动化领域的一个重要进展。它揭示了随着 IoT 厂商频繁更换云服务后端，社区驱动的反向工程在维持设备可用性和互操作性方面的关键作用。

1. 打破生态壁垒：通过实现 MCP 标准，该项目将 Shark 机器人纳入了 AI 代理的生态系统中。这意味着用户不再局限于官方 App 或特定的 Home Assistant 集成，而是可以利用 Claude 等通用 AI 助手，以更高阶的语义理解能力来控制设备。
2. 推动标准落地：该项目展示了 MCP 协议在实际硬件控制场景中的潜力。通过标准化的接口，不同厂商的设备可以更轻松地接入各种 AI 客户端，降低了开发者和用户的集成门槛。
3. 警示与启示：项目对认证流程和安全机制的详细披露，为其他开发者提供了处理受保护 IoT 云服务的参考案例。同时，它也提醒用户，依赖非官方集成存在厂商随时更改后端 API 的风险，需保持对社区更新的关注。

总之，SharkClean MCP 不仅是一个实用的工具，更是社区技术力量对抗封闭生态、推动开放互联的一次成功实践。