overpod/mcp-telegram

QR login through the IPC daemon — the final AUTH_KEY_DUPLICATED fix

v1.27.0 fixed the "multiple Claude sessions" flavor of AUTH_KEY_DUPLICATED via Master/Client IPC.

v1.28.0 fixes the "relogin via mcp-telegram login" flavor that was still broken:

What was wrong

mcp-telegram login ran as a separate GramJS process:

1. Connected to Telegram with a fresh session, wrote it to ~/.mcp-telegram/session*
2. Exited
3. But the Master daemon kept its old auth_key in memory — it doesn't re-read the session file
4. Next tool call → Master contacts Telegram with the invalidated old auth_key → AUTH_KEY_UNREGISTERED
5. Master's error handler wipes the session file → the just-logged-in session is lost, user must login yet again

What v1.28.0 does

QR login now flows through Master over IPC:

┌─ qr-login-cli ─┐           daemon.sock          ┌─ master ─┐
│                │  ──login_start──────────►       │ single   │
│  terminal UI   │  ◄────login_qr (refresh)──      │ GramJS   │
│  Ctrl+C safe   │  ◄────login_done (success)──    │ + session│
└────────────────┘                                  └──────────┘
                                                        │
                                             AbortController on
                                             active flow — socket
                                             close aborts cleanly

• IpcClient.loginFlow(onQr) — new client method; streams QR frames as they refresh (~every 10s)
• handleLoginStart on master — runs startQrLogin on the shared TelegramService. New session reaches master's memory immediately, no restart
• GlobalLock (FIFO mutex) — serializes tool calls with login flow. Tool calls from other clients queue behind login instead of hitting a stale client mid-relogin
• AbortController — socket.on("close") aborts the QR loop if the CLI is interrupted (Ctrl+C / terminal closed). globalLock releases immediately. Previously this would have blocked all tool calls for up to 5 minutes.
• Session swap ordering — startQrLogin now saves to disk first, then adopts in memory, and destroys the previous in-memory client. Prevents orphan Telegram connections accumulating per relogin.
• Standalone fallback kept — if no master is running, mcp-telegram login works exactly like before

Breaking change: IPC protocol

The IPC protocol is now a discriminated union with a required type tag:

type IpcMessage =
  | { type: "tool",          id, tool, args }
  | { type: "tool_response", id, result?, error? }
  | { type: "login_start",   id }
  | { type: "login_qr",      id, url }
  | { type: "login_done",    id, success, username?, error? }

What this means for you: if you upgrade mcp-telegram to 1.28.0 while an older master (1.27.x) is still running, the new client and old master cannot talk. Restart your editor / Claude Code after upgrading so the master daemon is replaced.

Parent-crash detection (stdin.end → exit) already kills stale masters in most cases, so for VS Code / Claude Desktop users this is essentially transparent.

Reliability improvements

• Socket errors on master now log to stderr (previously silently dropped — bad for debugging)
• client.destroy() in abort branches wrapped in try/catch — guarantees the correct "QR login aborted" error message even if Telegram destroy throws
• QR render errors (QRCode.toString failure) logged to stderr instead of silent drop
• handleLoginStart refactored for readability — 39 → 31 lines, single fail() helper

Tests

312/312 passing (was 288). New:

| File | Tests | Coverage |
|------|-------|----------|
| global-lock.test.ts | 6 | FIFO ordering, double-release safety, waitingCount |
| master-login.test.ts | 5 | QR URL forwarding, abort on socket close, globalLock released after abort |
| runclient-integration.test.ts | 2 | Child-process integration via tsx (not gitignored dist/) |
| ipc-client.test.ts (loginFlow suite) | 5 | success/failure/timeout/close/not-connected |
| ipc-protocol new discriminator branches | +3 | Type-tag validation, legacy protocol rejection |

Files changed

src/ipc-protocol.ts      (discriminated union, type-tag validation)
src/global-lock.ts       (NEW — FIFO mutex)
src/master.ts            (+handleLoginStart, AbortController, stdin.end→exit)
src/client.ts            (+loginFlow, message routing, setOnDisconnect)
src/qr-login-cli.ts      (IPC-first path, standalone fallback)
src/telegram-client.ts   (AbortSignal in startQrLogin, save-before-adopt, destroy old client)

Migration

npm update @overpod/mcp-telegram
# restart Claude Code / Claude Desktop / your MCP host

No config changes. Same invocation. Same binaries.

🤖 Generated with Claude Code