eventsorg-mcp

🌐 EventsOrg MCP：自主 AI 活动管理器

一个开源的 Model Context Protocol（MCP） 服务和后台自主 Agent，旨在管理现场活动的物流事务。

EventsOrg MCP 为大模型（如 Claude 和 Gemini）提供了“动手”的能力，使其能够读取实时活动数据、重新分配志愿者、取消缺席供应商的安排，并通过实际短信与工作人员沟通。

注意： 此代码库是一个框架，旨在让任何活动组织者都能部署自己的实例，接入自己的 API 密钥，并管理独立的活动。

---

✨ 功能

• 原生支持 MCP 协议： 向任何标准 AI 客户端提供 20 多种活动管理工具（例如 reassign_volunteer、get_vendor_status）。
• Twilio 短信编排： AI 可以向志愿者发送实际短信。收到的短信回复会自动解析并写回数据库。
• 自主 Agent 循环： 包含一个独立的 Gemini 驱动 Agent（agent.ts），全天候运行，主动监控活动，并在人类察觉之前解决问题。
• Google Sheets 同步： 自动将实时数据库状态推送到 Google Sheets 仪表板，供现场协调人员查看。
• 本地 Webhook 零配置： 使用 Cloudflare Tunnels（untun）在开发期间自动将 Twilio 收到的短信转发到你的 localhost。

---

🏗 架构与用例

此代码库支持三种完全不同的 AI 交互方式：

1. 本地桌面插件（stdio）

适合独立活动组织者或本地开发。将代码连接到 Claude Desktop 或 Cursor 后，AI 可通过标准终端输入/输出（stdio）直接与本地 SQLite 数据库交互。

• 要求：你的笔记本电脑必须保持开机并运行。

2. 面向 AI 的公共 API（HTTP / SSE）

使用 --transport http 标志启动服务后，可将本地服务转变为可从全球访问的 Web API。其他开发者、LangChain 应用或 AI IDE 可通过 Server-Sent Events（SSE）远程连接到你的活动。

• 要求：部署到 Railway、AWS 或 Render 等云托管平台。

3. 自主虚拟协调员

你甚至不需要聊天窗口。运行随附的 agent.ts 脚本后，Gemini 驱动的工作进程每 5 分钟唤醒一次，检查数据库中的异常（缺席供应商、安全事故、天气预警），处理这些问题并向工作人员发送短信——全程自主运行。

4. 打包的 Agent 技能（SKILL.md）

EventsOrg 按照开放的 SKILL.md 规范打包为标准 Agent Skill，并在 Agensi.io 等市场上架。它开箱即用，为 AI Agent（Claude Code、Cursor、Copilot）提供明确的 SOP、事故分流规则和实时短信调度协议。

• 软件包目录： skills/event-logistics-coordinator/

---

🚀 如何部署自己的活动

由于此系统使用本地 SQLite 数据库（grid.db），一次部署对应一场活动。 如果多个组织者要举办不同的活动，则必须分别部署此代码的独立实例。

前提条件

你需要准备以下 API 密钥：

• Twilio（账户 SID、Auth Token、电话号码）
• Google Cloud（已启用 Sheets API 的服务账号 JSON）
• Google Gemini（用于自主 Agent）

环境变量

将 .env.example 文件复制为 .env，并在启动服务前配置 API 密钥。或者，如果要部署到云平台（如 Render、AWS 或 Railway），可直接在其控制面板中添加这些变量：

# AI Models
GOOGLE_API_KEY=your_gemini_api_key

# Twilio SMS Engine
TWILIO_ACCOUNT_SID=your_twilio_sid
TWILIO_AUTH_TOKEN=your_twilio_token
TWILIO_PHONE_NUMBER=+1234567890

# External Integrations
OPENWEATHER_API_KEY=your_openweather_key
GOOGLE_MAPS_API_KEY=your_maps_key

# Escalation Emails
[email protected]
[email protected]
SMTP_PASS=your_app_password

# Webhook Config
PUBLIC_URL=eventsorg-mcp-production.up.railway.app # Set this when deployed publicly
WEBHOOK_PORT=3000

# Google Sheets Sync
GOOGLE_SHEET_ID=your_google_sheet_id
GOOGLE_SERVICE_ACCOUNT_JSON='{ "type": "service_account", ... }'

1. 与 Claude Desktop 配合使用（stdio 模式）

最简单的使用方式是将其作为 Claude 的本地插件。由于它已发布到 NPM，你甚至不需要克隆仓库。

