@overpod/mcp-telegram 1.19.0 → 1.21.0

package/CHANGELOG.md

@@ -0,0 +1,278 @@
+# Changelog
+
+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).
+
+## [Unreleased]
+
+## [1.21.0] - 2026-04-01
+
+### Added
+- `TelegramService.getClient()` — public accessor for the underlying GramJS `TelegramClient` instance, enabling event handlers like `NewMessage` for real-time listeners (#17)
+
+## [1.20.0] - 2026-03-31
+
+### Added
+- **Rate limiting & retry** — automatic FLOOD_WAIT handling, network error recovery with exponential backoff (`src/rate-limiter.ts`)
+- `send-message` now returns `messageId` in the response (`Message sent to @user [#12345]`), enabling send → edit workflows (closes #16)
+- Rate limiter unit tests (7 tests in `src/__tests__/rate-limiter.test.ts`)
+
+### Changed
+- `sendMessage()` return type changed from `void` to `Api.Message | Api.UpdateShortSentMessage | undefined`
+- Write methods (`sendMessage`, `sendFile`, `editMessage`, `deleteMessages`) are now rate-limited with automatic retry on transient errors
+
+## [1.19.0] - 2026-03-30
+
+### Added
+- Docker support for containerized deployment
+- Non-blocking startup behavior
+- Local QR code fallback for authentication
+- Automated test infrastructure with Node.js test runner
+- CI workflow to publish Docker images to GitHub Container Registry
+
+### Changed
+- Added pnpm-lock.yaml for better dependency management
+
+## [1.18.0] - 2026-03-28
+
+### Added
+- New `telegram-get-my-role` tool to check user's role in a chat
+- Role information in `telegram-get-chat-members` results
+
+## [1.17.0] - 2026-03-28
+
+### Added
+- Chat resolution by display name (not just ID or username)
+
+### Changed
+- Updated documentation to replace static tool list with auto-discovery note
+- Improved project structure documentation
+
+## [1.16.0] - 2026-03-28
+
+### Added
+- Group management tools: invite, kick, ban, edit, leave
+- Admin management capabilities
+
+## [1.15.0] - 2026-03-28
+
+### Added
+- `telegram-create-group` tool for creating new groups
+
+### Fixed
+- Documented `AUTH_KEY_DUPLICATED` error handling
+
+## [1.14.0] - 2026-03-28
+
+### Added
+- SOCKS5 proxy support for Telegram connections
+- MTProxy support for Telegram connections
+
+### Changed
+- Updated Biome to 2.4.9 with new config schema
+- Sorted imports for Biome compliance
+- Added proxy documentation to README
+
+## [1.13.0] - 2026-03-26
+
+### Changed
+- Refactored tools into modular files organized by category
+
+## [1.12.0] - 2026-03-26
+
+### Changed
+- Migrated to `registerTool()` API with tool annotations
+
+## [1.11.1] - 2026-03-25
+
+### Fixed
+- Sanitized unpaired UTF-16 surrogates in tool responses
+
+### Changed
+- Upgraded TypeScript to 6.0
+- Updated README with missing tools
+
+## [1.11.0] - 2026-03-23
+
+### Added
+- Full reactions support: read, send multiple reactions, get detailed info
+
+### Changed
+- Included message ID in all message-reading tool outputs
+
+## [1.10.1] - 2026-03-22
+
+### Fixed
+- Message ID now included in all message-reading tool outputs
+
+## [1.10.0] - 2026-03-20
+
+### Added
+- Enhanced `telegram-get-profile` with birthday, business, and premium data
+- New `telegram-get-profile-photo` tool
+- Global message search capability
+- Enriched chat search results
+
+## [1.9.0] - 2026-03-18
+
+### Added
+- Forum Topics support
+- Per-topic unread count for forum groups
+- Secure session storage with configurable path
+- Multiple accounts support
+
+### Fixed
+- Per-topic unread sum calculation for forum groups
+
+### Changed
+- Updated session path and security documentation
+- Upgraded GitHub Actions to v6
+- Replaced Node 20 with Node 24 in CI
+- Updated Biome to 2.4.7 and @types/node to 25.5.0
+
+## [1.8.1] - 2026-03-19
+
+### Fixed
+- Redirected console.log to stderr to prevent MCP JSON-RPC corruption
+
+### Changed
+- Updated dependencies (Biome 2.4.8)
+
+## [1.8.0] - 2026-03-18
+
+### Added
+- Secure session storage with configurable path via SESSION_PATH environment variable
+
+### Changed
+- Updated session path and security information in README
+
+## [1.7.0] - 2026-03-16
+
+### Added
+- CI workflow to publish to GitHub Packages alongside npm
+- Manual workflow dispatch trigger for publishing
+
+## [1.6.0] - 2026-03-16
+
+### Added
+- Contact request management
+- Block/unblock users
+- Report spam functionality
+- Add contact tool
+- ChatGPT to list of supported clients
+
+### Changed
+- Removed hardcoded tool counts from README and package.json
+- Updated Biome to 2.4.7 and @types/node to 25.5.0
+
+## [1.5.0] - 2026-03-16
+
+### Added
+- Reactions support
+- Scheduled messages
+- Polls creation and management
+- `telegram-join-chat` tool for joining groups and channels
+
+### Changed
+- Updated README with new tool documentation
+- Increased tool count to 24
+
+## [1.4.0] - 2026-03-15
+
+### Added
+- Glama.ai MCP catalog verification (glama.json)
+- Smithery MCP catalog listing (smithery.yaml)
+- Demo GIF and badges to README
+- Hosted version link
+
+### Fixed
+- Removed PNG file save from CLI QR login
+
+### Changed
+- Updated README with Glama MCP server badge
+
+## [1.3.1] - 2026-03-12
+
+### Fixed
+- Use `destroy()` instead of `disconnect()` to stop GramJS update loop
+- Adopt QR login client directly instead of destroy+reconnect flow
+- Destroy GramJS client in `logOut()` and `startQrLogin()` to stop update loop
+
+## [1.3.0] - 2026-03-12
+
+### Added
+- `logOut()` method for complete Telegram session termination
+
+## [1.2.0] - 2026-03-11
+
+### Added
+- `downloadMediaAsBuffer` for serverless media download
+- Library exports and declaration types
+- Date filters for messages
+- Comprehensive README for v1.0
+
+### Fixed
+- MIME type detection from magic bytes in `downloadMediaAsBuffer`
+- Made `saveSession` resilient to file write errors in Docker
+
+### Changed
+- Use `GetFullChannel`/`GetFullChat` for complete chat information
+- Improved `telegram-login` for Claude Desktop users
+- Added npm publishing support and GitHub Actions CI/CD
+
+## [1.1.0] - 2026-03-11
+
+### Added
+- Contact management tools
+- Chat members listing
+- User profile retrieval
+- Chat type filter
+- Media tools (send, download, get info)
+- Pin/unpin messages
+- Markdown support
+- Media information in messages
+- Unread counts
+- Mark messages as read
+- Forward messages
+- Edit messages
+- Delete messages
+- Detailed chat information
+- Pagination support
+
+## [1.0.0] - 2026-03-10
+
+### Added
+- Initial release: MCP server for Telegram userbot
+- Basic message reading and sending
+- Chat listing
+- Authentication via phone number and QR code
+- Session persistence
+- GramJS/MTProto integration
+
+[Unreleased]: https://github.com/overpod/mcp-telegram/compare/v1.19.0...HEAD
+[1.19.0]: https://github.com/overpod/mcp-telegram/compare/v1.18.0...v1.19.0
+[1.18.0]: https://github.com/overpod/mcp-telegram/compare/v1.17.0...v1.18.0
+[1.17.0]: https://github.com/overpod/mcp-telegram/compare/v1.16.0...v1.17.0
+[1.16.0]: https://github.com/overpod/mcp-telegram/compare/v1.15.0...v1.16.0
+[1.15.0]: https://github.com/overpod/mcp-telegram/compare/v1.14.0...v1.15.0
+[1.14.0]: https://github.com/overpod/mcp-telegram/compare/v1.13.0...v1.14.0
+[1.13.0]: https://github.com/overpod/mcp-telegram/compare/v1.12.0...v1.13.0
+[1.12.0]: https://github.com/overpod/mcp-telegram/compare/v1.11.1...v1.12.0
+[1.11.1]: https://github.com/overpod/mcp-telegram/compare/v1.11.0...v1.11.1
+[1.11.0]: https://github.com/overpod/mcp-telegram/compare/v1.10.1...v1.11.0
+[1.10.1]: https://github.com/overpod/mcp-telegram/compare/v1.10.0...v1.10.1
+[1.10.0]: https://github.com/overpod/mcp-telegram/compare/v1.9.0...v1.10.0
+[1.9.0]: https://github.com/overpod/mcp-telegram/compare/v1.8.1...v1.9.0
+[1.8.1]: https://github.com/overpod/mcp-telegram/compare/v1.8.0...v1.8.1
+[1.8.0]: https://github.com/overpod/mcp-telegram/compare/v1.7.0...v1.8.0
+[1.7.0]: https://github.com/overpod/mcp-telegram/compare/v1.6.0...v1.7.0
+[1.6.0]: https://github.com/overpod/mcp-telegram/compare/v1.5.0...v1.6.0
+[1.5.0]: https://github.com/overpod/mcp-telegram/compare/v1.4.0...v1.5.0
+[1.4.0]: https://github.com/overpod/mcp-telegram/compare/v1.3.1...v1.4.0
+[1.3.1]: https://github.com/overpod/mcp-telegram/compare/v1.3.0...v1.3.1
+[1.3.0]: https://github.com/overpod/mcp-telegram/compare/v1.2.0...v1.3.0
+[1.2.0]: https://github.com/overpod/mcp-telegram/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/overpod/mcp-telegram/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/overpod/mcp-telegram/releases/tag/v1.0.0

package/dist/__tests__/rate-limiter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/rate-limiter.test.js

@@ -0,0 +1,81 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { RateLimiter } from "../rate-limiter.js";
+describe("RateLimiter", () => {
+    it("should execute a function successfully", async () => {
+        const limiter = new RateLimiter({ maxRequestsPerSecond: 100 });
+        const result = await limiter.execute(async () => "success");
+        assert.strictEqual(result, "success");
+    });
+    it("should enforce rate limiting between requests", async () => {
+        const limiter = new RateLimiter({ maxRequestsPerSecond: 10 }); // 10 req/s = 100ms between requests
+        const start = Date.now();
+        await limiter.execute(async () => "first");
+        await limiter.execute(async () => "second");
+        const elapsed = Date.now() - start;
+        assert.ok(elapsed >= 90, `Expected at least 90ms, got ${elapsed}ms`);
+    });
+    it("should retry on FLOOD_WAIT error", async () => {
+        const limiter = new RateLimiter({ maxRetries: 2, maxRequestsPerSecond: 100 });
+        let attempts = 0;
+        const result = await limiter.execute(async () => {
+            attempts++;
+            if (attempts < 2) {
+                throw new Error("FLOOD_WAIT_1");
+            }
+            return "success after retry";
+        });
+        assert.strictEqual(result, "success after retry");
+        assert.strictEqual(attempts, 2);
+    });
+    it("should throw after max retries on FLOOD_WAIT", async () => {
+        const limiter = new RateLimiter({ maxRetries: 1, maxRequestsPerSecond: 100 });
+        await assert.rejects(async () => {
+            await limiter.execute(async () => {
+                throw new Error("FLOOD_WAIT_2");
+            });
+        }, {
+            message: /Rate limit exceeded after 1 retries/,
+        });
+    });
+    it("should retry on network errors with exponential backoff", async () => {
+        const limiter = new RateLimiter({
+            maxRetries: 2,
+            initialRetryDelay: 100,
+            maxRequestsPerSecond: 100,
+        });
+        let attempts = 0;
+        const result = await limiter.execute(async () => {
+            attempts++;
+            if (attempts < 2) {
+                throw new Error("TIMEOUT");
+            }
+            return "recovered";
+        });
+        assert.strictEqual(result, "recovered");
+        assert.strictEqual(attempts, 2);
+    });
+    it("should not retry on non-retryable errors", async () => {
+        const limiter = new RateLimiter({ maxRetries: 3, maxRequestsPerSecond: 100 });
+        let attempts = 0;
+        await assert.rejects(async () => {
+            await limiter.execute(async () => {
+                attempts++;
+                throw new Error("AUTH_KEY_UNREGISTERED");
+            });
+        }, {
+            message: "AUTH_KEY_UNREGISTERED",
+        });
+        assert.strictEqual(attempts, 1, "Should not retry non-retryable errors");
+    });
+    it("should handle FLOOD_WAIT with seconds parsing", async () => {
+        const limiter = new RateLimiter({ maxRetries: 1, maxRequestsPerSecond: 100 });
+        await assert.rejects(async () => {
+            await limiter.execute(async () => {
+                throw new Error("FLOOD_WAIT_1");
+            });
+        }, {
+            message: /Telegram requires 1s wait/,
+        });
+    });
+});

package/dist/index.js

@@ -14,7 +14,9 @@ import { registerTools } from "./tools/index.js";
 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] TELEGRAM_API_ID and TELEGRAM_API_HASH must be set");
+    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);
 }
 const telegram = new TelegramService(API_ID, API_HASH);

