@overpod/mcp-telegram 1.38.1 → 1.38.2

package/CHANGELOG.md

@@ -5,6 +5,14 @@ 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.2](https://github.com/mcp-telegram/mcp-telegram/compare/v1.38.1...v1.38.2) (2026-06-19)
+
+
+### Documentation
+
+* backfill v1.27–v1.28 in CHANGELOG; bump Pages actions off Node 20 ([#56](https://github.com/mcp-telegram/mcp-telegram/issues/56)) ([7786819](https://github.com/mcp-telegram/mcp-telegram/commit/778681917a2bc133ea8821e2ff8739a3f859b257))
+* generate changelog pages from CHANGELOG.md + refresh README ([#54](https://github.com/mcp-telegram/mcp-telegram/issues/54)) ([4422901](https://github.com/mcp-telegram/mcp-telegram/commit/442290178c5bee43cc6828f794ce468930cbe945))
+
 ## [1.38.1](https://github.com/mcp-telegram/mcp-telegram/compare/v1.38.0...v1.38.1) (2026-06-10)
 
 
@@ -350,6 +358,63 @@ Tests: 490/490 pass.
 - **Album mixed photo+video** — GramJS accepts mixed arrays via extension-based detection, but this is not covered by tests; recommend uniform media type per album until a live-test checkpoint confirms.
 - **Album flood control** — a 10-item album fans out 10 `messages.UploadMedia` calls inside one rate-limit slot; under heavy contention the later items may still hit `FLOOD_WAIT`. Rate limiter retries apply.
 
+## [1.28.1] - 2026-04-22
+
+### Added
+- **`telegram-logout`** — new tool (Auth category, annotated `DESTRUCTIVE`). Fully logs out: calls `auth.LogOut` on Telegram servers (session disappears from Settings → Devices), destroys the GramJS client, deletes the local session file, and clears in-memory state. Takes no parameters. Handles every state cleanly — connected (server revoke + local wipe), disconnected with a session file (local wipe only, with a notice), no session (`fail` "Not logged in"), and `auth.LogOut` throwing (local wipe still happens, with a "check Settings → Devices manually" hint).
+
+### Changed
+- **`TelegramService.logOut()` hardened** — server-revoke and client-destroy are now split: a successful `auth.LogOut` returns `true` even if `client.destroy()` throws (previously misreported "not confirmed"). The local wipe is verified post-unlink and throws if the session file survives (e.g. read-only Docker mount), instead of falsely reporting success. File removal now always runs even when server-revoke fails (network error, `AUTH_KEY_UNREGISTERED`).
+- **Master cancels active QR login on logout** — a `telegram-logout` request now aborts an in-progress QR login flow before acquiring `globalLock`, instead of queuing behind it for up to 5 minutes.
+
+### Testing
+- 322 unit tests (+10 vs v1.28.0) — `hasLocalSession()`, `logOut()` edge cases (connected / disconnected±file / network error / idempotency / FS-throws / destroy-throws-but-revoke-succeeds), and a Master integration test that logout aborts an active login over a real unix socket.
+
+### Notes & known limitations
+- In a 3-client FIFO scenario (A holds the lock via login, B queues a tool call, C requests logout), logout correctly aborts A, but B still runs before logout because FIFO order is preserved. A priority-aware queue is deferred.
+
+## [1.28.0] - 2026-04-22
+
+### Added
+- **QR login through the IPC daemon** — `mcp-telegram login` now flows through the Master daemon over IPC instead of running as a separate process. The new session reaches the Master's memory immediately, with no editor restart. This fixes the "relogin via `mcp-telegram login`" flavor of `AUTH_KEY_DUPLICATED`/`AUTH_KEY_UNREGISTERED`, where the standalone login wrote a fresh session to disk but the running Master kept the old, now-invalidated auth key in memory and then wiped the just-created session on the next tool call.
+  - `IpcClient.loginFlow(onQr)` — streams QR frames as they refresh (~every 10s).
+  - `handleLoginStart` on Master — runs `startQrLogin` on the shared `TelegramService`.
+  - `GlobalLock` (FIFO mutex) — serializes tool calls with the login flow so other clients queue 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 instead of blocking tool calls for up to 5 minutes.
+  - Session swap now saves to disk first, then adopts in memory and destroys the previous client — prevents orphan Telegram connections accumulating per relogin.
+  - Standalone fallback kept — if no Master is running, `mcp-telegram login` works exactly as before.
+
+### Changed
+- **BREAKING (internal IPC only): IPC protocol is now a discriminated union** with a required `type` tag (`tool` / `tool_response` / `login_start` / `login_qr` / `login_done`). A new 1.28.0 client and an older 1.27.x Master cannot talk — restart your editor / Claude Code after upgrading so the Master daemon is replaced. No public API or invocation change. (Parent-crash detection already kills stale Masters in most cases, so this is transparent for VS Code / Claude Desktop users.)
+
+### Fixed
+- Socket errors on Master now log to stderr instead of being silently dropped.
+- `client.destroy()` in abort branches wrapped in try/catch — guarantees the "QR login aborted" message even if Telegram destroy throws.
+- QR render errors (`QRCode.toString` failure) logged to stderr instead of silently dropped.
+
+### Testing
+- 312 unit tests (was 288) — new suites for `GlobalLock` (FIFO ordering, double-release safety), Master login (QR URL forwarding, abort on socket close), child-process integration via tsx, `IpcClient.loginFlow`, and IPC discriminated-union / legacy-protocol rejection.
+
+## [1.27.1] - 2026-04-22
+
+### Changed
+- Patch release — no new tools, no API changes; pure code-quality and test-coverage work. Refactored `telegram-client.ts` re-exports (eliminates 2 Biome `noUnusedImports` false-positives), replaced unsafe `(e as Error).message` casts with `e instanceof Error` guards in the stats methods, and added `McpRegisteredTool` / `McpServerInternal` types to `ipc-protocol.ts` as a single source of truth (previously duplicated across master.ts and client.ts).
+
+### Testing
+- 286 unit tests (+25 vs v1.27.0) — new branch coverage for `wireIpcProxies` (incl. a safety test that the original `TelegramService` handler is never called after wiring), the rate limiter (`throwOnFloodWait`, retry exhaustion, 5xx, GramJS `errorMessage`), and the IPC protocol parser (malformed JSON, blank lines, partial-line buffering, multiple messages per chunk). `rate-limiter.ts` reached 100% statements.
+
+## [1.27.0] - 2026-04-21
+
+### Added
+- **Master/Client IPC daemon — fixes `AUTH_KEY_DUPLICATED` across concurrent Claude sessions.** Opening multiple Claude sessions used to spawn separate `mcp-telegram` processes that each connected to Telegram with the same session, which Telegram rejected as a duplicate. Now the first process to start becomes the **Master** (holds the single GramJS connection, listens on a Unix socket at `~/.mcp-telegram/daemon.sock`) and every subsequent process becomes a thin **Client** that proxies tool calls to the Master over the socket — one connection, one auth key, no duplicates. Zero config change; same invocation.
+  - New files: `src/lock.ts` (atomic `O_EXCL` PID lockfile + stale-lock detection via `kill -0`), `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).
+  - Security: socket file is `chmod 0o600` (owner-only); the session string never leaves the Master process.
+
+### Fixed
+- Atomic lock via `O_EXCL` prevents a race when multiple sessions start simultaneously; stale socket from a previous crash is removed before `listen` (no `EADDRINUSE`).
+- One-shot connect timeout (not idle) so live connections survive inactivity; 30s IPC call timeout so a stuck Master surfaces a clean error instead of hanging.
+- Sequential `drainQueue()` loop for correct concurrent-request handling; `.catch()` on auto-connect to avoid `unhandledRejection`; idempotent cleanup (`cleanedUp` flag) so SIGINT/SIGTERM don't double-release.
+
 ## [1.26.0] - 2026-04-20
 
 ### Added

package/README.md

@@ -4,7 +4,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/@overpod/mcp-telegram)](https://www.npmjs.com/package/@overpod/mcp-telegram)
 [![Node.js](https://img.shields.io/badge/Node.js-18%2B-339933.svg?logo=node.js&logoColor=white)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-6.0-blue.svg?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
-[![MCP SDK](https://img.shields.io/badge/MCP%20SDK-1.27-green.svg)](https://modelcontextprotocol.io/)
+[![MCP SDK](https://img.shields.io/badge/MCP%20SDK-1.29-green.svg)](https://modelcontextprotocol.io/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![mcp-telegram MCP server](https://glama.ai/mcp/servers/overpod/mcp-telegram/badges/score.svg)](https://glama.ai/mcp/servers/overpod/mcp-telegram)
 
@@ -18,13 +18,15 @@ An MCP (Model Context Protocol) server that connects AI assistants like Claude t
 
 ## Features
 
-- **Comprehensive tool coverage** -- the most full-featured Telegram MCP server available (80+ tools)
+- **Comprehensive tool coverage** -- the most full-featured Telegram MCP server available
 - **MTProto protocol** -- direct Telegram API access, not the limited Bot API
 - **Userbot** -- operates as your personal account, not a bot
 - **Full-featured** -- messaging, reactions, polls, scheduled messages, stickers, media, contacts, and more
 - **Forum Topics** -- list topics, read per-topic messages, send to specific topics, per-topic unread counts
 - **Stickers** -- search sticker sets, browse installed/recent stickers, send stickers to any chat
 - **Account & profile management** -- update profile, set emoji status, birthday, personal channel, profile photo, manage privacy settings, sessions, auto-delete timers
+- **Chat folders** -- create, edit, delete and reorder folders, toggle folder tags, read suggested folders (v1.33.0)
+- **Global privacy** -- read and set account-wide privacy settings (v1.33.0)
 - **Global search** -- search messages across all chats at once
 - **Real-time polling** -- fetch updates via stateless cursors; agent owns `{pts, qts, date}` state
 - **Inline bots & buttons** -- query inline bots, send results, press callback buttons
@@ -34,6 +36,8 @@ An MCP (Model Context Protocol) server that connects AI assistants like Claude t
 - **Admin controls** -- toggle channel signatures, anti-spam, forum mode, prehistory; approve join requests
 - **Stats** -- channel and supergroup analytics (GetBroadcastStats / GetMegagroupStats)
 - **Boosts & Business** -- boost status, boosters list, Telegram Business chat links CRUD, work hours, location, greeting/away/intro messages
+- **Star gifts** -- browse available and saved gifts, save/convert gifts, manage Stars balance and subscriptions (opt-in via `MCP_TELEGRAM_ENABLE_STARS=1`, v1.34.0)
+- **Shared daemon** -- one background process serves multiple MCP clients over a single Telegram session; see the [shared-daemon guide](https://mcp-telegram.github.io/mcp-telegram/guides/shared-daemon) (v1.38.0)
 - **QR code login** -- authenticate by scanning a QR code in the Telegram app
 - **Session persistence** -- login once, stay connected across restarts
 - **Human-readable output** -- sender names are resolved, not just numeric IDs
@@ -363,6 +367,8 @@ All tools are auto-discoverable via MCP — your AI client will see the full lis
 | **Rich Media Sending** | `telegram-send-voice`, `telegram-send-video-note` (round video), `telegram-send-location` (static or live), `telegram-send-venue`, `telegram-send-contact`, `telegram-send-dice` (🎲🎯🎰🏀⚽🎳), `telegram-send-album` (2–10 grouped photos/videos) |
 | **Groups** | `telegram-create-group`, `telegram-edit-group`, `telegram-invite-to-group`, `telegram-join-chat`, `telegram-leave-group`, `telegram-kick-user`, `telegram-ban-user`, `telegram-unban-user`, `telegram-set-admin`, `telegram-remove-admin`, `telegram-get-my-role`, `telegram-set-chat-permissions`, `telegram-set-slow-mode`, `telegram-get-admin-log` |
 | **Chat Info** | `telegram-get-chat-info`, `telegram-get-chat-members`, `telegram-get-chat-folders` |
+| **Folders (v1.33.0)** | `telegram-create-folder`, `telegram-edit-folder`, `telegram-delete-folder`, `telegram-reorder-folders`, `telegram-get-suggested-folders`, `telegram-toggle-folder-tags` |
+| **Global Privacy (v1.33.0)** | `telegram-get-global-privacy-settings`, `telegram-set-global-privacy-settings` |
 | **Invite Links** | `telegram-create-invite-link`, `telegram-get-invite-links`, `telegram-revoke-invite-link` |
 | **Contacts** | `telegram-get-contacts`, `telegram-add-contact`, `telegram-get-contact-requests` |
 | **Moderation** | `telegram-block-user`, `telegram-unblock-user`, `telegram-report-spam` |
@@ -381,7 +387,7 @@ All tools are auto-discoverable via MCP — your AI client will see the full lis
 | **Read Receipts (v1.30.0)** | `telegram-get-message-read-participants`, `telegram-get-outbox-read-date` |
 | **Boosts** | `telegram-get-my-boosts`, `telegram-get-boosts-status`, `telegram-get-boosts-list` |
 | **Business (v1.32.0)** | `telegram-get-business-chat-links`, `telegram-create-business-chat-link`, `telegram-edit-business-chat-link`, `telegram-delete-business-chat-link`, `telegram-resolve-business-chat-link`, `telegram-set-business-hours`, `telegram-set-business-location`, `telegram-set-business-greeting`, `telegram-set-business-away`, `telegram-set-business-intro` |
-| **Opt-in (env-gated)** | `telegram-get-group-call`, `telegram-get-group-call-participants` (requires `MCP_TELEGRAM_ENABLE_GROUP_CALLS=1`), `telegram-get-stars-status`, `telegram-get-stars-transactions` (requires `MCP_TELEGRAM_ENABLE_STARS=1`), `telegram-get-quick-replies`, `telegram-get-quick-reply-messages` (requires `MCP_TELEGRAM_ENABLE_QUICK_REPLIES=1`) |
+| **Opt-in (env-gated)** | `telegram-get-group-call`, `telegram-get-group-call-participants` (requires `MCP_TELEGRAM_ENABLE_GROUP_CALLS=1`); Stars & gifts `telegram-get-stars-status`, `telegram-get-stars-transactions`, `telegram-get-stars-topup-options`, `telegram-get-stars-subscriptions`, `telegram-change-stars-subscription`, `telegram-get-available-star-gifts`, `telegram-get-saved-star-gifts`, `telegram-save-star-gift`, `telegram-convert-star-gift` (requires `MCP_TELEGRAM_ENABLE_STARS=1`); `telegram-get-quick-replies`, `telegram-get-quick-reply-messages` (requires `MCP_TELEGRAM_ENABLE_QUICK_REPLIES=1`) |
 
 > **Tip**: Ask your AI assistant *"What Telegram tools are available?"* to get the full list with parameters and descriptions.
 
@@ -392,7 +398,7 @@ Some tools are disabled by default and must be opted in via environment variable
 | Variable | Value | Tools enabled |
 |----------|-------|---------------|
 | `MCP_TELEGRAM_ENABLE_GROUP_CALLS` | `1` | `telegram-get-group-call`, `telegram-get-group-call-participants` |
-| `MCP_TELEGRAM_ENABLE_STARS` | `1` | `telegram-get-stars-status`, `telegram-get-stars-transactions` |
+| `MCP_TELEGRAM_ENABLE_STARS` | `1` | Stars balance & transactions, top-up options, subscriptions, and Star Gifts (browse / save / convert) |
 | `MCP_TELEGRAM_ENABLE_QUICK_REPLIES` | `1` | `telegram-get-quick-replies`, `telegram-get-quick-reply-messages` |
 
 Add these to your `.env` file or MCP client config to enable them.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@overpod/mcp-telegram",
-  "version": "1.38.1",
+  "version": "1.38.2",
   "description": "MCP server for Telegram userbot — messages, media, reactions, polls & more. Built on GramJS/MTProto.",
   "type": "module",
   "main": "dist/index.js",
@@ -34,7 +34,11 @@
     "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'",
+    "gen:changelog": "tsx scripts/gen-changelog-docs.ts",
+    "gen:changelog:check": "tsx scripts/gen-changelog-docs.ts --check",
+    "predocs:dev": "npm run gen:changelog",
     "docs:dev": "vitepress dev docs",
+    "predocs:build": "npm run gen:changelog",
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs"
   },
@@ -68,12 +72,12 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.16",
-    "@types/node": "^25.9.2",
+    "@biomejs/biome": "^2.5.0",
+    "@types/node": "^25.9.3",
     "@types/qrcode": "^1.5.6",
     "c8": "^11.0.0",
     "tsx": "^4.22.4",
     "typescript": "^6.0.3",
-    "vitepress": "^1.6.4"
+    "vitepress": "^2.0.0-alpha.17"
   }
 }