stayport

stayport

stayport 可从终端和 MCP 客户端连接 Hostex 房源管理账户，支持房源和房型、预订（包括创建直接预订、取消预订、门锁密码和每次入住的自定义字段）、可订状态、宾客对话、评价、Webhook、房源日历和价格、自定义渠道以及收入方式。一个二进制文件同时提供命令行界面和 stdio MCP 服务，公开相同的 23 项操作，作为 hostex_* 工具使用。

这里涉及两种凭证。每次 v3 API 调用都会发送 Hostex-Access-Token 请求头，其值来自 HOSTEX_ACCESS_TOKEN 环境变量；除非通过 HOSTEX_API_URL 覆盖基础 URL，否则调用将发送到 https://api.hostex.io/v3。如果未设置令牌，命令会报错并指出所需的环境变量，stayport 绝不会编造结果。宾客评价操作是令牌流程的唯一例外：它通过 Hostex Web 应用提交，因此使用 HOSTEX_EMAIL 和 HOSTEX_PASSWORD 登录（可选地通过 HOSTEX_WEB_API_URL 覆盖 Web 基础 URL，默认值为 https://hostex.io/api）；如果未设置这些变量，也会以同样明确的方式报错。

只有当响应封装中的 error_code 为 200 时，v3 调用才算成功；返回内容为封装中的 data。其他任何封装都会作为错误返回，并包含上游的 error_msg 和 request_id。

安装

npx @reneturcios/stayport properties

或者运行容器镜像：

docker run -i ghcr.io/cloudcorprecords/stayport

容器默认启动 MCP 服务（见下文）。传入 CLI 参数即可将其用作 CLI；传入上述环境变量，并使用 -e，让服务能够访问你的账户。

CLI

export HOSTEX_ACCESS_TOKEN=...   # from your Hostex account settings

stayport properties --limit 10
stayport room-types
stayport reservations --status accepted --start-check-in-date 2026-11-01
stayport create-reservation --property-id 123 --custom-channel-id 9 \
  --check-in-date 2026-11-10 --check-out-date 2026-11-12 \
  --guest-name "Ada Lovelace" --currency USD --rate-amount 20000 \
  --commission-amount 1000 --received-amount 20000 --income-method-id 3
stayport cancel-reservation RES-123
stayport update-lock-code STAY-9 4321
stayport get-custom-fields STAY-9
stayport update-custom-fields STAY-9 '{"gate_code":"88"}'
stayport availabilities --property-ids 1,2 --start-date 2026-11-01 --end-date 2026-11-07
stayport update-availabilities --property-ids 1,2 --available false --dates 2026-11-03
stayport conversations --limit 5
stayport conversation conv-9
stayport send-message conv-9 --message "Welcome! Check-in is at 3pm."
stayport reviews --property-id 123
stayport create-review RES-123 --score 5 --content "Great guest"
stayport webhooks
stayport create-webhook https://example.com/hook
stayport delete-webhook 17
stayport listing-calendar --start-date 2026-11-01 --end-date 2026-11-30 \
  --listings '[{"channel_type":"airbnb","listing_id":"L1"}]'
stayport update-listing-prices --channel-type airbnb --listing-id L1 \
  --prices '[{"date":"2026-11-05","price":15000}]'
stayport custom-channels
stayport income-methods

stayport --version

宾客评价命令还需要 Web 应用登录凭证：

export [email protected]
export HOSTEX_PASSWORD=...
stayport post-guest-review --reservation-order-code 0-ABC123-xyz \
  --content "Lovely stay" --recommend 1 --overall-rating 5 \
  --cleanliness 4 --respect-of-house-rules 5 --communication 5

命令成功时会将响应中的 data 以 JSON 格式打印出来。退出代码：成功时为 0；调用失败时为 1（凭证缺失、上游封装错误、网络故障）；用法错误时为 2。创建预订时，金额的单位为分，与 Hostex API 的要求完全一致；房源价格则按 API 预期的格式传入。

MCP 服务

一个二进制文件同时提供两种使用方式。mcp 子命令会启动 stdio MCP 服务：

npx -y @reneturcios/stayport mcp

MCP 客户端配置：

{
  "mcpServers": {
    "stayport": {
      "command": "npx",
      "args": ["-y", "@reneturcios/stayport", "mcp"],
      "env": {
        "HOSTEX_ACCESS_TOKEN": "..."
      }
    }
  }
}

如果希望宾客评价工具正常工作，请将 HOSTEX_EMAIL 和 HOSTEX_PASSWORD 添加到该 env 块中；其他 22 个工具只需要访问令牌。

工具

工具	输入	功能
hostex_list_properties	offset、limit、id（均为可选）	列出房源及其 ID、标题、地址、渠道和坐标。
hostex_list_room_types	offset、limit（可选）	列出房型。
hostex_list_reservations	reservation_code、property_id、status、入住/退房日期范围、order_by、offset、limit（均为可选）	列出并搜索预订。
hostex_create_reservation	property_id（字符串）、custom_channel_id、check_in_date、check_out_date、guest_name、currency、rate_amount、commission_amount、received_amount、income_method_id（必填）；number_of_guests、email、mobile、remarks（可选）	创建直接预订。金额以分为单位。
hostex_cancel_reservation	reservation_code	取消直接预订（不支持渠道预订）。
hostex_update_lock_code	stay_code、lock_code	设置住宿的门锁密码。
hostex_get_custom_fields	stay_code	读取住宿的自定义字段。
hostex_update_custom_fields	stay_code、custom_fields（对象）	写入住宿的自定义字段，可在自动消息中使用 {{cf.field_name}}。
hostex_list_availabilities	property_ids（逗号分隔的字符串）、start_date、end_date	查询指定日期范围内的可订情况。
hostex_update_availabilities	property_ids（数字数组）、available；start_date、end_date、dates（可选）	设置指定日期或日期范围的可订情况。
hostex_list_conversations	offset、limit（可选）	列出客人对话和咨询。
hostex_get_conversation	conversation_id	获取包含所有消息的对话。
hostex_send_message	conversation_id；message、jpeg_base64（可选）	向客人发送文本或 JPEG 图片消息。
hostex_list_reviews	reservation_code、property_id、review_status、退房日期范围、offset、limit（均为可选）	按筛选条件查询评价。
hostex_create_review	reservation_code；host_review_score、host_review_content、host_reply_content（可选）	为预订创建评价或回复。
hostex_post_guest_review	reservation_order_code、content、recommend（"0"/"1"）、overall_rating、cleanliness、respect_of_house_rules、communication（"1"–"5"）；三个可选的 *_content 备注	通过 Web 应用发布完整的客人评价；需要使用电子邮箱/密码登录。
hostex_list_webhooks	（无）	列出已配置的 Webhook。
hostex_create_webhook	url	创建 Webhook。
hostex_delete_webhook	webhook_id	删除可管理的 Webhook。
hostex_get_listing_calendar	start_date、end_date、listings（{channel_type, listing_id} 数组）	获取多个房源的日历信息。
hostex_update_listing_prices	channel_type、listing_id、prices（{date, price} 数组）	更新房源价格。
hostex_list_custom_channels	（无）	列出 Custom Options Page 中的自定义渠道。
hostex_list_income_methods	（无）	列出 Custom Options Page 中的收入方式。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx

许可证

MIT — 参见 LICENSE。