# Telegram Bot Sender 사용 설명서

## 개요

텔레그램 채팅/채널에 텍스트, 이미지, 링크, 문서를 일방향으로 전송하는 알림 봇입니다.

---

## 설치 및 실행

```bash
pip install -r requirements.txt

# GUI 실행
python app.py

# CLI 실행 (데모)
python bot.py

# MCP 서버 실행
python mcp_server.py
```

---

## GUI 사용법

### 1. 설정

상단 설정 영역에서 Bot Token과 Chat ID를 입력합니다.

| 항목 | 설명 |
|------|------|
| Bot Token | [@BotFather](https://t.me/BotFather)에서 발급받은 API 토큰 |
| Chat ID | 메시지를 받을 채팅/채널 ID |

**설정 저장 (.env)** 버튼을 누르면 `.env` 파일에 저장되어 다음 실행 시 자동으로 불러옵니다.

---

### 2. 텍스트 탭

메시지를 입력하고 **전송** 버튼을 눌러 텍스트 메시지를 보냅니다.

- **HTML로 전송** 체크박스:
  - **체크됨 (기본)** — HTML 태그가 텔레그램에서 서식으로 렌더링됩니다. 예: `<b>굵게</b>` → **굵게**
  - **해제됨** — HTML 태그가 이스케이프되어 텍스트 그대로 표시됩니다. 예: `<b>굵게</b>` → `<b>굵게</b>`

---

### 3. 이미지 탭

| 입력 | 설명 |
|------|------|
| 파일 | 로컬 이미지 파일 선택 (PNG, JPG, GIF, BMP, WebP) |
| 또는 URL | 인터넷 이미지 URL 직접 입력 |
| 캡션 | 이미지 아래에 표시될 텍스트 (선택) |

파일과 URL 중 하나만 입력하면 됩니다. 파일이 우선 적용됩니다.

---

### 4. 링크 탭

| 입력 | 설명 |
|------|------|
| 제목 (버튼 텍스트) | 인라인 버튼에 표시될 텍스트 |
| URL | 버튼 클릭 시 이동할 주소 |
| 설명 | 버튼 위에 표시될 메시지 텍스트 (선택) |

링크는 일반 텍스트가 아닌 **인라인 키보드 버튼**으로 전송됩니다.

---

### 5. 문서 탭

| 입력 | 설명 |
|------|------|
| 파일 | 전송할 문서 파일 선택 (모든 형식) |
| 캡션 | 문서 아래에 표시될 텍스트 (선택) |

---

### 6. 로그

화면 하단에 전송 결과와 오류 메시지가 시간과 함께 표시됩니다.

---

## 텔레그램 지원 HTML 태그

"HTML로 전송" 체크 시 아래 태그를 사용할 수 있습니다.

### 텍스트 스타일

| 태그 | 결과 | 예시 |
|------|------|------|
| `<b>`, `<strong>` | **굵게** | `<b>텍스트</b>` |
| `<i>`, `<em>` | *기울임* | `<i>텍스트</i>` |
| `<u>`, `<ins>` | 밑줄 | `<u>텍스트</u>` |
| `<s>`, `<strike>`, `<del>` | ~~취소선~~ | `<s>텍스트</s>` |
| `<span class="tg-spoiler">` | 스포일러 | `<span class="tg-spoiler">숨김</span>` |

### 링크

```html
<a href="https://example.com">링크 텍스트</a>
```

### 코드

| 태그 | 용도 | 예시 |
|------|------|------|
| `<code>` | 인라인 코드 | `<code>변수명</code>` |
| `<pre>` | 코드 블록 | `<pre>여러 줄 코드</pre>` |
| `<pre><code class="language-python">` | 언어별 코드 블록 | 구문 강조 적용 |

### 인용

```html
<blockquote>인용문</blockquote>
<blockquote expandable>접을 수 있는 긴 인용문</blockquote>
```

### 커스텀 이모지

```html
<tg-emoji emoji-id="5368324170671202286">👍</tg-emoji>
```

### 중첩 규칙

- `<b>`, `<i>`, `<u>`, `<s>`, 스포일러는 서로 중첩 가능
- `<pre>`, `<code>` 내부에는 다른 서식 태그 불가
- `<blockquote>`는 중첩 불가

### 주의사항

- `<br>` 태그는 지원되지 않음 — 줄바꿈은 텍스트에 직접 엔터로 입력
- 글꼴, 색상 변경은 지원되지 않음
- 지원되지 않는 태그 사용 시 전송 오류 발생 가능

---

## CLI 사용법 (bot.py)

`TelegramSender` 클래스를 직접 사용하여 프로그래밍 방식으로 메시지를 전송할 수 있습니다.

```python
import asyncio
from bot import TelegramSender

async def main():
    sender = TelegramSender()

    # 텍스트 전송
    await sender.send_text("<b>알림</b> 새 메시지입니다.")

    # 이미지 전송 (로컬 파일)
    await sender.send_image("./photo.jpg", caption="사진 캡션")

    # 이미지 전송 (URL)
    await sender.send_image_url("https://example.com/image.png", caption="URL 이미지")

    # 링크 전송 (인라인 버튼)
    await sender.send_link("사이트 방문", "https://example.com", description="설명 텍스트")

    # 문서 전송
    await sender.send_document("./report.pdf", caption="보고서")

asyncio.run(main())
```

모든 메서드는 `async`이며, 전송된 `Message` 객체를 반환합니다.

---

## MCP 서버 (AI 에이전트용)

`mcp_server.py`는 AI 에이전트가 텔레그램 메시지를 전송할 수 있도록 MCP 도구를 제공합니다.

### 제공 도구

| 도구 | 설명 |
|------|------|
| `send_text` | HTML 텍스트 메시지 전송 |
| `send_image` | 로컬 이미지 파일 전송 |
| `send_image_url` | URL 이미지 전송 |
| `send_link` | 인라인 버튼 링크 전송 |
| `send_document` | 문서/파일 전송 |

### AI 클라이언트 설정

`mcp_config.sample.json`의 내용을 사용하는 AI 클라이언트의 설정 파일에 추가합니다.

```json
{
  "mcpServers": {
    "telegram-sender": {
      "command": "python",
      "args": ["C:/Works/SmartStock/TeleBot/mcp_server.py"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your-bot-token-here",
        "TELEGRAM_CHAT_ID": "your-chat-id-here"
      }
    }
  }
}
```

| 클라이언트 | 설정 파일 위치 |
|-----------|--------------|
| Claude Desktop | `%APPDATA%\Claude\claude_desktop_config.json` |
| Claude Code | 프로젝트 루트 `.mcp.json` 또는 `~/.claude.json` |

환경변수는 `env` 필드 또는 `.env` 파일로 제공할 수 있습니다.

---

## 단일 실행파일 빌드

GUI 앱을 `.exe` 파일 하나로 패키징할 수 있습니다.

```bash
pip install pyinstaller

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에서 설정을 입력하면 됩니다.