# Telegram Bot MCP Server

Servidor MCP (*Model Context Protocol*) autónomo en TypeScript diseñado para la **distribución automatizada de contenido para YouTube, entrega instantánea de Lead Magnets (workflows de n8n, código y guías), encuestas interactivas comunitarias y alertas móviles directas a tu celular**, operando a coste **$0.00 de por vida** mediante la Telegram Bot API oficial.

---

## 🎯 ¿Por qué usar Telegram Bot MCP en YouTube y Desarrollo?

1. **Dominar la "Golden Hour" de YouTube:** Los primeros 60 minutos tras publicar un vídeo deciden la recomendación algorítmica. Telegram entrega notificaciones push instantáneas con una tasa de apertura superior al 75% (frente al 15% del email marketing).
2. **Descarga en 1 Clic del Lead Magnet:** Envía directamente a tu canal de suscriptores el archivo de flujo `.json` de n8n o scripts de código, aumentando drásticamente la conversión de espectadores a comunidad VIP.
3. **Validación Temática Pre-Grabación:** Lanza encuestas interactivas (`telegram_send_poll`) para que tus suscriptores voten el tema del próximo vídeo.
4. **DevOps y Alertas a tu Teléfono:** Recibe notificaciones push en tu propio chat privado cuando terminen procesos en segundo plano (transcripciones de `faster-whisper-mcp`, alertas de analítica o errores en webhooks).

---

## 🛠️ Stack Tecnológico

- **Runtime:** Node.js 20+ con soporte nativo de TypeScript (`--experimental-strip-types`)
- **Protocolo:** Model Context Protocol SDK (`@modelcontextprotocol/sdk`)
- **API:** Telegram Bot API oficial (HTTP/HTTPS nativo con `fetch` y `FormData`)
- **Variables de Entorno:** `dotenv`

---

## 📋 Requisitos Previos (Obtener Token de Bot en 1 minuto)

1. Abre la aplicación de Telegram y busca al bot oficial [@BotFather](https://t.me/BotFather).
2. Envía el comando `/newbot`.
3. Asigna un nombre a tu bot (ej: *Ramiro Medina Community Bot*) y un usuario (ej: *RamiroMedinaAIBot*).
4. `@BotFather` te entregará tu **Bot Token** (ej: `7123456789:AAH...`).
5. Añade tu bot como **Administrador** en tu canal o grupo de Telegram con permisos para publicar mensajes.

---

## ⚙️ Instalación y Configuración

### 1. Clonar o descargar el repositorio
```bash
git clone https://github.com/ramedina-ia/telegram-bot-mcp.git
cd telegram-bot-mcp
```

### 2. Instalar dependencias
```bash
npm install
```

### 3. Configurar variables de entorno
Copia la plantilla `.env.example` a `.env`:
```bash
cp .env.example .env
```

Edita `.env` con tus credenciales:
```env
# Token oficial de @BotFather
TELEGRAM_BOT_TOKEN=tu_token_aqui

# ID de tu canal oficial (ej: @TuCanal o -100123456789)
TELEGRAM_DEFAULT_CHAT_ID=@TuCanal

# Tu ID personal de usuario en Telegram para recibir alertas en tu móvil
TELEGRAM_ADMIN_CHAT_ID=123456789
```

---

## 🔌 Integración en Google Antigravity

Agrega el servidor en `~/.gemini/antigravity/mcp_config.json`:

```json
{
  "mcpServers": {
    "telegram-bot-mcp": {
      "command": "cmd.exe",
      "args": [
        "/c",
        "d:\\Respaldo Informacion NO BORRAR\\Desktop\\Proyectos Antigravity\\Estudio analiticas y rendimiento You Tube\\telegram-bot-mcp\\run.cmd"
      ]
    }
  }
}
```

---

## 🧰 Catálogo de Herramientas MCP

| Herramienta | Descripción | Parámetros Clave |
| :--- | :--- | :--- |
| `telegram_send_message` | Envía texto enriquecido con formato HTML/Markdown y botones inline clicables. | `text`, `chat_id?`, `buttons?`, `parse_mode?` |
| `telegram_send_document` | Sube y envía archivos locales (`.json`, `.zip`, `.pdf`, `.py`, etc.) al canal o grupo. | `file_path`, `caption?`, `chat_id?` |
| `telegram_send_photo` | Envía imágenes de alta resolución o miniaturas desde archivo local o URL. | `photo`, `caption?`, `chat_id?` |
| `telegram_send_poll` | Publica encuestas interactivas con entre 2 y 10 opciones de votación. | `question`, `options`, `is_anonymous?` |
| `telegram_send_video_alert` | Alerta optimizada de YouTube: gancho, botones de YouTube/WhatsApp y adjunta el JSON de n8n. | `video_title`, `video_url`, `attachment_path?` |
| `telegram_send_alert` | Notificación directa de telemetría a tu teléfono móvil personal. | `message`, `level?` (info, warning, success, error) |
| `telegram_get_me` | Diagnóstico: verifica el estado del bot y devuelve nombre y `@username`. | *Ninguno* |

---

## 💬 Prompts de Ejemplo para Antigravity

- *Acabo de publicar un nuevo vídeo en YouTube sobre n8n. Envía una alerta oficial a mi canal de Telegram adjuntando el archivo de flujo `workflow_lead_gen.json` y los botones interactivos.*
- *Lanza una encuesta en Telegram para que la comunidad vote si el próximo tutorial debe ser de Gemini 3.8 Flash o de Agentes en Supabase.*
- *Envíame una alerta a mi celular cuando la transcripción de Faster-Whisper haya terminado.*

---

## 🔒 Seguridad y Privacidad

- **Sin credenciales expuestas:** Toda comunicación con la API se autentica mediante variables en `.env`.
- **Aislamiento `.gitignore`:** Excluye `.env`, `node_modules/`, `dist/` y archivos de log.
- **Sin intermediarios:** Comunicación directa mediante HTTPS con `api.telegram.org`.

---

## 📄 Licencia

Distribuido bajo la Licencia MIT. Consulta el archivo [LICENSE](LICENSE) para más detalles.