@overpod/mcp-telegram 1.27.1 → 1.28.1

package/README.md

@@ -316,7 +316,7 @@ All tools are auto-discoverable via MCP — your AI client will see the full lis
 
 | Category | Tools |
 |----------|-------|
-| **Auth** | `telegram-status`, `telegram-login` |
+| **Auth** | `telegram-status`, `telegram-login`, `telegram-logout` |
 | **Messaging** | `telegram-send-message`, `telegram-edit-message`, `telegram-delete-message`, `telegram-forward-message`, `telegram-send-scheduled`, `telegram-send-typing`, `telegram-translate-message`, `telegram-get-message-link` |
 | **Scheduled** | `telegram-get-scheduled`, `telegram-delete-scheduled` |
 | **Reading** | `telegram-list-chats`, `telegram-read-messages`, `telegram-search-messages`, `telegram-search-global`, `telegram-search-chats`, `telegram-get-unread`, `telegram-mark-as-read`, `telegram-get-replies`, `telegram-get-unread-mentions`, `telegram-get-unread-reactions`, `telegram-get-saved-dialogs` |

package/dist/client.d.ts

@@ -1,22 +1,36 @@
 import { type Socket } from "node:net";
+import { type IpcLoginDone } from "./ipc-protocol.js";
 export interface IpcClientOptions {
     connectTimeoutMs?: number;
     callTimeoutMs?: number;
+    loginTimeoutMs?: number;
     connectFn?: (path: string) => Socket;
 }
 /** Thin IPC proxy: forwards tool calls to the master process over Unix socket */
 export declare class IpcClient {
     private socket;
     private pending;
+    private pendingLogins;
     private buf;
     private connected;
+    private destroyed;
+    private onDisconnect?;
     private readonly connectTimeoutMs;
     private readonly callTimeoutMs;
+    private readonly loginTimeoutMs;
     private readonly connectFn;
     constructor(opts?: IpcClientOptions);
+    /** Register a callback fired when the peer socket closes unexpectedly.
+     * Call this AFTER a successful connect() so aborted connection attempts don't fire it. */
+    setOnDisconnect(cb: () => void): void;
     connect(): Promise<boolean>;
+    private routeMessage;
     isConnected(): boolean;
     call(tool: string, args: Record<string, unknown>): Promise<unknown>;
+    /** Request QR login flow from master. `onQr` fires for each QR URL frame (refreshes ~every 10s).
+     * Only one login can run on the master side at a time — a concurrent call gets an immediate
+     * `login_done {success:false}` with "Another QR login is already in progress". */
+    loginFlow(onQr: (url: string) => void): Promise<IpcLoginDone>;
     destroy(): void;
 }
 export declare function runClient(apiId: number, apiHash: string, version: string): Promise<void>;

package/dist/client.js

@@ -2,27 +2,38 @@ import { randomUUID } from "node:crypto";
 import { connect } from "node:net";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { encodeMessage, parseMessages } from "./ipc-protocol.js";
+import { encodeMessage, parseMessages, } from "./ipc-protocol.js";
 import { socketPath } from "./lock.js";
 import { TelegramService } from "./telegram-client.js";
 import { registerTools } from "./tools/index.js";
 const CONNECT_TIMEOUT_MS = 5_000;
 const IPC_CALL_TIMEOUT_MS = 30_000;
