JinDaGe - nerdearla-agenda-mcp MCP Details

article

README

🚀 Nerdearla议程 - MCP服务器

这是一个MCP（模型上下文协议）服务器，可提供对Nerdearla议程的实时访问，遵循官方MCP架构。

🚀 快速开始

本MCP服务器用于实时获取Nerdearla议程信息。你可以按照以下步骤进行安装和使用：

安装

# 若未安装pnpm，可使用以下命令进行安装
npm install -g pnpm

# 安装项目依赖
pnpm install

运行

Transport STDIO（适用于Claude Desktop）

# 启动适用于Claude Desktop的MCP服务器
node src/index.js

# 或者使用npm脚本启动
pnpm start

Transport HTTP/SSE（适用于远程连接）

# 启动使用HTTP传输的MCP服务器
MCP_TRANSPORT=http node src/index.js

# 指定端口启动
MCP_TRANSPORT=http PORT=8000 node src/index.js

# 或者使用npm脚本启动
pnpm start:http

# 使用环境变量启动
MCP_TRANSPORT=http MCP_PORT=8000 pnpm start

✨ 主要特性

项目背景

本MCP服务器是为Manuel Bruña和Carlos Pereyra在Nerdearla 2025上的演讲 "Automatizá con flow: IA, n8n y MCP sin morir en el intento" 所开发的实践演示。该演讲展示了如何集成以下技术：

🤖 人工智能
🔗 n8n 用于工作流自动化
⚡ MCP（模型上下文协议） 用于连接人工智能与外部系统

你可以点击此处观看演讲。

MCP架构实现

本项目正确实现了MCP架构，包含以下部分：

数据层：采用JSON - RPC 2.0协议进行客户端 - 服务器通信。
传输层：支持STDIO（本地）和HTTP/SSE（远程）。
MCP原语：提供用于执行议程特定功能的工具。

功能（MCP工具）

可用工具

get_upcoming_talks - 根据GMT - 3获取即将举行的演讲信息，若有可用URL会一并提供。
get_past_talks - 获取已结束的演讲信息，若有可用URL会一并提供。
get_topics_by_tags - 列出按标签分组的可用主题。
get_next_talk - 获取即将举行的下一场演讲信息，若有可用URL会一并提供。
get_missed_talks - 获取已开始但你仍可能赶上的演讲信息，若有可用URL会一并提供。
get_best_talk_recommendation - 提供关于活动中最精彩演讲的专业推荐🎯。
get_cache_info - 获取智能缓存系统的信息（缓存有效期为24小时）。

隐藏彩蛋

想知道Nerdearla最棒的演讲是哪一场吗？试试 get_best_talk_recommendation 工具，发现我们的特别推荐😉。

智能缓存系统

MCP服务器实现了一个先进的缓存系统，以实现最高性能：

🚀 自动初始化：服务器启动时，自动进行全面的数据抓取。
⏰ 24小时缓存：数据在24小时内保持有效。
⚡ 即时响应：初始缓存完成后，所有查询的响应时间小于100ms。
🔄 自动更新：24小时后，下次查询时自动更新数据。
🛡️ 智能回退：若数据抓取失败，使用上一次可用的缓存数据。

# 服务器启动时的日志信息
[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!

# 后续查询时的日志信息
[agenda-service] ⚡ Using cached data (15min old, 23h left) - INSTANT response!

📦 安装指南

# 若未安装pnpm，可使用以下命令进行安装
npm install -g pnpm

# 安装项目依赖
pnpm install

💻 使用示例

基础用法 - Transport STDIO（Claude Desktop）

# 启动适用于Claude Desktop的MCP服务器
node src/index.js

# 或者使用npm脚本启动
pnpm start

高级用法 - Transport HTTP/SSE（远程连接）

# 启动使用HTTP传输的MCP服务器
MCP_TRANSPORT=http node src/index.js

# 指定端口启动
MCP_TRANSPORT=http PORT=8000 node src/index.js

# 或者使用npm脚本启动
pnpm start:http

# 使用环境变量启动
MCP_TRANSPORT=http MCP_PORT=8000 pnpm start

📚 详细文档

Claude Desktop配置

选项1：STDIO传输（推荐）

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

选项2：HTTP传输（远程）

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

文件位置：

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

测试

使用MCP Inspector

# 使用MCP Inspector（STDIO传输）
DANGEROUSLY_OMIT_AUTH=true npx @modelcontextprotocol/inspector node src/index.js

# 然后打开：http://localhost:6274

手动测试

# 测试STDIO传输
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node src/index.js

# 测试HTTP传输 - 健康检查
curl http://localhost:3000/health

# 测试HTTP传输 - 服务器信息
curl http://localhost:3000/

# 测试MCP端点（可流式传输的HTTP）
curl http://localhost:3000/mcp

使用MCP Inspector进行测试

# 选项1：自动脚本（推荐）
pnpm run inspector

# 选项2：手动方式
npx @modelcontextprotocol/inspector npx nerdearla-agenda

# 选项3：使用HTTP服务器
# 1. 启动服务器
pnpm start:http

# 2. 在Inspector界面中设置：
#    传输类型：Streamable HTTP
#    URL：http://localhost:3000/mcp

项目架构

src/
├── index.js          # 包含传输层的主MCP服务器
├── agenda-service.js # 业务逻辑（工具）
├── scraper.js        # 使用Puppeteer进行网页抓取
├── time-utils.js     # GMT - 3时间工具
└── mcp-tools.js      # MCP工具定义

工具执行示例

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

响应示例：

{
    "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}"
            }
        ]
    }
}

