OnceHub

O OnceHub MCP Server fornece uma maneira

GitHub

Documentação

Servidor MCP OnceHub

Python 3.13+ License: MIT Code Coverage MCP Compatible

O Servidor MCP OnceHub fornece uma maneira padronizada para AI models e agents interagirem diretamente com sua API de agendamento do OnceHub. Em vez de enviar aos usuários um link de reserva e pedir que agendem manualmente, um Agente de IA pode recuperar disponibilidade e agendar reuniões em nome do usuário usando ferramentas MCP, por meio de um fluxo de linguagem natural. Esta solução permite que Agentes de IA externos acessem as APIs de agendamento do OnceHub em fluxos de trabalho orientados por IA usando o Protocolo de Contexto de Modelo (MCP) padronizado, via servidor remoto.

Compatível com: VS Code Copilot, OpenAI e qualquer cliente de IA compatível com MCP.

Sumário

Recursos

  • 🔌 Suporte ao Protocolo MCP - Funciona com qualquer cliente de IA compatível com MCP
  • 📅 Recuperação de Intervalos de Tempo - Busca slots de reserva disponíveis nos calendários de agendamento do OnceHub
  • 🗓️ Agendamento de Reuniões - Agenda reuniões automaticamente com informações do convidado
  • 🔐 Autenticação Segura - Autenticação baseada em chave de API via cabeçalhos
  • 🧪 Bem Testado - 92% de cobertura de código com testes unitários abrangentes
  • 🐳 Pronto para Docker - Containerizado para fácil implantação
  • 📝 Prompts Amigáveis para IA - Orientação de fluxo de trabalho integrada para assistentes de IA

Início Rápido

Comece com o Servidor MCP OnceHub no seu cliente de IA:

1. Obtenha sua Chave de API

Obtenha sua chave de API do OnceHub na documentação de Autenticação.

2. Configure seu Cliente

Crie .vscode/mcp.json no seu espaço de trabalho:

{
  "servers": {
    "oncehub": {
      "url": "https://mcp.oncehub.com/sse",
      "type": "http",
      "headers": {
        "authorization": "Bearer YOUR_ONCEHUB_API_KEY"
      }
    }
  }
}

Substitua YOUR_ONCEHUB_API_KEY pela sua chave de API real.

3. Comece a Usar

Peça ao seu assistente de IA para:

  • "Mostre-me os intervalos de tempo disponíveis para o calendário BKC-XXXXXXXXXX"
  • "Agende uma reunião para amanhã às 14h com João Silva"

⚠️ Executando seu próprio servidor MCP? Consulte Instalação e Execução Local para instruções de configuração.

✅ Servidor de Produção: Nosso servidor MCP hospedado está disponível em https://mcp.oncehub.com/sse.

Arquitetura

Architecture

Estrutura do Projeto

mcp-server/
├── main.py              # MCP server with tool definitions
├── models.py            # Pydantic data schemas for BookingForm and Location
├── pyproject.toml       # Project dependencies and configuration
├── Dockerfile           # Docker image configuration
├── .dockerignore        # Files to exclude from Docker build
└── README.md            # This file

Ferramentas

1. get_booking_time_slots

Recupera intervalos de tempo disponíveis de um calendário de reservas.

Parâmetros:

  • calendar_id (str, obrigatório): O ID do calendário de reservas (ex.: 'BKC-XXXXXXXXXX')
  • start_time (str, opcional): Filtrar slots a partir desta data/hora no formato ISO 8601 (ex.: '2026-02-15T09:00:00Z')
  • end_time (str, opcional): Filtrar slots até esta data/hora no formato ISO 8601 (ex.: '2026-02-28T17:00:00Z')
  • timeout (int, padrão: 30): Tempo limite de solicitação em segundos

Exemplo de Resposta:

