Skip to main content
Glama
tabaldii

revpar-mcp

by tabaldii
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
TypeScript
Remote

RevPar MCP

CI

Agente de Revenue Management para hotelaria e aluguel por temporada, desenvolvido para demonstrar a integração entre LLMs, Model Context Protocol (MCP), APIs e regras determinísticas de negócio.

O sistema recebe perguntas em linguagem natural e combina dados de mercado, eventos locais e estratégias de precificação para produzir recomendações de ADR, ocupação, RevPAR e estadia mínima.

Status: MVP técnico para estudo e portfólio. Os dados de mercado e eventos são mocks locais e não representam informações de produção ou recomendações comerciais reais.

Demonstração

Acessar demonstração online

Objetivo do projeto

O RevPar MCP foi criado como um laboratório prático para estudar e demonstrar:

  • construção de agentes com uso de ferramentas;

  • integração entre OpenAI e MCP;

  • engenharia de prompt e controle de alucinações;

  • validação de respostas geradas por LLM;

  • modelagem de domínio com TypeScript e Zod;

  • tratamento de falhas em integrações externas;

  • observabilidade, testes automatizados e CI.

O projeto não foi desenhado para atender clientes reais, operar reservas ou substituir uma plataforma profissional de Revenue Management.

Visão geral

Exemplo de consulta:

Qual a diária recomendada para um imóvel simples em Chapecó no mês de dezembro?

O agente coordena as seguintes etapas:

  1. interpreta a solicitação e identifica cidade, período e tipologia;

  2. consulta métricas de mercado por meio de uma ferramenta MCP;

  3. busca eventos locais e possíveis impactos na demanda;

  4. executa o cálculo determinístico de precificação;

  5. valida as métricas e as premissas antes de responder;

  6. entrega uma resposta textual e indicadores estruturados para o dashboard.

Principais capacidades

Agente e MCP

  • Agente conversacional integrado à API da OpenAI.

  • Function calling para selecionar e executar ferramentas MCP.

  • Servidor MCP executado em memória por transporte interno.

  • Tools com schemas de entrada validados por Zod.

  • Resources MCP para políticas de precificação, ocupação e glossário de Revenue Management.

  • Prompts MCP parametrizados para análises de alta temporada e explicação de decisões tarifárias.

Motor de precificação

O cálculo é determinístico e considera:

  • ponderação entre ADR de aluguel por temporada e hotelaria;

  • multiplicador de demanda por eventos;

  • estratégia de lead time;

  • ajuste conforme ocupação-alvo;

  • piso operacional de R$ 150 por noite;

  • cálculo de RevPAR;

  • recomendação de estadia mínima (LOS).

Os dados mockados possuem normalização de cidade e bairro, incluindo acentos, caixa alta e variações de entrada.

Confiabilidade e controle do agente

  • Validação das métricas antes da resposta final.

  • Bloqueio de recomendações quando os dados são insuficientes ou inválidos.

  • Registro das fontes, premissas, nível de confiança e erros de validação.

  • Limite de rodadas de execução de ferramentas.

  • Timeout para chamadas MCP.

  • Retry controlado para falhas transitórias.

  • Circuit breaker para interromper temporariamente ferramentas com falhas consecutivas.

Segurança e operação da demonstração

  • Histórico conversacional isolado por sessão.

  • Cookie de sessão HTTP-only.

  • Rate limiting em memória.

  • Limite de tamanho das mensagens recebidas.

  • Respostas sem exposição de detalhes internos de exceções.

  • requestId para rastrear cada requisição.

  • Logs estruturados e trace individual das ferramentas executadas.

Esses controles são adequados ao objetivo demonstrativo do MVP. Rate limiting, sessões e histórico ainda dependem da memória da instância em execução.

Modelagem de domínio

As entidades principais estão centralizadas em src/domain/entities.ts e possuem tipos TypeScript e schemas Zod:

  • Property;

  • Neighborhood;

  • MarketMetric;

  • LocalEvent;

  • PricingRequest;

  • PricingRecommendation;

  • ToolExecution.

