MCP Analytics with GitHub OAuth

Un servidor MCP remoto con autenticación GitHub OAuth y seguimiento analítico integrado.

GitHub
3
Prueba este MCPPatrocinado

Documentación

Servidor de Protocolo de Contexto de Modelo (MCP) + GitHub OAuth + Analíticas

Este es un servidor de Protocolo de Contexto de Modelo (MCP) que admite conexiones MCP remotas, con autenticación GitHub OAuth y seguimiento de analíticas integrado impulsado por MCP Analytics.

Puedes implementarlo en tu propia cuenta de Cloudflare y, después de crear tu propia aplicación de cliente OAuth de GitHub, tendrás un servidor MCP remoto completamente funcional con analíticas exhaustivas. Los usuarios podrán conectarse a tu servidor MCP iniciando sesión con su cuenta de GitHub, y obtendrás información detallada sobre el uso de herramientas, el rendimiento y el comportamiento de los usuarios.

Características

  • ✅ Autenticación GitHub OAuth - Autenticación segura de usuarios mediante GitHub
  • ✅ Protocolo MCP Remoto - Implementación completa del servidor MCP
  • ✅ Seguimiento de Analíticas - Seguimiento automático del uso de herramientas, rendimiento y métricas de usuarios
  • ✅ Control de Acceso - Acceso a herramientas basado en roles según nombres de usuario de GitHub
  • ✅ Generación de Imágenes - Generación de imágenes impulsada por IA para usuarios autorizados
  • ✅ Listo para Producción - Implementado en Cloudflare Workers con Durable Objects

Panel de Analíticas

Este servidor realiza un seguimiento automático de:

  • 📊 Uso de Herramientas - Qué herramientas se utilizan con más frecuencia
  • ⏱️ Métricas de Rendimiento - Tiempos de ejecución y tasas de éxito
  • 👥 Analíticas de Usuarios - Usuarios activos y datos de sesiones
  • 🔧 Seguimiento de Errores - Solicitudes fallidas y detalles de errores
  • 💰 Seguimiento de Ingresos - Eventos de pago (si se utilizan herramientas de pago)

Consulta tus analíticas en: https://mcpanalytics.dev

Primeros Pasos

Clona el repositorio directamente e instala las dependencias:

git clone <your-repo-url>
cd mcp-github-oauth-analytics
npm install

Instrucciones de Configuración

1. Configuración de MCP Analytics

  1. Regístrate en https://mcpanalytics.dev
  2. Crea un nuevo proyecto y obtén tu clave de API
  3. Añade la clave de API a tu entorno:
# For production
wrangler secret put MCP_ANALYTICS_API_KEY

# For local development (.dev.vars file)
MCP_ANALYTICS_API_KEY=your_api_key_here

2. Configuración de GitHub OAuth

Para Producción

Crea una nueva Aplicación OAuth de GitHub:

  • URL de página de inicio: https://your-worker-name.your-subdomain.workers.dev
  • URL de devolución de llamada de autorización: https://your-worker-name.your-subdomain.workers.dev/callback
  • Anota tu ID de cliente y genera un secreto de cliente

Establece los secretos mediante Wrangler:

wrangler secret put GITHUB_CLIENT_ID
wrangler secret put GITHUB_CLIENT_SECRET
wrangler secret put COOKIE_ENCRYPTION_KEY # Use: openssl rand -hex 32

Para Desarrollo Local

Crea otra Aplicación OAuth de GitHub para desarrollo:

  • URL de página de inicio: http://localhost:8788
  • URL de devolución de llamada de autorización: http://localhost:8788/callback

Crea un archivo .dev.vars:

GITHUB_CLIENT_ID=your_development_github_client_id
GITHUB_CLIENT_SECRET=your_development_github_client_secret
COOKIE_ENCRYPTION_KEY=your_random_encryption_key
MCP_ANALYTICS_API_KEY=your_analytics_api_key

3. Configuración del Espacio de Nombres KV

# Create the KV namespace
wrangler kv:namespace create "OAUTH_KV"

# Update wrangler.toml with the returned KV ID

4. Configurar el Control de Acceso

Edita el ALLOWED_USERNAMES en tu archivo principal para controlar quién puede acceder a la herramienta de generación de imágenes:

const ALLOWED_USERNAMES = new Set<string>([
	'yourusername',
	'teammate1',
	'teammate2'
]);

Implementación

Implementa en Cloudflare Workers:

wrangler deploy

Tu servidor MCP estará disponible en: https://your-worker-name.your-subdomain.workers.dev/sse

Prueba de tu Servidor

Usando MCP Inspector

npx @modelcontextprotocol/inspector@latest

Introduce la URL de tu servidor y prueba el flujo de autenticación.