{
  "success": true,
  "status_code": 200,
  "calendar_id": "BKC-XXXXXXXXXX",
  "total_slots": 5,
  "data": [
    {"start_time": "2026-02-10T10:00:00Z", "end_time": "2026-02-10T11:00:00Z"},
    {"start_time": "2026-02-10T14:00:00Z", "end_time": "2026-02-10T15:00:00Z"}
  ]
}

2. schedule_meeting

Agenda uma reunião em um intervalo de tempo especificado. Sempre chame get_booking_time_slots primeiro para garantir que o intervalo de tempo esteja disponível.

Parâmetros:

  • calendar_id (str, obrigatório): ID do calendário de reservas (ex.: 'BKC-XXXXXXXXXX')
  • start_time (str, obrigatório): O horário de início exato de um slot disponível no formato ISO 8601
  • guest_time_zone (str, obrigatório): Fuso horário do convidado no formato IANA (ex.: 'America/New_York', 'Europe/London')
  • guest_name (str, obrigatório): Nome completo do convidado
  • guest_email (str, obrigatório): Endereço de e-mail do convidado para confirmação
  • guest_phone (str, opcional): Número de telefone do convidado no formato E.164 (ex.: '+15551234567')
  • location_type (str, opcional): Modo de reunião - 'virtual', 'virtual_static', 'physical' ou 'guest_phone'
  • location_value (str, opcional): Detalhes do local com base no tipo:
    • virtual: Nome do provedor (ex.: 'zoom', 'google_meet', 'microsoft_teams')
    • virtual_static: Use null
    • physical: ID do endereço (ex.: 'ADD-XXXXXXXXXX')
    • guest_phone: Número de telefone no formato E.164
  • custom_fields (dict, opcional): Campos de formulário personalizados como pares chave-valor (ex.: {"company": "Acme", "interests": ["Demo"]})
  • timeout (int, padrão: 30): Tempo limite de solicitação em segundos

Exemplo de Resposta:

{
  "success": true,
  "status_code": 200,
  "booking_id": "BKG-123456789",
  "confirmation": {
    "guest_name": "John Doe",
    "guest_email": "john@example.com",
    "scheduled_time": "2026-02-10T10:00:00Z",
    "timezone": "America/New_York"
  }
}

Pré-requisitos

  • Python 3.13 ou superior
  • Gerenciador de pacotes uv (recomendado)
  • Chave de API do OnceHub - Consulte a documentação de Autenticação para obter sua chave de API
  • URL do endpoint da API do OnceHub (geralmente https://api.oncehub.com)

Variáveis de Ambiente

Crie um arquivo .env ou defina estas variáveis de ambiente:

# Required: Your OnceHub API endpoint
ONCEHUB_API_URL=https://api.oncehub.com

# Note: API key is passed via Authorization header from MCP clients
# Do NOT commit API keys to version control

Configuração do Cliente

Este servidor MCP é compatível com VS Code Copilot, Claude Desktop, OpenAI e outros clientes compatíveis com MCP.

VS Code / GitHub Copilot

Passo 1: Criar Diretório de Configuração

Windows (PowerShell):

New-Item -Path ".vscode" -ItemType Directory -Force
New-Item -Path ".vscode\mcp.json" -ItemType File -Force

macOS/Linux:

mkdir -p .vscode
touch .vscode/mcp.json

Passo 2: Configurar o Servidor

Edite .vscode/mcp.json:

{
  "servers": {
    "oncehub": {
      "url": "http://0.0.0.0:8000/sse",
      "type": "http",
      "headers": {
        "authorization": "Bearer YOUR_ONCEHUB_API_KEY"
      }
    }
  }
}

Opções de Configuração:

  • url: O endpoint do servidor MCP (altere para a URL do seu servidor se estiver auto-hospedado)
  • authorization: Sua chave de API do OnceHub com o prefixo Bearer
  • Nome do servidor (oncehub): Pode ser personalizado para qualquer identificador

Passo 3: Recarregar o VS Code

Após salvar a configuração, recarregue o VS Code para ativar a conexão com o servidor MCP.

Claude Desktop

Edite o arquivo de configuração do Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "oncehub": {
      "url": "http://0.0.0.0:8000/sse",
      "headers": {
        "authorization": "Bearer YOUR_ONCEHUB_API_KEY"
      }
    }
  }
}

