mcp-telegram-agent 0.1.0__tar.gz

mcp_telegram_agent-0.1.0/.env.example

@@ -0,0 +1,5 @@
+# Telegram Bot Token：向 @BotFather 建立機器人後取得
+TELEGRAM_BOT_TOKEN=123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ
+
+# 預設目標 Chat ID：發送任一訊息給 @userinfobot 取得
+TELEGRAM_DEFAULT_CHAT_ID=123456789

mcp_telegram_agent-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      # 測試檔（tests/）不進版控，僅在本機驗證，此處直接建置發佈
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish

mcp_telegram_agent-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# ===== 本機開發與測試專區（絕不推上公開庫） =====
+dev_test/
+tests/
+*.local
+*.session
+*.token
+.env
+.env.*
+!.env.example
+
+# ===== Python =====
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# ===== IDE 與系統檔案 =====
+.idea/
+.vscode/
+*.swp
+.DS_Store
+Thumbs.db

mcp_telegram_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PCKuo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_telegram_agent-0.1.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.5
+Name: mcp-telegram-agent
+Version: 0.1.0
+Summary: FastMCP-style MCP server empowering AI agents with full-featured Telegram Bot control: rich keyboards, local files, media albums, and interactive widgets.
+Author: PCKuo
+License: MIT
+License-File: LICENSE
+Keywords: ai-agent,automation,fastmcp,mcp,model-context-protocol,telegram,telegram-bot
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Description-Content-Type: text/markdown
+
+# mcp-telegram-agent
+
+A lightweight, zero-login-risk Model Context Protocol (MCP) server empowering AI agents with Telegram Bot capabilities. Built with Python (SDK-compatible with both `mcp` 1.x FastMCP and 2.x MCPServer), designed to work seamlessly out-of-the-box with `uvx` and modern AI coding agents like VS Code Cline and Claude Desktop.
+
+Also includes the ultra-short command alias `tg-agent`.
+
+[繁體中文說明文件](README.zh-TW.md)
+
+---
+
+## Highlights
+
+* **Pure Bot API Architecture**: Zero login session risk, no SMS codes or sensitive credential files needed.
+* **Dual CLI Entry Points**: Call via standard `mcp-telegram-agent` or the compact `tg-agent` alias.
+* **Full Keyboard Support**: Effortlessly construct dynamic Inline Keyboards (with URLs or callback data) and custom Reply Keyboards.
+* **Rich Media & Local Files**: Deliver logs, reports, source code, images, audio, voice notes, videos, and multi-image albums (2–10 files).
+* **Interactive Tooling**: Launch quizzes, single/multiple-choice polls, GPS coordinates, digital contact cards, and animated dice.
+* **Message Lifecycle**: Broadcast bot statuses (typing, uploading) and edit or delete messages on the fly.
+* **Instant uvx Execution**: Run directly with no virtual environments or manual package installs.
+
+---
+
+## Quick Start
+
+### 1. Prerequisites
+* **Telegram Bot Token**: Obtain one from `@BotFather`.
+* **Chat ID**: Get your unique numerical Chat ID by sending any message to `@userinfobot`.
+
+### 2. Configuration for AI Clients
+
+Add the configuration below to your MCP settings file (e.g., `cline_mcp_settings.json` or `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "telegram": {
+      "command": "uvx",
+      "args": ["mcp-telegram-agent"],
+      "env": {
+        "TELEGRAM_BOT_TOKEN": "YOUR_TELEGRAM_BOT_TOKEN",
+        "TELEGRAM_DEFAULT_CHAT_ID": "YOUR_CHAT_ID"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Available Tools
+
+* `send_text_message`: Send Markdown/HTML text with inline buttons or custom reply keyboards.
+* `send_local_document`: Send any local file (PDF, CSV, code, logs, archives).
+* `send_local_photo`: Send image files with captions and inline buttons.
+* `send_local_video`: Send video files as native players.
+* `send_local_audio_or_voice`: Send music tracks or native voice audio notes.
+* `send_media_album`: Deliver 2 to 10 photos or videos as a grouped carousel.
+* `send_poll`: Create interactive single/multiple choice polls or scored quizzes.
+* `send_location`: Broadcast map location points via coordinates.
+* `send_contact`: Share phone contact cards.
+* `send_dice`: Send animated dice, basketball, football, or slot machines.
+* `send_chat_action`: Display temporary bot statuses (typing, uploading).
+* `edit_message_text`: Dynamically update previously sent text and keyboards.
+* `delete_message`: Clean up or remove specific messages.
+
+---
+
+## License
+
+This project is licensed under the MIT License.
+

mcp_telegram_agent-0.1.0/README.md

@@ -0,0 +1,71 @@
+# mcp-telegram-agent
+
+A lightweight, zero-login-risk Model Context Protocol (MCP) server empowering AI agents with Telegram Bot capabilities. Built with Python (SDK-compatible with both `mcp` 1.x FastMCP and 2.x MCPServer), designed to work seamlessly out-of-the-box with `uvx` and modern AI coding agents like VS Code Cline and Claude Desktop.
+
+Also includes the ultra-short command alias `tg-agent`.
+
+[繁體中文說明文件](README.zh-TW.md)
+
+---
+
+## Highlights
+
+* **Pure Bot API Architecture**: Zero login session risk, no SMS codes or sensitive credential files needed.
+* **Dual CLI Entry Points**: Call via standard `mcp-telegram-agent` or the compact `tg-agent` alias.
+* **Full Keyboard Support**: Effortlessly construct dynamic Inline Keyboards (with URLs or callback data) and custom Reply Keyboards.
+* **Rich Media & Local Files**: Deliver logs, reports, source code, images, audio, voice notes, videos, and multi-image albums (2–10 files).
+* **Interactive Tooling**: Launch quizzes, single/multiple-choice polls, GPS coordinates, digital contact cards, and animated dice.
+* **Message Lifecycle**: Broadcast bot statuses (typing, uploading) and edit or delete messages on the fly.
+* **Instant uvx Execution**: Run directly with no virtual environments or manual package installs.
+
+---
+
+## Quick Start
+
+### 1. Prerequisites
+* **Telegram Bot Token**: Obtain one from `@BotFather`.
+* **Chat ID**: Get your unique numerical Chat ID by sending any message to `@userinfobot`.
+
+### 2. Configuration for AI Clients
+
+Add the configuration below to your MCP settings file (e.g., `cline_mcp_settings.json` or `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "telegram": {
+      "command": "uvx",
+      "args": ["mcp-telegram-agent"],
+      "env": {
+        "TELEGRAM_BOT_TOKEN": "YOUR_TELEGRAM_BOT_TOKEN",
+        "TELEGRAM_DEFAULT_CHAT_ID": "YOUR_CHAT_ID"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Available Tools
+
+* `send_text_message`: Send Markdown/HTML text with inline buttons or custom reply keyboards.
+* `send_local_document`: Send any local file (PDF, CSV, code, logs, archives).
+* `send_local_photo`: Send image files with captions and inline buttons.
+* `send_local_video`: Send video files as native players.
+* `send_local_audio_or_voice`: Send music tracks or native voice audio notes.
+* `send_media_album`: Deliver 2 to 10 photos or videos as a grouped carousel.
+* `send_poll`: Create interactive single/multiple choice polls or scored quizzes.
+* `send_location`: Broadcast map location points via coordinates.
+* `send_contact`: Share phone contact cards.
+* `send_dice`: Send animated dice, basketball, football, or slot machines.
+* `send_chat_action`: Display temporary bot statuses (typing, uploading).
+* `edit_message_text`: Dynamically update previously sent text and keyboards.
+* `delete_message`: Clean up or remove specific messages.
+
+---
+
+## License
+
+This project is licensed under the MIT License.
+

mcp_telegram_agent-0.1.0/README.zh-TW.md

@@ -0,0 +1,70 @@
+# mcp-telegram-agent
+
+專為 AI 代理與自動化流程設計的全功能 Telegram 機器人控制協議伺服器。採用純 Python 實作，相容 mcp SDK 1.x（FastMCP）與 2.x（MCPServer），原生支援 `uvx` 隨選即用，完美相容 VS Code Cline 與 Claude Desktop 等開發環境。
+
+同時支援超短指令別名 `tg-agent`。
+
+[English Documentation](README.md)
+
+---
+
+## 專案亮點
+
+* **純機器人架構**：僅需 Bot Token 與 Chat ID，無需輸入電話驗證碼登入個人帳號，零帳號被封風險。
+* **雙命令列進入點**：同時支援標準 `mcp-telegram-agent` 與精簡 `tg-agent` 別名指令。
+* **完整鍵盤支援**：原生支援行內按鈕（超連結與回傳識別碼）以及手機底部回覆鍵盤。
+* **實體本機檔案與相簿**：輕鬆發送日誌、報表、原始碼、圖片、語音、影片，以及 2 至 10 個項目的多媒體相簿。
+* **豐富互動元件**：支援即時投票、測驗、地圖經緯度座標、電話名片及官方動畫表情符號。
+* **狀態與訊息生命週期維護**：支援即時廣播機器人打字狀態，並能動態更新或刪除指定訊息。
+* **uvx 極速啟動**：免除手動建立虛擬環境與安裝依賴的繁瑣步驟。
+
+---
+
+## 快速開始
+
+### 1. 前置準備
+* **Telegram Bot Token**：於 Telegram 搜尋 `@BotFather` 建立機器人並獲取 Token。
+* **Chat ID**：發送任一訊息給 `@userinfobot` 獲取個人專屬數值 Chat ID。
+
+### 2. 用戶端配置範例
+
+在 MCP 設定檔（例如 VS Code 的 `cline_mcp_settings.json` 或 `claude_desktop_config.json`）中加入以下內容：
+
+```json
+{
+  "mcpServers": {
+    "telegram": {
+      "command": "uvx",
+      "args": ["mcp-telegram-agent"],
+      "env": {
+        "TELEGRAM_BOT_TOKEN": "你的_BOT_TOKEN",
+        "TELEGRAM_DEFAULT_CHAT_ID": "你的_CHAT_ID"
+      }
+    }
+  }
+}
+```
+
+---
+
+## 提供之工具列表
+
+* `send_text_message`：發送 Markdown 與 HTML 格式化文字，支援行內按鈕或底部鍵盤。
+* `send_local_document`：傳送各類本機報告、CSV、ZIP 或原始碼檔案。
+* `send_local_photo`：發送圖片檔案並支援即時全螢幕預覽。
+* `send_local_video`：發送本機影片並支援內嵌播放器。
+* `send_local_audio_or_voice`：發送音訊或語音留言。
+* `send_media_album`：批次發送 2 至 10 張圖片或影片組成相簿輪播。
+* `send_poll`：建立互動式單選、多選投票或附帶解析之標準測驗。
+* `send_location`：傳送經緯度地理位置座標地圖。
+* `send_contact`：傳送名片聯絡人資訊。
+* `send_dice`：發送隨機動畫表情，如骰子與拉霸機等。
+* `send_chat_action`：向用戶端顯示當前操作狀態，如打字中與上傳檔案中。
+* `edit_message_text`：動態更新既有訊息內容與按鈕。
+* `delete_message`：清理特定暫存或歷史訊息。
+
+---
+
+## 授權條款
+
+本專案採用 MIT 授權協議開源發布。

mcp_telegram_agent-0.1.0/mcp_telegram_agent/__init__.py

@@ -0,0 +1,3 @@
+"""mcp-telegram-agent: FastMCP server for full-featured Telegram Bot control."""
+
+__version__ = "0.1.0"