+const LOGIN_FLOW_TIMEOUT_MS = 360_000; // 6 min — QR has ~5 min server-side window
 const MAX_RECONNECT_ATTEMPTS = 5;
 /** Thin IPC proxy: forwards tool calls to the master process over Unix socket */
 export class IpcClient {
     socket = null;
     pending = new Map();
+    pendingLogins = new Map();
     buf = "";
     connected = false;
+    destroyed = false;
+    onDisconnect;
     connectTimeoutMs;
     callTimeoutMs;
+    loginTimeoutMs;
     connectFn;
     constructor(opts = {}) {
         this.connectTimeoutMs = opts.connectTimeoutMs ?? CONNECT_TIMEOUT_MS;
         this.callTimeoutMs = opts.callTimeoutMs ?? IPC_CALL_TIMEOUT_MS;
+        this.loginTimeoutMs = opts.loginTimeoutMs ?? LOGIN_FLOW_TIMEOUT_MS;
         this.connectFn = opts.connectFn ?? connect;
     }
+    /** Register a callback fired when the peer socket closes unexpectedly.
+     * Call this AFTER a successful connect() so aborted connection attempts don't fire it. */
+    setOnDisconnect(cb) {
+        this.onDisconnect = cb;
+    }
     async connect() {
         return new Promise((resolve) => {
             const sock = socketPath();
@@ -41,20 +52,8 @@ export class IpcClient {
                     this.buf += chunk.toString("utf-8");
                     const { messages, remaining } = parseMessages(this.buf);
                     this.buf = remaining;
-                    for (const msg of messages) {
-                        const res = msg;
-                        const pending = this.pending.get(res.id);
-                        if (!pending)
-                            continue;
-                        clearTimeout(pending.timer);
-                        this.pending.delete(res.id);
-                        if (res.error) {
-                            pending.reject(new Error(res.error));
-                        }
-                        else {
-                            pending.resolve(res.result);
-                        }
-                    }
+                    for (const msg of messages)
+                        this.routeMessage(msg);
                 });
                 s.on("close", () => {
                     this.connected = false;
@@ -63,7 +62,17 @@ export class IpcClient {
                         p.reject(new Error("IPC connection closed"));
                     }
                     this.pending.clear();
+                    for (const [, l] of this.pendingLogins) {
+                        clearTimeout(l.timer);
+                        l.reject(new Error("IPC connection closed"));
+                    }
+                    this.pendingLogins.clear();
+                    if (!this.destroyed)
+                        this.onDisconnect?.();
                 });
+                // Post-connect errors (EPIPE, ECONNRESET) land here. Silent drop keeps the
+                // process alive for the "close" handler above to clean up pending calls.
+                // Node requires an error listener on sockets — absence crashes the process.
                 s.on("error", () => { });
                 resolve(true);
             };
@@ -75,6 +84,35 @@ export class IpcClient {
             s.once("error", onError);
         });
     }
+    routeMessage(msg) {
+        if (msg.type === "tool_response") {
+            const pending = this.pending.get(msg.id);
+            if (!pending)
+                return;
+            clearTimeout(pending.timer);
+            this.pending.delete(msg.id);
+            if (msg.error)
+                pending.reject(new Error(msg.error));
+            else
+                pending.resolve(msg.result);
+            return;
+        }
+        if (msg.type === "login_qr") {
+            const login = this.pendingLogins.get(msg.id);
+            login?.onQr(msg.url);
+            return;
+        }
+        if (msg.type === "login_done") {
+            const login = this.pendingLogins.get(msg.id);
+            if (!login)
+                return;
+            clearTimeout(login.timer);
+            this.pendingLogins.delete(msg.id);
+            login.resolve(msg);
+            return;
+        }
+        // tool / login_start are client→master only; ignored if received
+    }
     isConnected() {
         return this.connected;
     }
@@ -90,15 +128,39 @@ export class IpcClient {
                 reject(new Error(`IPC call timeout: ${tool}`));
             }, this.callTimeoutMs);
             this.pending.set(id, { resolve, reject, timer });
