Nerdearla Agenda MCP

🚀 Nerdearla Agenda - MCP Server

This is an MCP (Model Context Protocol) server that provides real - time access to the Nerdearla agenda, following the official MCP architecture.

🚀 Quick Start

This MCP Server was developed as a practical demonstration for the talk "Automate with flow: AI, n8n, and MCP without dying in the attempt" presented by Manuel Bruña and Carlos Pereyra at Nerdearla 2025.

The talk shows how to integrate:

• 🤖 Artificial Intelligence
• 🔗 n8n for workflow automation
• ⚡ MCP (Model Context Protocol) to connect AI with external systems

Want to watch the talk? 👉 Watch on Nerdearla

💡 Usage Tip
This project is a real - world example of how to implement a professional MCP Server that can be integrated with Claude, n8n, and other AI systems.

✨ Features

Available Tools

1. get_upcoming_talks - Retrieves upcoming talks based on GMT - 3. Includes URLs when available.
2. get_past_talks - Retrieves talks that have already taken place. Includes URLs when available.
3. get_topics_by_tags - Lists available topics grouped by tags.
4. get_next_talk - Retrieves the next closest talk. Includes the URL when available.
5. get_missed_talks - Retrieves talks that have started but you might still be able to attend. Includes URLs when available.
6. get_best_talk_recommendation - Provides an expert recommendation on the most outstanding talk of the event 🎯
7. get_cache_info - Information about the intelligent cache system (24 - hour duration).

🎪 Easter Egg

Looking for the best talk at Nerdearla? Try the get_best_talk_recommendation tool and discover our special recommendation... 😉

⚡ Intelligent Cache System

The MCP Server implements an advanced cache system for maximum performance:

• 🚀 Automatic Initialization: Automatically performs a full scrape when the server starts.
• ⏰ 24 - Hour Cache: Data remains valid for 24 hours.
• ⚡ Instant Responses: All queries respond in <100ms after the initial cache.
• 🔄 Automatic Renewal: Automatically updates on the next query after 24 hours.
• 🛡️ Intelligent Fallback: Uses the previous available cache if scraping fails.

# When starting the server:
[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!

# In subsequent queries:
[agenda-service] ⚡ Using cached data (15min old, 23h left) - INSTANT response!

📦 Installation

# Install pnpm if you don't have it
npm install -g pnpm

# Install dependencies
pnpm install

💻 Usage Examples

Transport STDIO (Claude Desktop)

# MCP Server for Claude Desktop
node src/index.js

# Or with npm script
pnpm start

Transport HTTP/SSE (Remote Connections)

# MCP Server with HTTP transport
MCP_TRANSPORT=http node src/index.js

# With a specific port
MCP_TRANSPORT=http PORT=8000 node src/index.js

# Or with npm script
pnpm start:http

# With environment variables
MCP_TRANSPORT=http MCP_PORT=8000 pnpm start

📚 Documentation

Claude Desktop Configuration

Option 1: STDIO Transport (Recommended)

{
    "mcpServers": {
        "nerdearla-agenda-mcp": {
            "command": "node",
            "args": ["/absolute/path/to/the/project/src/index.js"]
        }
    }
}

Option 2: HTTP Transport (Remote)

{
    "mcpServers": {
        "nerdearla-agenda-mcp": {
            "command": "node",
            "args": ["/absolute/path/to/the/project/src/index.js", "http", "3000"]
        }
    }
}

File Location:

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

Testing

With MCP Inspector

# MCP Inspector (STDIO transport)
DANGEROUSLY_OMIT_AUTH=true npx @modelcontextprotocol/inspector node src/index.js

# Then open: http://localhost:6274

Manual Testing

# 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

To test with the official MCP Inspector:

# Option 1: Automatic script (Recommended)
pnpm run inspector

# Option 2: Manual
npx @modelcontextprotocol/inspector npx nerdearla-agenda

# Option 3: With HTTP server
# 1. Start the server
pnpm start:http

# 2. In the inspector interface:
#    Transport Type: Streamable HTTP
#    URL: http://localhost:3000/mcp

Project Architecture

src/
├── index.js          # Main MCP Server with transport layers
├── agenda-service.js # Business logic (tools)
├── scraper.js        # Web scraping with Puppeteer
├── time-utils.js     # Time utilities for GMT - 3
└── mcp-tools.js      # Definition of MCP tools

Technical Features

• MCP Compliant: Follows the official MCP architecture.
• Multiple Transports: STDIO (local) and HTTP/SSE (remote) with a professional pattern.
• Tool Discovery: Implements tools/list for dynamic discovery.
• Tool Execution: Implements tools/call for tool execution.
• HTTP Features: Health checks, CORS, optional Bearer token authorization.
• Session Management: Manages SSE sessions with automatic cleanup.
• Intelligent Scraping: Uses Puppeteer for dynamic content in React SPAs.
• Intelligent Cache: Automatic initialization on startup + 24 - hour cache for instant responses.
• Timezone GMT - 3: Correctly handles Argentine time.
• Environment Variables: Flexible configuration with MCP_TRANSPORT, MCP_PORT, etc.

Example of Tool Execution

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

Response:

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

Build and Distribution

Node.js

# Create a package
pnpm build

# Install globally
pnpm install:global

# Use globally
npx nerdearla-agenda-mcp
npx nerdearla-agenda-mcp http

📦 Releases

Current Version: v1.2.0 - Intelligent Cache System

• ⚡ Automatic cache on startup: Instant responses from the start.
• 🕒 24 - hour cache: Maximum performance with automatic renewal.
• 🐳 Optimized Docker: Migration to pnpm and improved configuration.
• 🛠️ New tool: get_cache_info for system monitoring.
• 🔗 Included URLs: Links to talks when available.

See CHANGELOG.md for the full version history.

🐳 Docker

# Run with Docker Compose (Recommended)
docker-compose up --build

# Run in the background
docker-compose up -d --build

# Just Docker
docker build -t nerdearla-agenda-mcp .
docker run -p 3000:3000 nerdearla-agenda-mcp

# With authentication
docker run -p 3000:3000 \
  -e MCP_BEARER=my-secret-token \
  nerdearla-agenda-mcp

See DOCKER_GUIDE.md for advanced configuration.

Transport Layers

MCP Documentation

• MCP Architecture
• MCP Specification
• Transport Layers

Authors

About the Talk

"Automate with flow: AI, n8n, and MCP without dying in the attempt"

In this talk, we demonstrate how to create intelligent workflows that connect:

• 🤖 Claude/AI for intelligent processing
• 🔗 n8n for workflow orchestration
• ⚡ MCP for integration with external systems
• 🌐 REST APIs for universal connectivity

🛠️ Demonstrated Technology Stack

• MCP SDK 1.x - Communication protocol with AI
• Node.js + TypeScript - Runtime and typing
• Puppeteer - Dynamic web scraping
• Express - HTTP server
• n8n - Visual automation
• Claude Desktop - Native MCP client

🌟 Did You Like the Project?

If you find this MCP Server useful:

• ⭐ Give it a star on the repository
• 🐛 Report bugs if you find any
• 💡 Suggest improvements via Issues
• 🔄 Share it with other developers

📄 License

This project is under the MIT License. Feel free to use this code in your own projects.

Developed with ❤️ for the Nerdearla 2025 community