OnceHub

El servidor MCP de OnceHub proporciona una forma estandarizada para que modelos y agentes de IA interactúen directamente con tu API de programación de OnceHub.

GitHub

Documentación

Servidor MCP de OnceHub

Python 3.13+ License: MIT Code Coverage MCP Compatible

El servidor MCP de OnceHub proporciona una forma estandarizada para que AI models y agents interactúen directamente con tu API de programación de OnceHub. En lugar de enviar a los usuarios un enlace de reserva y pedirles que programen manualmente, un agente de IA puede recuperar disponibilidad y programar reuniones en nombre del usuario utilizando las herramientas MCP, a través de un flujo de lenguaje natural. Esta solución permite que agentes de IA externos accedan a las API de programación de OnceHub dentro de flujos de trabajo impulsados por IA utilizando el servidor remoto estandarizado Model Context Protocol (MCP).

Compatible con: VS Code Copilot, OpenAI y cualquier cliente de IA compatible con MCP.

Tabla de Contenidos

Características

  • 🔌 Soporte del Protocolo MCP - Funciona con cualquier cliente de IA compatible con MCP
  • 📅 Recuperación de Franjas Horarias - Obtén franjas de reserva disponibles de los calendarios de OnceHub
  • 🗓️ Programación de Reuniones - Programa reuniones automáticamente con información del invitado
  • 🔐 Autenticación Segura - Autenticación basada en clave API mediante cabeceras
  • 🧪 Bien Probado - 92% de cobertura de código con pruebas unitarias exhaustivas
  • 🐳 Listo para Docker - Contenerizado para un despliegue fácil
  • 📝 Indicaciones Amigables para IA - Guía de flujo de trabajo integrada para asistentes de IA

Inicio Rápido

Comienza con el servidor MCP de OnceHub en tu cliente de IA:

1. Obtén tu Clave API

Obtén tu clave API de OnceHub desde la documentación de Autenticación.

2. Configura tu Cliente

Crea .vscode/mcp.json en tu espacio de trabajo:

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

Reemplaza YOUR_ONCEHUB_API_KEY con tu clave API real.

3. Comienza a Usar

Pide a tu asistente de IA que:

  • "Muéstrame las franjas horarias disponibles para el calendario BKC-XXXXXXXXXX"
  • "Programa una reunión para mañana a las 2 PM con Juan Pérez"

⚠️ ¿Ejecutando tu propio servidor MCP? Consulta Instalación y Ejecución Local para instrucciones de configuración.

✅ Servidor de Producción: Nuestro servidor MCP alojado está disponible en https://mcp.oncehub.com/sse.

Arquitectura

Architecture

Estructura del Proyecto

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

Herramientas

1. get_booking_time_slots

Recupera las franjas horarias disponibles de un calendario de reservas.

Parámetros:

  • calendar_id (str, obligatorio): El ID del calendario de reservas (ej., 'BKC-XXXXXXXXXX')
  • start_time (str, opcional): Filtrar franjas desde esta fecha y hora en formato ISO 8601 (ej., '2026-02-15T09:00:00Z')
  • end_time (str, opcional): Filtrar franjas hasta esta fecha y hora en formato ISO 8601 (ej., '2026-02-28T17:00:00Z')
  • timeout (int, predeterminado: 30): Tiempo de espera de la solicitud en segundos

Ejemplo de Respuesta:

