@deus-ai/telegram-mcp 1.0.0

package/README.md

@@ -0,0 +1,48 @@
+# @deus-ai/telegram-mcp
+
+Standalone MCP server for Telegram bots. Uses [grammY](https://grammy.dev/) for the Telegram Bot API.
+
+Works with any MCP client — Claude Code, Claude Desktop, or your own application.
+
+## Quick Start
+
+```json
+{
+  "mcpServers": {
+    "telegram": {
+      "command": "npx",
+      "args": ["@deus-ai/telegram-mcp"],
+      "env": {
+        "TELEGRAM_BOT_TOKEN": "your-bot-token"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `send_message` | Send a text message to a chat |
+| `send_typing` | Show/hide typing indicator |
+| `get_status` | Connection status and bot info |
+| `list_chats` | List known chats and groups |
+| `get_new_messages` | Poll for incoming messages (cursor-based) |
+| `connect` / `disconnect` | Connection lifecycle |
+
+## Incoming Messages
+
+Messages are pushed in real-time via MCP logging notifications with `logger: "incoming_message"`. For clients that don't support notifications, use the `get_new_messages` polling tool.
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `TELEGRAM_BOT_TOKEN` | *(required)* | Bot token from @BotFather |
+| `ASSISTANT_NAME` | `Deus` | Name for @mention translation |
+| `LOG_LEVEL` | `info` | Pino log level |
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * Telegram MCP Server
+ *
+ * Standalone MCP server that provides Telegram bot messaging tools.
+ * Communicates via stdio (JSON-RPC). Can be used by any MCP client.
+ *
+ * Config (env vars):
+ *   TELEGRAM_BOT_TOKEN — Telegram bot token from @BotFather
+ *   ASSISTANT_NAME     — bot display name (default: Deus)
+ *   LOG_LEVEL          — pino log level (default: info)
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/**
+ * Telegram MCP Server
+ *
+ * Standalone MCP server that provides Telegram bot messaging tools.
+ * Communicates via stdio (JSON-RPC). Can be used by any MCP client.
+ *
+ * Config (env vars):
+ *   TELEGRAM_BOT_TOKEN — Telegram bot token from @BotFather
+ *   ASSISTANT_NAME     — bot display name (default: Deus)
+ *   LOG_LEVEL          — pino log level (default: info)
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { registerCommonTools } from '@deus-ai/channel-core';
+import { TelegramProvider } from './telegram.js';
+const server = new McpServer({
+    name: '@deus-ai/telegram-mcp',
+    version: '1.0.0',
+});
+const provider = new TelegramProvider();
+// Register common tools (send_message, get_status, etc.)
+registerCommonTools(server, provider);
+// ── Auto-connect if token is configured ───────────────────────────────
+if (provider.hasToken()) {
+    provider.connect().catch((err) => {
+        console.error('[@deus-ai/telegram-mcp] Auto-connect failed:', err.message);
+    });
+}
+// ── Start MCP transport ───────────────────────────────────────────────
+const transport = new StdioServerTransport();
+await server.connect(transport);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjD,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IAC3B,IAAI,EAAE,uBAAuB;IAC7B,OAAO,EAAE,OAAO;CACjB,CAAC,CAAC;AAEH,MAAM,QAAQ,GAAG,IAAI,gBAAgB,EAAE,CAAC;AAExC,yDAAyD;AACzD,mBAAmB,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAEtC,yEAAyE;AAEzE,IAAI,QAAQ,CAAC,QAAQ,EAAE,EAAE,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;QAC/B,OAAO,CAAC,KAAK,CAAC,8CAA8C,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;IAC7E,CAAC,CAAC,CAAC;AACL,CAAC;AAED,yEAAyE;AAEzE,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;AAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC"}

package/dist/telegram.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Standalone Telegram bot provider.
+ * Extracted from Deus TelegramChannel — no Deus-specific dependencies.
+ * Config comes from env vars; all messages are forwarded to onMessage.
+ */
+import type { ChannelProvider, ChannelStatus, ChatInfo, IncomingMessage } from '@deus-ai/channel-core';
+export declare class TelegramProvider implements ChannelProvider {
+    readonly name = "telegram";
+    private bot;
+    private connectTime;
+    private knownChats;
+    private botUsername?;
+    private consecutiveErrors;
+    private resetting;
+    onMessage: (msg: IncomingMessage) => void;
+    connect(): Promise<void>;
+    /**
+     * Reset the polling session after consecutive errors.
+     * Retries with exponential backoff (1s, 2s, 4s), then exits on failure.
+     */
+    private resetPolling;
+    sendMessage(chatId: string, text: string): Promise<void>;
+    isConnected(): boolean;
+    getStatus(): ChannelStatus;
+    disconnect(): Promise<void>;
+    setTyping(chatId: string, isTyping: boolean): Promise<void>;
+    listChats(): Promise<ChatInfo[]>;
+    /** Check if a bot token is configured. */
+    hasToken(): boolean;
+}

package/dist/telegram.js

@@ -0,0 +1,289 @@
+/**
+ * Standalone Telegram bot provider.
+ * Extracted from Deus TelegramChannel — no Deus-specific dependencies.
+ * Config comes from env vars; all messages are forwarded to onMessage.
+ */
+import https from 'https';
+import { Bot } from 'grammy';
+import pino from 'pino';
+const ASSISTANT_NAME = process.env.ASSISTANT_NAME || 'Deus';
+const BOT_TOKEN = process.env.TELEGRAM_BOT_TOKEN || '';
+// Use stderr for logging (stdout is reserved for MCP JSON-RPC)
+const logger = pino({ level: process.env.LOG_LEVEL || 'info' }, pino.destination(2));
+const MAX_MESSAGE_LENGTH = 4096;
+const MAX_CONSECUTIVE_ERRORS = 5;
+const MAX_RECONNECT_RETRIES = 3;
+const BASE_BACKOFF_MS = 1000;
+/**
+ * Send a message with Telegram Markdown parse mode, falling back to plain text.
+ */
+async function sendTelegramMessage(api, chatId, text, options = {}) {
+    try {
+        await api.sendMessage(chatId, text, { ...options, parse_mode: 'Markdown' });
+    }
+    catch {
+        await api.sendMessage(chatId, text, options);
+    }
+}
+export class TelegramProvider {
+    name = 'telegram';
+    bot = null;
+    connectTime = 0;
+    knownChats = new Map();
+    botUsername;
+    consecutiveErrors = 0;
+    resetting = false;
+    // Set by server-base.ts
+    onMessage = () => { };
+    async connect() {
+        if (!BOT_TOKEN) {
+            throw new Error('TELEGRAM_BOT_TOKEN not set');
+        }
+        this.bot = new Bot(BOT_TOKEN, {
+            client: {
+                baseFetchConfig: { agent: https.globalAgent, compress: true },
+            },
+        });
+        // /chatid command for registration
+        this.bot.command('chatid', (ctx) => {
+            const chatId = ctx.chat.id;
+            const chatType = ctx.chat.type;
+            const chatName = chatType === 'private'
+                ? ctx.from?.first_name || 'Private'
+                : ctx.chat.title || 'Unknown';
+            ctx.reply(`Chat ID: \`tg:${chatId}\`\nName: ${chatName}\nType: ${chatType}`, { parse_mode: 'Markdown' });
+        });
+        this.bot.command('ping', (ctx) => {
+            ctx.reply(`${ASSISTANT_NAME} is online.`);
+        });
+        const BOT_COMMANDS = new Set(['chatid', 'ping']);
+        // Handle text messages
+        this.bot.on('message:text', async (ctx) => {
+            this.consecutiveErrors = 0;
+            if (ctx.message.text.startsWith('/')) {
+                const cmd = ctx.message.text.slice(1).split(/[\s@]/)[0].toLowerCase();
+                if (BOT_COMMANDS.has(cmd))
+                    return;
+            }
+            const chatJid = `tg:${ctx.chat.id}`;
+            let content = ctx.message.text;
+            const timestamp = new Date(ctx.message.date * 1000).toISOString();
+            const senderName = ctx.from?.first_name ||
+                ctx.from?.username ||
+                ctx.from?.id.toString() ||
+                'Unknown';
+            const sender = ctx.from?.id.toString() || '';
+            const msgId = ctx.message.message_id.toString();
+            const isGroup = ctx.chat.type === 'group' || ctx.chat.type === 'supergroup';
+            const chatName = ctx.chat.type === 'private'
+                ? senderName
+                : ctx.chat.title || chatJid;
+            // Track chat
+            this.knownChats.set(chatJid, { name: chatName, isGroup });
+            // Translate @bot mentions to @AssistantName
+            const botUser = this.botUsername?.toLowerCase();
+            if (botUser) {
+                const entities = ctx.message.entities || [];
+                const isBotMentioned = entities.some((e) => {
+                    if (e.type === 'mention') {
+                        return (content.substring(e.offset, e.offset + e.length).toLowerCase() ===
+                            `@${botUser}`);
+                    }
+                    return false;
+                });
+                if (isBotMentioned) {
+                    content = `@${ASSISTANT_NAME} ${content}`;
+                }
+            }
+            // Reply context
+            const replyTo = ctx.message.reply_to_message;
+            // Forward ALL messages
+            this.onMessage({
+                id: msgId,
+                chat_id: chatJid,
+                sender,
+                sender_name: senderName,
+                content,
+                timestamp,
+                is_from_me: false,
+                is_group: isGroup,
+                chat_name: chatName,
+                metadata: {
+                    thread_id: ctx.message.message_thread_id?.toString(),
+                    reply_to_message_id: replyTo?.message_id?.toString(),
+                    reply_to_content: replyTo?.text || replyTo?.caption,
+                    reply_to_sender_name: replyTo
+                        ? replyTo.from?.first_name ||
+                            replyTo.from?.username ||
+                            replyTo.from?.id?.toString()
+                        : undefined,
+                },
+            });
+        });
+        // Handle media messages
+        const storeMedia = (ctx, placeholder) => {
+            const chatJid = `tg:${ctx.chat.id}`;
+            const timestamp = new Date(ctx.message.date * 1000).toISOString();
+            const senderName = ctx.from?.first_name ||
+                ctx.from?.username ||
+                ctx.from?.id?.toString() ||
+                'Unknown';
+            const caption = ctx.message.caption ? ` ${ctx.message.caption}` : '';
+            const isGroup = ctx.chat.type === 'group' || ctx.chat.type === 'supergroup';
+            this.knownChats.set(chatJid, {
+                name: ctx.chat.type === 'private'
+                    ? senderName
+                    : ctx.chat.title || chatJid,
+                isGroup,
+            });
+            this.onMessage({
+                id: ctx.message.message_id.toString(),
+                chat_id: chatJid,
+                sender: ctx.from?.id?.toString() || '',
+                sender_name: senderName,
+                content: `${placeholder}${caption}`,
+                timestamp,
+                is_from_me: false,
+                is_group: isGroup,
+            });
+        };
+        this.bot.on('message:photo', (ctx) => storeMedia(ctx, '[Photo]'));
+        this.bot.on('message:video', (ctx) => storeMedia(ctx, '[Video]'));
+        this.bot.on('message:voice', (ctx) => storeMedia(ctx, '[Voice message]'));
+        this.bot.on('message:audio', (ctx) => storeMedia(ctx, '[Audio]'));
+        this.bot.on('message:document', (ctx) => {
+            const name = ctx.message.document?.file_name || 'file';
+            storeMedia(ctx, `[Document: ${name}]`);
+        });
+        this.bot.on('message:sticker', (ctx) => {
+            const emoji = ctx.message.sticker?.emoji || '';
+            storeMedia(ctx, `[Sticker ${emoji}]`);
+        });
+        this.bot.on('message:location', (ctx) => storeMedia(ctx, '[Location]'));
+        this.bot.on('message:contact', (ctx) => storeMedia(ctx, '[Contact]'));
+        this.bot.catch((err) => {
+            this.consecutiveErrors++;
+            logger.error({ err: err.message, consecutiveErrors: this.consecutiveErrors }, 'Telegram bot error');
+            if (this.consecutiveErrors >= MAX_CONSECUTIVE_ERRORS && !this.resetting) {
+                this.resetPolling();
+            }
+        });
+        return new Promise((resolve) => {
+            this.bot.start({
+                onStart: (botInfo) => {
+                    this.botUsername = botInfo.username;
+                    this.connectTime = Date.now();
+                    this.consecutiveErrors = 0;
+                    logger.info({ username: botInfo.username, id: botInfo.id }, 'Telegram bot connected');
+                    resolve();
+                },
+            });
+        });
+    }
+    /**
+     * Reset the polling session after consecutive errors.
+     * Retries with exponential backoff (1s, 2s, 4s), then exits on failure.
+     */
+    async resetPolling() {
+        if (!this.bot || this.resetting)
+            return;
+        this.resetting = true;
+        logger.warn({ consecutiveErrors: this.consecutiveErrors }, 'Too many consecutive errors, resetting Telegram polling session');
+        const bot = this.bot;
+        bot.stop();
+        this.consecutiveErrors = 0;
+        for (let attempt = 0; attempt < MAX_RECONNECT_RETRIES; attempt++) {
+            const delayMs = BASE_BACKOFF_MS * Math.pow(2, attempt);
+            logger.info({ attempt: attempt + 1, delayMs }, 'Attempting polling reset with backoff');
+            await new Promise((r) => setTimeout(r, delayMs));
+            try {
+                await new Promise((resolve, reject) => {
+                    const timeout = setTimeout(() => {
+                        reject(new Error('Polling restart timed out'));
+                    }, 30_000);
+                    bot.start({
+                        onStart: (botInfo) => {
+                            clearTimeout(timeout);
+                            this.botUsername = botInfo.username;
+                            this.connectTime = Date.now();
+                            this.resetting = false;
+                            this.consecutiveErrors = 0;
+                            logger.info({ username: botInfo.username, id: botInfo.id }, 'Telegram bot reconnected after polling reset');
+                            resolve();
+                        },
+                    });
+                });
+                return; // Success — exit retry loop
+            }
+            catch (err) {
+                logger.error({ attempt: attempt + 1, err }, 'Polling reset attempt failed');
+                bot.stop();
+            }
+        }
+        logger.fatal('Telegram bot failed to reconnect after %d retries — exiting', MAX_RECONNECT_RETRIES);
+        process.exit(1);
+    }
+    async sendMessage(chatId, text) {
+        if (!this.bot)
+            return;
+        try {
+            const numericId = chatId.replace(/^tg:/, '');
+            if (text.length <= MAX_MESSAGE_LENGTH) {
+                await sendTelegramMessage(this.bot.api, numericId, text);
+            }
+            else {
+                for (let i = 0; i < text.length; i += MAX_MESSAGE_LENGTH) {
+                    await sendTelegramMessage(this.bot.api, numericId, text.slice(i, i + MAX_MESSAGE_LENGTH));
+                }
+            }
+        }
+        catch (err) {
+            logger.error({ chatId, err }, 'Failed to send Telegram message');
+        }
+    }
+    isConnected() {
+        return this.bot !== null;
+    }
+    getStatus() {
+        return {
+            connected: this.bot !== null,
+            channel: 'telegram',
+            identity: this.botUsername,
+            uptime_seconds: this.connectTime
+                ? Math.floor((Date.now() - this.connectTime) / 1000)
+                : 0,
+        };
+    }
+    async disconnect() {
+        if (this.bot) {
+            this.resetting = false;
+            this.consecutiveErrors = 0;
+            this.bot.stop();
+            this.bot = null;
+            logger.info('Telegram bot stopped');
+        }
+    }
+    async setTyping(chatId, isTyping) {
+        if (!this.bot || !isTyping)
+            return;
+        try {
+            const numericId = chatId.replace(/^tg:/, '');
+            await this.bot.api.sendChatAction(numericId, 'typing');
+        }
+        catch {
+            // Best effort
+        }
+    }
+    async listChats() {
+        return Array.from(this.knownChats.entries()).map(([id, info]) => ({
+            id,
+            name: info.name,
+            is_group: info.isGroup,
+        }));
+    }
+    /** Check if a bot token is configured. */
+    hasToken() {
+        return !!BOT_TOKEN;
+    }
+}
+//# sourceMappingURL=telegram.js.map

