eventsorg-mcp

🌐 EventsOrg MCP：自律型 AI イベントマネージャー

ライブイベントの運営を担う、オープンソースの Model Context Protocol (MCP) サーバー兼バックグラウンド自律型エージェントです。

EventsOrg MCP を使うと、LLM（Claude や Gemini など）がライブイベントのデータを読み取り、ボランティアの担当を変更し、来ないベンダーをキャンセルし、実際の SMS メッセージでスタッフと連絡を取れるようになります。

注： このリポジトリはフレームワークです。どのイベント主催者でも、このコードの独自インスタンスをデプロイし、自分の API キーを設定して、独立したイベントを運営できるように設計されています。

---

✨ 特長

• MCP プロトコルネイティブ： reassign_volunteer や get_vendor_status など、20 個以上のイベント管理ツールを、標準的な AI クライアントに公開します。
• Twilio SMS オーケストレーション： AI がボランティアに実際の SMS メッセージを送信できます。受信した SMS の返信は自動的に解析され、データベースに反映されます。
• 自律型エージェントループ： Gemini を利用したスタンドアロンエージェント（agent.ts）が付属しており、24 時間 365 日イベントを積極的に監視し、人間が気づく前に問題を解決します。
• Google Sheets 同期： リアルタイムのデータベース状態を Google Sheets ダッシュボードに自動で反映し、人間のコーディネーターが確認できるようにします。
• 設定不要のローカル Webhook： Cloudflare トンネル（untun）を使用し、開発中に Twilio SMS を localhost へ自動的にルーティングします。

---

🏗 アーキテクチャとユースケース

このコードベースでは、AI とやり取りする方法として、まったく異なる次の 3 つの方法をサポートしています。

1. ローカルデスクトッププラグイン（stdio）

個人のイベント主催者やローカル開発に最適です。コードを Claude Desktop または Cursor に接続すると、AI は標準のターミナル入出力（stdio）を介してローカルの SQLite データベースと直接やり取りします。

• 必要条件：ノート PC を起動したままにしておく必要があります。

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. パッケージ化されたエージェントスキル（SKILL.md）

EventsOrg は、オープンな SKILL.md 仕様に準拠する標準的なエージェントスキルとしてパッケージ化されており、Agensi.io などのマーケットプレイスに掲載されています。AI エージェント（Claude Code、Cursor、Copilot）に、明確な SOP、インシデントのトリアージルール、リアルタイム SMS 配信プロトコルをすぐに提供します。

• パッケージフォルダー： skills/event-logistics-coordinator/

---

🚀 独自のイベントをデプロイする方法

このシステムではローカルの SQLite データベース（grid.db）を使用するため、1 回のデプロイにつき 1 つのイベントとなります。 複数の主催者が異なるイベントを運営する場合、それぞれがこのコードの独立したインスタンスをデプロイする必要があります。

前提条件

以下の API キーが必要です。

• Twilio（Account SID、Auth Token、Phone Number）
• Google Cloud（Sheets API を有効にしたサービスアカウント JSON）
• Google Gemini（自律型エージェント用）

環境変数

サーバーを起動する前に、.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 アプリを構築したり、リモートエージェント（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.ts）を実行したりする場合は、次の手順に従ってください。

1. リポジトリをクローンし、npm install を実行します。
2. .env.example を .env にコピーし、キーを入力します。
3. npm run start（API 用）または npm run start:agent（自律型ワーカー用）を実行します。

クラウドへのデプロイ

AI がクラウド上で24時間体制で管理できるように、これを公開してホストする場合は、任意の 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 の下でライセンスされています。