{
  "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

Programa una reunión en una franja horaria específica. Siempre llama a get_booking_time_slots primero para asegurarte de que la franja esté disponible.

Parámetros:

  • calendar_id (str, obligatorio): ID del calendario de reservas (ej., 'BKC-XXXXXXXXXX')
  • start_time (str, obligatorio): La hora de inicio exacta de una franja disponible en formato ISO 8601
  • guest_time_zone (str, obligatorio): Zona horaria del invitado en formato IANA (ej., 'America/New_York', 'Europe/London')
  • guest_name (str, obligatorio): Nombre completo del invitado
  • guest_email (str, obligatorio): Correo electrónico del invitado para confirmación
  • guest_phone (str, opcional): Número de teléfono del invitado en formato E.164 (ej., '+15551234567')
  • location_type (str, opcional): Modo de reunión - 'virtual', 'virtual_static', 'physical' o 'guest_phone'
  • location_value (str, opcional): Detalles de ubicación según el tipo:
    • virtual: Nombre del proveedor (ej., 'zoom', 'google_meet', 'microsoft_teams')
    • virtual_static: Usar null
    • physical: ID de dirección (ej., 'ADD-XXXXXXXXXX')
    • guest_phone: Número de teléfono en formato E.164
  • custom_fields (dict, opcional): Campos de formulario personalizados como pares clave-valor (ej., {"company": "Acme", "interests": ["Demo"]})
  • timeout (int, predeterminado: 30): Tiempo de espera de la solicitud en segundos

Ejemplo de Respuesta:

{
  "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"
  }
}

Requisitos Previos

  • Python 3.13 o superior
  • uv administrador de paquetes (recomendado)
  • Clave API de OnceHub - Consulta la documentación de Autenticación para obtener tu clave API
  • URL del endpoint de la API de OnceHub (generalmente https://api.oncehub.com)

Variables de Entorno

Crea un archivo .env o establece estas variables de entorno:

# 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

Configuración del Cliente

Este servidor MCP es compatible con VS Code Copilot, Claude Desktop, OpenAI y otros clientes compatibles con MCP.

VS Code / GitHub Copilot

Paso 1: Crear el Directorio de Configuración

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

Paso 2: Configurar el Servidor

Edita .vscode/mcp.json:

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

Opciones de Configuración:

  • url: El endpoint del servidor MCP (cámbialo a la URL de tu servidor si lo autoalojas)
  • authorization: Tu clave API de OnceHub con el prefijo Bearer
  • Nombre del servidor (oncehub): Se puede personalizar a cualquier identificador

Paso 3: Recargar VS Code

Después de guardar la configuración, recarga VS Code para activar la conexión del servidor MCP.

Claude Desktop

Edita el archivo de configuración de 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"
      }
    }
  }
}

Reinicia Claude Desktop después de guardar.

Otros Clientes MCP

Para otros clientes compatibles con MCP, configúralos para conectarse a:

  • Endpoint: http://0.0.0.0:8000/sse
  • Protocolo: HTTP con Server-Sent Events (SSE)
  • Autenticación: Token Bearer en la cabecera Authorization

Nota de Seguridad: Nunca comprometas claves API en el control de versiones. Usa variables de entorno o gestión segura de secretos para despliegues en producción.

Instalación y Ejecución Local con uv

