@overpod/mcp-telegram 1.26.1 → 1.27.0

package/dist/client.d.ts

@@ -0,0 +1,12 @@
+/** 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;
+    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,136 @@
+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;
+    async connect() {
+        return new Promise((resolve) => {
+            const sock = socketPath();
+            const s = connect(sock);
+            // One-shot connect timeout — cleared immediately on connect (HIGH-3)
+            const connectTimer = setTimeout(() => {
+                s.destroy();
+                resolve(false);
+            }, CONNECT_TIMEOUT_MS);
+            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}`));
+            }, IPC_CALL_TIMEOUT_MS);
+            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,19 @@
+/** 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 @@
+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));
+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/package.json

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