NuVista Haven MCP server ("AI front desk")

Model Context Protocol server that lets AI assistants answer, from live data:

what NuVista Haven properties exist → search_properties
what's free on given dates → check_availability (Hospitable calendars)
what's the price → get_quote (nightly rates × nights + cleaning fee)
where to book direct → get_booking_link (nuvistahaven.com)

Security model

Read-only by construction. hospitable_client.py exposes exactly one HTTP verb (GET) against an allow-list of read paths (/user, /properties, /reservations). There are no POST/PUT/PATCH/DELETE methods anywhere — even though the token may carry write scopes, this code cannot mutate anything in Hospitable.
Token handling. The Hospitable Personal Access Token is read ONLY from the HOSPITABLE_API_TOKEN environment variable. It is never hardcoded, never logged, never written to disk.

Setup

bash

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

Run

bash

# 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

Tests (mocked, no token needed)

bash

./venv/bin/python test_server.py

One-time: map Hospitable property IDs

properties.py holds the 12 canonical properties with best-effort Hospitable name guesses (7 strong, 5 guesses — see guess_confidence). With a live token, run the matcher and confirm each mapping by hand, then fill in hospitable_id per property:

bash

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

Entries with "needs_human_confirm": true must be verified before use — check_availability/get_quote refuse to run for unmapped properties.

Known API gaps / assumptions (verify against live API)

Calendar query params: get_calendar sends start_date/end_date (the Hospitable convention used by /reservations). If the endpoint ignores them, availability windows may be wrong — verify on first live run.
Cleaning fee: not part of the calendar day object. get_quote probes the property record for common fee shapes; if absent, the total is explicitly marked total_is_partial_estimate: true — never silently zero.
Booking-link date params: date pre-fill via query string on nuvistahaven.com is unverified, so get_booking_link returns the plain property URL (no fabricated params).
Reservations cross-check: list_reservations is implemented but the calendar is the source of truth; reservations are not currently consulted.