@overpod/mcp-telegram 1.37.1 → 1.38.1

package/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.38.1](https://github.com/mcp-telegram/mcp-telegram/compare/v1.38.0...v1.38.1) (2026-06-10)
+
+
+### Fixed
+
+* **deps:** bump transitive hono 4.12.18 → 4.12.25 (security) ([f90b32c](https://github.com/mcp-telegram/mcp-telegram/commit/f90b32c61588c92e4f83d938d6b68c83d4deb82f))
+
+
+### Documentation
+
+* **daemon:** fix dead link to packaging/ — point at GitHub, not a relative path ([0574c6a](https://github.com/mcp-telegram/mcp-telegram/commit/0574c6a369b9c0d30311abf374c59f80462b289e))
+
+## [1.38.0](https://github.com/mcp-telegram/mcp-telegram/compare/v1.37.1...v1.38.0) (2026-06-10)
+
+
+### Added
+
+* shared daemon (serve mode) for concurrent MCP clients ([#49](https://github.com/mcp-telegram/mcp-telegram/issues/49)) ([7568927](https://github.com/mcp-telegram/mcp-telegram/commit/75689270ffb21ca4f14e9e7673a36af25f36cde5))
+
 ## [1.37.1](https://github.com/mcp-telegram/mcp-telegram/compare/v1.37.0...v1.37.1) (2026-06-06)
 
 

package/README.md

@@ -102,6 +102,22 @@ claude mcp add telegram-personal -s user \
 
 Each account gets its own session file — no conflicts.
 
+### Multiple agents / concurrent clients (shared daemon)
+
+The opposite of multiple accounts: **one** account driven by **many** clients at once — several Claude Code windows, parallel sub-agents, or multiple IDEs. Normally each process opens the same session and they evict one another with `AUTH_KEY_DUPLICATED`. Serve mode fixes this.
+
+Run a single persistent **daemon** that owns the one Telegram connection. Every other process auto-detects the daemon (via a PID lock) and becomes a thin client that proxies tool calls to it over a local Unix socket:
+
+```bash
+# On the host, once: start the daemon (owns the connection, no stdio)
+TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH mcp-telegram serve
+# (or set MCP_TELEGRAM_DAEMON=1 instead of the `serve` argument)
+```
+
+Then point each MCP client at the same install with the same `TELEGRAM_SESSION_PATH` — no `serve` argument. They connect to the daemon automatically; closing any client never drops the shared connection. Credentials are only required by the daemon (the owner), so client commands can omit `TELEGRAM_API_ID`/`TELEGRAM_API_HASH` and keep them where the daemon runs.
+
+See the **[shared daemon guide](docs/guides/shared-daemon.md)** for a systemd unit and SSH usage.
+
 ### Proxy Support
 
 If Telegram is blocked or you're running in a containerized environment (Docker, K3s), use a SOCKS5 or MTProxy:

package/dist/index.js

@@ -12,23 +12,40 @@ const { version } = require("../package.json");
 // Telegram API credentials from env
 const API_ID = Number(process.env.TELEGRAM_API_ID);
 const API_HASH = process.env.TELEGRAM_API_HASH;
-if (!API_ID || !API_HASH) {
-    console.error("[mcp-telegram] Missing TELEGRAM_API_ID and TELEGRAM_API_HASH");
-    console.error("Get your credentials at https://my.telegram.org/apps (API development tools)");
-    console.error("Set them in .env or export as environment variables");
-    process.exit(1);
+// Credentials are required only on the OWNER paths (serve/master) that open the real
+// Telegram connection. A client proxies every call over IPC and never connects, so it
+// runs without them — letting credentials stay only where the daemon runs.
+function requireCreds() {
+    if (!API_ID || !API_HASH) {
+        console.error("[mcp-telegram] Missing TELEGRAM_API_ID and TELEGRAM_API_HASH (required to own the Telegram connection)");
+        console.error("Get your credentials at https://my.telegram.org/apps (API development tools)");
+        console.error("Set them in .env or export as environment variables");
+        process.exit(1);
+    }
 }
 async function main() {
+    // Persistent daemon mode: `mcp-telegram serve` (or MCP_TELEGRAM_DAEMON=1). The daemon owns
+    // the connection with no stdio attached; every other process becomes a client.
+    if (process.argv[2] === "serve" || process.env.MCP_TELEGRAM_DAEMON === "1") {
+        requireCreds();
+        console.error("[mcp-telegram] Starting in serve (daemon) mode");
+        const { runServe } = await import("./serve.js");
+        await runServe(API_ID, API_HASH, version);
+        return;
+    }
     const isMaster = tryAcquireLock();
     if (isMaster) {
+        requireCreds();
         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)");
+        // Client proxies all tool calls to the owner over IPC; the dummy TelegramService is
+        // never used for real calls, so API credentials are optional here.
+        console.error("[mcp-telegram] Starting as client process (owner already running)");
         const { runClient } = await import("./client.js");
-        await runClient(API_ID, API_HASH, version);
+        await runClient(API_ID || 0, API_HASH ?? "", version);
     }
 }
 main().catch((err) => {

package/dist/lock.js

@@ -37,8 +37,12 @@ export function tryAcquireLock() {
                     // Process is alive — another master owns the lock
                     return false;
                 }
-                catch {
-                    // ESRCH: process not found — stale lock, take over
+                catch (err) {
+                    // ESRCH: process not found — stale lock, take over.
+                    // EPERM: process is alive but owned by another uid we can't signal —
+                    // treat as a live owner and DON'T steal the lock.
+                    if (err.code === "EPERM")
+                        return false;
                     unlinkSync(lock);
                 }
             }
@@ -76,8 +80,30 @@ export function releaseLock() {
 export function releaseSocket() {
     try {
         const sock = socketPath();
-        if (existsSync(sock))
-            unlinkSync(sock);
+        if (!existsSync(sock))
+            return;
+        // Ownership guard (mirrors releaseLock): never unlink a socket owned by a different,
+        // still-alive process. Otherwise any process that imports this module and exits (e.g. a
+        // one-shot run or a test on the same host) would delete a running daemon's socket file,
+        // leaving the daemon listening in memory but unreachable for new clients.
+        const lock = lockPath();
+        if (existsSync(lock)) {
+            const pid = Number.parseInt(readFileSync(lock, "utf-8").trim(), 10);
+            // Ignore non-positive PIDs (e.g. 0) so kill() can't probe our own process group.
+            if (!Number.isNaN(pid) && pid > 0 && pid !== process.pid) {
+                try {
+                    process.kill(pid, 0); // foreign owner still alive?
+                    return; // yes — leave its socket alone
+                }
+                catch (err) {
+                    // ESRCH: stale owner — safe to remove. EPERM: owner is alive under a
+                    // different uid (e.g. a systemd daemon) — leave its socket alone too.
+                    if (err.code === "EPERM")
+                        return;
+                }
+            }
+        }
+        unlinkSync(sock);
     }
     catch { }
 }

package/dist/master.d.ts

@@ -1,5 +1,20 @@
-import { type Socket } from "node:net";
+import { type Server, type Socket } from "node:net";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 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 interface OwnerHandle {
+    server: McpServer;
+    srv: Server;
+    gracefulExit: () => Promise<void>;
+}
+/**
+ * Bootstrap the connection owner shared by master (stdio) and serve (daemon) modes:
+ * build the tool registry, listen on the IPC socket, install a graceful shutdown that
+ * disconnects Telegram, and auto-connect the single client. No stdio is attached here —
+ * the caller decides whether to also serve a stdio MCP session (master) or not (serve).
+ */
+export declare function startOwner(telegram: TelegramService, version: string, opts?: {
+    label?: string;
+}): Promise<OwnerHandle>;
 export declare function runMaster(apiId: number, apiHash: string, version: string): Promise<void>;

package/dist/master.js

@@ -17,8 +17,6 @@ function cleanup() {
     releaseSocket();
 }
 process.on("exit", cleanup);
-process.on("SIGINT", () => process.exit(0));
-process.on("SIGTERM", () => process.exit(0));
 // 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.
@@ -126,15 +124,25 @@ async function handleLoginStart(socket, req, telegram) {
         unlock();
     }
 }
-export async function runMaster(apiId, apiHash, version) {
-    const telegram = new TelegramService(apiId, apiHash);
+/**
+ * Bootstrap the connection owner shared by master (stdio) and serve (daemon) modes:
+ * build the tool registry, listen on the IPC socket, install a graceful shutdown that
+ * disconnects Telegram, and auto-connect the single client. No stdio is attached here —
+ * the caller decides whether to also serve a stdio MCP session (master) or not (serve).
+ */
+export async function startOwner(telegram, version, opts = {}) {
+    const label = opts.label ?? "mcp-telegram";
     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)
+    // Remove a stale socket file from a previous crash before attempting to listen.
     releaseSocket();
     const sock = socketPath();
-    const srv = createServer((socket) => handleClient(socket, mcpServer, telegram));
+    const srv = createServer((socket) => {
+        console.error(`[${label}] client connected`);
+        socket.on("close", () => console.error(`[${label}] client disconnected`));
+        handleClient(socket, mcpServer, telegram);
+    });
     await new Promise((resolve, reject) => {
         srv.listen(sock, resolve);
         srv.once("error", reject);
@@ -144,27 +152,49 @@ export async function runMaster(apiId, apiHash, version) {
         await chmod(sock, 0o600);
     }
     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)");
-    // Auto-connect with saved session — catch to avoid unhandled rejection (MEDIUM-2)
+    console.error(`[${label}] IPC socket ready: ${sock}`);
+    let shuttingDown = false;
+    const gracefulExit = async () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        console.error(`[${label}] Shutting down, disconnecting from Telegram...`);
+        try {
+            await telegram.disconnect();
+        }
+        catch (err) {
+            console.error(`[${label}] Disconnect error:`, err);
+        }
+        process.exit(0);
+    };
+    process.on("SIGINT", gracefulExit);
+    process.on("SIGTERM", gracefulExit);
+    // Auto-connect with saved session — catch to avoid unhandled rejection.
     telegram
         .loadSession()
         .then(async () => {
         if (await telegram.connect()) {
             const me = await telegram.getMe();
-            console.error(`[mcp-telegram] Auto-connected as @${me.username}`);
+            console.error(`[${label}] connected as @${me.username}`);
         }
         else if (telegram.lastError) {
-            console.error(`[mcp-telegram] ${telegram.lastError}`);
+            console.error(`[${label}] ${telegram.lastError}`);
         }
     })
         .catch((err) => {
-        console.error("[mcp-telegram] Auto-connect failed:", err);
+        console.error(`[${label}] Auto-connect failed:`, err);
     });
+    return { server, srv, gracefulExit };
+}
+export async function runMaster(apiId, apiHash, version) {
+    const telegram = new TelegramService(apiId, apiHash);
+    const { server, gracefulExit } = await startOwner(telegram, version, { label: "mcp-telegram (master)" });
+    // 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", gracefulExit);
+    // Master also serves the launching window directly over stdio.
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("[mcp-telegram] MCP server running on stdio (master)");
 }

package/dist/serve.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Persistent daemon mode: own the single Telegram connection and serve many concurrent
+ * IPC clients, with no stdio and no stdin-exit, so closing any client never tears the
+ * connection down. Intended to run under a supervisor (systemd, Docker) with Restart=always.
+ */
+export declare function runServe(apiId: number, apiHash: string, version: string): Promise<void>;

package/dist/serve.js

@@ -0,0 +1,22 @@
+import { tryAcquireLock } from "./lock.js";
+import { startOwner } from "./master.js";
+import { TelegramService } from "./telegram-client.js";
+/**
+ * Persistent daemon mode: own the single Telegram connection and serve many concurrent
+ * IPC clients, with no stdio and no stdin-exit, so closing any client never tears the
+ * connection down. Intended to run under a supervisor (systemd, Docker) with Restart=always.
+ */
+export async function runServe(apiId, apiHash, version) {
+    // The daemon must be the sole connection owner. If another owner already holds the lock,
+    // refuse rather than open a second client on the same session (AUTH_KEY_DUPLICATED).
+    if (!tryAcquireLock()) {
+        console.error("[serve] Another owner already holds the lock; refusing to start a second daemon.");
+        process.exit(1);
+    }
+    const telegram = new TelegramService(apiId, apiHash);
+    // Owner core: socket server + IPC dispatch + auto-connect + SIGINT/SIGTERM graceful shutdown.
+    // No StdioServerTransport and no process.stdin handler — the daemon's lifetime is independent
+    // of any client. The listening socket keeps the event loop alive until a termination signal.
+    await startOwner(telegram, version, { label: "serve" });
+    console.error("[serve] daemon ready — owning the Telegram connection, no stdio attached");
+}

package/package.json

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