Hotel MCP

独立的酒店工单业务服务。工单、客房/前台权限、状态机、幂等和事件归本项目；AI 硬件平台仅通过 MCP 调用工具和订阅业务事件。本项目不导入硬件平台代码，不需要相邻仓库，使用 Python 3.12。

启动与测试

python -m venv .venv
.venv/Scripts/python.exe -m pip install -e ".[test]"
.venv/Scripts/python.exe -m hotel_mcp --init
.venv/Scripts/python.exe -m hotel_mcp
.venv/Scripts/python.exe -m pytest -q

默认 127.0.0.1:8120，健康检查 /health。--init 创建 data/config.json 的随机独立凭据，不覆盖已有配置。业务数据库 data/hotel.sqlite3。已迁入旧数据时跳过 --init。配置、数据库、日志均不提交。

容器独立构建：docker compose up -d --build。首次须先用上述命令生成配置。Compose 只暴露本机 8120；跨机器使用 TLS 代理，按部署拓扑配置网络，不依赖硬件平台的 Docker 网络。

Related MCP server: rebar-mcp

MCP 接口与业务边界

传输为 Streamable HTTP，认证 Authorization: Bearer <该 principal 的 token>。每个 principal 使用独立 ID、至少 32 字符的独立随机 token。酒店、角色、房间从服务端配置确定，模型不能传参越权；MCP session 也按凭据隔离。

状态路径：客房提交 → 前台受理 → 前台完成。提交必须提供稳定 request_key，重试复用原值；同键不同内容拒绝，同状态同备注重试不产生重复事件。请求和事件在同一 SQLite 事务提交。只有工作人员明确确认后才受理/完成，通知不能自动改变工单状态。

客房提示词建议：确认住客要求后提交请求；同次请求及重试复用 request_key，失败不声称前台已收到；可查询工单进度。 前台提示词建议：查询待办，确认具体工单和工作人员意见后受理或完成，不因收到通知自动操作。

事件契约

服务声明可订阅资源 business://events，更新发 notifications/resources/updated。客户端调用 resources/read，URI business://events?after=<seq>。返回 JSON { "events": [{"seq":1,"event_type":"...","speech_text":"..."}], "has_more":false, "next_cursor":1 }。每页最多 50 条；seq 在数据库内递增，当前凭据只读授权范围事件，空洞正常。

平台事件订阅器持久化自己的游标，通知仅用于唤醒，断线后按游标补读。平台如何把文本通知到智能体/设备由平台实现；本服务不持有 manager 密钥、模型密钥、设备 MAC、MQTT 或硬件 SDK。业务凭据不同即可连接不同业务实例。

硬件平台接入时分别为客房和前台智能体配置上述服务地址及凭据，再由平台的通用事件订阅器绑定设备与智能体配置。地址由平台服务访问，不是由 ESP32 访问；容器访问宿主机需使用可达地址。

事件投递接受不等于设备已播放。业务状态以工单查询为准；本参考实现没有播放完成回执，不保证通知恰好播放一次。数据库重建并重置序号时，消费者必须重置对应游标。单进程部署；多副本需升级共享存储与消费者租约。

迁移与验证

2026-10-18 从 WhiteCat Interactive 的酒店服务拆出，来源提交 6a2aafc74edae378f8e0c965f6fc33b0389b0451 的 services/hotel_mcp/{server,store,__main__}.py，修改包路径、默认数据位置和独立构建入口。平台事件桥接器留在平台，不在本项目部署。Git 历史保留本仓库原始 Apache-2.0 LICENSE 提交。

测试通过真实 HTTP MCP 会话覆盖：请求—受理—完成、资源订阅、断线补读、幂等、跨房间/酒店/角色/会话拒绝。测试客户端只是协议验收夹具，不是运行依赖。没有使用真实设备播报作为验收证据。