@overpod/mcp-telegram 1.18.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;
     });

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;

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@overpod/mcp-telegram",
-  "version": "1.18.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",