构建和分发

Node.js

# 创建包
pnpm build

# 全局安装
pnpm install:global

# 全局使用
npx nerdearla-agenda-mcp
npx nerdearla-agenda-mcp http

版本发布

当前版本：v1.2.0 - 智能缓存系统

⚡ 启动时自动缓存：从一开始就实现即时响应。
🕒 24小时缓存：通过自动更新实现最高性能。
🐳 优化的Docker：迁移到pnpm并进行了更好的配置。
🛠️ 新工具：get_cache_info 用于系统监控。
🔗 包含URL：演讲信息中包含可用的链接。

查看 CHANGELOG.md 以获取完整的版本历史记录。

Docker

# 使用Docker Compose运行（推荐）
docker-compose up --build

# 在后台运行
docker-compose up -d --build

# 仅使用Docker
docker build -t nerdearla-agenda-mcp .
docker run -p 3000:3000 nerdearla-agenda-mcp

# 使用认证
docker run -p 3000:3000 \
  -e MCP_BEARER=mi-token-secreto \
  nerdearla-agenda-mcp

查看 DOCKER_GUIDE.md 以获取高级配置信息。

传输层对比

| 传输方式 | 端口 | 使用场景 | 连接类型 | | ------------ | ------ | ------------------ | -------- | | STDIO | - | Claude Desktop | 本地 | | HTTP/SSE | 3000 | 远程连接 | 网络 |

MCP文档

关于演讲

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

在本次演讲中，我们展示了如何创建智能工作流，连接以下组件：

🤖 Claude/人工智能 用于智能处理
🔗 n8n 用于工作流编排
⚡ MCP 用于外部系统集成
🌐 REST API 用于通用连接

演示的技术栈

MCP SDK 1.x - 与人工智能的通信协议
Node.js + TypeScript - 运行时和类型检查
Puppeteer - 动态网页抓取
Express - HTTP服务器
n8n - 可视化自动化工具
Claude Desktop - 原生MCP客户端

🔧 技术细节

符合MCP标准：遵循官方MCP架构。
多传输方式：支持STDIO（本地）和HTTP/SSE（远程）的专业模式。
工具发现：实现 tools/list 用于动态发现工具。
工具执行：实现 tools/call 用于执行工具。
HTTP功能：支持健康检查、CORS、可选的Bearer令牌认证。
会话管理：管理SSE会话并自动清理。
智能抓取：使用Puppeteer抓取React SPA的动态内容。
智能缓存：启动时自动初始化，24小时缓存以实现即时响应。
GMT - 3时区处理：正确处理阿根廷本地时间。
环境变量配置：通过 MCP_TRANSPORT、MCP_PORT 等环境变量进行灵活配置。

👥 作者

| 演讲者 | GitHub | LinkedIn | | ------------------ | -------------------------------------------------- | ------------------------------------------------- | | Manuel Bruña | @manubruña | LinkedIn | | Carlos Pereyra | @carlospereyra | LinkedIn |

🌟 项目反馈

如果你觉得这个MCP服务器有用：

⭐ 给仓库点个星
🐛 发现问题请提交Bug报告
💡 通过Issues提出改进建议
🔄 与其他开发者分享

📄 许可证

本项目采用MIT许可证，你可以自由地在自己的项目中使用此代码。

为Nerdearla 2025社区用心开发 ❤️