Nerdearla Agenda - MCP Server

MCP Version Node TypeScript License Nerdearla

Un servidor MCP (Model Context Protocol) que proporciona acceso a la agenda de Nerdearla en tiempo real, siguiendo la arquitectura MCP oficial.

🎪 Sobre Este Proyecto

Este MCP Server fue desarrollado como demostración práctica para la charla "Automatizá con flow: IA, n8n y MCP sin morir en el intento" presentada por Manuel Bruña y Carlos Pereyra en Nerdearla 2025.

Banner

La charla muestra cómo integrar:

🤖 Inteligencia Artificial
🔗 n8n para automatización de workflows
⚡ MCP (Model Context Protocol) para conectar IA con sistemas externos

¿Quieres ver la charla? 👉 Ver en Nerdearla

💡 Tip: Este proyecto es un ejemplo real de cómo implementar un MCP Server profesional que puede integrarse con Claude, n8n y otros sistemas de IA.

🏗️ Arquitectura MCP

Este proyecto implementa correctamente la arquitectura MCP con:

Data Layer: Protocolo JSON-RPC 2.0 para comunicación cliente-servidor
Transport Layer: Soporte para STDIO (local) y HTTP/SSE (remoto)
MCP Primitives: Tools para ejecutar funciones específicas de la agenda

🚀 Funcionalidades (MCP Tools)

Herramientas Disponibles

get_upcoming_talks - Obtiene las próximas charlas basadas en GMT-3. Incluye URLs cuando están disponibles.
get_past_talks - Obtiene charlas que ya pasaron. Incluye URLs cuando están disponibles.
get_topics_by_tags - Lista temas disponibles agrupados por tags
get_next_talk - Obtiene la próxima charla más cercana. Incluye URL cuando está disponible.
get_missed_talks - Obtiene charlas que empezaron pero podrías alcanzar. Incluye URLs cuando están disponibles.
get_best_talk_recommendation - Proporciona una recomendación experta sobre la charla más destacada del evento 🎯
get_cache_info - Información del sistema de cache inteligente (24 horas de duración)

🎪 Easter Egg

¿Buscas la mejor charla de Nerdearla? Prueba la herramienta get_best_talk_recommendation y descubre nuestra recomendación especial... 😉

⚡ Sistema de Cache Inteligente

El MCP Server implementa un sistema de cache avanzado para máximo rendimiento:

🚀 Inicialización Automática: Al arrancar el servidor, hace scraping completo automáticamente
⏰ Cache de 24 Horas: Los datos se mantienen válidos por 24 horas
⚡ Respuestas Instantáneas: Todas las consultas responden en <100ms después del cache inicial
🔄 Renovación Automática: Después de 24h, se actualiza automáticamente en la siguiente consulta
🛡️ Fallback Inteligente: Si falla el scraping, usa cache anterior disponible

# Al arrancar el servidor: [agenda-service] 🚀 Initializing MCP Server - Starting initial cache... [agenda-service] ✅ Initial cache ready! Scraped 45 talks in 8500ms [agenda-service] ⚡ MCP Server ready - All queries will be INSTANT for 24 hours! # En consultas posteriores: [agenda-service] ⚡ Using cached data (15min old, 23h left) - INSTANT response!

📦 Instalación

# Instalar pnpm si no lo tienes npm install -g pnpm # Instalar dependencias pnpm install

🎯 Uso

Transport STDIO (Claude Desktop)

# Servidor MCP para Claude Desktop node src/index.js # O con npm script pnpm start

Transport HTTP/SSE (Conexiones Remotas)

# Servidor MCP con HTTP transport MCP_TRANSPORT=http node src/index.js # Con puerto específico MCP_TRANSPORT=http PORT=8000 node src/index.js # O con npm script pnpm start:http # Con variables de entorno MCP_TRANSPORT=http MCP_PORT=8000 pnpm start

⚙️ Configuración Claude Desktop

Opción 1: STDIO Transport (Recomendado)

{ "mcpServers": { "nerdearla-agenda-mcp": { "command": "node", "args": ["/ruta/absoluta/al/proyecto/src/index.js"] } } }

Opción 2: HTTP Transport (Remoto)

{ "mcpServers": { "nerdearla-agenda-mcp": { "command": "node", "args": ["/ruta/absoluta/al/proyecto/src/index.js", "http", "3000"] } } }

Ubicación del archivo:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

🧪 Testing

Con MCP Inspector

# Inspector MCP (STDIO transport) DANGEROUSLY_OMIT_AUTH=true npx @modelcontextprotocol/inspector node src/index.js # Luego abrir: http://localhost:6274

Testing Manual

# Test STDIO transport echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node src/index.js # Test HTTP transport - Health check curl http://localhost:3000/health # Test HTTP transport - Server info curl http://localhost:3000/ # Test MCP endpoint (Streamable HTTP) curl http://localhost:3000/mcp

