TeleBot CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

A Python Telegram notification bot (one-way message sender) that sends text, images, links, and documents to a configured Telegram chat. It is not a conversational bot — it only pushes messages outbound. Three interfaces: a programmatic async API, a Tkinter GUI, and an MCP server for AI agents.

Commands

# Install dependencies
pip install -r requirements.txt

# Run the bot (CLI, demo mode)
python bot.py

# Run the GUI application
python app.py

# Run the MCP server (stdio transport)
python mcp_server.py

Build (단일 실행파일)

pip install pyinstaller

# GUI 앱을 단일 .exe로 빌드 (콘솔 창 없음)
pyinstaller --onefile --noconsole --name TelegramSender --exclude-module PyQt5 --exclude-module PySide6 --exclude-module numpy --exclude-module PIL --exclude-module IPython --exclude-module pytest --exclude-module zmq --exclude-module nbformat --exclude-module jedi app.py

빌드 결과는 dist/TelegramSender.exe에 생성됨. .env 파일을 exe와 같은 디렉터리에 배치하거나, 실행 후 GUI에서 설정 입력.

Architecture

Three entry points sharing one core class:

• bot.py — Core library. Contains TelegramSender, an async wrapper around python-telegram-bot (v21.6) Bot API. Methods: send_text, send_image, send_image_url, send_link, send_document. All methods are async and return the sent Message object. The main() function demonstrates usage via asyncio.run().

• app.py — Tkinter GUI (App class) that wraps TelegramSender. Multi-tab interface (text, image, link, document). Each send operation spawns a daemon thread running asyncio.run() to avoid blocking the UI; GUI updates use root.after() for thread safety. Also provides .env configuration editing via python-dotenv.set_key().

• mcp_server.py — FastMCP 기반 MCP 서버. TelegramSender의 5개 메서드를 MCP 도구로 노출하여 AI 에이전트가 텔레그램 메시지를 전송할 수 있도록 함. stdio transport 사용. 설정 샘플은 mcp_config.sample.json 참조.