overpod/mcp-telegram

What's new

AUTH_KEY_DUPLICATED — finally fixed

When you open multiple Claude sessions simultaneously, each spawned a separate mcp-telegram process connecting to Telegram with the same session → Telegram rejected the duplicate with AUTH_KEY_DUPLICATED.

v1.27.0 introduces a Master/Client IPC architecture that solves this permanently:

• The first process to start becomes Master — it holds the single GramJS connection and listens on a Unix socket at ~/.mcp-telegram/daemon.sock
• Every subsequent process becomes a Client — a thin IPC proxy that forwards all tool calls to the Master over the socket
• One GramJS connection, one auth key, no duplicates — ever

Zero config change

Same npx @overpod/mcp-telegram / binary invocation. Nothing to change in Claude Desktop or Claude Code settings.

How it works

Claude session 1 → mcp-telegram (Master)  ← GramJS + Unix socket server
Claude session 2 → mcp-telegram (Client)  → daemon.sock → Master
Claude session 3 → mcp-telegram (Client)  → daemon.sock → Master

Lock mechanism: atomic O_EXCL PID file at ~/.mcp-telegram/daemon.lock — prevents race conditions when multiple sessions start simultaneously. Stale locks (from crashes) are detected via kill -0 and cleaned up automatically.

Security: socket file is chmod 0o600 — only the owner can connect. Session string never leaves the Master process.

Resilience:

• Client retries connection 5× with exponential backoff (150ms → 2.4s) to handle Master startup lag
• Stale socket from previous crash is removed before Master attempts to listen
• IPC calls have a 30s timeout — Claude gets a clean error instead of hanging forever
• Master crash → Client exits cleanly with a clear message (no second Master)

New files

| File | Purpose |
|------|---------|
| src/lock.ts | Atomic PID lockfile + stale lock detection |
| src/ipc-protocol.ts | IPC message types + newline-delimited JSON parser |
| src/master.ts | Unix socket server, sequential queue dispatcher |
| src/client.ts | IpcClient with timeout + retry, handler proxy |

Changelog

• feat Master/Client IPC daemon — fixes AUTH_KEY_DUPLICATED across Claude sessions
• fix Atomic lock via O_EXCL flag — prevents race condition on simultaneous startup
• fix Stale socket cleanup before listen — no EADDRINUSE after crash
• fix One-shot connect timeout (not idle) — live connections survive inactivity
• fix Sequential drainQueue() loop — correct handling of concurrent IPC requests
• fix unhandledRejection on auto-connect failure — added .catch() chain
• fix Idempotent cleanup with cleanedUp flag — no double-release on SIGINT/SIGTERM
• fix 30s IPC call timeout — prevents hanging when Master is stuck