🔍 MCP Inspector

Para probar con el MCP Inspector oficial:

# Opción 1: Script automático (Recomendado) pnpm run inspector # Opción 2: Manual npx @modelcontextprotocol/inspector npx nerdearla-agenda # Opción 3: Con servidor HTTP # 1. Iniciar el servidor pnpm start:http # 2. En la interfaz del inspector: # Transport Type: Streamable HTTP # URL: http://localhost:3000/mcp

🏗️ Arquitectura del Proyecto

src/ ├── index.js # MCP Server principal con transport layers ├── agenda-service.js # Lógica de negocio (herramientas) ├── scraper.js # Web scraping con Puppeteer ├── time-utils.js # Utilidades de tiempo GMT-3 └── mcp-tools.js # Definición de MCP tools

🔧 Características Técnicas

MCP Compliant: Sigue la arquitectura oficial MCP
Múltiples Transports: STDIO (local) y HTTP/SSE (remoto) con patrón profesional
Tool Discovery: Implementa tools/list para descubrimiento dinámico
Tool Execution: Implementa tools/call para ejecución de herramientas
HTTP Features: Health checks, CORS, autorización Bearer token opcional
Session Management: Manejo de sesiones SSE con cleanup automático
Scraping Inteligente: Puppeteer para contenido dinámico de React SPA
Cache Inteligente: Inicialización automática al arrancar + cache de 24 horas para respuestas instantáneas
Timezone GMT-3: Manejo correcto de hora argentina
Variables de Entorno: Configuración flexible con MCP_TRANSPORT, MCP_PORT, etc.

📊 Ejemplo de Tool Execution

{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "get_upcoming_talks", "arguments": { "limit": 3 } } }

Respuesta:

{ "jsonrpc": "2.0", "id": 1, "result": { "content": [ { "type": "text", "text": "{\n \"currentTime\": \"2025-09-23T15:30:00-03:00\",\n \"upcomingTalks\": [...],\n \"total\": 3\n}" } ] } }

🚀 Build y Distribución

Node.js

# Crear paquete pnpm build # Instalar globalmente pnpm install:global # Usar globalmente npx nerdearla-agenda-mcp npx nerdearla-agenda-mcp http

📦 Releases

Versión Actual: v1.2.0 - Sistema de Cache Inteligente

⚡ Cache automático al arrancar: Respuestas instantáneas desde el primer momento
🕒 Cache de 24 horas: Máximo rendimiento con renovación automática
🐳 Docker optimizado: Migración a pnpm y configuración mejorada
🛠️ Nueva herramienta: get_cache_info para monitoreo del sistema
🔗 URLs incluidas: Enlaces a charlas cuando están disponibles

Ver CHANGELOG.md para historial completo de versiones.

🐳 Docker

# Ejecutar con Docker Compose (Recomendado) docker-compose up --build # Ejecutar en background docker-compose up -d --build # Solo Docker docker build -t nerdearla-agenda-mcp . docker run -p 3000:3000 nerdearla-agenda-mcp # Con autenticación docker run -p 3000:3000 \ -e MCP_BEARER=mi-token-secreto \ nerdearla-agenda-mcp

Ver DOCKER_GUIDE.md para configuración avanzada.

🆚 Transport Layers

Transport	Puerto	Uso	Conexión
STDIO	-	Claude Desktop	Local
HTTP/SSE	3000	Conexiones remotas	Red

📚 Documentación MCP

👥 Autores

Speaker	GitHub	LinkedIn
Manuel Bruña	@manubruña	LinkedIn
Carlos Pereyra	@carlospereyra	LinkedIn

🎯 Sobre la Charla

"Automatizá con flow: IA, n8n y MCP sin morir en el intento"

En esta charla demostramos cómo crear workflows inteligentes que conectan:

🤖 Claude/IA para procesamiento inteligente
🔗 n8n para orquestación de workflows
⚡ MCP para integración de sistemas externos
🌐 APIs REST para conectividad universal

🛠️ Stack Tecnológico Demostrado

MCP SDK 1.x - Protocolo de comunicación con IA
Node.js + TypeScript - Runtime y tipado
Puppeteer - Web scraping dinámico
Express - HTTP server
n8n - Automatización visual
Claude Desktop - Cliente MCP nativo

🌟 ¿Te Gustó el Proyecto?

Si este MCP Server te resultó útil:

⭐ Dale una estrella al repositorio
🐛 Reporta bugs si encuentras alguno
💡 Sugiere mejoras via Issues
🔄 Comparte con otros desarrolladores

📄 Licencia

MIT License - Siéntete libre de usar este código en tus propios proyectos.

Desarrollado con ❤️ para la comunidad de Nerdearla 2025

Nerdearla Agenda MCP Server