Innaguma MCP Server

Un servidor Model Context Protocol (MCP) que proporciona integración con la API de Innaguma para acceder a estadísticas, análisis de contenido y datos de gestión de plataformas.

Descripción

Este MCP expone las funcionalidades principales de la API de Innaguma a través de herramientas fáciles de usar, permitiendo a los clientes MCP acceder a:

• Búsqueda Avanzada: Búsqueda por Elasticsearch en contenido protegido
• Reportes Personalizados: Usuarios únicos, noticias visitadas, noticias subidas, evolución de visitas
• Estadísticas Totales: Accesos, noticias, lectores, analistas, descargas, subidas y votos
• Gestión de Lectores: Información de usuarios, historial de visualizaciones, votos y descargas
• Gestión de Noticias: Listados, detalles, votos y estadísticas de visitas
• Gestión de Categorías: Categorías disponibles, suscriptores e información detallada
• Gestión de Analistas: Analistas, publicaciones y análisis de votación

Instalación

Requisitos

• Python 3.10+
• pip

Pasos de instalación

1. Clona o crea el proyecto:

cd InnagunaMCP

2. Instala las dependencias:

pip install -e .

O instala las dependencias manualmente:

pip install fastmcp>=2.13.0 aiohttp>=3.9.0 python-dotenv>=1.0.0 pyjwt>=2.8.0

Configuración

1. Copia el archivo .env.example a .env:

cp .env.example .env

2. Edita .env con tus credenciales de Innaguma:

INNAGUMA_AUTH_URL=https://<tu-subdominio>.innguma.com
INNAGUMA_SITE=<tu-subdominio>
INNAGUMA_USERNAME=<tu-usuario>
INNAGUMA_PASSWORD=<tu-contraseña>

Uso

Iniciar el servidor

python MCP.py

O si está instalado como paquete:

innaguma-mcp

Herramientas Disponibles

Búsqueda y Reportes Personalizados

• search_innaguma(query, page, order): Busca contenido en Innaguma usando Elasticsearch

  • query - Término de búsqueda
  • page - Número de página (default: 1)
  • order - Orden: "relevance" o "date" (default: "relevance")
  • Retorna: Títulos, URLs, fecha, fragmentos, etiquetas e imágenes

• get_unic_users_with_dates(start_date, end_date, report_id): Obtiene reporte de usuarios únicos en un período

  • start_date - Fecha inicial (formato: YYYY-MM-DD o DD-MM-YYYY)
  • end_date - Fecha final (formato: YYYY-MM-DD o DD-MM-YYYY)
  • report_id - ID del reporte (default: 3)
  • Retorna: Título, descripción, tabla de datos y conteo de filas

• get_most_visited_news(year, month, limit): Obtiene noticias más visitadas de un mes (Reporte 32)

  • year - Año (opcional, ej: 2025)
  • month - Mes (opcional, 1-12)
  • limit - Límite de items (opcional, ej: 25)
  • Retorna: Lista de noticias con títulos, URLs y conteo de visitas

• get_evolution_of_visited_news(): Obtiene evolución de noticias visitadas por mes (Reporte 14)

  • Retorna: Lista mensual con contador de noticias visitadas

• get_unvisited_news(fecha_inicio, fecha_fin, limit): Obtiene noticias no visitadas (Reporte 27)

  • fecha_inicio - Fecha inicial (opcional, formato: DD-MM-YY o YYYY-MM-DD)
  • fecha_fin - Fecha final (opcional, formato: DD-MM-YY o YYYY-MM-DD)
  • limit - Límite de items (opcional)
  • Retorna: Lista de noticias no visitadas con títulos y URLs

• news_uploaded_month(year, month): Obtiene cantidad de noticias subidas en un mes (Reporte 29)

  • year - Año (ej: 2025)
  • month - Mes (1-12)
  • Retorna: Año, mes y cantidad de noticias subidas

Estadísticas Totales

• get_platform_totals(): Obtiene estadísticas totales de la plataforma
• get_users_totals(): Obtiene estadísticas totales de usuarios
• get_user_totals(user_id): Obtiene estadísticas de un usuario específico
• get_news_totals(): Obtiene estadísticas de noticias
• get_categories_totals(): Obtiene estadísticas de categorías
• get_most_searched_words(from_date, to_date): Obtiene palabras más buscadas en rango de fechas

Lectores (Readers)

• list_readers(): Lista todos los lectores
• get_readers_overview(): Obtiene resumen completo de lectores
• get_reader_overview(reader_id): Obtiene detalles de un lector específico
• get_reader_viewed_news(reader_id): Obtiene noticias vistas por un lector
• get_reader_voted_news(reader_id): Obtiene noticias votadas por un lector
• get_reader_downloads(reader_id): Obtiene archivos descargados por un lector

Noticias