-            socket.write(encodeMessage({ id, tool, args }));
+            socket.write(encodeMessage({ type: "tool", id, tool, args }));
+        });
+    }
+    /** Request QR login flow from master. `onQr` fires for each QR URL frame (refreshes ~every 10s).
+     * Only one login can run on the master side at a time — a concurrent call gets an immediate
+     * `login_done {success:false}` with "Another QR login is already in progress". */
+    async loginFlow(onQr) {
+        if (!this.socket || !this.connected) {
+            throw new Error("IPC client not connected");
+        }
+        const id = randomUUID();
+        const socket = this.socket;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pendingLogins.delete(id);
+                reject(new Error("Login flow timeout"));
+            }, this.loginTimeoutMs);
+            this.pendingLogins.set(id, { onQr, resolve, reject, timer });
+            socket.write(encodeMessage({ type: "login_start", id }));
         });
     }
     destroy() {
+        this.destroyed = true;
         for (const [, p] of this.pending) {
             clearTimeout(p.timer);
             p.reject(new Error("IPC client destroyed"));
         }
         this.pending.clear();
+        for (const [, l] of this.pendingLogins) {
+            clearTimeout(l.timer);
+            l.reject(new Error("IPC client destroyed"));
+        }
+        this.pendingLogins.clear();
         this.socket?.destroy();
         this.socket = null;
         this.connected = false;
@@ -132,12 +194,20 @@ export async function runClient(apiId, apiHash, version) {
         process.exit(1);
     }
     console.error(`[mcp-telegram] Client mode — proxying to master via ${socketPath()}`);
+    // Master died → socket closes → nothing to proxy. Exit so parent respawns us against a fresh master.
+    // Wire only AFTER successful connect, so retry attempts inside the loop above can't trip it.
+    ipc.setOnDisconnect(() => {
+        console.error("[mcp-telegram] IPC connection to master closed, exiting");
+        process.exit(1);
+    });
     // Register all tools for MCP schema; dummy telegram instance is never used for actual calls
     const telegram = new TelegramService(apiId, apiHash);
     const server = new McpServer({ name: "mcp-telegram", version });
     registerTools(server, telegram);
     // Replace all handlers with IPC-forwarding versions
     wireIpcProxies(server, ipc);
+    // Parent closed stdio → exit so parent can spawn a fresh instance cleanly
+    process.stdin.on("end", () => process.exit(0));
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error("[mcp-telegram] MCP server running on stdio (client)");

package/dist/global-lock.d.ts

@@ -0,0 +1,10 @@
+/** FIFO mutex — ensures only one critical section runs at a time.
+ * Used in master to serialize tool calls with QR login flow:
+ * login holds the lock for up to minutes; tool calls queue behind it. */
+export declare class GlobalLock {
+    private locked;
+    private waiters;
+    acquire(): Promise<() => void>;
+    isLocked(): boolean;
+    waitingCount(): number;
+}

package/dist/global-lock.js

@@ -0,0 +1,29 @@
+/** FIFO mutex — ensures only one critical section runs at a time.
+ * Used in master to serialize tool calls with QR login flow:
+ * login holds the lock for up to minutes; tool calls queue behind it. */
+export class GlobalLock {
+    locked = false;
+    waiters = [];
+    async acquire() {
+        if (this.locked) {
+            await new Promise((resolve) => this.waiters.push(resolve));
+        }
+        this.locked = true;
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            this.locked = false;
+            const next = this.waiters.shift();
+            if (next)
+                next();
+        };
+    }
+    isLocked() {
+        return this.locked;
+    }
+    waitingCount() {
+        return this.waiters.length;
+    }
+}

package/dist/ipc-protocol.d.ts

