@ebowwa/mcp-telegram 0.1.4 → 0.2.0

package/dist/index.js

@@ -21,6 +21,7 @@ import { TelegramClient } from "telegram";
 import { StringSession } from "telegram/sessions";
 import { Api } from "telegram";
 import bigInt from "big-integer";
+import { NewMessage } from "telegram/events";
 import { homedir } from "os";
 import { join } from "path";
 import { mkdirSync, existsSync, writeFileSync, readFileSync } from "fs";
@@ -37,6 +38,10 @@ if (!existsSync(SESSION_DIR)) {
 // Global client instance
 let client = null;
 let sessionString = "";
+// Event storage
+const subscriptions = new Map();
+const eventQueue = [];
+const eventHandlers = new Map(); // Track registered handlers for cleanup
 // ==============
 // Helper Functions
 // ==============
@@ -115,6 +120,56 @@ function formatMessage(message) {
     };
 }
 // ==============
+// Event Subscription Helpers
+// ==============
+function generateId() {
+    return `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+}
+function queueEvent(subscriptionId, type, data) {
+    const event = {
+        id: generateId(),
+        subscriptionId,
+        type,
+        data,
+        timestamp: new Date(),
+    };
+    eventQueue.push(event);
+    // Keep only last 100 events to prevent memory issues
+    if (eventQueue.length > 100) {
+        eventQueue.shift();
+    }
+    // Send MCP notification
+    server.sendResourceUpdated({
+        uri: `telegram://events/${subscriptionId}`,
+    }).catch((err) => console.error("Failed to send MCP notification:", err));
+}
+async function setupEventHandlers(c, subscription) {
+    const handlerKey = subscription.id;
+    // Remove existing handler if any
+    if (eventHandlers.has(handlerKey)) {
+        // GramJS doesn't have a clean removeEventHandler, so we track and skip
+        eventHandlers.delete(handlerKey);
+    }
+    // Create handler for new messages
+    if (subscription.events.includes('new_message')) {
+        const handler = async (event) => {
+            const message = event.message;
+            const chatId = message.peerId?.userId?.toString() ||
+                message.peerId?.chatId?.toString() ||
+                message.peerId?.channelId?.toString();
+            // Only process if this message is from our subscribed chat
+            if (chatId === subscription.chatId || message.chatId?.toString() === subscription.chatId) {
+                queueEvent(subscription.id, 'new_message', {
+                    message: formatMessage(message),
+                    chatId,
+                });
+            }
+        };
+        c.addEventHandler(handler, new NewMessage({ incoming: true }));
+        eventHandlers.set(handlerKey, handler);
+    }
+}
+// ==============
 // MCP Server
 // ==============
 const server = new Server({
@@ -123,6 +178,10 @@ const server = new Server({
 }, {
     capabilities: {
         tools: {},
+        resources: {
+            subscribe: true,
+            listChanged: true,
+        },
     },
 });
 // List available tools
@@ -428,6 +487,82 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     required: ["entity"],
                 },
             },
+            // Real-time Event Subscriptions
+            {
+                name: "telegram_subscribe",
+                description: "Subscribe to real-time events from a Telegram chat. The AI will receive MCP notifications when new messages arrive.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        entity: {
+                            type: "string",
+                            description: "Username, phone, or entity ID of the chat to subscribe to",
+                        },
+                        events: {
+                            type: "array",
+                            items: { type: "string", enum: ["new_message", "edited_message", "deleted_message"] },
+                            description: "Event types to subscribe to (default: ['new_message'])",
+                        },
+                    },
+                    required: ["entity"],
+                },
+            },
+            {
+                name: "telegram_unsubscribe",
+                description: "Unsubscribe from a Telegram chat's events.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        subscriptionId: {
+                            type: "string",
+                            description: "Subscription ID to remove",
+                        },
+                    },
+                    required: ["subscriptionId"],
+                },
+            },
+            {
+                name: "telegram_get_subscriptions",
+                description: "List all active event subscriptions.",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                },
+            },
+            {
+                name: "telegram_get_events",
+                description: "Get queued events from subscriptions. Call this after receiving an MCP resource notification.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        subscriptionId: {
+                            type: "string",
+                            description: "Filter events by subscription ID (optional)",
+                        },
+                        limit: {
+                            type: "number",
+                            description: "Maximum number of events to return (default: 50)",
+                        },
+                        clear: {
+                            type: "boolean",
+                            description: "Clear retrieved events from queue (default: true)",
+                        },
+                    },
+                },
+            },
+            {
+                name: "telegram_clear_events",
+                description: "Clear all queued events or events for a specific subscription.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        subscriptionId: {
+                            type: "string",
+                            description: "Clear events only for this subscription (optional, clears all if not provided)",
+                        },
+                    },
+                },
+            },
         ],
     };
 });
@@ -774,6 +909,171 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         }],
                 };
             }