package/dist/rate-limiter.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Rate limiter and retry logic for Telegram API calls.
+ * Handles FLOOD_WAIT errors and implements exponential backoff.
+ */
+export interface RateLimiterOptions {
+    /** Maximum number of requests per second (default: 20) */
+    maxRequestsPerSecond?: number;
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Initial retry delay in milliseconds (default: 1000) */
+    initialRetryDelay?: number;
+    /** Maximum retry delay in milliseconds (default: 60000) */
+    maxRetryDelay?: number;
+}
+export declare class RateLimiter {
+    private lastRequestTime;
+    private minInterval;
+    private maxRetries;
+    private initialRetryDelay;
+    private maxRetryDelay;
+    constructor(options?: RateLimiterOptions);
+    /** Execute a function with rate limiting and automatic retry */
+    execute<T>(fn: () => Promise<T>, context?: string): Promise<T>;
+    private executeWithRetry;
+    private waitForSlot;
+}

package/dist/rate-limiter.js

@@ -0,0 +1,80 @@
+/**
+ * Rate limiter and retry logic for Telegram API calls.
+ * Handles FLOOD_WAIT errors and implements exponential backoff.
+ */
+export class RateLimiter {
+    lastRequestTime = 0;
+    minInterval;
+    maxRetries;
+    initialRetryDelay;
+    maxRetryDelay;
+    constructor(options = {}) {
+        const maxRequestsPerSecond = options.maxRequestsPerSecond ?? 20;
+        this.minInterval = 1000 / maxRequestsPerSecond;
+        this.maxRetries = options.maxRetries ?? 3;
+        this.initialRetryDelay = options.initialRetryDelay ?? 1000;
+        this.maxRetryDelay = options.maxRetryDelay ?? 60000;
+    }
+    /** Execute a function with rate limiting and automatic retry */
+    async execute(fn, context = "API call") {
+        return this.executeWithRetry(fn, context, 0);
+    }
+    async executeWithRetry(fn, context, attempt) {
+        await this.waitForSlot();
+        try {
+            return await fn();
+        }
+        catch (error) {
+            const errorMessage = error.errorMessage || error.message || String(error);
+            // FLOOD_WAIT — wait the exact time Telegram requires
+            const floodMatch = errorMessage.match(/FLOOD_WAIT[_]?(\d+)/i);
+            if (floodMatch) {
+                const waitSeconds = Number.parseInt(floodMatch[1], 10);
+                if (attempt >= this.maxRetries) {
+                    throw new Error(`Rate limit exceeded after ${this.maxRetries} retries. Telegram requires ${waitSeconds}s wait. Try again later.`);
+                }
+                console.error(`[rate-limiter] FLOOD_WAIT for ${context}. Waiting ${waitSeconds}s (attempt ${attempt + 1}/${this.maxRetries})`);
+                await sleep(waitSeconds * 1000);
+                return this.executeWithRetry(fn, context, attempt + 1);
+            }
+            // Network/timeout errors — exponential backoff
+            if (isNetworkError(errorMessage)) {
+                if (attempt >= this.maxRetries) {
+                    throw new Error(`Network error after ${this.maxRetries} retries: ${errorMessage}. Check your connection.`);
+                }
+                const delay = Math.min(this.initialRetryDelay * 2 ** attempt, this.maxRetryDelay);
+                console.error(`[rate-limiter] Network error for ${context}. Retrying in ${delay}ms (attempt ${attempt + 1}/${this.maxRetries})`);
+                await sleep(delay);
+                return this.executeWithRetry(fn, context, attempt + 1);
+            }
+            // Temporary server errors (5xx) — exponential backoff
+            if (isTemporaryError(errorMessage)) {
+                if (attempt >= this.maxRetries) {
+                    throw new Error(`Temporary error after ${this.maxRetries} retries: ${errorMessage}`);
+                }
+                const delay = Math.min(this.initialRetryDelay * 2 ** attempt, this.maxRetryDelay);
+                await sleep(delay);
+                return this.executeWithRetry(fn, context, attempt + 1);
+            }
+            // Non-retryable — throw immediately
+            throw error;
+        }
+    }
+    async waitForSlot() {
+        const now = Date.now();
+        const elapsed = now - this.lastRequestTime;
+        if (elapsed < this.minInterval) {
+            await sleep(this.minInterval - elapsed);
+        }
+        this.lastRequestTime = Date.now();
+    }
+}
+function isNetworkError(msg) {
+    return /TIMEOUT|ETIMEDOUT|ECONNREFUSED|ENETUNREACH|ENOTFOUND|EHOSTUNREACH|network|timed out/i.test(msg);
+}
+function isTemporaryError(msg) {
+    return /INTERNAL|^50[023]$|Internal Server Error|Service Unavailable|Bad Gateway/i.test(msg);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/telegram-client.d.ts

@@ -1,3 +1,5 @@
+import { TelegramClient } from "telegram";
+import { Api } from "telegram/tl/index.js";
 export declare class TelegramService {
     private client;
     private apiId;
@@ -5,8 +7,10 @@ export declare class TelegramService {
     private sessionString;
     private connected;
     private sessionPath;
+    private rateLimiter;
     lastError: string;
     get sessionDir(): string;
+    getClient(): TelegramClient | null;
     constructor(apiId: number, apiHash: string, options?: {
         sessionPath?: string;
     });
@@ -37,7 +41,7 @@ export declare class TelegramService {
         username?: string;
         firstName?: string;
     }>;
-    sendMessage(chatId: string, text: string, replyTo?: number, parseMode?: "md" | "html", topicId?: number): Promise<void>;
+    sendMessage(chatId: string, text: string, replyTo?: number, parseMode?: "md" | "html", topicId?: number): Promise<Api.Message | Api.UpdateShortSentMessage | undefined>;
     sendFile(chatId: string, filePath: string, caption?: string): Promise<void>;
     downloadMedia(chatId: string, messageId: number, downloadPath: string): Promise<string>;
     downloadMediaAsBuffer(chatId: string, messageId: number): Promise<{

package/dist/telegram-client.js

@@ -9,12 +9,14 @@ import { TelegramClient } from "telegram";
 import { CustomFile } from "telegram/client/uploads.js";
 import { StringSession } from "telegram/sessions/index.js";
 import { Api } from "telegram/tl/index.js";
+import { RateLimiter } from "./rate-limiter.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const LEGACY_SESSION_FILE = join(__dirname, "..", ".telegram-session");
 const DEFAULT_SESSION_DIR = join(homedir(), ".mcp-telegram");
 const DEFAULT_SESSION_FILE = join(DEFAULT_SESSION_DIR, "session");
 const SESSION_STRING_RE = /^[A-Za-z0-9+/=]+$/;
 const MIN_SESSION_LENGTH = 100;
+const NOT_CONNECTED_ERROR = "Not connected. Run telegram-status to check or telegram-login to authenticate.";
 function resolveSessionPath(sessionPath) {
     return sessionPath ?? process.env.TELEGRAM_SESSION_PATH ?? DEFAULT_SESSION_FILE;
 }
@@ -49,10 +51,14 @@ export class TelegramService {
     sessionString = "";
     connected = false;
     sessionPath;
+    rateLimiter = new RateLimiter();
     lastError = "";
     get sessionDir() {
         return dirname(this.sessionPath);
     }
+    getClient() {
+        return this.client;
+    }
     constructor(apiId, apiHash, options) {
         this.apiId = apiId;
         this.apiHash = apiHash;
@@ -136,7 +142,7 @@ export class TelegramService {
             // Auth revoked — delete invalid session
             if (msg === "AUTH_KEY_UNREGISTERED" || msg === "SESSION_REVOKED" || msg === "USER_DEACTIVATED") {
                 await this.clearSession();
-                this.lastError = "Session revoked. Re-login required.";
+                this.lastError = "Session revoked. Run telegram-login to re-authenticate.";
             }
             // Network error — keep session, just report
             else if (msg.includes("TIMEOUT") ||
@@ -144,7 +150,7 @@ export class TelegramService {
                 msg.includes("ENETUNREACH") ||
                 msg.includes("ENOTFOUND") ||
                 msg.includes("network")) {
-                this.lastError = `Network error: ${msg}. Session preserved, will retry on next call.`;
+                this.lastError = `Network error: ${msg}. Run telegram-status to retry connection.`;
             }
             // Unknown error
             else {
@@ -290,7 +296,7 @@ export class TelegramService {
     }
     async getMe() {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const me = await this.client.getMe();
         const user = me;
         return {
@@ -301,38 +307,47 @@ export class TelegramService {
     }
     async sendMessage(chatId, text, replyTo, parseMode, topicId) {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
-        const resolved = await this.resolvePeer(chatId);
-        if (topicId) {
-            // Forum topics require raw API call with InputReplyToMessage
-            const peer = await this.client.getInputEntity(resolved);
-            await this.client.invoke(new Api.messages.SendMessage({
-                peer,
-                message: text,
-                randomId: bigInt(Math.floor(Math.random() * 1e15)),
-                replyTo: new Api.InputReplyToMessage({
-                    replyToMsgId: replyTo ?? topicId,
-                    topMsgId: topicId,
-                }),
-            }));
-        }
-        else {
-            await this.client.sendMessage(resolved, {
+            throw new Error(NOT_CONNECTED_ERROR);
+        return this.rateLimiter.execute(async () => {
+            const resolved = await this.resolvePeer(chatId);
+            if (topicId) {
+                const peer = await this.client?.getInputEntity(resolved);
+                const result = await this.client?.invoke(new Api.messages.SendMessage({
+                    peer,
+                    message: text,
+                    randomId: bigInt(Math.floor(Math.random() * 1e15)),
+                    replyTo: new Api.InputReplyToMessage({
+                        replyToMsgId: replyTo ?? topicId,
+                        topMsgId: topicId,
+                    }),
+                }));
+                if (result instanceof Api.UpdateShortSentMessage)
+                    return result;
+                if (result instanceof Api.Updates || result instanceof Api.UpdatesCombined) {
+                    const msgUpdate = result.updates.find((u) => u instanceof Api.UpdateNewMessage);
+                    if (msgUpdate?.message instanceof Api.Message)
+                        return msgUpdate.message;
+                }
+                return undefined;
+            }
+            return await this.client?.sendMessage(resolved, {
                 message: text,
                 ...(replyTo ? { replyTo } : {}),
                 ...(parseMode ? { parseMode: parseMode === "html" ? "html" : "md" } : {}),
             });
-        }
+        }, `sendMessage to ${chatId}`);
     }
     async sendFile(chatId, filePath, caption) {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
-        const resolved = await this.resolvePeer(chatId);
-        await this.client.sendFile(resolved, { file: filePath, caption });
+            throw new Error(NOT_CONNECTED_ERROR);
+        await this.rateLimiter.execute(async () => {
+            const resolved = await this.resolvePeer(chatId);
+            await this.client?.sendFile(resolved, { file: filePath, caption });
+        }, `sendFile to ${chatId}`);
     }
     async downloadMedia(chatId, messageId, downloadPath) {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const resolved = await this.resolvePeer(chatId);
         const messages = await this.client.getMessages(resolved, { ids: [messageId] });
         const message = messages[0];
@@ -348,7 +363,7 @@ export class TelegramService {
     }
     async downloadMediaAsBuffer(chatId, messageId) {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const resolved = await this.resolvePeer(chatId);
         const messages = await this.client.getMessages(resolved, { ids: [messageId] });
         const message = messages[0];
@@ -384,19 +399,19 @@ export class TelegramService {
     }
     async pinMessage(chatId, messageId, silent = false) {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const resolved = await this.resolvePeer(chatId);
         await this.client.pinMessage(resolved, messageId, { notify: !silent });
     }
     async unpinMessage(chatId, messageId) {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const resolved = await this.resolvePeer(chatId);
         await this.client.unpinMessage(resolved, messageId);
     }
     async getDialogs(limit = 20, offsetDate, filterType) {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const fetchLimit = filterType ? limit * 3 : limit;
         const dialogs = await this.client.getDialogs({ limit: fetchLimit, ...(offsetDate ? { offsetDate } : {}) });
         const mapped = dialogs.map((d) => {
@@ -419,7 +434,7 @@ export class TelegramService {
     }
     async getUnreadDialogs(limit = 20) {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const dialogs = await this.client.getDialogs({ limit: limit * 3 });
         const unread = dialogs.filter((d) => d.unreadCount > 0).slice(0, limit);
         const results = await Promise.all(unread.map(async (d) => {
@@ -460,7 +475,7 @@ export class TelegramService {
     }
     async getContactRequests(limit = 20) {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const dialogs = await this.client.getDialogs({ limit: limit * 5 });
         return dialogs
             .filter((d) => {
@@ -485,7 +500,7 @@ export class TelegramService {
     }
     async addContact(userId, firstName, lastName, phone) {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const entity = await this.client.getInputEntity(userId);
         await this.client.invoke(new Api.contacts.AddContact({
             id: entity,
@@ -496,39 +511,43 @@ export class TelegramService {
     }
     async blockUser(userId) {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const entity = await this.client.getInputEntity(userId);
         await this.client.invoke(new Api.contacts.Block({ id: entity }));
     }
     async reportSpam(chatId) {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const peer = await this.client.getInputEntity(chatId);
         await this.client.invoke(new Api.messages.ReportSpam({ peer }));
     }
     async markAsRead(chatId) {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         await this.client.markAsRead(chatId);
     }
     async forwardMessage(fromChatId, toChatId, messageIds) {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const resolvedFrom = await this.resolvePeer(fromChatId);
         const resolvedTo = await this.resolvePeer(toChatId);
         await this.client.forwardMessages(resolvedTo, { messages: messageIds, fromPeer: resolvedFrom });
     }
     async editMessage(chatId, messageId, newText) {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
-        const resolved = await this.resolvePeer(chatId);
-        await this.client.editMessage(resolved, { message: messageId, text: newText });
+            throw new Error(NOT_CONNECTED_ERROR);
+        await this.rateLimiter.execute(async () => {
+            const resolved = await this.resolvePeer(chatId);
+            await this.client?.editMessage(resolved, { message: messageId, text: newText });
+        }, `editMessage ${messageId} in ${chatId}`);
     }
     async deleteMessages(chatId, messageIds) {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
-        const resolved = await this.resolvePeer(chatId);
-        await this.client.deleteMessages(resolved, messageIds, { revoke: true });
+            throw new Error(NOT_CONNECTED_ERROR);
+        await this.rateLimiter.execute(async () => {
+            const resolved = await this.resolvePeer(chatId);
+            await this.client?.deleteMessages(resolved, messageIds, { revoke: true });
+        }, `deleteMessages in ${chatId}`);
     }
     /**
      * Resolve a chat by ID, username, or display name.
@@ -537,7 +556,7 @@ export class TelegramService {
     // biome-ignore lint: GramJS has no proper entity union type
     async resolveChat(chatId) {
         if (!this.client)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         // First try direct resolve (numeric ID, username, phone)
         try {
             return await this.client.getEntity(chatId);
@@ -576,7 +595,7 @@ export class TelegramService {
     }
     async getChatInfo(chatId) {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const entity = await this.resolveChat(chatId);
         if (entity instanceof Api.User) {
             const parts = [entity.firstName, entity.lastName].filter(Boolean);
@@ -684,7 +703,7 @@ export class TelegramService {
     }
     async getMessages(chatId, limit = 10, offsetId, minDate, maxDate) {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const resolved = await this.resolvePeer(chatId);
         const opts = {
             limit,
@@ -708,7 +727,7 @@ export class TelegramService {
     }
     async searchChats(query, limit = 10) {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const result = await this.client.invoke(new Api.contacts.Search({ q: query, limit }));
         const chats = [];
         for (const user of result.users) {
@@ -769,7 +788,7 @@ export class TelegramService {
     }
     async searchGlobal(query, limit = 20, minDate, maxDate) {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const result = await this.client.invoke(new Api.messages.SearchGlobal({
             q: query,
             filter: new Api.InputMessagesFilterEmpty(),
@@ -838,7 +857,7 @@ export class TelegramService {
     }
     async searchMessages(chatId, query, limit = 20, minDate, maxDate) {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const resolved = await this.resolvePeer(chatId);
         const messages = await this.client.getMessages(resolved, {
             search: query,
@@ -861,7 +880,7 @@ export class TelegramService {
     }
     async getContacts(limit = 50) {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const result = await this.client.invoke(new Api.contacts.GetContacts({ hash: bigInt(0) }));
         if (!(result instanceof Api.contacts.Contacts))
             return [];
@@ -881,7 +900,7 @@ export class TelegramService {
     }
     async getChatMembers(chatId, limit = 50) {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const entity = await this.resolveChat(chatId);
         if (entity instanceof Api.Channel) {
             const result = await this.client.invoke(new Api.channels.GetParticipants({
@@ -926,7 +945,7 @@ export class TelegramService {
     }
     async getMyRole(chatId) {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const entity = await this.resolveChat(chatId);
         const me = await this.getMe();
         if (entity instanceof Api.Channel) {
@@ -978,7 +997,7 @@ export class TelegramService {
     }
     async getProfile(userId) {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const entity = await this.client.getEntity(userId);
         if (!(entity instanceof Api.User))
             throw new Error("Entity is not a user");
@@ -1038,7 +1057,7 @@ export class TelegramService {
     }
     async downloadProfilePhoto(entityId, options) {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const entity = await this.client.getEntity(entityId);
         const buffer = (await this.client.downloadProfilePhoto(entity, {
             isBig: options?.isBig !== false,
@@ -1089,7 +1108,7 @@ export class TelegramService {
     }
     async sendReaction(chatId, messageId, emoji, addToExisting = false) {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const resolved = await this.resolvePeer(chatId);
         const peer = await this.client.getInputEntity(resolved);
         const reactionList = [];
@@ -1129,7 +1148,7 @@ export class TelegramService {
     }
     async getMessageReactions(chatId, messageId) {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const resolved = await this.resolvePeer(chatId);
         const peer = await this.client.getInputEntity(resolved);
         // First get the message to know which reactions exist
@@ -1184,7 +1203,7 @@ export class TelegramService {
     }
     async sendScheduledMessage(chatId, text, scheduleDate, replyTo, parseMode) {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const resolved = await this.resolvePeer(chatId);
         await this.client.sendMessage(resolved, {
             message: text,
@@ -1195,7 +1214,7 @@ export class TelegramService {
     }
     async createPoll(chatId, question, answers, options) {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const peer = await this.client.getInputEntity(chatId);
         const pollAnswers = answers.map((text, i) => new Api.PollAnswer({
             text: new Api.TextWithEntities({ text, entities: [] }),
@@ -1231,7 +1250,7 @@ export class TelegramService {
     }
     async getForumTopics(chatId, limit = 100) {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const entity = await this.resolveChat(chatId);
         if (!(entity instanceof Api.Channel))
             throw new Error("Forum topics are only available in supergroups");
@@ -1260,7 +1279,7 @@ export class TelegramService {
     }
     async getTopicMessages(chatId, topicId, limit = 20, offsetId) {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const peer = await this.client.getInputEntity(chatId);
         const result = await this.client.invoke(new Api.messages.GetReplies({
             peer,
@@ -1289,7 +1308,7 @@ export class TelegramService {
     /** Check if a chat entity is a forum (has topics enabled) */
     async isForum(chatId) {
         if (!this.client || !this.connected)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         try {
             const entity = await this.resolveChat(chatId);
             if (entity instanceof Api.Channel) {
@@ -1301,7 +1320,7 @@ export class TelegramService {
     }
     async joinChat(target) {
         if (!this.client)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         // Extract invite hash from various link formats
         const inviteMatch = target.match(/(?:t\.me\/\+|t\.me\/joinchat\/|tg:\/\/join\?invite=)([a-zA-Z0-9_-]+)/);
         if (inviteMatch) {
@@ -1332,7 +1351,7 @@ export class TelegramService {
     }
     async createGroup(options) {
         if (!this.client)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const { title, users, supergroup = false, forum = false, description } = options;
         if (supergroup || forum) {
             // Create supergroup/channel via channels.CreateChannel
@@ -1406,7 +1425,7 @@ export class TelegramService {
     }
     async inviteToGroup(chatId, users) {
         if (!this.client)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const entity = await this.resolveChat(chatId);
         const invited = [];
         const failed = [];
@@ -1434,7 +1453,7 @@ export class TelegramService {
     }
     async kickUser(chatId, userId) {
         if (!this.client)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const entity = await this.resolveChat(chatId);
         const user = await this.client.getEntity(userId);
         if (!(user instanceof Api.User))
@@ -1459,7 +1478,7 @@ export class TelegramService {
     }
     async banUser(chatId, userId) {
         if (!this.client)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const entity = await this.resolveChat(chatId);
         const user = await this.client.getEntity(userId);
         if (!(user instanceof Api.User))
@@ -1475,7 +1494,7 @@ export class TelegramService {
     }
     async unbanUser(chatId, userId) {
         if (!this.client)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const entity = await this.resolveChat(chatId);
         const user = await this.client.getEntity(userId);
         if (!(user instanceof Api.User))
@@ -1491,7 +1510,7 @@ export class TelegramService {
     }
     async editGroup(chatId, options) {
         if (!this.client)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const entity = await this.resolveChat(chatId);
         if (options.title) {
             if (entity instanceof Api.Channel) {
@@ -1521,7 +1540,7 @@ export class TelegramService {
     }
     async leaveGroup(chatId) {
         if (!this.client)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const entity = await this.resolveChat(chatId);
         if (entity instanceof Api.Channel) {
             await this.client.invoke(new Api.channels.LeaveChannel({ channel: entity }));
@@ -1538,7 +1557,7 @@ export class TelegramService {
     }
     async setAdmin(chatId, userId, options) {
         if (!this.client)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const entity = await this.resolveChat(chatId);
         if (!(entity instanceof Api.Channel))
             throw new Error("Set admin is only supported for supergroups and channels");
@@ -1564,7 +1583,7 @@ export class TelegramService {
     }
     async removeAdmin(chatId, userId) {
         if (!this.client)
-            throw new Error("Not connected");
+            throw new Error(NOT_CONNECTED_ERROR);
         const entity = await this.resolveChat(chatId);
         if (!(entity instanceof Api.Channel))
             throw new Error("Remove admin is only supported for supergroups and channels");

package/dist/tools/messages.js

@@ -16,9 +16,11 @@ export function registerMessageTools(server, telegram) {
         if (err)
             return fail(new Error(err));
         try {
-            await telegram.sendMessage(chatId, text, replyTo, parseMode, topicId);
+            const result = await telegram.sendMessage(chatId, text, replyTo, parseMode, topicId);
             const dest = topicId ? `topic ${topicId} in ${chatId}` : chatId;
-            return ok(`Message sent to ${dest}`);
+            const messageId = result?.id;
+            const idInfo = messageId ? ` [#${messageId}]` : "";
+            return ok(`Message sent to ${dest}${idInfo}`);
         }
         catch (e) {
             return fail(e);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@overpod/mcp-telegram",
-  "version": "1.19.0",
+  "version": "1.21.0",
   "description": "MCP server for Telegram userbot — messages, media, reactions, polls & more. Built on GramJS/MTProto.",
   "type": "module",
   "main": "dist/index.js",
@@ -14,7 +14,8 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "dev": "tsx watch src/index.ts",