Nerdearla Agenda - MCP Server
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.
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/listpara descubrimiento dinámico - Tool Execution: Implementa
tools/callpara 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_infopara 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 | |
|---|---|---|
| Manuel Bruña | @manubruña | |
| Carlos Pereyra | @carlospereyra |
🎯 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