@overpod/mcp-telegram 1.26.1 → 1.27.1

package/dist/client.d.ts

@@ -0,0 +1,22 @@
+import { type Socket } from "node:net";
+export interface IpcClientOptions {
+    connectTimeoutMs?: number;
+    callTimeoutMs?: 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 buf;
+    private connected;
+    private readonly connectTimeoutMs;
+    private readonly callTimeoutMs;
+    private readonly connectFn;
+    constructor(opts?: IpcClientOptions);
+    connect(): Promise<boolean>;
+    isConnected(): boolean;
+    call(tool: string, args: Record<string, unknown>): Promise<unknown>;
+    destroy(): void;
+}
+export declare function runClient(apiId: number, apiHash: string, version: string): Promise<void>;

package/dist/client.js

@@ -0,0 +1,144 @@
+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 { 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 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();
+    buf = "";
+    connected = false;
+    connectTimeoutMs;
+    callTimeoutMs;
+    connectFn;
+    constructor(opts = {}) {
+        this.connectTimeoutMs = opts.connectTimeoutMs ?? CONNECT_TIMEOUT_MS;
+        this.callTimeoutMs = opts.callTimeoutMs ?? IPC_CALL_TIMEOUT_MS;
+        this.connectFn = opts.connectFn ?? connect;
+    }
+    async connect() {
+        return new Promise((resolve) => {
+            const sock = socketPath();
+            const s = this.connectFn(sock);
+            // One-shot connect timeout — cleared immediately on connect (HIGH-3)
+            const connectTimer = setTimeout(() => {
+                s.destroy();
+                resolve(false);
+            }, this.connectTimeoutMs);
+            const onConnect = () => {
+                clearTimeout(connectTimer);
+                this.socket = s;
+                this.connected = true;
+                s.removeListener("error", onError);
+                s.on("data", (chunk) => {
+                    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);
+                        }
+                    }
+                });
+                s.on("close", () => {
+                    this.connected = false;
+                    for (const [, p] of this.pending) {
+                        clearTimeout(p.timer);
+                        p.reject(new Error("IPC connection closed"));
+                    }
+                    this.pending.clear();
+                });
+                s.on("error", () => { });
+                resolve(true);
+            };
+            const onError = () => {
+                clearTimeout(connectTimer);
+                resolve(false);
+            };
+            s.once("connect", onConnect);
+            s.once("error", onError);
+        });
+    }
+    isConnected() {
+        return this.connected;
+    }
+    async call(tool, args) {
+        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.pending.delete(id);
+                reject(new Error(`IPC call timeout: ${tool}`));
+            }, this.callTimeoutMs);
+            this.pending.set(id, { resolve, reject, timer });
+            socket.write(encodeMessage({ id, tool, args }));
+        });
+    }
+    destroy() {
+        for (const [, p] of this.pending) {
+            clearTimeout(p.timer);
+            p.reject(new Error("IPC client destroyed"));
+        }
+        this.pending.clear();
+        this.socket?.destroy();
+        this.socket = null;
+        this.connected = false;
+    }
+}
+function wireIpcProxies(server, ipc) {
+    const s = server;
+    for (const [name, tool] of Object.entries(s._registeredTools)) {
+        Object.assign(tool, {
+            handler: (args) => ipc.call(name, args),
+        });
+    }
+}
+export async function runClient(apiId, apiHash, version) {
+    // Try to connect to master with retries — master may still be initializing its socket
+    let ipc = null;
+    for (let attempt = 0; attempt < MAX_RECONNECT_ATTEMPTS; attempt++) {
+        const candidate = new IpcClient();
+        if (await candidate.connect()) {
+            ipc = candidate;
+            break;
+        }
+        if (attempt < MAX_RECONNECT_ATTEMPTS - 1) {
+            await new Promise((r) => setTimeout(r, 150 * 2 ** attempt)); // 150ms, 300ms, 600ms, 1200ms
+        }
+    }
+    if (!ipc) {
+        // Master acquired lock but socket not ready — this process should not become master
+        // (it lost the lock race). Exit with clear message instead of creating two masters (CRITICAL-2)
+        console.error("[mcp-telegram] Cannot connect to master process. Try again in a moment.");
+        process.exit(1);
+    }
+    console.error(`[mcp-telegram] Client mode — proxying to master via ${socketPath()}`);
+    // 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);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("[mcp-telegram] MCP server running on stdio (client)");
+}

package/dist/index.js

@@ -1,16 +1,12 @@
 #!/usr/bin/env node
 // Redirect console.log to stderr BEFORE any imports.
 // GramJS Logger uses console.log (stdout) which corrupts MCP JSON-RPC stream.
-const _origLog = console.log;
 console.log = (...args) => {
     console.error(...args);
 };
 import "dotenv/config";
 import { createRequire } from "node:module";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { TelegramService } from "./telegram-client.js";
