NuVista Haven MCP Server

NuVista Haven MCP サーバー（「AI フロントデスク」）

AI アシスタントがライブデータをもとに回答できるようにする Model Context Protocol サーバーです：

• NuVista Haven の物件 → search_properties
• 指定した日付に空きがあるか → check_availability（Hospitable のカレンダー）
• 料金はいくらか → get_quote（1泊あたりの料金 × 泊数 ＋ 清掃料金）
• 直接予約するにはどこにアクセスするか → get_booking_link（nuvistahaven.com）

セキュリティモデル

• 設計上、読み取り専用です。 hospitable_client.py が公開する HTTP メソッドは、読み取りパスの許可リスト（/user、 /properties、/reservations）に対する 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 には、Hospitable の物件名の最善努力による推定を含む、正規の 12 件の物件が登録されています（確度が高いものが 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 の慣例に従ったものです。エンドポイントが これらを無視する場合、空き状況の期間が正しくない可能性があります。初回のライブ実行時に確認してください。
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 — モックベースのテスト