package/dist/telegram.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram.js","sourceRoot":"","sources":["../src/telegram.ts"],"names":[],"mappings":"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"}

package/dist/telegram.test.d.ts

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

package/dist/telegram.test.js

@@ -0,0 +1,152 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+// vi.hoisted runs before vi.mock hoisting — set env before module evaluation
+vi.hoisted(() => {
+    process.env.TELEGRAM_BOT_TOKEN = 'test-token-123';
+});
+// Shared state for the mock bot
+let catchHandler = null;
+const mockStart = vi.fn((options) => {
+    if (options?.onStart) {
+        options.onStart({ username: 'test_bot', id: 123 });
+    }
+    return Promise.resolve();
+});
+const mockStop = vi.fn();
+const mockCommand = vi.fn();
+const mockOn = vi.fn();
+const mockCatch = vi.fn((handler) => {
+    catchHandler = handler;
+});
+vi.mock('grammy', () => {
+    return {
+        Bot: class MockBot {
+            command = mockCommand;
+            on = mockOn;
+            catch = mockCatch;
+            start = mockStart;
+            stop = mockStop;
+            api = {
+                sendMessage: vi.fn(),
+                sendChatAction: vi.fn(),
+            };
+        },
+        Api: class {
+        },
+    };
+});
+vi.mock('pino', () => {
+    const mockLogger = {
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+        debug: vi.fn(),
+        fatal: vi.fn(),
+    };
+    const pinoFn = () => mockLogger;
+    pinoFn.destination = () => ({});
+    return { default: pinoFn };
+});
+import { TelegramProvider } from './telegram.js';
+describe('TelegramProvider', () => {
+    let provider;
+    beforeEach(() => {
+        catchHandler = null;
+        // Reset implementations but keep fns alive
+        mockStart.mockImplementation((options) => {
+            if (options?.onStart) {
+                options.onStart({ username: 'test_bot', id: 123 });
+            }
+            return Promise.resolve();
+        });
+        mockStop.mockReset();
+        mockCommand.mockReset();
+        mockOn.mockReset();
+        mockCatch.mockImplementation((handler) => {
+            catchHandler = handler;
+        });
+        provider = new TelegramProvider();
+    });
+    describe('error tracking and polling reset', () => {
+        beforeEach(() => {
+            vi.useFakeTimers();
+        });
+        afterEach(() => {
+            vi.useRealTimers();
+        });
+        it('tracks consecutive errors via the catch handler', async () => {
+            await provider.connect();
+            expect(catchHandler).toBeDefined();
+            // Simulate errors below threshold
+            for (let i = 0; i < 3; i++) {
+                catchHandler({ message: `error ${i}` });
+            }
+            // Bot should not have been stopped
+            expect(mockStop).not.toHaveBeenCalled();
+        });
+        it('resets polling after MAX_CONSECUTIVE_ERRORS (5) failures', async () => {
+            await provider.connect();
+            // Reset call counts from connect()
+            mockStop.mockClear();
+            mockStart.mockClear();
+            // Simulate 5 consecutive errors (the threshold)
+            for (let i = 0; i < 5; i++) {
+                catchHandler({ message: `error ${i}` });
+            }
+            // Stop is called immediately in resetPolling
+            expect(mockStop).toHaveBeenCalledTimes(1);
+            // Advance past the first backoff delay (1s) to trigger start
+            await vi.advanceTimersByTimeAsync(1100);
+            expect(mockStart).toHaveBeenCalledTimes(1);
+        });
+        it('does not reset polling twice while already resetting', async () => {
+            await provider.connect();
+            // Make start not call onStart (simulating slow restart that times out)
+            mockStart.mockImplementationOnce(() => Promise.resolve());
+            mockStop.mockClear();
+            mockStart.mockClear();
+            // Trigger 5 errors to start a reset
+            for (let i = 0; i < 5; i++) {
+                catchHandler({ message: `error ${i}` });
+            }
+            // Now send 5 more errors while resetting
+            for (let i = 0; i < 5; i++) {
+                catchHandler({ message: `error ${i}` });
+            }
+            // Should only have triggered one reset (one stop call)
+            expect(mockStop).toHaveBeenCalledTimes(1);
+            // Drain pending timers so resetPolling's async loop completes cleanly
+            // Mock process.exit to prevent test runner from exiting
+            const mockExit = vi
+                .spyOn(process, 'exit')
+                .mockImplementation(() => undefined);
+            await vi.runAllTimersAsync();
+            mockExit.mockRestore();
+        });
+    });
+    describe('disconnect', () => {
+        it('cleans up state on disconnect', async () => {
+            await provider.connect();
+            mockStop.mockClear();
+            await provider.disconnect();
+            expect(mockStop).toHaveBeenCalledTimes(1);
+            expect(provider.isConnected()).toBe(false);
+        });
+    });
+    describe('basic operations', () => {
+        it('reports connected after successful connect', async () => {
+            await provider.connect();
+            expect(provider.isConnected()).toBe(true);
+        });
+        it('returns correct status', async () => {
+            await provider.connect();
+            const status = provider.getStatus();
+            expect(status.connected).toBe(true);
+            expect(status.channel).toBe('telegram');
+            expect(status.identity).toBe('test_bot');
+        });
+        it('has name "telegram"', () => {
+            expect(provider.name).toBe('telegram');
+        });
+    });
+});
+//# sourceMappingURL=telegram.test.js.map