Reinicie o Claude Desktop após salvar.

Outros Clientes MCP

Para outros clientes compatíveis com MCP, configure-os para conectar a:

  • Endpoint: http://0.0.0.0:8000/sse
  • Protocolo: HTTP com Server-Sent Events (SSE)
  • Autenticação: Token Bearer no cabeçalho Authorization

Nota de Segurança: Nunca envie chaves de API para o controle de versão. Use variáveis de ambiente ou gerenciamento seguro de segredos para implantações em produção.

Instalação e Execução Local com uv

1. Instalar uv (se ainda não estiver instalado)

Windows (PowerShell):

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Clonar o repositório

git clone https://github.com/scheduleonce/mcp-server.git
cd mcp-server

3. Definir variáveis de ambiente

Windows (PowerShell):

$env:ONCEHUB_API_URL="https://api.oncehub.com"

macOS/Linux:

export ONCEHUB_API_URL="https://api.oncehub.com"

Ou crie um arquivo .env:

echo "ONCEHUB_API_URL=https://api.oncehub.com" > .env

Nota: A chave de API é passada via cabeçalho Authorization dos clientes MCP (não como uma variável de ambiente).

4. Executar o servidor usando uv

Opção 1: Execução direta

uv run main.py

Opção 2: Usando o ponto de entrada do script

uv run mcp-server

O servidor iniciará em http://0.0.0.0:8000

5. Verificar se o servidor está em execução

Verificação de saúde:

curl http://localhost:8000/health

Conectar ao endpoint SSE:

curl http://localhost:8000/sse

Executando com Docker

Construir a imagem Docker

docker build -t mcp-server .

Executar o contêiner

docker run -p 8000:8000 mcp-server

Com variáveis de ambiente

docker run -p 8000:8000 \
  -e ONCEHUB_API_URL="https://api.oncehub.com" \
  mcp-server

Usando Docker Compose (recomendado)

Crie docker-compose.yml:

version: '3.8'
services:
  mcp-server:
    build: .
    ports:
      - "8000:8000"
    environment:
      - ONCEHUB_API_URL=https://api.oncehub.com
    restart: unless-stopped

Depois execute:

docker-compose up -d

Esquemas de Dados

Location

Representa detalhes do local da reunião.

Campos:

  • type (str): Tipo de local ("physical", "virtual", "phone")
  • value (str): Detalhes do local (endereço, URL, número de telefone)

Registro de Logs

O servidor inclui registro abrangente de logs para solicitações HTTP ao OnceHub:

  • Solicitações de saída (→)
  • Códigos de status de resposta (←)
  • Corpos de solicitação/resposta

Os logs são exibidos no console com carimbos de data/hora e níveis de log.

Endpoints da API

  • GET /health - Endpoint de verificação de saúde
  • GET /healthy - Endpoint alternativo de verificação de saúde
  • GET /sse - Endpoint Server-Sent Events para comunicação do protocolo MCP
  • GET /tools - Retorna as ferramentas MCP registradas com suas descrições, parâmetros obrigatórios e detalhes dos campos de entrada

Desenvolvimento

Instalar dependências manualmente

uv pip install fastmcp pydantic httpx

Instalar dependências de teste

uv pip install -e ".[test]"

Executar com diferentes níveis de log

Edite main.py e altere o parâmetro log_level:

asyncio.run(mcp.run_sse_async(host="0.0.0.0", port=8000, log_level="debug"))

Níveis de log disponíveis: "debug", "info", "warning", "error", "critical"

Testes

O projeto inclui testes unitários abrangentes para todas as ferramentas e funções.

Instalar Dependências de Teste