1. 打开 claude_desktop_config.json 文件。
2. 添加此配置（填入你自己的 API 密钥）：

   {
     "mcpServers": {
       "eventsorg-mcp": {
         "command": "npx",
         "args": ["-y", "eventsorg-mcp"],
         "env": {
           "TWILIO_ACCOUNT_SID": "your_twilio_sid",
           "TWILIO_AUTH_TOKEN": "your_twilio_token",
           "TWILIO_PHONE_NUMBER": "+1234567890",
           "GOOGLE_API_KEY": "your_gemini_api_key"
         }
       }
     }
   }
   

3. 重启 Claude Desktop。

使用示例： 打开 Claude 并说：“我的安保供应商刚刚来电，说他们会晚到 30 分钟。你能更新系统，并给户外区域的志愿者发短信吗？” Claude 会立即在后台调用你的 NPM 包、更新本地数据库并发送 Twilio 短信。

2. 独立云 API（SSE 模式）

如果你想构建自定义 Web 应用，或允许远程 Agent（如 LangChain 或自定义脚本）通过互联网管理你的活动：

1. 租用云服务器，并以 HTTP 模式运行此包：

   npx -y eventsorg-mcp --transport http
   

2. 服务启动后，会在你的 URL 上监听（例如，https://your-server.com/sse）。
3. 现在，你可以在自定义应用中使用官方 MCP SDK 远程连接：

   import { Client } from "@modelcontextprotocol/sdk/client/index.js";
   import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
   
   const transport = new SSEClientTransport("https://your-server.com/sse");
   const mcpClient = new Client();
   await mcpClient.connect(transport);
   
   // Trigger tools remotely over the internet!
   await mcpClient.callTool({ name: "get_event_summary", arguments: {} });
   

（注意：运行 npx 命令前，请确保已在终端或云控制面板中设置环境变量。）

3. 开发者设置（克隆）

如果你想修改代码或运行自主后台 Agent（agent.ts）：

1. 克隆仓库并运行 npm install。
2. 将 .env.example 复制为 .env，并填入密钥。
3. 运行 npm run start（启动 API）或 npm run start:agent（启动自主工作进程）。

云部署

如果你想公开托管此项目，让 AI 全天候在云端管理活动，可以将其部署到任何 Node.js 托管服务提供商（如 Render、AWS、Railway、Heroku 或 Fly.io）：

1. 将此代码推送到你自己的 GitHub 仓库。
2. 将仓库连接到你的云服务提供商并部署。
3. 将 .env 变量粘贴到云服务提供商的控制面板中。
4. 确保服务提供商提供公开 URL（例如，https://my-events.onrender.com），并将其设为 PUBLIC_URL 环境变量。
5. 在 Twilio 控制台中，将电话号码的 webhook 指向 https://<YOUR-PUBLIC-URL>/webhook/sms。

（注意：npm start 命令会自动用虚构的“示例活动”数据填充数据库。如果你要举办真实活动，请从 package.json 的 start 脚本中移除 tsx src/seed.ts！）

---

🧪 使用实时“示例活动”进行测试

如果你只想测试 MCP 协议的工作方式，而不托管真实活动，我已经部署了此服务的公开测试实例。每次测试服务启动时，都会彻底清空数据库，并填入一个混乱且问题频出的音乐节数据（供应商迟到 45 分钟，区域人手不足）。

你可以立即构建或连接自己的 MCP 客户端（如 LangChain、自定义应用或 AI 代码编辑器）进行测试！

实时测试 SSE 端点： https://eventsorg-mcp-production.up.railway.app/sse

将你的 AI 连接到此 URL 并询问它：“我的活动目前是什么情况？” 看看它如何识别问题并发送实际短信，试图挽救这场音乐节！

---

🛠 可用的 MCP 工具

此 MCP 服务提供 20 多种工具，让你的 AI 全面掌控活动。以下是主要亮点：

• 📱 Twilio SMS 编排：（send_sms、get_sms_history）让 AI 可以直接给工作人员发送短信。收到的回复会通过 webhook 自动记录到数据库中。
• 📊 Google Sheets 仪表板：（sync_to_sheets）将数据库的实时状态推送到远程 Google 表格，供人工协调员查看。
• 🗺️ 地图与天气：（get_directions、get_weather）为 AI 提供实时上下文数据，例如重新分配志愿者时的步行时间，或户外区域的降雨提醒。
• 🔍 核心操作：（get_event_summary、reassign_volunteer、cancel_vendor_slot、escalate_to_coordinator、move_zone_indoors）

（注意：以上仅为部分亮点！此服务还包含许多更细化的工具，可用于管理突发事件、为供应商办理签到，以及查询数据库的精确状态。）

---

📄 许可证

本项目采用 ISC License 许可。