NuVista Haven MCP Server

npx add-mcp 'https://nuvista-haven-mcp.onrender.com/mcp'

Servidor MCP NuVista Haven ("recepção de IA")

Servidor Model Context Protocol que permite que assistentes de IA respondam, a partir de dados ao vivo:

• quais propriedades da NuVista Haven existem → search_properties
• o que está disponível em determinadas datas → check_availability (calendários Hospitable)
• qual é o preço → get_quote (tarifas noturnas × noites + taxa de limpeza)
• onde reservar diretamente → get_booking_link (nuvistahaven.com)

Modelo de segurança

• Somente leitura por construção. hospitable_client.py expõe exatamente um verbo HTTP (GET) contra uma lista de permissões de caminhos de leitura (/user, /properties, /reservations). Não há métodos POST/PUT/PATCH/DELETE em nenhum lugar — mesmo que o token possa carregar escopos de escrita, este código não pode alterar nada no Hospitable.
• Manuseio de token. O Token de Acesso Pessoal do Hospitable é lido SOMENTE da variável de ambiente HOSPITABLE_API_TOKEN. Ele nunca é codificado, nunca é registrado em log, nunca é gravado em disco.

Configuração

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

Execução

# 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

Testes (simulados, sem necessidade de token)

./venv/bin/python test_server.py

Única vez: mapear IDs de propriedades Hospitable

properties.py contém as 12 propriedades canônicas com suposições de nomes Hospitable de melhor esforço (7 fortes, 5 suposições — veja guess_confidence). Com um token ativo, execute o correspondente e confirme cada mapeamento manualmente, depois preencha hospitable_id por propriedade:

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

Entradas com "needs_human_confirm": true devem ser verificadas antes do uso — check_availability/get_quote se recusam a executar para propriedades não mapeadas.

Lacunas/suposições conhecidas da API (verifique contra a API ao vivo)

1. Parâmetros de consulta do calendário: get_calendar envia start_date/end_date (a convenção Hospitable usada por /reservations). Se o endpoint os ignorar, as janelas de disponibilidade podem estar incorretas — verifique na primeira execução ao vivo.
2. Taxa de limpeza: não faz parte do objeto de dia do calendário. get_quote verifica o registro da propriedade em busca de formatos comuns de taxa; se ausente, o total é explicitamente marcado como total_is_partial_estimate: true — nunca zerado silenciosamente.
3. Parâmetros de data do link de reserva: o pré-preenchimento de data via string de consulta em nuvistahaven.com não é verificado, então get_booking_link retorna a URL simples da propriedade (sem parâmetros fabricados).
4. Verificação cruzada de reservas: list_reservations está implementado, mas o calendário é a fonte da verdade; as reservas não são consultadas atualmente.

Arquivos

• server.py — servidor FastMCP, 4 ferramentas, stdio + Streamable HTTP
• logic.py — lógica das ferramentas (testável sem MCP)
• hospitable_client.py — cliente GET-only da Hospitable Public API v2
• properties.py — registro canônico de 12 propriedades + mapeamento Hospitable
• test_server.py — testes baseados em simulação