@overpod/mcp-telegram 1.27.0 → 1.27.1

package/dist/client.d.ts

@@ -1,9 +1,19 @@
+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>;

package/dist/client.js

@@ -15,15 +15,23 @@ export class IpcClient {
     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 = 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;
@@ -80,7 +88,7 @@ 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 }));
         });

package/dist/ipc-protocol.d.ts

@@ -1,3 +1,10 @@
+/** 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;

package/dist/master.d.ts

@@ -1 +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

@@ -1,7 +1,7 @@
 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 { 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";
@@ -18,7 +18,7 @@ function cleanup() {
 process.on("exit", cleanup);
 process.on("SIGINT", () => process.exit(0));
 process.on("SIGTERM", () => process.exit(0));
-function handleClient(socket, mcpServer) {
+export function handleClient(socket, mcpServer) {
     let buf = "";
     // Processing queue — ensures sequential handling even when handler awaits
     let processing = false;

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.27.0",
+  "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"