Essa camada cria contratos explícitos para os conceitos do negócio e reduz o risco de cada parte da aplicação interpretar os mesmos dados de maneira diferente.

Interface

Dashboard de Revenue Management

Interface para acompanhar ADR sugerida, RevPAR, ocupação, estadia mínima e comparação entre tarifas de mercado.

Dashboard do RevPar MCP

Interações com o agente

O agente interpreta perguntas em linguagem natural, consulta as ferramentas MCP e apresenta recomendações contextualizadas.

Interações com o RevPar MCP

Arquitetura

Usuário
  |
  v
Dashboard Next.js
  |
  | POST /api/chat
  v
RevParAgent
  |
  +--> OpenAI Adapter
  |       |
  |       v
  |    MCP Client <----> MCP Server em memória
  |                         |
  |                         +--> get_market_intelligence
  |                         +--> get_local_events
  |                         +--> calculate_dynamic_pricing_v2
  |                         +--> Resources e Prompts
  |
  +--> Validação de domínio
  +--> Observabilidade e Tool Trace
  +--> Histórico em memória por sessão

A separação entre agente, servidor MCP, ferramentas, domínio e validação permite evoluir cada responsabilidade de forma independente. O transporte em memória foi escolhido para manter o MVP simples e autocontido.

Ferramentas MCP

get_market_intelligence

Consulta métricas de mercado por localização, tipologia e mês.

Parâmetros principais:

  • city: cidade;

  • neighborhood: bairro ou região;

  • propertyType: studio, 1br, 2br ou luxury;

  • month: mês numérico de 01 a 12.

get_local_events

Busca eventos de impacto por cidade e mês, incluindo multiplicador de demanda e estadia mínima recomendada.

calculate_dynamic_pricing_v2

Calcula a recomendação tarifária considerando:

  • baseAirbnbAdr;

  • baseHotelAdr;

  • targetOccupancy;

  • eventDemandMultiplier;

  • eventMinStayDays;

  • leadTimeDays.

O retorno inclui suggestedAdr, estimatedRevPar e suggestedMinStayDays.

Testes e qualidade

Os testes priorizam as regras determinísticas e os contratos de integração, sem depender de chamadas reais à API da OpenAI.

São cobertos, entre outros pontos:

  • cálculo de precificação, RevPAR e estadia mínima;

  • diferenciação por cidade, bairro e tipologia;

  • identificação de eventos e impacto na demanda;

  • contrato entre servidor MCP e adaptador OpenAI;

  • validação das métricas e respostas do agente;

  • rate limiting e isolamento de sessão;

  • timeout, retry e circuit breaker;

  • histórico separado por sessão e expiração por TTL;

  • schemas das entidades de domínio;

  • validação do endpoint HTTP.

Comandos principais:

npm test
npm run typecheck
npm run build

O workflow de CI executa esses comandos automaticamente em pushes e pull requests.

Stack

  • Next.js 16;

  • React 19;

  • TypeScript 5;

  • OpenAI SDK;

  • Model Context Protocol SDK;

  • Zod;

  • Tailwind CSS;

  • Vitest.

Estrutura do projeto

src/
├── domain/
│   └── entities.ts          # Entidades e schemas do domínio
├── agent/
│   ├── historyRepository.ts # Histórico de recomendações por sessão
│   ├── openaiAdapter.ts     # Integração MCP com ferramentas OpenAI
│   ├── recommendationValidator.ts
│   ├── runner.ts            # Orquestração conversacional
│   └── toolExecutor.ts      # Timeout, retry, circuit breaker e trace
├── app/
│   ├── api/chat/route.ts    # Endpoint HTTP do agente
│   ├── page.tsx             # Dashboard
│   └── globals.css          # Estilos globais
├── mcp/
│   ├── mockData.ts          # Dados locais de mercado e eventos
│   ├── repository.ts        # Contrato de acesso aos dados
│   ├── server.ts            # Tools, resources e prompts MCP
│   └── tools.ts             # Regras de negócio expostas ao agente
├── lib/
│   └── security.ts          # Sessão e rate limiting
tests/                       # Testes unitários e de integração
.github/workflows/ci.yml    # Pipeline de qualidade