@@ -5,22 +5,44 @@ export type McpRegisteredTool = {
 export interface McpServerInternal {
     _registeredTools: Record<string, McpRegisteredTool>;
 }
-/** Request from Client → Master */
-export interface IpcRequest {
+/** Client → Master: invoke MCP tool */
+export interface IpcToolRequest {
+    type: "tool";
     id: string;
     tool: string;
     args: Record<string, unknown>;
 }
-/** Response from Master → Client */
-export interface IpcResponse {
+/** Master → Client: tool result */
+export interface IpcToolResponse {
+    type: "tool_response";
     id: string;
     result?: unknown;
     error?: string;
 }
+/** Client → Master: begin QR login flow */
+export interface IpcLoginStart {
+    type: "login_start";
+    id: string;
+}
+/** Master → Client: QR code URL to display (may fire multiple times as URL refreshes) */
+export interface IpcLoginQr {
+    type: "login_qr";
+    id: string;
+    url: string;
+}
+/** Master → Client: QR login finished */
+export interface IpcLoginDone {
+    type: "login_done";
+    id: string;
+    success: boolean;
+    username?: string;
+    error?: string;
+}
+export type IpcMessage = IpcToolRequest | IpcToolResponse | IpcLoginStart | IpcLoginQr | IpcLoginDone;
 /** Encode a message as newline-delimited JSON */
-export declare function encodeMessage(msg: IpcRequest | IpcResponse): string;
+export declare function encodeMessage(msg: IpcMessage): string;
 /** Parse newline-delimited JSON messages from a buffer, returns parsed messages + leftover */
 export declare function parseMessages(buf: string): {
-    messages: (IpcRequest | IpcResponse)[];
+    messages: IpcMessage[];
     remaining: string;
 };

package/dist/ipc-protocol.js

@@ -12,7 +12,9 @@ export function parseMessages(buf) {
         if (!trimmed)
             continue;
         try {
-            messages.push(JSON.parse(trimmed));
+            const parsed = JSON.parse(trimmed);
+            if (isIpcMessage(parsed))
+                messages.push(parsed);
         }
         catch {
             // Skip malformed lines
@@ -20,3 +22,12 @@ export function parseMessages(buf) {
     }
     return { messages, remaining };
 }
+function isIpcMessage(m) {
+    if (!m || typeof m !== "object" || typeof m.type !== "string" || typeof m.id !== "string")
+        return false;
+    return (m.type === "tool" ||
+        m.type === "tool_response" ||
+        m.type === "login_start" ||
+        m.type === "login_qr" ||
+        m.type === "login_done");
+}

package/dist/master.d.ts

@@ -1,4 +1,5 @@
 import { type Socket } from "node:net";
 import { type McpServerInternal } from "./ipc-protocol.js";
-export declare function handleClient(socket: Socket, mcpServer: McpServerInternal): void;
+import { TelegramService } from "./telegram-client.js";
+export declare function handleClient(socket: Socket, mcpServer: McpServerInternal, telegram: TelegramService): void;
 export declare function runMaster(apiId: number, apiHash: string, version: string): Promise<void>;

package/dist/master.js

@@ -1,52 +1,51 @@
 import { createServer } from "node:net";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { GlobalLock } from "./global-lock.js";
 import { encodeMessage, parseMessages, } from "./ipc-protocol.js";
 import { releaseLock, releaseSocket, socketPath } from "./lock.js";
 import { TelegramService } from "./telegram-client.js";
 import { registerTools } from "./tools/index.js";
-let socketServer = null;
 let cleanedUp = false;
 function cleanup() {
     if (cleanedUp)
         return;
     cleanedUp = true;
+    // Sync unlink only — process.exit handlers cannot await async server.close(),
+    // and unlinking the socket file is sufficient to release the listening address.
     releaseLock();
     releaseSocket();
-    socketServer?.close();
 }
 process.on("exit", cleanup);
 process.on("SIGINT", () => process.exit(0));
 process.on("SIGTERM", () => process.exit(0));
-export function handleClient(socket, mcpServer) {
+// Serializes tool calls with QR login — login holds the lock for up to minutes,
+// tool calls queue behind it. Prevents tool calls from running against a stale
+// Telegram client mid-relogin.
+const globalLock = new GlobalLock();
+let activeLogin = null;
+export function handleClient(socket, mcpServer, telegram) {
     let buf = "";
-    // Processing queue — ensures sequential handling even when handler awaits
     let processing = false;
     const queue = [];
+    // Per-socket FIFO: messages from one client execute in arrival order.
+    // Parallelism across DIFFERENT clients is enforced by globalLock (acquired per handler),
+    // not here — a tool call from client A can proceed while client B is in login flow.
     async function drainQueue() {
         if (processing)
             return;
         processing = true;
         while (queue.length > 0) {
-            const req = queue.shift();
-            if (!req)
+            const msg = queue.shift();
+            if (!msg)
                 break;
-            const tool = mcpServer._registeredTools[req.tool];
-            const response = { id: req.id };
-            if (!tool) {
-                response.error = `Unknown tool: ${req.tool}`;
+            if (msg.type === "tool") {
+                await handleToolRequest(socket, msg, mcpServer);
             }
-            else {
-                try {
-                    response.result = await tool.handler(req.args ?? {}, {});
-                }
-                catch (err) {
-                    response.error = err instanceof Error ? err.message : String(err);
-                }
-            }
-            if (!socket.destroyed) {
-                socket.write(encodeMessage(response));
+            else if (msg.type === "login_start") {
+                await handleLoginStart(socket, msg, telegram);
             }
+            // Responses and QR frames are master→client only — client-side messages ignored here
         }
         processing = false;
     }
@@ -54,15 +53,78 @@ export function handleClient(socket, mcpServer) {
         buf += chunk.toString("utf-8");
         const { messages, remaining } = parseMessages(buf);
         buf = remaining;
-        for (const msg of messages) {
-            const req = msg;
-            if (!req.id || !req.tool)
-                continue;
-            queue.push(req);
-        }
+        for (const msg of messages)
+            queue.push(msg);
         drainQueue();
     });
-    socket.on("error", () => { });
+    // If this socket owned an in-progress QR login, abort it so globalLock
+    // releases and tool calls from other clients aren't blocked for minutes.
+    socket.on("close", () => {
+        if (activeLogin && activeLogin.socket === socket) {
+            activeLogin.abort.abort();
+        }
+    });
+    // Node requires an error listener on sockets. EPIPE/ECONNRESET happen when the peer
+    // disappears mid-write; log for diagnostics but don't crash the master.
+    socket.on("error", (err) => {
+        console.error("[mcp-telegram] IPC socket error:", err.message);
+    });
+}
+function send(socket, msg) {
+    if (!socket.destroyed)
+        socket.write(encodeMessage(msg));
+}
+async function handleToolRequest(socket, req, mcpServer) {
+    const tool = mcpServer._registeredTools[req.tool];
+    const response = { type: "tool_response", id: req.id };
+    if (!tool) {
+        response.error = `Unknown tool: ${req.tool}`;
+    }
+    else {
+        // telegram-logout must cancel an in-progress QR login instead of queueing behind it
+        // for up to 5 minutes. Aborting releases the globalLock held by handleLoginStart.
+        if (req.tool === "telegram-logout" && activeLogin) {
+            activeLogin.abort.abort();
+        }
+        const unlock = await globalLock.acquire();
+        try {
+            response.result = await tool.handler(req.args ?? {}, {});
+        }
+        catch (err) {
+            response.error = err instanceof Error ? err.message : String(err);
+        }
+        finally {
+            unlock();
+        }
+    }
+    send(socket, response);
+}
+async function handleLoginStart(socket, req, telegram) {
+    const fail = (error) => send(socket, { type: "login_done", id: req.id, success: false, error });
+    if (activeLogin) {
+        fail("Another QR login is already in progress");
+        return;
+    }
+    const abort = new AbortController();
+    activeLogin = { socket, abort };
+    const unlock = await globalLock.acquire();
+    try {
+        const result = await telegram.startQrLogin(() => { }, (url) => send(socket, { type: "login_qr", id: req.id, url }), abort.signal);
+        if (result.success) {
+            const me = await telegram.getMe();
+            send(socket, { type: "login_done", id: req.id, success: true, username: me.username ?? undefined });
+        }
+        else {
+            fail(result.message);
+        }
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err));
+    }
+    finally {
+        activeLogin = null;
+        unlock();
+    }
 }
 export async function runMaster(apiId, apiHash, version) {
     const telegram = new TelegramService(apiId, apiHash);
@@ -72,8 +134,7 @@ export async function runMaster(apiId, apiHash, version) {
     // Remove stale socket file from previous crash before attempting to listen (HIGH-2)
     releaseSocket();
     const sock = socketPath();
-    const srv = createServer((socket) => handleClient(socket, mcpServer));
-    socketServer = srv;
+    const srv = createServer((socket) => handleClient(socket, mcpServer, telegram));
     await new Promise((resolve, reject) => {
         srv.listen(sock, resolve);
         srv.once("error", reject);
@@ -84,6 +145,10 @@ export async function runMaster(apiId, apiHash, version) {
     }
     catch { }
     console.error(`[mcp-telegram] Master mode — IPC socket ready: ${sock}`);
+    // Parent (Claude Code / MCP client) can close stdio without sending a signal.
+    // Without this, the process keeps running as an orphan with a live Telegram connection,
+    // blocking auth_key from being reused — causes AUTH_KEY_DUPLICATED on next start.
+    process.stdin.on("end", () => process.exit(0));
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error("[mcp-telegram] MCP server running on stdio (master)");

package/dist/qr-login-cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import "dotenv/config";
 import QRCode from "qrcode";
+import { IpcClient } from "./client.js";
 import { TelegramService } from "./telegram-client.js";
 const API_ID = Number(process.env.TELEGRAM_API_ID);
 const API_HASH = process.env.TELEGRAM_API_HASH;
@@ -8,9 +9,43 @@ if (!API_ID || !API_HASH) {
     console.error("Set TELEGRAM_API_ID and TELEGRAM_API_HASH in .env file");
     process.exit(1);
 }
-const telegram = new TelegramService(API_ID, API_HASH);
-async function main() {
-    // Check if already connected
+async function printQr(url) {
+    const terminalQr = await QRCode.toString(url, { type: "terminal", small: true });
+    console.log(terminalQr);
+    console.log("Waiting for scan...\n");
+}
+function printLoginHeader(viaDaemon) {
+    console.log(`\nStarting Telegram QR login${viaDaemon ? " (via running daemon)" : ""}...\n`);
+    console.log("Scan the QR code in Telegram app:");
+    console.log("  Settings > Devices > Link Desktop Device\n");
+}
+async function ipcLogin() {
+    const ipc = new IpcClient();
+    const connected = await ipc.connect();
+    if (!connected)
+        return false;
+    printLoginHeader(true);
+    try {
+        const result = await ipc.loginFlow((url) => {
+            printQr(url).catch((err) => {
+                console.error(`[mcp-telegram] Failed to render QR: ${err instanceof Error ? err.message : String(err)}`);
+            });
+        });
+        if (result.success) {
+            console.log(`Login successful!`);
+            console.log(`  Account: @${result.username ?? "unknown"}\n`);
+        }
+        else {
+            console.log(`Error: ${result.error ?? "unknown"}\n`);
+        }
+    }
+    finally {
+        ipc.destroy();
+    }
+    return true;
+}
+async function standaloneLogin() {
+    const telegram = new TelegramService(API_ID, API_HASH);
     await telegram.loadSession();
     if (await telegram.connect()) {
         const me = await telegram.getMe();
@@ -18,13 +53,9 @@ async function main() {
         await telegram.disconnect();
         return;
     }
-    console.log("\nStarting Telegram QR login...\n");
-    console.log("Scan the QR code in Telegram app:");
-    console.log("  Settings > Devices > Link Desktop Device\n");
+    printLoginHeader(false);
     const result = await telegram.startQrLogin(() => { }, async (url) => {
-        const terminalQr = await QRCode.toString(url, { type: "terminal", small: true });
-        console.log(terminalQr);
-        console.log("Waiting for scan...\n");
+        await printQr(url);
     });
     if (result.success) {
         console.log("Login successful!");
@@ -36,4 +67,9 @@ async function main() {
     }
     await telegram.disconnect();
 }
+async function main() {
+    const viaIpc = await ipcLogin();
+    if (!viaIpc)
+        await standaloneLogin();
+}
 main().catch(console.error);

package/dist/telegram-client.d.ts

@@ -16,6 +16,7 @@ export declare class TelegramService {
     private entityCache;
     lastError: string;
     get sessionDir(): string;
+    hasLocalSession(): boolean;
     getClient(): TelegramClient | null;
     constructor(apiId: number, apiHash: string, options?: {
         sessionPath?: string;
@@ -33,12 +34,15 @@ export declare class TelegramService {
     ensureConnected(): Promise<boolean>;
     disconnect(): Promise<void>;
     /**
-     * Log out from Telegram completely — terminates the session on Telegram servers.
-     * After this, the session string becomes invalid and won't appear in "Active Sessions".
+     * Terminates the session on Telegram servers, destroys the client, and clears
+     * local session (in-memory + file). Returns true only when server-side revoke
+     * confirmed. False means server revoke could not be confirmed — local wipe
+     * was still attempted. Throws if local file removal failed so callers can
+     * surface the partial state instead of silently misreporting success.
      */
     logOut(): Promise<boolean>;
     isConnected(): boolean;
-    startQrLogin(onQrDataUrl: (dataUrl: string) => void, onQrUrl?: (url: string) => void): Promise<{
+    startQrLogin(onQrDataUrl: (dataUrl: string) => void, onQrUrl?: (url: string) => void, signal?: AbortSignal): Promise<{
         success: boolean;
         message: string;
     }>;

package/dist/telegram-client.js

@@ -60,6 +60,9 @@ export class TelegramService {
     get sessionDir() {
         return dirname(this.sessionPath);
     }
+    hasLocalSession() {
+        return existsSync(this.sessionPath);
+    }
     // ─── Session & Auth ────────────────────────────────────────────────────────
     getClient() {
         return this.client;
@@ -195,30 +198,50 @@ export class TelegramService {
         }
     }
     /**
-     * Log out from Telegram completely — terminates the session on Telegram servers.
-     * After this, the session string becomes invalid and won't appear in "Active Sessions".
+     * Terminates the session on Telegram servers, destroys the client, and clears
+     * local session (in-memory + file). Returns true only when server-side revoke
+     * confirmed. False means server revoke could not be confirmed — local wipe
+     * was still attempted. Throws if local file removal failed so callers can
+     * surface the partial state instead of silently misreporting success.
      */
     async logOut() {
-        if (!this.client || !this.connected)
+        const wipeLocalOrThrow = async () => {
+            await this.clearSession();
+            if (existsSync(this.sessionPath)) {
+                throw new Error(`Local session file still present after clearSession: ${this.sessionPath}`);
+            }
+        };
+        if (!this.client || !this.connected) {
+            if (existsSync(this.sessionPath))
+                await wipeLocalOrThrow();
             return false;
+        }
+        const client = this.client;
+        let revoked = false;
         try {
-            await this.client.invoke(new Api.auth.LogOut());
-            await this.client.destroy();
-            this.connected = false;
-            this.sessionString = "";
-            this.client = null;
-            return true;
+            await client.invoke(new Api.auth.LogOut());
+            revoked = true;
         }
         catch (error) {
-            console.error("[telegram] logOut error:", error);
-            await this.disconnect();
-            return false;
+            console.error("[telegram] auth.LogOut failed:", error);
+        }
+        // destroy() failure must NOT mask a successful server revoke — log and continue.
+        try {
+            await client.destroy();
+        }
+        catch (err) {
+            console.error("[telegram] client.destroy failed during logOut:", err);
         }
+        await wipeLocalOrThrow();
+        return revoked;
     }
     isConnected() {
         return this.connected;
     }
-    async startQrLogin(onQrDataUrl, onQrUrl) {
+    async startQrLogin(onQrDataUrl, onQrUrl, signal) {
+        // Early exit if already aborted — avoids creating a Telegram connection we'd immediately tear down.
+        if (signal?.aborted)
+            return { success: false, message: "QR login aborted" };
         const session = new StringSession("");
         const proxy = resolveProxy();
         const client = new TelegramClient(session, this.apiId, this.apiHash, {
@@ -227,6 +250,13 @@ export class TelegramService {
         });
         try {
             await client.connect();
+            if (signal?.aborted) {
+                try {
+                    await client.destroy();
+                }
+                catch { }
+                return { success: false, message: "QR login aborted" };
+            }
             let loginAccepted = false;
             let resolved = false;
             let lastQrUrl = "";
@@ -237,6 +267,8 @@ export class TelegramService {
             });
             const maxAttempts = 30; // 5 minutes
             for (let i = 0; i < maxAttempts && !resolved; i++) {
+                if (signal?.aborted)
+                    break;
                 try {
                     const result = await client.invoke(new Api.auth.ExportLoginToken({
                         apiId: this.apiId,
@@ -277,17 +309,45 @@ export class TelegramService {
                     }
                 }
                 if (!resolved) {
-                    await new Promise((r) => setTimeout(r, loginAccepted ? 1500 : 10000));
+                    // Abortable sleep — wakes immediately when caller cancels
+                    const waitMs = loginAccepted ? 1500 : 10000;
+                    await new Promise((resolve) => {
+                        const timer = setTimeout(() => {
+                            signal?.removeEventListener("abort", onAbort);
+                            resolve();
+                        }, waitMs);
+                        const onAbort = () => {
+                            clearTimeout(timer);
+                            resolve();
+                        };
+                        if (signal?.aborted)
+                            onAbort();
+                        else
+                            signal?.addEventListener("abort", onAbort, { once: true });
+                    });
                 }
             }
+            if (signal?.aborted && !resolved) {
+                try {
+                    await client.destroy();
+                }
+                catch { }
+                return { success: false, message: "QR login aborted" };
+            }
             if (resolved) {
                 const newSession = client.session.save();
-                // Adopt the QR login client directly instead of destroy+reconnect
-                // This avoids creating a second Telegram session from DC migration auth keys
+                // Persist FIRST, adopt SECOND — so if file write fails, in-memory state still
+                // matches whatever's on disk; saveSession is try/catch-safe for Docker etc.
+                await this.saveSession(newSession);
+                // Destroy the previous in-memory client to free its auth_key / socket.
+                // Previously left dangling → accumulated orphan Telegram connections per relogin.
+                const oldClient = this.client;
                 this.client = client;
-                this.sessionString = newSession;
                 this.connected = true;
-                await this.saveSession(newSession);
+                this.entityCache.clear();
+                if (oldClient) {
+                    oldClient.destroy().catch(() => { });
+                }
                 return { success: true, message: "Telegram login successful" };
             }
             await client.destroy();

package/dist/tools/auth.js

@@ -1,6 +1,6 @@
 import { writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { fail, ok, READ_ONLY, WRITE } from "./shared.js";
+import { DESTRUCTIVE, fail, ok, READ_ONLY, WRITE } from "./shared.js";
 export function registerAuthTools(server, telegram) {
     server.registerTool("telegram-status", { description: "Check Telegram connection status", annotations: READ_ONLY }, async () => {
         if (await telegram.ensureConnected()) {
@@ -65,4 +65,29 @@ export function registerAuthTools(server, telegram) {
             ],
         };
     });
+    server.registerTool("telegram-logout", {
+        description: "Log out from Telegram completely. Revokes the session on Telegram servers (removes it from Settings → Devices), deletes the local session file, and disconnects. After this you must run telegram-login to re-authenticate.",
+        annotations: DESTRUCTIVE,
+    }, async () => {
+        const wasConnected = await telegram.ensureConnected();
+        if (!wasConnected && !telegram.hasLocalSession()) {
+            return fail(new Error("Not logged in. Nothing to log out from."));
+        }
+        try {
+            const revoked = await telegram.logOut();
+            if (!wasConnected) {
+                return ok("Local session removed (was already disconnected). Server-side revoke was not performed.");
+            }
+            if (revoked) {
+                return ok("Logged out. Session revoked on Telegram servers and removed locally.");
+            }
+            return fail(new Error("Local session removed, but server-side revoke could not be confirmed. Open 'Settings → Devices' in Telegram and terminate the session manually if it is still listed."));
+        }
+        catch (err) {
+            // Local file removal failed (read-only FS, permission denied, etc.).
+            // Never claim local cleanup succeeded when the file may still be on disk.
+            return fail(new Error(`Failed to remove local session file: ${err instanceof Error ? err.message : String(err)}. ` +
+                `Delete it manually (check telegram-status for the path).`));
+        }
+    });
 }

package/package.json

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