package/dist/telegram.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram.test.js","sourceRoot":"","sources":["../src/telegram.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@deus-ai/telegram-mcp",
+  "version": "1.0.0",
+  "description": "Telegram MCP server — standalone Telegram bot integration for any MCP client",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "deus-ai-telegram-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@deus-ai/channel-core": "^1.0.0",
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "grammy": "^1.39.3",
+    "pino": "^10.3.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.7",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}

package/src/index.ts

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+/**
+ * Telegram MCP Server
+ *
+ * Standalone MCP server that provides Telegram bot messaging tools.
+ * Communicates via stdio (JSON-RPC). Can be used by any MCP client.
+ *
+ * Config (env vars):
+ *   TELEGRAM_BOT_TOKEN — Telegram bot token from @BotFather
+ *   ASSISTANT_NAME     — bot display name (default: Deus)
+ *   LOG_LEVEL          — pino log level (default: info)
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { registerCommonTools } from '@deus-ai/channel-core';
+
+import { TelegramProvider } from './telegram.js';
+
+const server = new McpServer({
+  name: '@deus-ai/telegram-mcp',
+  version: '1.0.0',
+});
+
+const provider = new TelegramProvider();
+
+// Register common tools (send_message, get_status, etc.)
+registerCommonTools(server, provider);
+
+// ── Auto-connect if token is configured ───────────────────────────────
+
+if (provider.hasToken()) {
+  provider.connect().catch((err) => {
+    console.error('[@deus-ai/telegram-mcp] Auto-connect failed:', err.message);
+  });
+}
+
+// ── Start MCP transport ───────────────────────────────────────────────
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/telegram.test.ts

@@ -0,0 +1,180 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+// vi.hoisted runs before vi.mock hoisting — set env before module evaluation
+vi.hoisted(() => {
+  process.env.TELEGRAM_BOT_TOKEN = 'test-token-123';
+});
+
+// Shared state for the mock bot
+let catchHandler: Function | null = null;
+const mockStart = vi.fn((options: any) => {
+  if (options?.onStart) {
+    options.onStart({ username: 'test_bot', id: 123 });
+  }
+  return Promise.resolve();
+});
+const mockStop = vi.fn();
+const mockCommand = vi.fn();
+const mockOn = vi.fn();
+const mockCatch = vi.fn((handler: Function) => {
+  catchHandler = handler;
+});
+
+vi.mock('grammy', () => {
+  return {
+    Bot: class MockBot {
+      command = mockCommand;
+      on = mockOn;
+      catch = mockCatch;
+      start = mockStart;
+      stop = mockStop;
+      api = {
+        sendMessage: vi.fn(),
+        sendChatAction: vi.fn(),
+      };
+    },
+    Api: class {},
+  };
+});
+
+vi.mock('pino', () => {
+  const mockLogger = {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+    fatal: vi.fn(),
+  };
+  const pinoFn: any = () => mockLogger;
+  pinoFn.destination = () => ({});
+  return { default: pinoFn };
+});
+
+import { TelegramProvider } from './telegram.js';
+
+describe('TelegramProvider', () => {
+  let provider: TelegramProvider;
+
+  beforeEach(() => {
+    catchHandler = null;
+    // Reset implementations but keep fns alive
+    mockStart.mockImplementation((options: any) => {
+      if (options?.onStart) {
+        options.onStart({ username: 'test_bot', id: 123 });
+      }
+      return Promise.resolve();
+    });
+    mockStop.mockReset();
+    mockCommand.mockReset();
+    mockOn.mockReset();
+    mockCatch.mockImplementation((handler: Function) => {
+      catchHandler = handler;
+    });
+    provider = new TelegramProvider();
+  });
+
+  describe('error tracking and polling reset', () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it('tracks consecutive errors via the catch handler', async () => {
+      await provider.connect();
+      expect(catchHandler).toBeDefined();
+
+      // Simulate errors below threshold
+      for (let i = 0; i < 3; i++) {
+        catchHandler!({ message: `error ${i}` });
+      }
+
+      // Bot should not have been stopped
+      expect(mockStop).not.toHaveBeenCalled();
+    });
+
+    it('resets polling after MAX_CONSECUTIVE_ERRORS (5) failures', async () => {
+      await provider.connect();
+
+      // Reset call counts from connect()
+      mockStop.mockClear();
+      mockStart.mockClear();
+
+      // Simulate 5 consecutive errors (the threshold)
+      for (let i = 0; i < 5; i++) {
+        catchHandler!({ message: `error ${i}` });
+      }
+
+      // Stop is called immediately in resetPolling
+      expect(mockStop).toHaveBeenCalledTimes(1);
+
+      // Advance past the first backoff delay (1s) to trigger start
+      await vi.advanceTimersByTimeAsync(1100);
+
+      expect(mockStart).toHaveBeenCalledTimes(1);
+    });
+
+    it('does not reset polling twice while already resetting', async () => {
+      await provider.connect();
+
+      // Make start not call onStart (simulating slow restart that times out)
+      mockStart.mockImplementationOnce(() => Promise.resolve());
+      mockStop.mockClear();
+      mockStart.mockClear();
+
+      // Trigger 5 errors to start a reset
+      for (let i = 0; i < 5; i++) {
+        catchHandler!({ message: `error ${i}` });
+      }
+
+      // Now send 5 more errors while resetting
+      for (let i = 0; i < 5; i++) {
+        catchHandler!({ message: `error ${i}` });
+      }
+
+      // Should only have triggered one reset (one stop call)
+      expect(mockStop).toHaveBeenCalledTimes(1);
+
+      // Drain pending timers so resetPolling's async loop completes cleanly
+      // Mock process.exit to prevent test runner from exiting
+      const mockExit = vi
+        .spyOn(process, 'exit')
+        .mockImplementation(() => undefined as never);
+      await vi.runAllTimersAsync();
+      mockExit.mockRestore();
+    });
+  });
+
+  describe('disconnect', () => {
+    it('cleans up state on disconnect', async () => {
+      await provider.connect();
+      mockStop.mockClear();
+
+      await provider.disconnect();
+
+      expect(mockStop).toHaveBeenCalledTimes(1);
+      expect(provider.isConnected()).toBe(false);
+    });
+  });
+
+  describe('basic operations', () => {
+    it('reports connected after successful connect', async () => {
+      await provider.connect();
+      expect(provider.isConnected()).toBe(true);
+    });
+
+    it('returns correct status', async () => {
+      await provider.connect();
+      const status = provider.getStatus();
+      expect(status.connected).toBe(true);
+      expect(status.channel).toBe('telegram');
+      expect(status.identity).toBe('test_bot');
+    });
+
+    it('has name "telegram"', () => {
+      expect(provider.name).toBe('telegram');
+    });
+  });
+});

package/src/telegram.ts

@@ -0,0 +1,372 @@
+/**
+ * Standalone Telegram bot provider.
+ * Extracted from Deus TelegramChannel — no Deus-specific dependencies.
+ * Config comes from env vars; all messages are forwarded to onMessage.
+ */
+
+import https from 'https';
+
+import { Api, Bot } from 'grammy';
+import pino from 'pino';
+
+import type {
+  ChannelProvider,
+  ChannelStatus,
+  ChatInfo,
+  IncomingMessage,
+} from '@deus-ai/channel-core';
+
+const ASSISTANT_NAME = process.env.ASSISTANT_NAME || 'Deus';
+const BOT_TOKEN = process.env.TELEGRAM_BOT_TOKEN || '';
+
+// Use stderr for logging (stdout is reserved for MCP JSON-RPC)
+const logger = pino(
+  { level: process.env.LOG_LEVEL || 'info' },
+  pino.destination(2),
+);
+
+const MAX_MESSAGE_LENGTH = 4096;
+const MAX_CONSECUTIVE_ERRORS = 5;
+const MAX_RECONNECT_RETRIES = 3;
+const BASE_BACKOFF_MS = 1000;
+
+/**
+ * Send a message with Telegram Markdown parse mode, falling back to plain text.
+ */
+async function sendTelegramMessage(
+  api: { sendMessage: Api['sendMessage'] },
+  chatId: string | number,
+  text: string,
+  options: { message_thread_id?: number } = {},
+): Promise<void> {
+  try {
+    await api.sendMessage(chatId, text, { ...options, parse_mode: 'Markdown' });
+  } catch {
+    await api.sendMessage(chatId, text, options);
+  }
+}
+
+export class TelegramProvider implements ChannelProvider {
+  readonly name = 'telegram';
+
+  private bot: Bot | null = null;
+  private connectTime = 0;
+  private knownChats = new Map<string, { name: string; isGroup: boolean }>();
+  private botUsername?: string;
+  private consecutiveErrors = 0;
+  private resetting = false;
+
+  // Set by server-base.ts
+  onMessage: (msg: IncomingMessage) => void = () => {};
+
+  async connect(): Promise<void> {
+    if (!BOT_TOKEN) {
+      throw new Error('TELEGRAM_BOT_TOKEN not set');
+    }
+
+    this.bot = new Bot(BOT_TOKEN, {
+      client: {
+        baseFetchConfig: { agent: https.globalAgent, compress: true },
+      },
+    });
+
+    // /chatid command for registration
+    this.bot.command('chatid', (ctx) => {
+      const chatId = ctx.chat.id;
+      const chatType = ctx.chat.type;
+      const chatName =
+        chatType === 'private'
+          ? ctx.from?.first_name || 'Private'
+          : (ctx.chat as any).title || 'Unknown';
+      ctx.reply(
+        `Chat ID: \`tg:${chatId}\`\nName: ${chatName}\nType: ${chatType}`,
+        { parse_mode: 'Markdown' },
+      );
+    });
+
+    this.bot.command('ping', (ctx) => {
+      ctx.reply(`${ASSISTANT_NAME} is online.`);
+    });
+
+    const BOT_COMMANDS = new Set(['chatid', 'ping']);
+
+    // Handle text messages
+    this.bot.on('message:text', async (ctx) => {
+      this.consecutiveErrors = 0;
+      if (ctx.message.text.startsWith('/')) {
+        const cmd = ctx.message.text.slice(1).split(/[\s@]/)[0].toLowerCase();
+        if (BOT_COMMANDS.has(cmd)) return;
+      }
+
+      const chatJid = `tg:${ctx.chat.id}`;
+      let content = ctx.message.text;
+      const timestamp = new Date(ctx.message.date * 1000).toISOString();
+      const senderName =
+        ctx.from?.first_name ||
+        ctx.from?.username ||
+        ctx.from?.id.toString() ||
+        'Unknown';
+      const sender = ctx.from?.id.toString() || '';
+      const msgId = ctx.message.message_id.toString();
+      const isGroup =
+        ctx.chat.type === 'group' || ctx.chat.type === 'supergroup';
+      const chatName =
+        ctx.chat.type === 'private'
+          ? senderName
+          : (ctx.chat as any).title || chatJid;
+
+      // Track chat
+      this.knownChats.set(chatJid, { name: chatName, isGroup });
+
+      // Translate @bot mentions to @AssistantName
+      const botUser = this.botUsername?.toLowerCase();
+      if (botUser) {
+        const entities = ctx.message.entities || [];
+        const isBotMentioned = entities.some((e) => {
+          if (e.type === 'mention') {
+            return (
+              content.substring(e.offset, e.offset + e.length).toLowerCase() ===
+              `@${botUser}`
+            );
+          }
+          return false;
+        });
+        if (isBotMentioned) {
+          content = `@${ASSISTANT_NAME} ${content}`;
+        }
+      }
+
+      // Reply context
+      const replyTo = ctx.message.reply_to_message;
+
+      // Forward ALL messages
+      this.onMessage({
+        id: msgId,
+        chat_id: chatJid,
+        sender,
+        sender_name: senderName,
+        content,
+        timestamp,
+        is_from_me: false,
+        is_group: isGroup,
+        chat_name: chatName,
+        metadata: {
+          thread_id: ctx.message.message_thread_id?.toString(),
+          reply_to_message_id: replyTo?.message_id?.toString(),
+          reply_to_content: replyTo?.text || replyTo?.caption,
+          reply_to_sender_name: replyTo
+            ? replyTo.from?.first_name ||
+              replyTo.from?.username ||
+              replyTo.from?.id?.toString()
+            : undefined,
+        },
+      });
+    });
+
+    // Handle media messages
+    const storeMedia = (ctx: any, placeholder: string) => {
+      const chatJid = `tg:${ctx.chat.id}`;
+      const timestamp = new Date(ctx.message.date * 1000).toISOString();
+      const senderName =
+        ctx.from?.first_name ||
+        ctx.from?.username ||
+        ctx.from?.id?.toString() ||
+        'Unknown';
+      const caption = ctx.message.caption ? ` ${ctx.message.caption}` : '';
+      const isGroup =
+        ctx.chat.type === 'group' || ctx.chat.type === 'supergroup';
+
+      this.knownChats.set(chatJid, {
+        name:
+          ctx.chat.type === 'private'
+            ? senderName
+            : (ctx.chat as any).title || chatJid,
+        isGroup,
+      });
+
+      this.onMessage({
+        id: ctx.message.message_id.toString(),
+        chat_id: chatJid,
+        sender: ctx.from?.id?.toString() || '',
+        sender_name: senderName,
+        content: `${placeholder}${caption}`,
+        timestamp,
+        is_from_me: false,
+        is_group: isGroup,
+      });
+    };
+
+    this.bot.on('message:photo', (ctx) => storeMedia(ctx, '[Photo]'));
+    this.bot.on('message:video', (ctx) => storeMedia(ctx, '[Video]'));
+    this.bot.on('message:voice', (ctx) => storeMedia(ctx, '[Voice message]'));
+    this.bot.on('message:audio', (ctx) => storeMedia(ctx, '[Audio]'));
+    this.bot.on('message:document', (ctx) => {
+      const name = ctx.message.document?.file_name || 'file';
+      storeMedia(ctx, `[Document: ${name}]`);
+    });
+    this.bot.on('message:sticker', (ctx) => {
+      const emoji = ctx.message.sticker?.emoji || '';
+      storeMedia(ctx, `[Sticker ${emoji}]`);
+    });
+    this.bot.on('message:location', (ctx) => storeMedia(ctx, '[Location]'));
+    this.bot.on('message:contact', (ctx) => storeMedia(ctx, '[Contact]'));
+
+    this.bot.catch((err) => {
+      this.consecutiveErrors++;
+      logger.error(
+        { err: err.message, consecutiveErrors: this.consecutiveErrors },
+        'Telegram bot error',
+      );
+
+      if (this.consecutiveErrors >= MAX_CONSECUTIVE_ERRORS && !this.resetting) {
+        this.resetPolling();
+      }
+    });
+
+    return new Promise<void>((resolve) => {
+      this.bot!.start({
+        onStart: (botInfo) => {
+          this.botUsername = botInfo.username;
+          this.connectTime = Date.now();
+          this.consecutiveErrors = 0;
+          logger.info(
+            { username: botInfo.username, id: botInfo.id },
+            'Telegram bot connected',
+          );
+          resolve();
+        },
+      });
+    });
+  }
+
+  /**
+   * Reset the polling session after consecutive errors.
+   * Retries with exponential backoff (1s, 2s, 4s), then exits on failure.
+   */
+  private async resetPolling(): Promise<void> {
+    if (!this.bot || this.resetting) return;
+    this.resetting = true;
+    logger.warn(
+      { consecutiveErrors: this.consecutiveErrors },
+      'Too many consecutive errors, resetting Telegram polling session',
+    );
+
+    const bot = this.bot;
+    bot.stop();
+    this.consecutiveErrors = 0;
+
+    for (let attempt = 0; attempt < MAX_RECONNECT_RETRIES; attempt++) {
+      const delayMs = BASE_BACKOFF_MS * Math.pow(2, attempt);
+      logger.info(
+        { attempt: attempt + 1, delayMs },
+        'Attempting polling reset with backoff',
+      );
+
+      await new Promise((r) => setTimeout(r, delayMs));
+
+      try {
+        await new Promise<void>((resolve, reject) => {
+          const timeout = setTimeout(() => {
+            reject(new Error('Polling restart timed out'));
+          }, 30_000);
+
+          bot.start({
+            onStart: (botInfo) => {
+              clearTimeout(timeout);
+              this.botUsername = botInfo.username;
+              this.connectTime = Date.now();
+              this.resetting = false;
+              this.consecutiveErrors = 0;
+              logger.info(
+                { username: botInfo.username, id: botInfo.id },
+                'Telegram bot reconnected after polling reset',
+              );
+              resolve();
+            },
+          });
+        });
+        return; // Success — exit retry loop
+      } catch (err) {
+        logger.error(
+          { attempt: attempt + 1, err },
+          'Polling reset attempt failed',
+        );
+        bot.stop();
+      }
+    }
+
+    logger.fatal(
+      'Telegram bot failed to reconnect after %d retries — exiting',
+      MAX_RECONNECT_RETRIES,
+    );
+    process.exit(1);
+  }
+
+  async sendMessage(chatId: string, text: string): Promise<void> {
+    if (!this.bot) return;
+    try {
+      const numericId = chatId.replace(/^tg:/, '');
+      if (text.length <= MAX_MESSAGE_LENGTH) {
+        await sendTelegramMessage(this.bot.api, numericId, text);
+      } else {
+        for (let i = 0; i < text.length; i += MAX_MESSAGE_LENGTH) {
+          await sendTelegramMessage(
+            this.bot.api,
+            numericId,
+            text.slice(i, i + MAX_MESSAGE_LENGTH),
+          );
+        }
+      }
+    } catch (err) {
+      logger.error({ chatId, err }, 'Failed to send Telegram message');
+    }
+  }
+
+  isConnected(): boolean {
+    return this.bot !== null;
+  }
+
+  getStatus(): ChannelStatus {
+    return {
+      connected: this.bot !== null,
+      channel: 'telegram',
+      identity: this.botUsername,
+      uptime_seconds: this.connectTime
+        ? Math.floor((Date.now() - this.connectTime) / 1000)
+        : 0,
+    };
+  }
+
+  async disconnect(): Promise<void> {
+    if (this.bot) {
+      this.resetting = false;
+      this.consecutiveErrors = 0;
+      this.bot.stop();
+      this.bot = null;
+      logger.info('Telegram bot stopped');
+    }
+  }
+
+  async setTyping(chatId: string, isTyping: boolean): Promise<void> {
+    if (!this.bot || !isTyping) return;
+    try {
+      const numericId = chatId.replace(/^tg:/, '');
+      await this.bot.api.sendChatAction(numericId, 'typing');
+    } catch {
+      // Best effort
+    }
+  }
+
+  async listChats(): Promise<ChatInfo[]> {
+    return Array.from(this.knownChats.entries()).map(([id, info]) => ({
+      id,
+      name: info.name,
+      is_group: info.isGroup,
+    }));
+  }
+
+  /** Check if a bot token is configured. */
+  hasToken(): boolean {
+    return !!BOT_TOKEN;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}