NuVista Haven MCP Server

NuVista Haven MCP 服务（“AI 前台”）

Model Context Protocol 服务，让 AI 助手能够根据实时数据回答：

• NuVista Haven 有哪些房源 → search_properties
• 指定日期有哪些空房 → check_availability（Hospitable 日历）
• 价格是多少 → get_quote（每晚房价 × 入住晚数 + 清洁费）
• 如何直接预订 → get_booking_link（nuvistahaven.com）

安全模型

• 从设计上只读。 hospitable_client.py 仅通过允许的只读路径列表（/user、/properties、/reservations）使用一种 HTTP 方法（GET）。代码中没有任何 POST/PUT/PATCH/DELETE 方法——即使令牌具有写入权限范围，这段代码也无法修改 Hospitable 中的任何内容。
• 令牌处理。 Hospitable Personal Access Token 仅从 HOSPITABLE_API_TOKEN 环境变量中读取。绝不会将其硬编码、记录到日志或写入磁盘。

设置

cd ~/workspace/nuvista-mcp
python3 -m venv venv
./venv/bin/pip install -r requirements.txt

运行

# local testing (stdio)
HOSPITABLE_API_TOKEN=<token> ./venv/bin/python server.py

# public hosting (Streamable HTTP)
HOSPITABLE_API_TOKEN=<token> ./venv/bin/python server.py --http --port 8000

测试（使用模拟，无需令牌）

./venv/bin/python test_server.py

一次性操作：映射 Hospitable 房源 ID

properties.py 包含 12 个规范房源，并附有尽力推测的 Hospitable 名称（7 个把握较大，5 个为猜测——参见 guess_confidence）。 使用有效令牌运行匹配器，手动确认每个映射，然后为每个房源填写 hospitable_id：

HOSPITABLE_API_TOKEN=<token> ./venv/bin/python - <<'EOF'
import sys; sys.path.insert(0, '.')
from hospitable_client import HospitableClient
from logic import build_id_mapping
import json
print(json.dumps(build_id_mapping(HospitableClient()), indent=2))
EOF

"needs_human_confirm": true 的条目必须先经过验证才能使用——对于未映射的房源，check_availability/get_quote 不会运行。

已知 API 缺口／假设（请对照实时 API 验证）

1. 日历查询参数：get_calendar 发送 start_date/end_date（这是 /reservations 使用的 Hospitable 惯例）。如果端点忽略这些参数，可用日期范围可能不正确——请在首次连接实时 API 时验证。
2. 清洁费：日历日对象不包含清洁费。get_quote 会检查房源记录中常见的费用字段格式；如果不存在，结果会明确标记 total_is_partial_estimate: true——绝不会默默按零计算。
3. 预订链接日期参数：尚未验证能否通过查询字符串在 nuvistahaven.com 上预填日期，因此 get_booking_link 返回不带虚构参数的普通房源 URL。
4. 预订交叉核对：已实现 list_reservations，但日历才是事实来源；目前不会参考预订记录。

文件

• server.py — FastMCP 服务，包含 4 个工具，支持 stdio 和 Streamable HTTP
• logic.py — 工具逻辑（无需 MCP 即可测试）
• hospitable_client.py — 仅使用 GET 的 Hospitable Public API v2 客户端
• properties.py — 包含规范的 12 个房源注册表及 Hospitable 映射
• test_server.py — 基于模拟的测试