MCP Integration example with Telegram

Telegram との MCP 統合例

LLM が Telegram 経由で通知を送信し、ユーザーからの返信を受信できる、Python ベースの Model Context Protocol（MCP）クライアントおよびサーバーです。

機能

• 緊急度をカスタマイズして、Telegram チャットにテキストアラートを送信します
• タイムアウトを設定して、ユーザーからの返信を確認します
• MCP 対応の LLM アプリケーションに統合するための柔軟なテンプレートを提供します

MCP と関数呼び出しまたはエージェントツールの比較

MCP プロトコル（Model Context Protocol）：

• LLM の推論（「コンテキスト」）と外部アクションの実行を分離します。たとえば、LLM が実行するアクションを決定し、MCP サーバーがそのアクションの実行方法を処理します。
• この分離により、LLM の中核モデルやプロンプトを変更せずに、外部ツールを更新または入れ替えられます。
• また、アクションをより安全かつ制御された方法で実行できます。

LLM の関数呼び出しまたはエージェント：

• 直接的な関数呼び出しやエージェントベースの手法では、意思決定ロジックと実行ロジックが混在することが多く、システムのモジュール性が損なわれる可能性があります。
• アクションの実行方法を変更するには、エージェントの再設計やLLMのプロンプトの変更が必要になる場合があり、メンテナンスが難しくなります。

前提条件

• Python 3.11+
• Telegram ボットトークン（@BotFatherから取得）
• ご利用の Telegram チャット ID

インストール

1. リポジトリをクローンします：

   git [email protected]:arananet/mcp-telegram-poc.git
   cd mcp-telegram-poc
   

2. 依存関係をインストールします：

   pip install -r requirements.txt
   

3. 仮想環境を作成します：

   python3 -m venv .venv
   

4. .env.example を .env にコピーし、Telegram の認証情報を入力します：

   cp .env.example .env
   nano .env
   

設定

.env を編集し、次の項目を設定します：

• TELEGRAM_BOT_TOKEN=your_bot_token_here
• TELEGRAM_CHAT_ID=your_chat_id_here
• OPENAI_API_KEY=your_openai_apikey

Telegram ボットトークンの取得

1. Telegram で @BotFather に話しかけます。
2. /newbot を送信し、名前（例：mcp_example）を入力します。続けてユーザー名（例：mcp_example_bot）を入力すると、Telegram の BotFather がトークンを返信します。
3. 返信されたトークンをコピーします。

チャット ID の確認

1. ボットにメッセージを送信します（作成したボットを開き、例として「hi」などを送信します）。
2. https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates にアクセスします。
3. chat オブジェクトの id フィールドを確認します。次のような内容が表示されます（例：「chat":{"id":107184517,"first_name":"Edu","last_name":"Arana"...）。チャット ID は 107184517 です。

使用方法

単独での実行

python3 src/mcp_handler.py

プログラムからの使用

アラートの送受信をテストするには：

python3 examples/test_client.py

エージェントとの統合

autogen 0.4 フレームワークのエージェントを使用した MCP 統合をテストするには：

python3 examples/test_autogen_agent.py

ローカルでのテスト

テストスクリプトを使用します（Linux/macOS）：

chmod +x test_server.sh
./test_server.sh

利用可能なツール

send_alert

• パラメーター：
  • message（str、必須）：送信するメッセージ（Markdown に対応）。
  • project（str、必須）：プロジェクト名。
  • urgency（str、任意）：「low」、「medium」、「high」（デフォルト：「medium」）。
• 説明：Telegram アラートを送信し、返信を待ちます。

check_reply

• パラメーター：
  • message_id（int、必須）：確認するメッセージ ID。
  • timeout_seconds（int、任意）：待機時間（デフォルト：60）。
• 説明：特定のメッセージへの返信をポーリングします。

開発

• 依存関係のインストール：pip install -r requirements.txt
• サーバーの実行：python3 src/mcp_handler.py
• クライアントのテスト：python3 examples/test_client.py
• エージェントのテスト：python3 examples/test_autogen_agent.py

例

examples フォルダーには、次のファイルが含まれています：

• test_server.py：サーバーを単独で実行します。

• test_client.py：クライアントとのやり取りを実演します。

• test_autogen_agent.py：AutoGen エージェントとの MCP 統合を実演します。

• images フォルダーには、テストのスクリーンショットがあります。

開発者

• Eduardo Arana

利用状況

• MCPHub 認定：https://mcphub.com/mcp-servers/arananet/mcp-telegram-poc