-import { registerTools } from "./tools/index.js";
+import { tryAcquireLock } from "./lock.js";
 const require = createRequire(import.meta.url);
 const { version } = require("../package.json");
 // Telegram API credentials from env
@@ -22,26 +18,18 @@ if (!API_ID || !API_HASH) {
     console.error("Set them in .env or export as environment variables");
     process.exit(1);
 }
-const telegram = new TelegramService(API_ID, API_HASH);
-const server = new McpServer({
-    name: "mcp-telegram",
-    version,
-});
-registerTools(server, telegram);
 async function main() {
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-    console.error("[mcp-telegram] MCP server running on stdio");
-    // Auto-connect with saved session after MCP is ready (non-blocking)
-    telegram.loadSession().then(async () => {
-        if (await telegram.connect()) {
-            const me = await telegram.getMe();
-            console.error(`[mcp-telegram] Auto-connected as @${me.username}`);
-        }
-        else if (telegram.lastError) {
-            console.error(`[mcp-telegram] ${telegram.lastError}`);
-        }
-    });
+    const isMaster = tryAcquireLock();
+    if (isMaster) {
+        console.error("[mcp-telegram] Starting as master process");
+        const { runMaster } = await import("./master.js");
+        await runMaster(API_ID, API_HASH, version);
+    }
+    else {
+        console.error("[mcp-telegram] Starting as client process (master already running)");
+        const { runClient } = await import("./client.js");
+        await runClient(API_ID, API_HASH, version);
+    }
 }
 main().catch((err) => {
     console.error("[mcp-telegram] Fatal:", err);

package/dist/ipc-protocol.d.ts

@@ -0,0 +1,26 @@
+/** 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>;
+}
+/** Request from Client → Master */
+export interface IpcRequest {
+    id: string;
+    tool: string;
+    args: Record<string, unknown>;
+}
+/** Response from Master → Client */
+export interface IpcResponse {
+    id: string;
+    result?: unknown;
+    error?: string;
+}
+/** Encode a message as newline-delimited JSON */
+export declare function encodeMessage(msg: IpcRequest | IpcResponse): string;
+/** Parse newline-delimited JSON messages from a buffer, returns parsed messages + leftover */
+export declare function parseMessages(buf: string): {
+    messages: (IpcRequest | IpcResponse)[];
+    remaining: string;
+};

package/dist/ipc-protocol.js

@@ -0,0 +1,22 @@
+/** Encode a message as newline-delimited JSON */
+export function encodeMessage(msg) {
+    return `${JSON.stringify(msg)}\n`;
+}
+/** Parse newline-delimited JSON messages from a buffer, returns parsed messages + leftover */
+export function parseMessages(buf) {
+    const lines = buf.split("\n");
+    const remaining = lines.pop() ?? "";
+    const messages = [];
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            messages.push(JSON.parse(trimmed));
+        }
+        catch {
+            // Skip malformed lines
+        }
+    }
+    return { messages, remaining };
+}

package/dist/lock.d.ts

@@ -0,0 +1,12 @@
+export declare function lockPath(): string;
+export declare function socketPath(): string;
+/**
+ * Try to acquire the master lock.
+ * Returns true if this process is now the master.
+ * Returns false if another live master process holds the lock.
+ *
+ * Uses PID file + kill -0 to detect stale locks after crashes.
+ */
+export declare function tryAcquireLock(): boolean;
+export declare function releaseLock(): void;
+export declare function releaseSocket(): void;

package/dist/lock.js

@@ -0,0 +1,83 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+const DEFAULT_SESSION_DIR = join(homedir(), ".mcp-telegram");
+function resolveSessionDir() {
+    const sessionPath = process.env.TELEGRAM_SESSION_PATH;
+    if (sessionPath)
+        return dirname(sessionPath);
+    return DEFAULT_SESSION_DIR;
+}
+export function lockPath() {
+    return join(resolveSessionDir(), "daemon.lock");
+}
+export function socketPath() {
+    return join(resolveSessionDir(), "daemon.sock");
+}
+/**
+ * Try to acquire the master lock.
+ * Returns true if this process is now the master.
+ * Returns false if another live master process holds the lock.
+ *
+ * Uses PID file + kill -0 to detect stale locks after crashes.
+ */
+export function tryAcquireLock() {
+    const lock = lockPath();
+    const dir = dirname(lock);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    if (existsSync(lock)) {
+        try {
+            const pid = Number.parseInt(readFileSync(lock, "utf-8").trim(), 10);
+            if (!Number.isNaN(pid) && pid > 0) {
+                try {
+                    // kill -0: check if process is alive without sending a signal
+                    process.kill(pid, 0);
+                    // Process is alive — another master owns the lock
+                    return false;
+                }
+                catch {
+                    // ESRCH: process not found — stale lock, take over
+                    unlinkSync(lock);
+                }
+            }
+        }
+        catch {
+            // Unreadable lock — remove and take over
+            try {
+                unlinkSync(lock);
+            }
+            catch { }
+        }
+    }
+    try {
+        // O_EXCL flag: atomic exclusive create — prevents TOCTOU race between two simultaneous starts
+        writeFileSync(lock, String(process.pid), { flag: "wx", mode: 0o600 });
+        return true;
+    }
+    catch {
+        // EEXIST: another process just created the lock — we lost the race, become client
+        return false;
+    }
+}
+export function releaseLock() {
+    try {
+        const lock = lockPath();
+        if (existsSync(lock)) {
+            const pid = Number.parseInt(readFileSync(lock, "utf-8").trim(), 10);
+            // Only remove our own lock
+            if (pid === process.pid)
+                unlinkSync(lock);
+        }
+    }
+    catch { }
+}
+export function releaseSocket() {
+    try {
+        const sock = socketPath();
+        if (existsSync(sock))
+            unlinkSync(sock);
+    }
+    catch { }
+}

