Honyar IoT MCP Server

鸿雁云统一 MCP Server，面向 smarthome-v3-all 提供的 Open API 能力。当前首批 tools 覆盖酒店智能化 /open/hotel/**，后续可继续在同一个 MCP 包内扩展设备、项目、能耗、AI 网关等鸿雁云能力。

当前酒店智能化 tools 只把 MCP 调用适配到鸿雁云 /open/hotel/** HTTP Open API，不实现产品匹配、报价计算、复核规则或文件生成业务逻辑。

安装与启动

公开 npm 包名：

npx -y @honyar/iot-mcp

本地开发：

cd mcp/honyar-iot-mcp
npm install
npm test
npm start

环境变量

| 变量 | 必填 | 说明 | |------|------|------| | HONYAR_OPEN_API_BASE | 否 | 鸿雁 IoT Open API 基础地址，包含后端上下文路径，不包含 /open/** 业务域路径。默认生产地址：https://api.hongyanyun.cn/v3；测试环境可覆盖为 https://spa-dev.hongyanyun.cn/v3 | | HONYAR_OPEN_API_KEY | 是 | 开放 API Key。请求云端时会发送 Authorization: Bearer <key> | | HONYAR_OPEN_API_TIMEOUT_MS | 否 | HTTP 超时时间，默认 30000 |

MCP stdio 配置

OpenAI Studio、Codex、Claude Desktop 等 stdio MCP 客户端可使用同类配置：

{
  "mcpServers": {
    "honyar-iot": {
      "command": "npx",
      "args": ["-y", "@honyar/iot-mcp"],
      "env": {
        "HONYAR_OPEN_API_KEY": "hy_xxx"
      }
    }
  }
}

测试环境或私有化部署可显式覆盖 Open API 地址：

{
  "mcpServers": {
    "honyar-iot-dev": {
      "command": "npx",
      "args": ["-y", "@honyar/iot-mcp"],
      "env": {
        "HONYAR_OPEN_API_BASE": "https://spa-dev.hongyanyun.cn/v3",
        "HONYAR_OPEN_API_KEY": "hy_xxx"
      }
    }
  }
}

本地源码调试可改为：

{
  "mcpServers": {
    "honyar-iot-local": {
      "command": "node",
      "args": ["/Users/jerry/Developer/Honyar/smarthome-v3-all/mcp/honyar-iot-mcp/bin/honyar-iot-mcp.js"],
      "env": {
        "HONYAR_OPEN_API_BASE": "https://spa-dev.hongyanyun.cn/v3",
        "HONYAR_OPEN_API_KEY": "hy_xxx"
      }
    }
  }
}

Tools

当前 tools 属于酒店业务域，后续设备、项目、能耗、AI 网关等能力继续在同一个 IoT MCP 包内扩展。

| MCP tool | HTTP API | |----------|----------| | create_hotel_work_package | POST /open/hotel/work-packages | | submit_hotel_ai_draft | POST /open/hotel/work-packages/{id}/ai-draft | | match_hotel_products | POST /open/hotel/work-packages/{id}/product-matches | | create_hotel_review_session | POST /open/hotel/work-packages/{id}/review-session | | get_hotel_review_status | GET /open/hotel/work-packages/{id}/review-status | | get_hotel_review_result | GET /open/hotel/work-packages/{id}/review-result | | generate_hotel_deliverables | POST /open/hotel/work-packages/{id}/deliverables | | upload_hotel_assets | POST /open/hotel/work-packages/{id}/assets | | list_hotel_assets | GET /open/hotel/work-packages/{id}/assets | | search_hotel_products | GET /open/hotel/products | | get_hotel_product_detail | GET /open/hotel/products/{mcode} |

参数约定

• work_package_id 支持数字或字符串，会作为 path 参数传给云端。
• create_hotel_work_package 支持 title、project、customer、opportunity、sensitivity、source_agent、skill_version 等顶层字段，也支持 request 透传未来字段；顶层字段覆盖 request 中的同名字段。
• submit_hotel_ai_draft 的 ai_draft 会作为 HTTP body 原样提交。
• match_hotel_products 可传 requests，不传时云端复用最新 AI draft 的 product_requests。
• generate_hotel_deliverables 支持 require_reviewed；默认行为由云端 Open API 决定。
• upload_hotel_assets 支持将客户资料、图纸预览、报价截图/文件、脚本解析结果和 AI 分析结果挂到工作包；assets 数组元素可传 asset_key、asset_type、title、content_type、data_url、content_data、content_url、storage_type、metadata、source_refs。
• list_hotel_assets 可传 asset_type 过滤，例如 drawing_preview、quote_image、analysis_json、material。资产读取和 Skill Web 复核页面由云端复核 token 控制。

发布到 npmjs

发布前确认包内容和测试：

cd mcp/honyar-iot-mcp
npm test
npm pack --dry-run
npm view @honyar/iot-mcp name

首次发布或切换账号：

npm login
npm whoami

启用或修改 npm 2FA 后，先刷新本机 CLI 登录会话：

npm logout
npm login --auth-type=web
npm whoami
npm profile get

如果发布时报：

Two-factor authentication or granular access token with bypass 2fa enabled is required to publish packages.

说明当前 npm 登录会话不满足发布安全策略。任选一种方式处理：

• 如果使用 security key / Touch ID，先执行上面的 npm logout + npm login --auth-type=web，在浏览器里完成 security key 验证后再重新发布。
• 如果使用 authenticator app / TOTP，重新执行 npm publish --access public，按提示输入 OTP；如果 CLI 未提示，可使用 npm publish --access public --otp 123456。
• 在 npmjs.com 生成 Granular Access Token，权限选择 packages/scopes 的 @honyar read and write，并启用 bypass 2FA。不要把 token 写入仓库，可临时使用：

export NPM_TOKEN="npm_xxx"
printf "//registry.npmjs.org/:_authToken=${NPM_TOKEN}\n" > /tmp/honyar-npmrc
npm whoami --userconfig /tmp/honyar-npmrc
npm publish --access public --userconfig /tmp/honyar-npmrc
rm /tmp/honyar-npmrc
unset NPM_TOKEN

发布公开 scoped package：

npm publish --access public
npm view @honyar/iot-mcp version

如果 npm view @honyar/iot-mcp name 返回 404 Not Found，表示该包名尚未被占用，可以首次发布。首次发布当前 0.1.0 时不要先执行 npm version patch；后续发新版时再用 npm version patch/minor/major 递增版本。

发布后用 stdio 客户端配置中的 npx -y @honyar/iot-mcp 验证启动。