Usando Claude Desktop

  1. Abre Claude Desktop → Configuración → Desarrollador → Editar Configuración
  2. Añade esta configuración:
{
  "mcpServers": {
    "github-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-worker-name.your-subdomain.workers.dev/sse"
      ]
    }
  }
}
  1. Reinicia Claude Desktop y completa el flujo OAuth
  2. Prueba con: "¿Podrías usar la herramienta de matemáticas para sumar 23 y 19?"

Usando Otros Clientes MCP

Cursor: Usa el formato de comando: npx mcp-remote https://your-worker-url/sse

Windsurf: Añade la misma configuración JSON que en Claude Desktop

Herramientas Disponibles

add (Todos los Usuarios)

Herramienta simple de suma matemática para probar la conectividad.

Uso: "Suma 5 y 3"

generateImage (Solo Usuarios Autorizados)

Generación de imágenes impulsada por IA utilizando el modelo Flux de Cloudflare.

Uso: "Genera una imagen de una puesta de sol sobre las montañas"

Parámetros:

  • prompt: Descripción de la imagen a generar
  • steps: Pasos de calidad (4-8, mayor = mejor calidad)

Integración de Analíticas

Este servidor utiliza el AnalyticsMcpAgent que realiza un seguimiento automático de:

  • ✅ Tiempos de Ejecución de Herramientas - Cuánto tarda cada herramienta en ejecutarse
  • ✅ Tasas de Éxito/Fallo - Qué herramientas funcionan de manera fiable
  • ✅ Sesiones de Usuarios - Quién usa tu servidor y cuándo
  • ✅ Registro de Parámetros - Qué entradas proporcionan los usuarios (saneadas de forma segura)
  • ✅ Detalles de Errores - Contexto completo de errores para depuración
  • ✅ Datos de Usuario de GitHub - Correo electrónico y nombre de usuario de OAuth (para analíticas de usuarios)

Visualización de Analíticas

  1. Visita https://dashboard.mcpanalytics.dev
  2. Inicia sesión con la misma cuenta utilizada para crear tu clave de API
  3. Consulta paneles en tiempo real que muestran:
    • Tendencias de uso de herramientas
    • Métricas de rendimiento
    • Actividad de usuarios
    • Tasas de error y detalles

Desarrollo Local

Inicia el servidor de desarrollo:

wrangler dev

Tu servidor estará disponible en http://localhost:8788/sse

Arquitectura

Proveedor OAuth

La biblioteca del Proveedor OAuth sirve como una implementación completa del servidor OAuth 2.1, gestionando:

  • Autenticación de clientes MCP
  • Integración con GitHub OAuth
  • Gestión y validación de tokens
  • Almacenamiento seguro de estado en Cloudflare KV

Agente de Analíticas

El AnalyticsMcpAgent amplía la funcionalidad base de MCP con:

  • Seguimiento automático de eventos para todas las llamadas a herramientas
  • Identificación de usuarios mediante propiedades OAuth
  • Monitoreo de rendimiento y seguimiento de errores
  • Registro seguro de parámetros y resultados

Durable Objects

Proporciona gestión de estado persistente con:

  • Continuidad de sesiones de usuarios
  • Preservación del contexto de autenticación
  • Conexiones en tiempo real escalables

Seguridad y Privacidad

  • 🔒 OAuth 2.1 - Autenticación estándar de la industria
  • 🔐 Tokens Cifrados - Todos los datos de autenticación cifrados en tránsito y almacenamiento
  • 🛡️ Control de Acceso - Permisos granulares por usuario de GitHub
  • 🧹 Saneamiento de Datos - Los datos sensibles se redactan automáticamente de los registros
  • ⏰ Expiración de Tokens - Renovación y expiración automática de tokens

Solución de Problemas

Problemas Comunes

"Clave de API no válida" en analíticas: Verifica que tu MCP_ANALYTICS_API_KEY esté configurada correctamente

Errores de devolución de llamada OAuth: Asegúrate de que las URL de tu aplicación OAuth de GitHub coincidan exactamente con las URL de tu implementación

Las herramientas no aparecen: Comprueba que el nombre de usuario de GitHub del usuario esté en ALLOWED_USERNAMES para herramientas restringidas

Tiempos de espera de conexión: Verifica que tu Worker esté implementado y respondiendo en la URL correcta

Soporte

  • 📖 Documentación de MCP Analytics: https://docs.mcpanalytics.dev
  • 💬 Problemas de GitHub: Para errores y solicitudes de funciones
  • 📧 Soporte por Correo Electrónico: Disponible para usuarios del plan Pro

Licencia

Licencia MIT - consulta el archivo LICENSE para obtener más detalles.