package/dist/master.d.ts

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

package/dist/master.js

@@ -0,0 +1,105 @@
+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 { 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;
+    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) {
+    let buf = "";
+    // Processing queue — ensures sequential handling even when handler awaits
+    let processing = false;
+    const queue = [];
+    async function drainQueue() {
+        if (processing)
+            return;
+        processing = true;
+        while (queue.length > 0) {
+            const req = queue.shift();
+            if (!req)
+                break;
+            const tool = mcpServer._registeredTools[req.tool];
+            const response = { id: req.id };
+            if (!tool) {
+                response.error = `Unknown tool: ${req.tool}`;
+            }
+            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));
+            }
+        }
+        processing = false;
+    }
+    socket.on("data", (chunk) => {
+        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);
+        }
+        drainQueue();
+    });
+    socket.on("error", () => { });
+}
+export async function runMaster(apiId, apiHash, version) {
+    const telegram = new TelegramService(apiId, apiHash);
+    const server = new McpServer({ name: "mcp-telegram", version });
+    registerTools(server, telegram);
+    const mcpServer = server;
+    // 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;
+    await new Promise((resolve, reject) => {
+        srv.listen(sock, resolve);
+        srv.once("error", reject);
+    });
+    const { chmod } = await import("node:fs/promises");
+    try {
+        await chmod(sock, 0o600);
+    }
+    catch { }
+    console.error(`[mcp-telegram] Master mode — IPC socket ready: ${sock}`);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("[mcp-telegram] MCP server running on stdio (master)");
+    // Auto-connect with saved session — catch to avoid unhandled rejection (MEDIUM-2)
+    telegram
+        .loadSession()
+        .then(async () => {
+        if (await telegram.connect()) {
+            const me = await telegram.getMe();
+            console.error(`[mcp-telegram] Auto-connected as @${me.username}`);
+        }
+        else if (telegram.lastError) {
+            console.error(`[mcp-telegram] ${telegram.lastError}`);
+        }
+    })
+        .catch((err) => {
+        console.error("[mcp-telegram] Auto-connect failed:", err);
+    });
+}

package/dist/telegram-client.js

@@ -60,6 +60,7 @@ export class TelegramService {
     get sessionDir() {
         return dirname(this.sessionPath);
     }
+    // ─── Session & Auth ────────────────────────────────────────────────────────
     getClient() {
         return this.client;
     }
@@ -300,6 +301,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 +412,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 +502,7 @@ export class TelegramService {
             };
         });
     }
+    // ─── Contacts ──────────────────────────────────────────────────────────────
     async addContact(userId, firstName, lastName, phone) {
         if (!this.client || !this.connected)
             throw new Error(NOT_CONNECTED_ERROR);
@@ -522,6 +526,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 +791,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 +1131,7 @@ export class TelegramService {
         })));
         return results;
     }
+    // ─── Search ────────────────────────────────────────────────────────────────
     async getContacts(limit = 50) {
         if (!this.client || !this.connected)
             throw new Error(NOT_CONNECTED_ERROR);
@@ -1302,6 +1309,7 @@ export class TelegramService {
             businessLocation,
         };
     }
+    // ─── Profiles & Media ──────────────────────────────────────────────────────
     async downloadProfilePhoto(entityId, options) {
         if (!this.client || !this.connected)
             throw new Error(NOT_CONNECTED_ERROR);
@@ -1360,6 +1368,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 +1505,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 +1624,7 @@ export class TelegramService {
         catch { }
         return false;
     }
+    // ─── Chat membership & management ──────────────────────────────────────────
     async joinChat(target) {
         if (!this.client)
             throw new Error(NOT_CONNECTED_ERROR);
@@ -1895,7 +1906,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 +2144,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 +2317,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 +2349,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 +2361,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 +2417,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 +2491,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 +2567,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 +2671,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 +2764,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 +2960,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 +3017,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 +3065,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 +3098,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 +3129,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.26.1",
+  "version": "1.27.1",
   "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"