@overpod/mcp-telegram 1.6.0 → 1.7.0

package/README.md

@@ -173,23 +173,32 @@ const telegramMcp = new MCPClient({
 
 | Tool | Description |
 |------|-------------|
-| `telegram-list-chats` | List recent dialogs with unread counts |
+| `telegram-list-chats` | List recent dialogs with unread counts, bot/contact markers |
 | `telegram-read-messages` | Read recent messages from a chat |
 | `telegram-search-chats` | Search for chats, users, or channels by name |
 | `telegram-search-messages` | Search messages in a chat by text |
-| `telegram-get-unread` | Get chats with unread messages |
+| `telegram-get-unread` | Get chats with unread messages, bot/contact markers |
+| `telegram-get-contact-requests` | Get incoming messages from non-contacts with preview |
 
 ### Chat Management
 
 | Tool | Description |
 |------|-------------|
 | `telegram-mark-as-read` | Mark a chat as read |
-| `telegram-get-chat-info` | Get detailed info about a chat (name, type, members count, description) |
+| `telegram-get-chat-info` | Get detailed info about a chat (name, type, members, bot/contact status) |
 | `telegram-get-chat-members` | List members of a group or channel |
 | `telegram-join-chat` | Join a group or channel by username or invite link |
 | `telegram-pin-message` | Pin a message in a chat |
 | `telegram-unpin-message` | Unpin a message in a chat |
 
+### Contacts & Moderation
+
+| Tool | Description |
+|------|-------------|
+| `telegram-add-contact` | Add a user to your contacts (accept contact request) |
+| `telegram-block-user` | Block a user from sending you messages |
+| `telegram-report-spam` | Report a chat as spam to Telegram |
+
 ### User Info
 
 | Tool | Description |
@@ -224,7 +233,7 @@ Most tools accept `chatId` as a string -- either a numeric ID (e.g., `"-10012345
 |-----------|------|----------|-------------|
 | `limit` | number | no | Number of chats to return (default: 20) |
 | `offsetDate` | number | no | Unix timestamp for pagination |
-| `filterType` | `"private"` / `"group"` / `"channel"` | no | Filter by chat type |
+| `filterType` | `"private"` / `"group"` / `"channel"` / `"contact_requests"` | no | Filter by chat type |
 
 ### telegram-read-messages
 
@@ -356,6 +365,33 @@ Most tools accept `chatId` as a string -- either a numeric ID (e.g., `"-10012345
 |-----------|------|----------|-------------|
 | `limit` | number | no | Number of unread chats (default: 20) |
 
+### telegram-get-contact-requests
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `limit` | number | no | Number of contact requests (default: 20) |
+
+### telegram-add-contact
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `userId` | string | yes | User ID or @username to add |
+| `firstName` | string | yes | First name for the contact |
+| `lastName` | string | no | Last name for the contact |
+| `phone` | string | no | Phone number for the contact |
+
+### telegram-block-user
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `userId` | string | yes | User ID or @username to block |
+
+### telegram-report-spam
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `chatId` | string | yes | Chat ID or @username to report |
+
 ## Development
 
 ```bash

package/dist/telegram-client.d.ts

@@ -4,9 +4,13 @@ export declare class TelegramService {
     private apiHash;
     private sessionString;
     private connected;
+    private sessionPath;
     lastError: string;
-    constructor(apiId: number, apiHash: string);
+    constructor(apiId: number, apiHash: string, options?: {
+        sessionPath?: string;
+    });
     loadSession(): Promise<boolean>;
+    private isValidSessionString;
     /** Set session string in memory (for programmatic / hosted use) */
     setSessionString(session: string): void;
     /** Get the current session string (for external persistence) */

package/dist/telegram-client.js

@@ -1,5 +1,6 @@
-import { existsSync } from "node:fs";
-import { readFile, unlink, writeFile } from "node:fs/promises";
+import { existsSync, mkdirSync } from "node:fs";
+import { chmod, readFile, unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import bigInt from "big-integer";
@@ -8,25 +9,66 @@ import { TelegramClient } from "telegram";
 import { StringSession } from "telegram/sessions/index.js";
 import { Api } from "telegram/tl/index.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const SESSION_FILE = join(__dirname, "..", ".telegram-session");
+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;
+function resolveSessionPath(sessionPath) {
+    return sessionPath ?? process.env.TELEGRAM_SESSION_PATH ?? DEFAULT_SESSION_FILE;
+}
+function ensureSessionDir(filePath) {
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+}
 export class TelegramService {
     client = null;
     apiId;
     apiHash;
     sessionString = "";
     connected = false;
+    sessionPath;
     lastError = "";
-    constructor(apiId, apiHash) {
+    constructor(apiId, apiHash, options) {
         this.apiId = apiId;
         this.apiHash = apiHash;
+        this.sessionPath = resolveSessionPath(options?.sessionPath);
     }
     async loadSession() {
-        if (existsSync(SESSION_FILE)) {
-            this.sessionString = (await readFile(SESSION_FILE, "utf-8")).trim();
-            return true;
+        // Try current session path
+        if (existsSync(this.sessionPath)) {
+            const raw = (await readFile(this.sessionPath, "utf-8")).trim();
+            if (this.isValidSessionString(raw)) {
+                this.sessionString = raw;
+                // Fix permissions on existing files
+                try {
+                    await chmod(this.sessionPath, 0o600);
+                }
+                catch { }
+                return true;
+            }
+        }
+        // Migrate from legacy path (inside node_modules / package root)
+        if (this.sessionPath === DEFAULT_SESSION_FILE && existsSync(LEGACY_SESSION_FILE)) {
+            const raw = (await readFile(LEGACY_SESSION_FILE, "utf-8")).trim();
+            if (this.isValidSessionString(raw)) {
+                this.sessionString = raw;
+                ensureSessionDir(this.sessionPath);
+                await writeFile(this.sessionPath, raw, { encoding: "utf-8", mode: 0o600 });
+                try {
+                    await unlink(LEGACY_SESSION_FILE);
+                }
+                catch { }
+                return true;
+            }
         }
         return false;
     }
+    isValidSessionString(value) {
+        return value.length >= MIN_SESSION_LENGTH && SESSION_STRING_RE.test(value);
+    }
     /** Set session string in memory (for programmatic / hosted use) */
     setSessionString(session) {
         this.sessionString = session;
@@ -38,7 +80,8 @@ export class TelegramService {
     async saveSession(session) {
         this.sessionString = session;
         try {
-            await writeFile(SESSION_FILE, session, "utf-8");
+            ensureSessionDir(this.sessionPath);
+            await writeFile(this.sessionPath, session, { encoding: "utf-8", mode: 0o600 });
         }
         catch {
             // File write may fail in containerized environments — session string is still in memory
@@ -95,8 +138,8 @@ export class TelegramService {
         this.connected = false;
         this.sessionString = "";
         this.client = null;
-        if (existsSync(SESSION_FILE)) {
-            await unlink(SESSION_FILE);
+        if (existsSync(this.sessionPath)) {
+            await unlink(this.sessionPath);
         }
     }
     /** Ensure connection is active, auto-reconnect if session exists */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@overpod/mcp-telegram",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "MCP server for Telegram userbot — messages, media, reactions, polls & more. Built on GramJS/MTProto.",
   "type": "module",
   "main": "dist/index.js",
@@ -56,8 +56,8 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.6",
-    "@types/node": "^25.4.0",
+    "@biomejs/biome": "^2.4.7",
+    "@types/node": "^25.5.0",
     "@types/qrcode": "^1.5.6",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3"