# Install test dependencies
uv pip install pytest pytest-asyncio pytest-cov pytest-mock

Executar Testes

Executar todos os testes:

uv run pytest

Executar testes com relatório de cobertura:

uv run pytest --cov=. --cov-report=html --cov-report=term

Executar arquivo de teste específico:

uv run pytest test_tools.py

Executar classe de teste específica:

uv run pytest test_tools.py::TestGetBookingTimeSlots

Executar teste específico:

uv run pytest test_tools.py::TestGetBookingTimeSlots::test_get_time_slots_success

Executar com saída detalhada:

uv run pytest -v

Executar e parar na primeira falha:

uv run pytest -x

Cobertura de Testes

Após executar os testes com cobertura, abra o relatório HTML:

# Windows
start htmlcov/index.html

# macOS
open htmlcov/index.html

# Linux
xdg-open htmlcov/index.html

Estrutura de Testes

  • test_tools.py - Testes unitários para todas as funções de ferramentas
    • TestGetApiKeyFromContext - Testes para extração de chave de API
    • TestGetBookingTimeSlots - Testes para recuperação de intervalos de tempo
    • TestScheduleMeeting - Testes para agendamento de reuniões

Todos os testes usam mocking para evitar chamadas reais à API e garantir execução rápida e confiável.

Implantação em Produção

Melhores Práticas de Segurança

  1. Gerenciamento de Chave de API

    • Nunca envie chaves de API para o controle de versão
    • Use variáveis de ambiente ou sistemas de gerenciamento de segredos
    • Rotacione as chaves de API regularmente

  2. Segurança de Rede

    • Use HTTPS em produção (adicione um proxy reverso como nginx)
    • Implemente limitação de taxa para evitar abuso
    • Use regras de firewall para restringir o acesso

  3. Monitoramento

    • Monitore o endpoint /health para disponibilidade
    • Configure agregação de logs (ex.: pilha ELK, CloudWatch)
    • Acompanhe os tempos de resposta da API e as taxas de erro

Opções de Implantação

Implantação Docker

# Build and tag the image
docker build -t oncehub-mcp-server:1.0.0 .

# Run with restart policy
docker run -d \
  --name oncehub-mcp \
  --restart unless-stopped \
  -p 8000:8000 \
  -e ONCEHUB_API_URL="https://api.oncehub.com" \
  oncehub-mcp-server:1.0.0

Implantação em Nuvem

  • AWS: Use ECS, Fargate ou EC2 com Application Load Balancer
  • Azure: Implante em Azure Container Instances ou App Service
  • GCP: Use Cloud Run ou Google Kubernetes Engine

Considerações de Desempenho

  • O tempo limite padrão é de 30 segundos - ajuste conforme suas necessidades
  • O servidor usa asyncio para tratamento concorrente de solicitações
  • Considere escalonamento horizontal para cenários de alto tráfego
  • Use pool de conexões para banco de dados/cache, se adicionado

Monitoramento de Saúde

# Simple health check script
curl -f http://localhost:8000/health || exit 1

# Docker healthcheck (add to Dockerfile)
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:8000/health || exit 1

Solução de Problemas

Erro: "API key is required"

Certifique-se de estar passando o parâmetro api_key ao chamar as ferramentas.

Erro: "404 Not Found" em /health

Certifique-se de que o servidor esteja em execução e acessível na porta 8000.

Erro: "405 Method Not Allowed" em /sse

O endpoint SSE requer uma solicitação GET, não POST. Use bibliotecas de cliente MCP adequadas ou curl com GET.

Nenhum log aparecendo para solicitações do OnceHub

Verifique se o registro de logs está configurado corretamente em main.py e se o servidor está em execução com log_level="info" ou "debug".

Licença

Este projeto é licenciado sob os termos da licença de código aberto MIT. Consulte MIT para os termos completos.

Suporte

Agradecimentos

Feito pela equipe Oncehub