+            // ==================
+            // Real-time Event Subscriptions
+            // ==================
+            case "telegram_subscribe": {
+                if (!args?.entity) {
+                    throw new Error("entity is required");
+                }
+                const c = await getClient();
+                const entity = await c.getEntity(args.entity);
+                const chatId = entity.id?.toString();
+                if (!chatId) {
+                    throw new Error("Could not resolve chat ID");
+                }
+                // Check if already subscribed
+                const existing = Array.from(subscriptions.values()).find((s) => s.chatId === chatId);
+                if (existing) {
+                    return {
+                        content: [{
+                                type: "text",
+                                text: JSON.stringify({
+                                    success: true,
+                                    message: "Already subscribed to this chat",
+                                    subscription: existing,
+                                }, null, 2),
+                            }],
+                    };
+                }
+                const events = args?.events || ["new_message"];
+                const subscription = {
+                    id: generateId(),
+                    chatId,
+                    chatName: entity.title || entity.username || entity.firstName,
+                    events,
+                    createdAt: new Date(),
+                };
+                subscriptions.set(subscription.id, subscription);
+                // Set up GramJS event handlers
+                await setupEventHandlers(c, subscription);
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                success: true,
+                                message: `Subscribed to ${subscription.chatName || chatId}`,
+                                subscription,
+                                notificationUri: `telegram://events/${subscription.id}`,
+                            }, null, 2),
+                        }],
+                };
+            }
+            case "telegram_unsubscribe": {
+                const subscriptionId = args?.subscriptionId;
+                if (!subscriptionId) {
+                    throw new Error("subscriptionId is required");
+                }
+                const subscription = subscriptions.get(subscriptionId);
+                if (!subscription) {
+                    return {
+                        content: [{
+                                type: "text",
+                                text: JSON.stringify({
+                                    success: false,
+                                    message: "Subscription not found",
+                                }, null, 2),
+                            }],
+                    };
+                }
+                subscriptions.delete(subscriptionId);
+                eventHandlers.delete(subscriptionId);
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                success: true,
+                                message: `Unsubscribed from ${subscription.chatName || subscription.chatId}`,
+                            }, null, 2),
+                        }],
+                };
+            }
+            case "telegram_get_subscriptions": {
+                const list = Array.from(subscriptions.values()).map((s) => ({
+                    id: s.id,
+                    chatId: s.chatId,
+                    chatName: s.chatName,
+                    events: s.events,
+                    createdAt: s.createdAt,
+                }));
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                total: list.length,
+                                subscriptions: list,
+                            }, null, 2),
+                        }],
+                };
+            }
+            case "telegram_get_events": {
+                const subscriptionId = args?.subscriptionId;
+                const limit = args?.limit || 50;
+                const clear = args?.clear !== false;
+                let filteredEvents = eventQueue;
+                if (subscriptionId) {
+                    filteredEvents = eventQueue.filter((e) => e.subscriptionId === subscriptionId);
+                }
+                const events = filteredEvents.slice(-limit);
+                if (clear) {
+                    // Remove retrieved events from queue
+                    const eventIds = new Set(events.map((e) => e.id));
+                    const queueIndex = eventQueue.findIndex((e) => eventIds.has(e.id));
+                    if (queueIndex !== -1) {
+                        eventQueue.splice(queueIndex, events.length);
+                    }
+                }
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                total: events.length,
+                                events: events.map((e) => ({
+                                    id: e.id,
+                                    type: e.type,
+                                    data: e.data,
+                                    timestamp: e.timestamp,
+                                })),
+                            }, null, 2),
+                        }],
+                };
+            }
+            case "telegram_clear_events": {
+                const subscriptionId = args?.subscriptionId;
+                if (subscriptionId) {
+                    const before = eventQueue.length;
+                    const indicesToRemove = [];
+                    eventQueue.forEach((e, i) => {
+                        if (e.subscriptionId === subscriptionId) {
+                            indicesToRemove.push(i);
+                        }
+                    });
+                    // Remove from end to start to preserve indices
+                    indicesToRemove.reverse().forEach((i) => eventQueue.splice(i, 1));
+                    return {
+                        content: [{
+                                type: "text",
+                                text: JSON.stringify({
+                                    success: true,
+                                    message: `Cleared ${indicesToRemove.length} events for subscription`,
+                                }, null, 2),
+                            }],
+                    };
+                }
+                else {
+                    const count = eventQueue.length;
+                    eventQueue.length = 0;
+                    return {
+                        content: [{
+                                type: "text",
+                                text: JSON.stringify({
+                                    success: true,
+                                    message: `Cleared ${count} events`,
+                                }, null, 2),
+                            }],
+                    };
+                }
+            }
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ebowwa/mcp-telegram",
-  "version": "0.1.4",
-  "description": "Telegram MTProto client MCP server using GramJS - full user account access",
+  "version": "0.2.0",
+  "description": "Telegram MTProto client MCP server using GramJS - full user account access with real-time event subscriptions",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -21,10 +21,12 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
+    "big-integer": "^1.6.52",
     "telegram": "^2.26.20",
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@types/big-integer": "^0.0.35",
     "@types/bun": "latest",
     "@types/node": "^22.10.2",
     "typescript": "^5.7.2"