• list_news_by_date(from_date, to_date): Lista noticias en rango de fechas
• get_news_overview(): Obtiene resumen de todas las noticias
• get_news_details(news_id): Obtiene detalles de una noticia específica
• get_news_votes(news_id): Obtiene votos de una noticia
• get_news_visits(news_id): Obtiene visitas de una noticia

Categorías

• list_categories(): Lista todas las categorías
• get_categories_overview(): Obtiene resumen de categorías
• get_category_details(category_id): Obtiene detalles de una categoría
• get_category_subscriptions(category_id): Obtiene suscriptores de una categoría

Analistas

• list_analysts(): Lista todos los analistas
• get_analysts_overview(): Obtiene resumen de analistas
• get_analyst_overview(analyst_id): Obtiene detalles de un analista
• get_analyst_publications(analyst_id): Obtiene publicaciones de un analista
• get_analyst_voted_publications(analyst_id): Obtiene publicaciones votadas de un analista

Formato de Fechas

Las fechas deben proporcionarse en formato YYYY-MM-DD:

2024-01-15
2024-12-31

Manejo de Errores

El servidor maneja los siguientes tipos de errores:

• 400 Bad Request: Faltan cabeceras requeridas
• 401 Unauthorized: Token de autenticación inválido o expirado
• 404 Not Found: Recurso no encontrado o formato de fecha inválido
• 500 Internal Server Error: Error interno del servidor

Autenticación

El servidor realiza autenticación automática mediante:

1. Autenticación de API (JWT): Obtiene un token JWT durante la primera solicitud a través de la API de autenticación de Innaguma. El token se renovará automáticamente si expira.

2. Autenticación de Sesión Web: Para reportes y búsqueda, el servidor mantiene una sesión web autenticada que se establece automáticamente al acceder por primera vez a estos recursos.

Los tokens expiran después de 30 días y se renuevan automáticamente sin intervención del usuario.

Estructura del Proyecto

InnagunaMCP/
├── MCP.py                      # Servidor MCP principal
├── pyproject.toml              # Configuración del proyecto
├── .env.example                # Plantilla de variables de entorno
├── Especificaciones_API_Innguma.txt  # Especificaciones de la API
└── README.md                   # Este archivo

Dependencias

• fastmcp>=2.13.0: Framework para Model Context Protocol
• aiohttp>=3.9.0: Cliente HTTP asincrónico
• python-dotenv>=1.0.0: Carga de variables de entorno
• pyjwt>=2.8.0: Soporte para tokens JWT
• beautifulsoup4>=4.12.0: Web scraping y parsing HTML
• lxml>=4.9.0: Parser XML/HTML rápido

Ejemplos de Uso

Buscar contenido en Innaguma

# Buscar noticias sobre "innovación"
result = await search_innaguma("innovación", page=1, order="relevance")
# Retorna lista de resultados con títulos, URLs, tipos, fechas y fragmentos

Obtener usuarios únicos en un período

# Obtener usuarios únicos del 1 al 31 de enero de 2025
result = await get_unic_users_with_dates("2025-01-01", "2025-01-31")
# Retorna tabla con datos de usuarios únicos

Obtener noticias más visitadas

# Obtener las 25 noticias más visitadas de enero de 2025
result = await get_most_visited_news(year=2025, month=1, limit=25)
# Retorna lista de noticias con conteo de visitas

Obtener estadísticas generales

# Obtener estadísticas totales de la plataforma
stats = await get_platform_totals()
# Retorna accesos totales, noticias, lectores, analistas, etc.

Obtener información de un lector

# Obtener detalles de un lector específico
reader = await get_reader_overview(reader_id=123)
# Retorna nombre, email, fecha de registro, accesos, etc.

# Obtener noticias vistas por el lector
viewed = await get_reader_viewed_news(reader_id=123)
# Retorna lista de noticias que ha visto

Notas Importantes

• La autenticación es automática y transparente para el usuario
• Los reportes web (reporte 3, 14, 27, 29, 32) requieren sesión web autenticada
• Las búsquedas pueden filtrar por orden (relevancia o fecha)
• Los reportes de fecha aceptan múltiples formatos: YYYY-MM-DD, DD-MM-YYYY o DD-MM-YY
• Los errores HTTP se procesan automáticamente y se proporcionan mensajes descriptivos

Cambios Recientes

Versión 0.0.1

• ✅ Herramientas de búsqueda Elasticsearch
• ✅ Reportes personalizados (usuarios únicos, noticias visitadas, no visitadas, evolución, subidas)
• ✅ Autenticación automática JWT
• ✅ Sesión web autenticada para reportes
• ✅ Acceso completo a API de estadísticas (usuarios, noticias, categorías, analistas)
• ✅ Logging detallado para debugging
• ✅ Manejo automático de tokens expirados
• ✅ Parsing HTML robusto para reportes web

Licencia

Este proyecto es de uso interno de Ingeteam.

Autor

Bruno Izaguirre - bruno.izaguirre@ingeteam.com