Floyd

Servidor MCP Floyd

Servidor MCP que expõe ferramentas de agendamento e reserva do Floyd Engine para agentes de IA. Construído sobre o transporte HTTP Streamable do Model Context Protocol.

Para a documentação da API do motor, consulte a pasta docs no repositório do motor.

Ferramentas

Ferramenta	Descrição
floyd_get_available_slots	Verifica horários disponíveis para um serviço
floyd_hold_booking	Coloca uma reserva temporária em um horário
floyd_confirm_booking	Confirma uma reserva mantida (requer consentimento explícito do usuário)
floyd_cancel_booking	Cancela uma reserva mantida ou confirmada
floyd_reschedule_booking	Move uma reserva para um novo horário
floyd_update_booking	Atualiza os metadados de uma reserva
floyd_get_booking	Recupera detalhes e status da reserva

Configuração

pnpm install

Variáveis de ambiente

Variável	Obrigatória	Padrão	Descrição
FLOYD_BASE_URL	Não	http://localhost:4000/v1	URL base do Floyd Engine
PORT	Não	3000	Porta do servidor HTTP

Uso

Modo HTTP (HTTP Streamable)

pnpm dev

Endpoint MCP: POST / Verificação de saúde: GET /health

Modo Stdio

pnpm dev -- --stdio

Autenticação

Quando o motor Floyd exige autenticação, os agentes conectados fornecem sua chave de API via:

1. Cabeçalho Authorization: Bearer <token> (preferido)
2. Parâmetro de consulta ?token=<value>

A chave de API é encaminhada ao motor Floyd em cada solicitação. Se o motor tiver a autenticação desativada (ex.: auto-hospedado), nenhuma chave é necessária.

Fluxo de reserva

get_available_slots → hold_booking → confirm_booking
                                   ↘ cancel_booking
                                   ↘ reschedule_booking
                                   ↘ update_booking (metadata)

1. Obter horários — consulta horários disponíveis, retorna tokens slotId assinados
2. Manter — reserva um horário usando o slotId (ou campos explícitos). Cria uma reserva no estado held
3. Confirmar — finaliza a reserva. Requer userConfirmed: true
4. Cancelar — libera uma reserva mantida ou confirmada
5. Reagendar — move uma reserva para um novo horário, preservando sua identidade
6. Atualizar — anexa ou substitui metadados (ex.: tamanho do grupo, solicitações especiais)

Desenvolvimento

pnpm test          # run tests
pnpm typecheck     # type-check
pnpm lint          # eslint
pnpm format        # prettier
pnpm build         # bundle with tsup

Produção

pnpm build
pnpm start

O servidor lida com SIGTERM/SIGINT para encerramento gracioso. Solicitações HTTP à API Floyd têm um tempo limite de 10 segundos.