1. Instalar uv (si no está 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 el repositorio

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

3. Establecer variables de entorno

Windows (PowerShell):

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

macOS/Linux:

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

O crear un archivo .env:

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

Nota: La clave API se pasa a través de la cabecera Authorization desde los clientes MCP (no como variable de entorno).

4. Ejecutar el servidor usando uv

Opción 1: Ejecución directa

uv run main.py

Opción 2: Usando el punto de entrada del script

uv run mcp-server

El servidor se iniciará en http://0.0.0.0:8000

5. Verificar que el servidor está funcionando

Comprobación de salud:

curl http://localhost:8000/health

Conectar al endpoint SSE:

curl http://localhost:8000/sse

Ejecución con Docker

Construir la imagen Docker

docker build -t mcp-server .

Ejecutar el contenedor

docker run -p 8000:8000 mcp-server

Con variables de entorno

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

Usando Docker Compose (recomendado)

Crea docker-compose.yml:

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

Luego ejecuta:

docker-compose up -d

Esquemas de Datos

Location

Representa los detalles de ubicación de la reunión.

Campos:

  • type (str): Tipo de ubicación ("physical", "virtual", "phone")
  • value (str): Detalles de ubicación (dirección, URL, número de teléfono)

Registro (Logging)

El servidor incluye un registro exhaustivo para solicitudes HTTP a OnceHub:

  • Solicitudes salientes (→)
  • Códigos de estado de respuesta (←)
  • Cuerpos de solicitud/respuesta

Los registros se emiten a la consola con marcas de tiempo y niveles de registro.

Endpoints de la API

  • GET /health - Endpoint de comprobación de salud
  • GET /healthy - Endpoint alternativo de comprobación de salud
  • GET /sse - Endpoint Server-Sent Events para comunicación del protocolo MCP
  • GET /tools - Devuelve las herramientas MCP registradas con sus descripciones, parámetros requeridos y detalles de campos de entrada

Desarrollo

Instalar dependencias manualmente

uv pip install fastmcp pydantic httpx

Instalar dependencias de prueba

uv pip install -e ".[test]"

Ejecutar con diferentes niveles de registro

Edita main.py y cambia el parámetro log_level:

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

Niveles de registro disponibles: "debug", "info", "warning", "error", "critical"

Pruebas

El proyecto incluye pruebas unitarias exhaustivas para todas las herramientas y funciones.

Instalar Dependencias de Prueba

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

Ejecutar Pruebas

Ejecutar todas las pruebas:

uv run pytest

Ejecutar pruebas con informe de cobertura:

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

Ejecutar un archivo de prueba específico:

uv run pytest test_tools.py

Ejecutar una clase de prueba específica:

uv run pytest test_tools.py::TestGetBookingTimeSlots

Ejecutar una prueba específica:

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

Ejecutar con salida detallada:

uv run pytest -v

Ejecutar y detenerse en el primer fallo:

uv run pytest -x

Cobertura de Pruebas

Después de ejecutar las pruebas con cobertura, abre el informe HTML:

# Windows
start htmlcov/index.html

# macOS
open htmlcov/index.html

# Linux
xdg-open htmlcov/index.html

Estructura de Pruebas

  • test_tools.py - Pruebas unitarias para todas las funciones de herramientas
    • TestGetApiKeyFromContext - Pruebas para la extracción de clave API
    • TestGetBookingTimeSlots - Pruebas para la recuperación de franjas horarias
    • TestScheduleMeeting - Pruebas para la programación de reuniones

Todas las pruebas usan mocking para evitar llamadas API reales y garantizar una ejecución rápida y confiable.

Despliegue en Producción

Mejores Prácticas de Seguridad

  1. Gestión de Claves API

    • Nunca comprometas claves API en el control de versiones
    • Usa variables de entorno o sistemas de gestión de secretos
    • Rota las claves API regularmente

  2. Seguridad de Red

    • Usa HTTPS en producción (agrega un proxy inverso como nginx)
    • Implementa limitación de velocidad para prevenir abusos
    • Usa reglas de firewall para restringir el acceso

  3. Monitoreo

    • Monitorea el endpoint /health para disponibilidad
    • Configura agregación de registros (ej., stack ELK, CloudWatch)
    • Realiza seguimiento de tiempos de respuesta y tasas de error de la API

Opciones de Despliegue

Despliegue con 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

Despliegue en la Nube

  • AWS: Usa ECS, Fargate o EC2 con Application Load Balancer
  • Azure: Despliega en Azure Container Instances o App Service
  • GCP: Usa Cloud Run o Google Kubernetes Engine

Consideraciones de Rendimiento

  • El tiempo de espera predeterminado es de 30 segundos - ajústalo según tus necesidades
  • El servidor usa asyncio para el manejo concurrente de solicitudes
  • Considera el escalado horizontal para escenarios de alto tráfico
  • Usa agrupación de conexiones para base de datos/caché si se agrega

Monitoreo de Salud

# 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

Solución de Problemas

Error: "API key is required"

Asegúrate de pasar el parámetro api_key al llamar a las herramientas.

Error: "404 Not Found" en /health

Asegúrate de que el servidor esté funcionando y sea accesible en el puerto 8000.

Error: "405 Method Not Allowed" en /sse

El endpoint SSE requiere una solicitud GET, no POST. Usa bibliotecas de cliente MCP adecuadas o curl con GET.

No se muestran registros para solicitudes de OnceHub

Verifica que el registro esté configurado correctamente en main.py y que el servidor se esté ejecutando con log_level="info" o "debug".

Licencia

Este proyecto está licenciado bajo los términos de la licencia de código abierto MIT. Consulta MIT para los términos completos.

Soporte

Agradecimientos

Hecho por el equipo de Oncehub