@overpod/mcp-telegram 1.27.0 → 1.28.0

package/dist/client.d.ts

@@ -1,12 +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,28 +2,47 @@ 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();
-            const s = connect(sock);
+            const s = this.connectFn(sock);
             // One-shot connect timeout — cleared immediately on connect (HIGH-3)
             const connectTimer = setTimeout(() => {
                 s.destroy();
                 resolve(false);
-            }, CONNECT_TIMEOUT_MS);
+            }, this.connectTimeoutMs);
             const onConnect = () => {
                 clearTimeout(connectTimer);
                 this.socket = s;
@@ -33,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;
@@ -55,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);
             };
@@ -67,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;
     }
@@ -80,17 +126,41 @@ export class IpcClient {
             const timer = setTimeout(() => {
                 this.pending.delete(id);
                 reject(new Error(`IPC call timeout: ${tool}`));
-            }, IPC_CALL_TIMEOUT_MS);
+            }, 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;
@@ -124,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

@@ -1,19 +1,48 @@
-/** Request from Client → Master */
-export interface IpcRequest {
+/** MCP SDK internal tool registry — field name "handler" confirmed in SDK v1.29.0 */
+export type McpRegisteredTool = {
+    handler: (args: Record<string, unknown>, extra: Record<string, unknown>) => Promise<unknown>;
+};
+export interface McpServerInternal {
+    _registeredTools: Record<string, McpRegisteredTool>;
+}
+/** 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 +1,5 @@
+import { type Socket } from "node:net";
+import { type McpServerInternal } from "./ipc-protocol.js";
+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 { encodeMessage, parseMessages } from "./ipc-protocol.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));
-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,73 @@ 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 {
+        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 +129,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 +140,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

@@ -38,7 +38,7 @@ export declare class TelegramService {
      */
     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,7 @@ export class TelegramService {
     get sessionDir() {
         return dirname(this.sessionPath);
     }
+    // ─── Session & Auth ────────────────────────────────────────────────────────
     getClient() {
         return this.client;
     }
@@ -217,7 +218,10 @@ export class TelegramService {
     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, {
@@ -226,6 +230,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 = "";
@@ -236,6 +247,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,
@@ -276,17 +289,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();
@@ -300,6 +341,7 @@ export class TelegramService {
             return { success: false, message: `Login failed: ${err.message}` };
         }
     }
+    // ─── Messages ──────────────────────────────────────────────────────────────
     async getMe() {
         if (!this.client || !this.connected)
             throw new Error(NOT_CONNECTED_ERROR);
@@ -410,6 +452,7 @@ export class TelegramService {
         const resolved = await this.resolvePeer(chatId);
         await this.client.unpinMessage(resolved, messageId);
     }
+    // ─── Dialogs ───────────────────────────────────────────────────────────────
     async getDialogs(limit = 20, offsetDate, filterType) {
         if (!this.client || !this.connected)
             throw new Error(NOT_CONNECTED_ERROR);
@@ -499,6 +542,7 @@ export class TelegramService {
             };
         });
     }
+    // ─── Contacts ──────────────────────────────────────────────────────────────
     async addContact(userId, firstName, lastName, phone) {
         if (!this.client || !this.connected)
             throw new Error(NOT_CONNECTED_ERROR);
@@ -522,6 +566,7 @@ export class TelegramService {
         const peer = await this.client.getInputEntity(chatId);
         await this.client.invoke(new Api.messages.ReportSpam({ peer }));
     }
+    // ─── Read state ────────────────────────────────────────────────────────────
     async markAsRead(chatId) {
         if (!this.client || !this.connected)
             throw new Error(NOT_CONNECTED_ERROR);
@@ -786,6 +831,7 @@ export class TelegramService {
             }
         }, `sendTyping in ${chatId}`);
     }
+    // ─── Chat lookup & info ────────────────────────────────────────────────────
     /**
      * Resolve a chat by ID, username, or display name.
      * Falls back to searching user's dialogs if getEntity() fails.
@@ -1125,6 +1171,7 @@ export class TelegramService {
         })));
         return results;
     }
+    // ─── Search ────────────────────────────────────────────────────────────────
     async getContacts(limit = 50) {
         if (!this.client || !this.connected)
             throw new Error(NOT_CONNECTED_ERROR);
@@ -1302,6 +1349,7 @@ export class TelegramService {
             businessLocation,
         };
     }
+    // ─── Profiles & Media ──────────────────────────────────────────────────────
     async downloadProfilePhoto(entityId, options) {
         if (!this.client || !this.connected)
             throw new Error(NOT_CONNECTED_ERROR);
@@ -1360,6 +1408,7 @@ export class TelegramService {
         }
         return items.length > 0 ? items : undefined;
     }
+    // ─── Reactions ─────────────────────────────────────────────────────────────
     async sendReaction(chatId, messageId, emoji, addToExisting = false) {
         if (!this.client || !this.connected)
             throw new Error(NOT_CONNECTED_ERROR);
@@ -1496,6 +1545,7 @@ export class TelegramService {
             return out;
         }, "getRecentReactions");
     }
+    // ─── Scheduled & Polls ─────────────────────────────────────────────────────
     async sendScheduledMessage(chatId, text, scheduleDate, replyTo, parseMode) {
         if (!this.client || !this.connected)
             throw new Error(NOT_CONNECTED_ERROR);
@@ -1614,6 +1664,7 @@ export class TelegramService {
         catch { }
         return false;
     }
+    // ─── Chat membership & management ──────────────────────────────────────────
     async joinChat(target) {
         if (!this.client)
             throw new Error(NOT_CONNECTED_ERROR);
@@ -1895,7 +1946,7 @@ export class TelegramService {
             rank: "",
         }));
     }
-    // ── New tools: feature parity ──────────────────────────────────────
+    // ─── Chat settings & moderation ────────────────────────────────────────────
     async unblockUser(userId) {
         if (!this.client || !this.connected)
             throw new Error(NOT_CONNECTED_ERROR);
@@ -2133,6 +2184,7 @@ export class TelegramService {
             await this.client?.invoke(new Api.messages.HideChatJoinRequest({ peer: entity, userId: inputUser, approved }));
         }, `approveChatJoinRequest ${chatId}/${userId}`);
     }
+    // ─── Inline bots & buttons ─────────────────────────────────────────────────
     async getInlineBotResults(bot, chatId, query, offset) {
         if (!this.client || !this.connected)
             throw new Error(NOT_CONNECTED_ERROR);
@@ -2305,7 +2357,7 @@ export class TelegramService {
                 result = response;
             }
             catch (e) {
-                const msg = e.message ?? String(e);
+                const msg = e instanceof Error ? e.message : String(e);
                 if (/CHAT_ADMIN_REQUIRED|ADMIN_RANK_INVALID/i.test(msg)) {
                     throw new Error("Access denied: channel stats require admin rights (and may require Telegram Premium)");
                 }
@@ -2337,7 +2389,7 @@ export class TelegramService {
                 result = response;
             }
             catch (e) {
-                const msg = e.message ?? String(e);
+                const msg = e instanceof Error ? e.message : String(e);
                 if (/CHAT_ADMIN_REQUIRED|ADMIN_RANK_INVALID/i.test(msg)) {
                     throw new Error("Access denied: supergroup stats require admin rights");
                 }
@@ -2349,6 +2401,7 @@ export class TelegramService {
             return summarizeMegagroupStats(result, options?.includeGraphs === true);
         }, `getMegagroupStats ${chatId}`, { throwOnFloodWait: true });
     }
+    // ─── Stats & updates ───────────────────────────────────────────────────────
     async getUpdatesState() {
         if (!this.client || !this.connected)
             throw new Error(NOT_CONNECTED_ERROR);
@@ -2404,6 +2457,7 @@ export class TelegramService {
             return summarizeChannelDifference(diff, entity.id.toString(), cursor.pts);
         }, `getChannelUpdates ${chatId}`);
     }
+    // ─── Forum topics ──────────────────────────────────────────────────────────
     async createForumTopic(chatId, title, iconColor, iconEmojiId) {
         if (!this.client || !this.connected)
             throw new Error(NOT_CONNECTED_ERROR);
@@ -2477,6 +2531,7 @@ export class TelegramService {
             }));
         }, `deleteForumTopic ${chatId}/${topicId}`);
     }
+    // ─── Invite links & folders ────────────────────────────────────────────────
     async exportInviteLink(chatId, options) {
         if (!this.client || !this.connected)
             throw new Error(NOT_CONNECTED_ERROR);
@@ -2552,6 +2607,7 @@ export class TelegramService {
         const peer = await this.client.getInputEntity(resolved);
         await this.client.invoke(new Api.messages.SetHistoryTTL({ peer, period }));
     }
+    // ─── Account & privacy ─────────────────────────────────────────────────────
     async getActiveSessions() {
         if (!this.client || !this.connected)
             throw new Error(NOT_CONNECTED_ERROR);
@@ -2655,7 +2711,7 @@ export class TelegramService {
             throw new Error(NOT_CONNECTED_ERROR);
         await this.client.invoke(new Api.account.UpdateUsername({ username }));
     }
-    // ─── Stickers ──────────────────────────────────────────────
+    // ─── Stickers ──────────────────────────────────────────────────────────────
     async getStickerSet(shortName) {
         if (!this.client || !this.connected)
             throw new Error(NOT_CONNECTED_ERROR);
@@ -2748,6 +2804,7 @@ export class TelegramService {
             });
         }, `sendSticker to ${chatId}`);
     }
+    // ─── Drafts & saved dialogs ────────────────────────────────────────────────
     async saveDraft(chatId, text, replyTo) {
         if (!this.client || !this.connected)
             throw new Error(NOT_CONNECTED_ERROR);
@@ -2943,6 +3000,7 @@ export class TelegramService {
             emoji: emojiMap.get(doc.id.toString()) || "",
         }));
     }
+    // ─── Stories ───────────────────────────────────────────────────────────────
     async getAllStories(options) {
         if (!this.client || !this.connected)
             throw new Error(NOT_CONNECTED_ERROR);
@@ -2999,6 +3057,7 @@ export class TelegramService {
             return summarizeStoryViewsList(response);
         }, `getStoryViewsList ${chatId}/${options.id}`);
     }
+    // ─── Boosts ────────────────────────────────────────────────────────────────
     async getMyBoosts() {
         if (!this.client || !this.connected)
             throw new Error(NOT_CONNECTED_ERROR);
@@ -3046,6 +3105,7 @@ export class TelegramService {
             return summarizeBusinessChatLinks(response);
         }, "getBusinessChatLinks");
     }
+    // ─── Group calls ───────────────────────────────────────────────────────────
     async getGroupCall(chatId, options = {}) {
         if (!this.client || !this.connected)
             throw new Error(NOT_CONNECTED_ERROR);
@@ -3078,6 +3138,7 @@ export class TelegramService {
             return summarizeGroupCallParticipants(response);
         }, `getGroupCallParticipants ${chatId}`);
     }
+    // ─── Stars ─────────────────────────────────────────────────────────────────
     async getStarsStatus(chatId) {
         if (!this.client || !this.connected)
             throw new Error(NOT_CONNECTED_ERROR);
@@ -3108,6 +3169,7 @@ export class TelegramService {
             return summarizeStarsStatus(response);
         }, `getStarsTransactions ${chatId}`);
     }
+    // ─── Quick replies ─────────────────────────────────────────────────────────
     async getQuickReplies(hash) {
         if (!this.client || !this.connected)
             throw new Error(NOT_CONNECTED_ERROR);

package/dist/telegram-helpers.js

@@ -109,12 +109,12 @@ function compactGraph(g) {
         }
         return { type: "data", data: parsed, zoomToken: g.zoomToken };
     }
-    const any = g;
-    if (typeof any.token === "string")
-        return { type: "async", token: any.token };
-    if (typeof any.error === "string")
-        return { type: "error", error: any.error };
-    return { type: "data", data: any.json?.data, zoomToken: any.zoomToken };
+    const graph = g;
+    if (typeof graph.token === "string")
+        return { type: "async", token: graph.token };
+    if (typeof graph.error === "string")
+        return { type: "error", error: graph.error };
+    return { type: "data", data: graph.json?.data, zoomToken: graph.zoomToken };
 }
 export function summarizeMegagroupStats(stats, includeGraphs) {
     const summary = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@overpod/mcp-telegram",
-  "version": "1.27.0",
+  "version": "1.28.0",
   "description": "MCP server for Telegram userbot — messages, media, reactions, polls & more. Built on GramJS/MTProto.",
   "type": "module",
   "main": "dist/index.js",
@@ -27,8 +27,9 @@
     "lint": "biome check src/",
     "lint:fix": "biome check --fix src/",
     "format": "biome format --write src/",
-    "test": "tsx --test src/**/*.test.ts",
-    "test:watch": "tsx --test --watch src/**/*.test.ts",
+    "test": "tsx --test 'src/**/*.test.ts'",
+    "test:watch": "tsx --test --watch 'src/**/*.test.ts'",
+    "test:coverage": "c8 --all --src src --exclude 'src/**/*.test.ts' --reporter=text tsx --test 'src/**/*.test.ts'",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs"
@@ -65,6 +66,7 @@
     "@biomejs/biome": "^2.4.12",
     "@types/node": "^25.6.0",
     "@types/qrcode": "^1.5.6",
+    "c8": "^11.0.0",
     "tsx": "^4.21.0",
     "typescript": "^6.0.3",
     "vitepress": "^1.6.4"