@overpod/mcp-telegram 1.17.0 → 1.19.0

package/README.md

@@ -138,6 +138,34 @@ cd mcp-telegram
 npm install && npm run build
 ```
 
+### Docker
+
+```bash
+docker build -t mcp-telegram https://github.com/overpod/mcp-telegram.git
+```
+
+Login (interactive terminal required):
+
+```bash
+docker run -it --rm \
+  -e TELEGRAM_API_ID=YOUR_ID \
+  -e TELEGRAM_API_HASH=YOUR_HASH \
+  -v ~/.mcp-telegram:/root/.mcp-telegram \
+  --entrypoint node mcp-telegram dist/qr-login-cli.js
+```
+
+Run the MCP server:
+
+```bash
+docker run -i --rm \
+  -e TELEGRAM_API_ID=YOUR_ID \
+  -e TELEGRAM_API_HASH=YOUR_HASH \
+  -v ~/.mcp-telegram:/root/.mcp-telegram \
+  mcp-telegram
+```
+
+> **Note**: Login must be done once via terminal. After that, the session is persisted in `~/.mcp-telegram` and reused automatically.
+
 ## Usage with MCP Clients
 
 ### Claude Code (CLI)
@@ -174,12 +202,37 @@ claude mcp add telegram -s user \
 
 3. Restart Claude Desktop.
 
-4. Ask Claude: **"Run telegram-login"** -- a QR code will appear. If the image is not visible, Claude will provide a browser link to view the QR code. Scan it in Telegram (**Settings > Devices > Link Desktop Device**).
+4. Ask Claude: **"Run telegram-login"** -- a QR code will appear. If the image is not visible, it's also saved to `~/.mcp-telegram/qr-login.png`. Scan it in Telegram (**Settings > Devices > Link Desktop Device**).
 
 5. Ask Claude: **"Run telegram-status"** to verify the connection.
 
 > **Note**: No terminal required! Login works entirely through Claude Desktop.
 
+### Claude Desktop (Docker)
+
+1. Login via terminal first (see [Docker](#docker) section above).
+
+2. Add to your config file:
+
+```json
+{
+  "mcpServers": {
+    "telegram": {
+      "command": "docker",
+      "args": [
+        "run", "-i", "--rm",
+        "-e", "TELEGRAM_API_ID=YOUR_ID",
+        "-e", "TELEGRAM_API_HASH=YOUR_HASH",
+        "-v", "~/.mcp-telegram:/root/.mcp-telegram",
+        "mcp-telegram"
+      ]
+    }
+  }
+}
+```
+
+3. Restart Claude Desktop. Ask Claude: **"Run telegram-status"** to verify.
+
 ### Cursor / VS Code
 
 Add the same JSON config above to your MCP settings (Cursor Settings > MCP, or VS Code MCP config).
@@ -276,6 +329,8 @@ Then set `TELEGRAM_SESSION_PATH` in each environment's MCP config accordingly.
 - Session is stored in `~/.mcp-telegram/session` with `0600` permissions (owner-only access)
 - Session directory is created with `0700` permissions
 - Phone number is **not required** -- QR-only authentication
+- No data is sent to third-party services -- all communication goes directly to Telegram servers via MTProto
+- QR login codes are generated locally and never leave your machine
 - **One session per process** -- using the same session in multiple processes simultaneously causes `AUTH_KEY_DUPLICATED` errors (see [Troubleshooting](#troubleshooting))
 - This is a **userbot** (personal account), not a bot -- respect the [Telegram Terms of Service](https://core.telegram.org/api/terms)
 

package/dist/__tests__/tools/shared.test.d.ts

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

package/dist/__tests__/tools/shared.test.js

@@ -0,0 +1,110 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { DESTRUCTIVE, fail, formatReactions, ok, READ_ONLY, sanitize, WRITE } from "../../tools/shared.js";
+describe("shared utilities", () => {
+    describe("ok()", () => {
+        it("should return success response with text content", () => {
+            const result = ok("Operation successful");
+            assert.deepStrictEqual(result, {
+                content: [{ type: "text", text: "Operation successful" }],
+            });
+        });
+        it("should handle empty string", () => {
+            const result = ok("");
+            assert.deepStrictEqual(result, {
+                content: [{ type: "text", text: "" }],
+            });
+        });
+    });
+    describe("fail()", () => {
+        it("should return error response with isError flag", () => {
+            const error = new Error("Something went wrong");
+            const result = fail(error);
+            assert.deepStrictEqual(result, {
+                content: [{ type: "text", text: "Error: Something went wrong" }],
+                isError: true,
+            });
+        });
+        it("should handle non-Error objects", () => {
+            const result = fail({ message: "Custom error" });
+            assert.ok(result.content[0].text.includes("Error:"));
+            assert.strictEqual(result.isError, true);
+        });
+    });
+    describe("sanitize()", () => {
+        it("should remove unpaired high surrogates", () => {
+            const input = "Hello\uD800World";
+            const result = sanitize(input);
+            assert.strictEqual(result, "Hello\uFFFDWorld");
+        });
+        it("should remove unpaired low surrogates", () => {
+            const input = "Hello\uDC00World";
+            const result = sanitize(input);
+            assert.strictEqual(result, "Hello\uFFFDWorld");
+        });
+        it("should preserve valid surrogate pairs", () => {
+            const input = "Hello\uD83D\uDE00World"; // 😀 emoji
+            const result = sanitize(input);
+            assert.strictEqual(result, "Hello\uD83D\uDE00World");
+        });
+        it("should handle normal text without surrogates", () => {
+            const input = "Hello World";
+            const result = sanitize(input);
+            assert.strictEqual(result, "Hello World");
+        });
+        it("should handle empty string", () => {
+            const result = sanitize("");
+            assert.strictEqual(result, "");
+        });
+    });
+    describe("formatReactions()", () => {
+        it("should format reactions with counts", () => {
+            const reactions = [
+                { emoji: "👍", count: 5, me: false },
+                { emoji: "❤️", count: 3, me: true },
+                { emoji: "🔥", count: 1, me: false },
+            ];
+            const result = formatReactions(reactions);
+            assert.strictEqual(result, " [👍×5 ❤️×3(me) 🔥×1]");
+        });
+        it("should mark reactions from current user", () => {
+            const reactions = [{ emoji: "👍", count: 2, me: true }];
+            const result = formatReactions(reactions);
+            assert.strictEqual(result, " [👍×2(me)]");
+        });
+        it("should return empty string for undefined reactions", () => {
+            const result = formatReactions(undefined);
+            assert.strictEqual(result, "");
+        });
+        it("should return empty string for empty reactions array", () => {
+            const result = formatReactions([]);
+            assert.strictEqual(result, "");
+        });
+        it("should handle single reaction", () => {
+            const reactions = [{ emoji: "🎉", count: 1, me: false }];
+            const result = formatReactions(reactions);
+            assert.strictEqual(result, " [🎉×1]");
+        });
+    });
+    describe("MCP tool annotations", () => {
+        it("should define READ_ONLY preset", () => {
+            assert.deepStrictEqual(READ_ONLY, {
+                readOnlyHint: true,
+                openWorldHint: true,
+            });
+        });
+        it("should define WRITE preset", () => {
+            assert.deepStrictEqual(WRITE, {
+                readOnlyHint: false,
+                openWorldHint: true,
+            });
+        });
+        it("should define DESTRUCTIVE preset", () => {
+            assert.deepStrictEqual(DESTRUCTIVE, {
+                readOnlyHint: false,
+                destructiveHint: true,
+                openWorldHint: true,
+            });
+        });
+    });
+});

package/dist/index.js

@@ -24,18 +24,19 @@ const server = new McpServer({
 });
 registerTools(server, telegram);
 async function main() {
-    // Try to auto-connect with saved session
-    await telegram.loadSession();
-    if (await telegram.connect()) {
-        const me = await telegram.getMe();
-        console.error(`[mcp-telegram] Auto-connected as @${me.username}`);
-    }
-    else if (telegram.lastError) {
-        console.error(`[mcp-telegram] ${telegram.lastError}`);
-    }
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error("[mcp-telegram] MCP server running on stdio");
+    // Auto-connect with saved session after MCP is ready (non-blocking)
+    telegram.loadSession().then(async () => {
+        if (await telegram.connect()) {
+            const me = await telegram.getMe();
+            console.error(`[mcp-telegram] Auto-connected as @${me.username}`);
+        }
+        else if (telegram.lastError) {
+            console.error(`[mcp-telegram] ${telegram.lastError}`);
+        }
+    });
 }
 main().catch((err) => {
     console.error("[mcp-telegram] Fatal:", err);

package/dist/telegram-client.d.ts

@@ -6,6 +6,7 @@ export declare class TelegramService {
     private connected;
     private sessionPath;
     lastError: string;
+    get sessionDir(): string;
     constructor(apiId: number, apiHash: string, options?: {
         sessionPath?: string;
     });
@@ -182,7 +183,15 @@ export declare class TelegramService {
         id: string;
         name: string;
         username?: string;
+        role: string;
     }>>;
+    getMyRole(chatId: string): Promise<{
+        role: string;
+        chatId: string;
+        chatName: string;
+    }>;
+    private getParticipantUserId;
+    private getParticipantRole;
     getProfile(userId: string): Promise<{
         id: string;
         name: string;

package/dist/telegram-client.js

@@ -50,6 +50,9 @@ export class TelegramService {
     connected = false;
     sessionPath;
     lastError = "";
+    get sessionDir() {
+        return dirname(this.sessionPath);
+    }
     constructor(apiId, apiHash, options) {
         this.apiId = apiId;
         this.apiHash = apiHash;
@@ -879,19 +882,99 @@ export class TelegramService {
     async getChatMembers(chatId, limit = 50) {
         if (!this.client || !this.connected)
             throw new Error("Not connected");
-        const participants = await this.client.getParticipants(chatId, { limit });
-        const members = [];
-        for (const p of participants) {
-            if (p instanceof Api.User) {
-                const parts = [p.firstName, p.lastName].filter(Boolean);
-                members.push({
-                    id: p.id.toString(),
+        const entity = await this.resolveChat(chatId);
+        if (entity instanceof Api.Channel) {
+            const result = await this.client.invoke(new Api.channels.GetParticipants({
+                channel: entity,
+                filter: new Api.ChannelParticipantsRecent(),
+                offset: 0,
+                limit,
+                hash: bigInt.zero,
+            }));
+            if (!(result instanceof Api.channels.ChannelParticipants))
+                return [];
+            const userMap = new Map();
+            for (const u of result.users) {
+                if (u instanceof Api.User)
+                    userMap.set(u.id.toString(), u);
+            }
+            return result.participants.map((p) => {
+                const userId = this.getParticipantUserId(p);
+                const user = userMap.get(userId);
+                const parts = user ? [user.firstName, user.lastName].filter(Boolean) : [];
+                return {
+                    id: userId,
                     name: parts.join(" ") || "Unknown",
-                    username: p.username ?? undefined,
-                });
+                    username: user?.username ?? undefined,
+                    role: this.getParticipantRole(p),
+                };
+            });
+        }
+        // Basic group — use getParticipants (no role info available)
+        const participants = await this.client.getParticipants(entity, { limit });
+        return participants
+            .filter((p) => p instanceof Api.User)
+            .map((p) => {
+            const parts = [p.firstName, p.lastName].filter(Boolean);
+            return {
+                id: p.id.toString(),
+                name: parts.join(" ") || "Unknown",
+                username: p.username ?? undefined,
+                role: "member",
+            };
+        });
+    }
+    async getMyRole(chatId) {
+        if (!this.client || !this.connected)
+            throw new Error("Not connected");
+        const entity = await this.resolveChat(chatId);
+        const me = await this.getMe();
+        if (entity instanceof Api.Channel) {
+            const result = await this.client.invoke(new Api.channels.GetParticipant({ channel: entity, participant: new Api.InputUserSelf() }));
+            return {
+                role: this.getParticipantRole(result.participant),
+                chatId: entity.id.toString(),
+                chatName: entity.title ?? "Unknown",
+            };
+        }
+        if (entity instanceof Api.Chat) {
+            // Basic group — check if creator
+            if (entity.creator) {
+                return { role: "creator", chatId: entity.id.toString(), chatName: entity.title ?? "Unknown" };
+            }
+            if (entity.adminRights) {
+                return { role: "admin", chatId: entity.id.toString(), chatName: entity.title ?? "Unknown" };
             }
+            return { role: "member", chatId: entity.id.toString(), chatName: entity.title ?? "Unknown" };
         }
-        return members;
+        if (entity instanceof Api.User) {
+            return { role: "user", chatId: entity.id.toString(), chatName: me.username ?? "self" };
+        }
+        return { role: "unknown", chatId: chatId, chatName: "Unknown" };
+    }
+    getParticipantUserId(p) {
+        if (p instanceof Api.ChannelParticipantCreator)
+            return p.userId.toString();
+        if (p instanceof Api.ChannelParticipantAdmin)
+            return p.userId.toString();
+        if (p instanceof Api.ChannelParticipantSelf)
+            return p.userId.toString();
+        if (p instanceof Api.ChannelParticipantBanned)
+            return p.peer?.userId?.toString() ?? "0";
+        if (p instanceof Api.ChannelParticipant)
+            return p.userId.toString();
+        return "0";
+    }
+    getParticipantRole(p) {
+        if (p instanceof Api.ChannelParticipantCreator)
+            return "creator";
+        if (p instanceof Api.ChannelParticipantAdmin)
+            return "admin";
+        if (p instanceof Api.ChannelParticipantBanned)
+            return "banned";
+        if (p instanceof Api.ChannelParticipantLeft)
+            return "left";
+        return "member";
     }
     async getProfile(userId) {
         if (!this.client || !this.connected)

package/dist/tools/auth.js

@@ -1,3 +1,5 @@
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
 import { fail, ok, READ_ONLY, WRITE } from "./shared.js";
 export function registerAuthTools(server, telegram) {
     server.registerTool("telegram-status", { description: "Check Telegram connection status", annotations: READ_ONLY }, async () => {
@@ -18,11 +20,8 @@ export function registerAuthTools(server, telegram) {
         annotations: WRITE,
     }, async () => {
         let qrDataUrl = "";
-        let qrRawUrl = "";
         const loginPromise = telegram.startQrLogin((dataUrl) => {
             qrDataUrl = dataUrl;
-        }, (url) => {
-            qrRawUrl = url;
         });
         // Wait for first QR to be generated
         const startTime = Date.now();
@@ -41,20 +40,17 @@ export function registerAuthTools(server, telegram) {
                 console.error(`[mcp-telegram] Login failed: ${result.message}`);
             }
         });
-        // Return as MCP image content + text with fallback options
+        // Save QR to file as fallback (no data sent to third-party services)
         const base64 = qrDataUrl.replace(/^data:image\/png;base64,/, "");
-        const qrApiUrl = qrRawUrl
-            ? `https://api.qrserver.com/v1/create-qr-code/?size=256x256&data=${encodeURIComponent(qrRawUrl)}`
-            : "";
+        const qrFilePath = join(telegram.sessionDir, "qr-login.png");
+        await writeFile(qrFilePath, Buffer.from(base64, "base64")).catch(() => { });
         const instructions = [
             "Scan this QR code in Telegram: **Settings → Devices → Link Desktop Device**.",
             "",
-            qrApiUrl ? `If the QR image is not visible, open this link in your browser:\n${qrApiUrl}` : "",
+            `If the QR image is not visible, it's also saved to: ${qrFilePath}`,
             "",
             "After scanning, run **telegram-status** to verify the connection.",
-        ]
-            .filter(Boolean)
-            .join("\n");
+        ].join("\n");
         return {
             content: [
                 {

package/dist/tools/chats.js

@@ -93,13 +93,36 @@ export function registerChatTools(server, telegram) {
             return fail(new Error(err));
         try {
             const members = await telegram.getChatMembers(chatId, limit);
-            const text = members.map((m) => `${m.name}${m.username ? ` (@${m.username})` : ""} (${m.id})`).join("\n");
+            const text = members
+                .map((m) => {
+                const role = m.role !== "member" ? ` [${m.role}]` : "";
+                return `${m.name}${m.username ? ` (@${m.username})` : ""} (${m.id})${role}`;
+            })
+                .join("\n");
             return ok(sanitize(text) || "No members found");
         }
         catch (e) {
             return fail(e);
         }
     });
+    server.registerTool("telegram-get-my-role", {
+        description: "Get the current user's role in a chat (creator, admin, or member)",
+        inputSchema: {
+            chatId: z.string().describe("Chat ID or username"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ chatId }) => {
+        const err = await requireConnection(telegram);
+        if (err)
+            return fail(new Error(err));
+        try {
+            const result = await telegram.getMyRole(chatId);
+            return ok(`Role: ${result.role}\nChat: ${result.chatName} (${result.chatId})`);
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
     server.registerTool("telegram-create-group", {
         description: "Create a new Telegram group or supergroup",
         inputSchema: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@overpod/mcp-telegram",
-  "version": "1.17.0",
+  "version": "1.19.0",
   "description": "MCP server for Telegram userbot — messages, media, reactions, polls & more. Built on GramJS/MTProto.",
   "type": "module",
   "main": "dist/index.js",
@@ -25,7 +25,9 @@
     "prepublishOnly": "npm run build",
     "lint": "biome check src/",
     "lint:fix": "biome check --fix src/",
-    "format": "biome format --write src/"
+    "format": "biome format --write src/",
+    "test": "tsx --test src/**/*.test.ts",
+    "test:watch": "tsx --test --watch src/**/*.test.ts"
   },
   "keywords": [
     "mcp",