@overpod/mcp-telegram 1.36.5 → 1.37.0

package/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.37.0] — 2026-06-04
+
+### Added
+
+- `TELEGRAM_USE_WSS` env-var. When set to `true`, gramJS uses port `443` instead of the default `80` for the MTProto TCPFull transport. This unblocks deployments on VPS/hosting IP ranges where outbound port `80` to Telegram DC IP blocks is dropped (anti-abuse policy on some shared-VPS providers), which otherwise hangs the client forever in `Connecting to ...:80/TCPFull...`. Default is `false`, so existing setups are unaffected. Contributed by Ivan Ponomarev (@Baho73).
+- When `TELEGRAM_USE_WSS=true` is combined with `TELEGRAM_PROXY_*` (which gramJS cannot do — SSL transport over a proxy is unsupported), the conflict is now detected early: a clear warning is logged and `useWSS` is ignored, letting the proxy take precedence, instead of crashing deep inside `connect()`.
+
 ## [1.36.5] — 2026-06-01
 
 ### Changed

package/README.md

@@ -128,6 +128,18 @@ npx @overpod/mcp-telegram
 | `TELEGRAM_PROXY_USERNAME` | Optional proxy auth |
 | `TELEGRAM_PROXY_PASSWORD` | Optional proxy auth |
 
+### Connecting via WSS (port 443)
+
+If your VPS or hosting IP is reachable on outbound port `443` but not the default MTProto port `80` (some cloud providers ban port `80` on Telegram DC IP ranges as anti-abuse policy), set:
+
+```bash
+TELEGRAM_USE_WSS=true npx @overpod/mcp-telegram
+```
+
+| Variable | Description |
+|----------|-------------|
+| `TELEGRAM_USE_WSS` | When `true`, gramJS uses port `443` instead of `80` for the MTProto TCPFull transport. Default: `false`. Cannot be combined with `TELEGRAM_PROXY_*` (gramJS limitation) — if both are set, `useWSS` is ignored and the proxy takes precedence (a warning is logged). |
+
 ## Installation Options
 
 ### npx (recommended, zero install)

package/dist/telegram-client.js

@@ -40,6 +40,18 @@ function resolveProxy() {
         ...(process.env.TELEGRAM_PROXY_PASSWORD && { password: process.env.TELEGRAM_PROXY_PASSWORD }),
     };
 }
+// When true, gramJS uses port 443 instead of the default 80 for the MTProto
+// TCPFull transport. Useful on hosts where outbound port 80 to Telegram DC IP
+// ranges is blocked. gramJS cannot combine useWSS with a proxy, so warn early
+// rather than let it fail deep inside connect() with an opaque error.
+function resolveUseWSS(proxy) {
+    const useWSS = process.env.TELEGRAM_USE_WSS === "true";
+    if (useWSS && proxy) {
+        console.error("[mcp-telegram] TELEGRAM_USE_WSS=true cannot be combined with TELEGRAM_PROXY_* — gramJS does not support SSL transport over a proxy. Ignoring useWSS; the proxy takes precedence.");
+        return false;
+    }
+    return useWSS;
+}
 function ensureSessionDir(filePath) {
     const dir = dirname(filePath);
     if (!existsSync(dir)) {
@@ -135,6 +147,7 @@ export class TelegramService {
         const proxy = resolveProxy();
         this.client = new TelegramClient(session, this.apiId, this.apiHash, {
             connectionRetries: 5,
+            useWSS: resolveUseWSS(proxy),
             ...(proxy && { proxy }),
         });
         try {
@@ -246,6 +259,7 @@ export class TelegramService {
         const proxy = resolveProxy();
         const client = new TelegramClient(session, this.apiId, this.apiHash, {
             connectionRetries: 5,
+            useWSS: resolveUseWSS(proxy),
             ...(proxy && { proxy }),
         });
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@overpod/mcp-telegram",
-  "version": "1.36.5",
+  "version": "1.37.0",
   "description": "MCP server for Telegram userbot — messages, media, reactions, polls & more. Built on GramJS/MTProto.",
   "type": "module",
   "main": "dist/index.js",