hostaway-kit

hostaway-kit

面向已将 Hostaway 用作 PMS 的运营人员的只读 MCP 服务，以及 Cursor / Claude Code / Codex 技能。

向助手询问房源、日历、收件箱和简单报告。Hostaway 仍是事实来源系统。本工具包绝不写入数据——不发送消息、不添加日历屏蔽时段、不创建预订。

由 STYLABS 推出。STYLABS 是一家 AI 原生创业工作室，打造定制的 Hostaway 预订网站和运营仪表盘。STYLABS 并非 Hostaway 官方合作伙伴。

你将获得

1. 只读 MCP（stdio）——list_listings、get_listing、get_calendar、list_reservations、list_conversations、list_messages，以及收件箱分类、回复草稿和报告。
2. 应用于每个房源 / 预订 / 消息载荷的拒绝列表：wifiPassword、wifiUsername、doorSecurityCode、doorCode、doorCodeVendor、doorCodeInstruction，以及所有 invoicing* 联系人字段。
3. Hostaway 不会计算的收件箱智能功能——未回复 / SLA 分类，以及基于该房源的字段、入住须知和日历生成的建议回复。房价取自日历，否则会标记为未知。不会发送任何内容。
4. Hostaway 不提供的业主报告——根据日历统计入住率和空置时段、未回复对话数量、房源完整度（照片 / 入住须知 / 便利设施）。不含财务数据。
5. 本仓库中的技能（不在 npm 上），用于指导模型使用 MCP 工具，且绝不编造数字。

与 Hostaway Public API 的映射如下：

工具包行为	Hostaway
正在营业的房源	GET /v1/listings?specialStatus[]=active
单个房源	GET /v1/listings/{id}?includeResources=1
日历	GET /v1/listings/{id}/calendar?includeResources=1
在房源列表中搜索入住日期	availabilityDateStart、availabilityDateEnd、availabilityGuestNumber
入住 / 退房时间	整数 0–23（checkInTimeStart、checkInTimeEnd、checkOutTime）
便利设施	amenityId 整数，而非自由文本名称（GET /v1/amenities 可解析名称）
收件箱	GET /v1/conversations、GET /v1/conversations/{id}/messages
创建预订 / 发送消息	不支持

如果未设置 HOSTAWAY_ACCOUNT_ID 或 HOSTAWAY_CLIENT_SECRET，服务会提供捆绑的示例数据，因此仍可通过 npx 演示。

安装 / 运行

npx -y hostaway-kit

或者从本仓库运行：

npm install
npm run build
node dist/index.js

仅支持 stdio。日志会输出到 stderr。凭据为可选项。

环境变量

变量	必需	用途
HOSTAWAY_ACCOUNT_ID	实时读取时需要	Hostaway 账号 ID（POST /v1/accessTokens 中的 client_id）
HOSTAWAY_CLIENT_SECRET	实时读取时需要	Hostaway 控制面板中的客户端密钥
HOSTAWAY_KIT_NOW	否	用于固定 SLA 计算中“当前时间”的 ISO 时间戳（供测试使用）

从 Hostaway 控制面板获取 API 客户端密钥。本工具包不提供也不使用 Hostaway 账号。

Cursor

添加到 ~/.cursor/mcp.json（或项目的 .cursor/mcp.json）：

{
  "mcpServers": {
    "hostaway": {
      "command": "npx",
      "args": ["-y", "hostaway-kit"],
      "env": {
        "HOSTAWAY_ACCOUNT_ID": "your-account-id",
        "HOSTAWAY_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

将两个 env 值留空，或省略 env，即可运行示例数据演示。

将本仓库中的技能复制到 Cursor：

cp -R skills/* ~/.cursor/skills/

Claude Code

添加到 ~/.claude.json（或项目的 .mcp.json）：

{
  "mcpServers": {
    "hostaway": {
      "command": "npx",
      "args": ["-y", "hostaway-kit"],
      "env": {
        "HOSTAWAY_ACCOUNT_ID": "your-account-id",
        "HOSTAWAY_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

技能：

mkdir -p .claude/skills
cp -R skills/* .claude/skills/

Codex

~/.codex/config.toml：

[mcp_servers.hostaway]
command = "npx"
args = ["-y", "hostaway-kit"]

[mcp_servers.hostaway.env]
HOSTAWAY_ACCOUNT_ID = "your-account-id"
HOSTAWAY_CLIENT_SECRET = "your-client-secret"

技能位于本仓库的 skills/ 目录下。将 Codex 指向该目录，或将 SKILL.md 文件复制到 Codex 技能路径中。

技能（仅限仓库）

技能	使用场景
skills/hostaway-pms	Hostaway 仍是 PMS。不要推荐他们的网站构建器。
skills/hostaway-guest-answers	仅根据该房源的字段回答客人。
skills/hostaway-availability	使用列表筛选条件和日历查询日期范围内的可订状态。
skills/hostaway-inbox	SLA 分类和回复草稿。绝不发送。
skills/hostaway-reporting	入住率、空置时段、未回复数量、完整度。

npm 包仅包含 MCP 服务。技能保留在 git 中。

工具

工具	功能
list_listings	活跃房源；可选按城市 / 名称 / 可订状态筛选
get_listing	单个房源，包含资源，并移除机密信息
get_calendar	按天列出状态、isAvailable 和 price（null = 未知）
list_reservations	预订；移除门禁码
list_conversations	收件箱对话串
list_messages	对话串中的消息
inbox_triage	未回复消息 + SLA（breached / waiting / answered）
draft_reply	基于事实起草回复。send 始终为 false。
report_occupancy	已预订 / 可订 / 已屏蔽 + 已屏蔽的空档
report_inbox	未回复对话串数量
report_completeness	缺少照片、入住须知、便利设施的情况

入住率 = 已预订晚数 ÷（已预订晚数 + 可订晚数）。已屏蔽晚数会作为空档列出，不计入入住率。

Fixture 数据

演示房源（并非真实的 Hostaway 账户）：

• 101 Harbor View Studio — 信息完整的房源。原始 fixture 包含 wifiPassword / 发票联系人；拒绝名单会移除这些信息。
• 102 Riverside Loft — 没有照片。
• 103 Pine Cabin — 没有入住须知，也没有便利设施。
• 199 — 已归档；除非 includeArchived 为 true，否则不会列出。
• 101 的 2026 年 8 月日历包含已预订晚数、一个为期两晚的已屏蔽空档（8 月 6–7 日），以及 price: null 的 8 月 11 日。
• 未读对话串 501（SLA 违约）、502（未超出 SLA）、504（询问信息不完整房源的宠物规定）。503 已回复。

测试

npm test

涵盖拒绝名单、fixture 筛选、入住率计算、SLA 计数、拒绝泄露机密信息和编造价格的回复草稿，以及不存在发送路径。

范围之外

任何形式的写入操作。房客付款、Stripe、WordPress 插件、托管的 Claude 连接器、Cursor 市场插件、Hostaway 网站构建器、Flagship 房客网站、业主结算单或真实客户端数据。

许可证

MIT。请参阅 LICENSE。

Hostaway 是其所有者的商标。本项目与 Hostaway 无关，也未获得 Hostaway 的认可。