@mseep/telegram-api-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 timoncool
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,247 @@
+<div align="center">
+
+# telegram-api-mcp
+
+**Ultimate MCP server for Telegram Bot API — 169 methods, full v9.6 coverage, meta-mode, rate limiting, circuit breaker.**
+
+[![Stars](https://img.shields.io/github/stars/timoncool/telegram-api-mcp?style=flat-square)](https://github.com/timoncool/telegram-api-mcp/stargazers)
+[![npm](https://img.shields.io/npm/v/telegram-api-mcp?style=flat-square)](https://www.npmjs.com/package/telegram-api-mcp)
+[![License](https://img.shields.io/github/license/timoncool/telegram-api-mcp?style=flat-square)](LICENSE)
+[![Bot API](https://img.shields.io/badge/Telegram%20Bot%20API-9.6-26A5E4?style=flat-square&logo=telegram)](https://core.telegram.org/bots/api)
+[![TRAIL](https://img.shields.io/badge/TRAIL-v2.1-6366f1?style=flat-square)](https://github.com/timoncool/trail-spec)
+
+</div>
+
+169/169 Bot API methods with Zod validation, token masking, tool annotations, and zero bloat (2 dependencies).
+
+## Features
+
+- **169/169 Bot API methods** — messages, media, polls, chats, forums, stickers, payments, business, stories, gifts, games, inline, managed bots
+- **Bot API 9.6** (April 2026) — managed bots, revoting polls, shuffle options, poll descriptions
+- **Meta-mode** — 2 tools instead of 169, saves ~99% context tokens
+- **Rate limiting** — global (30 req/sec) + per-chat (20 msg/min), token bucket with async mutex
+- **Circuit breaker** — 3-state (closed/open/half-open), auto-recovery
+- **Retry with backoff** — respects Telegram 429 `retry_after`, exponential backoff on 5xx
+- **Zod validation** — every parameter validated before hitting Telegram API
+- **Token masking** — bot token never appears in responses, logs, or error messages
+- **File upload security** — path traversal protection, configurable allowed directories
+- **Tool annotations** — all 169 methods annotated (readOnly, destructive, idempotent, openWorld)
+- **Response truncation** — 100K char limit to prevent context overflow
+- **Zero bloat** — only 2 dependencies: `@modelcontextprotocol/sdk` + `zod`
+
+## Quick Start
+
+### Claude Code
+
+```bash
+claude mcp add telegram -- npx telegram-api-mcp -e TELEGRAM_BOT_TOKEN=your_token
+```
+
+With meta-mode (recommended for large conversations):
+
+```bash
+claude mcp add telegram -- npx telegram-api-mcp \
+  -e TELEGRAM_BOT_TOKEN=your_token \
+  -e TELEGRAM_META_MODE=true
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "telegram": {
+      "command": "npx",
+      "args": ["telegram-api-mcp"],
+      "env": {
+        "TELEGRAM_BOT_TOKEN": "your_token_from_botfather"
+      }
+    }
+  }
+}
+```
+
+### With default chat (skip chat_id in every call)
+
+```json
+{
+  "mcpServers": {
+    "telegram": {
+      "command": "npx",
+      "args": ["telegram-api-mcp"],
+      "env": {
+        "TELEGRAM_BOT_TOKEN": "your_token",
+        "TELEGRAM_DEFAULT_CHAT_ID": "-1001234567890"
+      }
+    }
+  }
+}
+```
+
+### From source
+
+```bash
+git clone https://github.com/timoncool/telegram-api-mcp.git
+cd telegram-api-mcp
+npm install && npm run build
+TELEGRAM_BOT_TOKEN=your_token node dist/index.js
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|:---:|:---:|-------------|
+| `TELEGRAM_BOT_TOKEN` | **Yes** | — | Bot token from [@BotFather](https://t.me/BotFather) |
+| `TELEGRAM_DEFAULT_CHAT_ID` | No | — | Default chat ID for all tools |
+| `TELEGRAM_DEFAULT_THREAD_ID` | No | — | Default forum topic thread ID |
+| `TELEGRAM_META_MODE` | No | `false` | Use 2 meta-tools instead of 169 |
+| `TELEGRAM_GLOBAL_RATE_LIMIT` | No | `30` | Max requests/sec ([Telegram limit](https://core.telegram.org/bots/faq#my-bot-is-hitting-limits)) |
+| `TELEGRAM_PER_CHAT_RATE_LIMIT` | No | `20` | Max messages/min per group ([Telegram limit](https://core.telegram.org/bots/faq#my-bot-is-hitting-limits)) |
+| `TELEGRAM_MAX_RETRIES` | No | `3` | Retry attempts on transient errors |
+| `TELEGRAM_CB_THRESHOLD` | No | `5` | Failures before circuit opens |
+| `TELEGRAM_CB_COOLDOWN` | No | `30000` | Circuit breaker cooldown (ms) |
+| `TELEGRAM_ALLOWED_UPLOAD_DIRS` | No | — | Comma-separated allowed upload paths |
+| `TELEGRAM_MAX_FILE_SIZE` | No | `52428800` | Max upload file size (50MB) |
+
+## Meta Mode
+
+When `TELEGRAM_META_MODE=true`, the server exposes only 2 tools instead of 169:
+
+- **`telegram_find`** — search methods by keyword or category
+- **`telegram_call`** — call any method by name with JSON params
+
+This saves ~99% of context tokens while keeping full API access:
+
+```
+User: "Post a poll in my channel"
+AI: → telegram_find(query: "poll")
+AI: → telegram_call(method: "sendPoll", params: { chat_id: ..., question: "...", options: [...] })
+```
+
+## API Coverage
+
+169/169 methods — **100% Bot API 9.6** (April 2026)
+
+| Category | Count | Key methods |
+|----------|:---:|-------------|
+| Bot | 21 | getMe, setMyCommands, setMyProfilePhoto, getFile, getUserProfilePhotos |
+| Stickers | 16 | sendSticker, createNewStickerSet, uploadStickerFile, setStickerKeywords |
+| Chat | 15 | getChat, setChatTitle, setChatPermissions, pinChatMessage, leaveChat |
+| Business | 14 | readBusinessMessage, setBusinessAccountName, getBusinessConnection |
+| Forum | 13 | createForumTopic, editForumTopic, closeForumTopic, deleteForumTopic |
+| Editing | 10 | editMessageText, editMessageMedia, deleteMessage, deleteMessages, stopPoll |
+| Messages | 9 | sendMessage, sendMessageDraft, sendLocation, sendContact, sendChecklist |
+| Media | 9 | sendPhoto, sendVideo, sendAudio, sendDocument, sendMediaGroup, sendPaidMedia |
+| Members | 9 | banChatMember, promoteChatMember, setChatMemberTag, restrictChatMember |
+| Invite | 8 | createChatInviteLink, createChatSubscriptionInviteLink, approveChatJoinRequest |
+| Payments | 8 | sendInvoice, createInvoiceLink, getStarTransactions, getMyStarBalance |
+| Gifts | 8 | sendGift, getUserGifts, getChatGifts, giftPremiumSubscription, upgradeGift |
+| Other | 5 | verifyUser, verifyChat, setUserEmojiStatus, savePreparedInlineMessage |
+| Forwarding | 4 | forwardMessage, forwardMessages, copyMessage, copyMessages |
+| Stories | 4 | postStory, editStory, deleteStory, repostStory |
+| Inline | 4 | answerInlineQuery, answerCallbackQuery, answerWebAppQuery, savePreparedInlineMessage |
+| Updates | 4 | getUpdates, setWebhook, deleteWebhook, getWebhookInfo |
+| Games | 3 | sendGame, setGameScore, getGameHighScores |
+| Managed Bots | 3 | getManagedBotToken, replaceManagedBotToken, savePreparedKeyboardButton |
+| Polls | 1 | sendPoll (v9.6: revoting, shuffle, multiple correct, descriptions) |
+| Passport | 1 | setPassportDataErrors |
+
+## Architecture
+
+```
+src/
+├── index.ts              # Entry point
+├── config.ts             # Environment config with validation
+├── server.ts             # MCP server (standard + meta mode)
+├── telegram-client.ts    # HTTP client with retry, rate limit, circuit breaker
+├── rate-limiter.ts       # Token bucket: global + per-chat
+├── circuit-breaker.ts    # 3-state circuit breaker (closed/open/half-open)
+├── method-registry.ts    # Declarative method definitions + Zod schema builder
+└── methods/
+    ├── index.ts          # Aggregator + search
+    ├── messages.ts       # sendMessage, sendDice, sendChecklist, ...
+    ├── forwarding.ts     # forwardMessage, copyMessage, ...
+    ├── editing.ts        # editMessageText, deleteMessage, ...
+    ├── chat.ts           # getChat, setChatTitle, banChatMember, ...
+    ├── bot.ts            # getMe, setMyCommands, getFile, ...
+    ├── forum.ts          # createForumTopic, editForumTopic, ...
+    ├── stickers.ts       # sendSticker, createNewStickerSet, ...
+    ├── payments.ts       # sendInvoice, getStarTransactions, ...
+    ├── business.ts       # readBusinessMessage, setBusinessAccount*, ...
+    ├── stories.ts        # postStory, editStory, deleteStory, ...
+    ├── gifts.ts          # sendGift, getUserGifts, convertGiftToStars, ...
+    ├── games.ts          # sendGame, setGameScore, ...
+    ├── inline.ts         # answerInlineQuery, answerCallbackQuery
+    ├── managed-bots.ts   # getManagedBotToken, replaceManagedBotToken
+    ├── updates.ts        # getUpdates, setWebhook, ...
+    ├── passport.ts       # setPassportDataErrors
+    └── other.ts          # verifyUser, setChatMenuButton, ...
+```
+
+### Design principles
+
+- **Declarative registry** — each method is pure data (name, params, types, annotations). One generic handler serves all 169 methods. Adding a new method = one array entry.
+- **Zod validation** — every parameter validated before reaching Telegram. Clear error messages with hints instead of opaque API 400s.
+- **Token bucket rate limiting** — no race conditions (async mutex). Defaults match [Telegram's official limits](https://core.telegram.org/bots/faq#my-bot-is-hitting-limits): 30 req/sec global, 20 msg/min per group.
+- **Circuit breaker** — 429 (rate limit) is NOT counted as failure. Only real errors (5xx, network) trip the breaker. Half-open probe recovers automatically.
+- **Tool annotations** — every method has MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) so AI clients know which tools are safe to auto-approve.
+- **Response truncation** — responses capped at 100K chars to prevent context window overflow.
+
+## Security
+
+- Bot token never appears in MCP tool responses or error messages (masked as `***`)
+- File upload paths validated against allowed directories (`TELEGRAM_ALLOWED_UPLOAD_DIRS`)
+- Path traversal attacks blocked (resolve + normalize + separator check)
+- No `eval()`, no `Function()`, no dynamic imports
+- No external requests except `api.telegram.org`
+- No telemetry, no analytics, no phone-home
+- Zero bloat: only 2 runtime dependencies (`@modelcontextprotocol/sdk` + `zod`)
+
+## Development
+
+```bash
+npm install
+npm run build         # TypeScript compilation
+npm run typecheck     # Type checking without emit
+npm test              # Run all tests (vitest)
+npm run test:watch    # Watch mode
+npm run lint          # ESLint
+```
+
+## Other Projects by [@timoncool](https://github.com/timoncool)
+
+| Project | Description |
+|---------|-------------|
+| [civitai-mcp-ultimate](https://github.com/timoncool/civitai-mcp-ultimate) | Civitai API as MCP server |
+| [trail-spec](https://github.com/timoncool/trail-spec) | TRAIL — cross-MCP content tracking protocol |
+| [ACE-Step Studio](https://github.com/timoncool/ACE-Step-Studio) | AI music studio — songs, vocals, covers, videos |
+| [VideoSOS](https://github.com/timoncool/videosos) | AI video production in the browser |
+| [tg-challenge-bot](https://github.com/timoncool/tg-challenge-bot) | AI anti-spam bot for Telegram |
+| [Bulka](https://github.com/timoncool/Bulka) | Live-coding music platform |
+
+## Support the Author
+
+I build open-source software and do AI research. Most of what I create is free and available to everyone. Your donations help me keep creating without worrying about where the next meal comes from =)
+
+**[All donation methods](https://github.com/timoncool/ACE-Step-Studio/blob/master/DONATE.md)** | **[dalink.to/nerual_dreming](https://dalink.to/nerual_dreming)** | **[boosty.to/neuro_art](https://boosty.to/neuro_art)**
+
+- **BTC:** `1E7dHL22RpyhJGVpcvKdbyZgksSYkYeEBC`
+- **ETH (ERC20):** `0xb5db65adf478983186d4897ba92fe2c25c594a0c`
+- **USDT (TRC20):** `TQST9Lp2TjK6FiVkn4fwfGUee7NmkxEE7C`
+
+
+## Star History
+
+<a href="https://www.star-history.com/?repos=timoncool%2Ftelegram-api-mcp&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=timoncool/telegram-api-mcp&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=timoncool/telegram-api-mcp&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=timoncool/telegram-api-mcp&type=date&legend=top-left" />
+ </picture>
+</a>
+
+## License
+
+MIT

package/dist/circuit-breaker.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Circuit breaker to prevent cascading failures when Telegram API is down.
+ *
+ * States:
+ * - CLOSED: normal operation, requests pass through
+ * - OPEN: too many failures, requests fail immediately
+ * - HALF_OPEN: cooldown expired, allow one probe request
+ *
+ * 429 (rate limit) does NOT count as a failure — it's expected behavior.
+ */
+export type CircuitState = "closed" | "open" | "half_open";
+export declare class CircuitBreaker {
+    private state;
+    private failureCount;
+    private lastFailureTime;
+    private threshold;
+    private cooldownMs;
+    constructor(threshold: number, cooldownMs: number);
+    /** Check if request is allowed. Throws if circuit is open. */
+    check(): void;
+    /** Record a successful response. Resets the breaker. */
+    recordSuccess(): void;
+    /**
+     * Record a failure. Does NOT count 429 as failure.
+     * Returns true if the circuit just opened.
+     */
+    recordFailure(statusCode?: number): boolean;
+    getState(): CircuitState;
+    getFailureCount(): number;
+}
+export declare class CircuitOpenError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../src/circuit-breaker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,UAAU,CAAS;gBAEf,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;IAKjD,8DAA8D;IAC9D,KAAK,IAAI,IAAI;IAiBb,wDAAwD;IACxD,aAAa,IAAI,IAAI;IAKrB;;;OAGG;IACH,aAAa,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO;IAqB3C,QAAQ,IAAI,YAAY;IAIxB,eAAe,IAAI,MAAM;CAG1B;AAED,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI5B"}

package/dist/circuit-breaker.js

@@ -0,0 +1,64 @@
+export class CircuitBreaker {
+    state = "closed";
+    failureCount = 0;
+    lastFailureTime = 0;
+    threshold;
+    cooldownMs;
+    constructor(threshold, cooldownMs) {
+        this.threshold = threshold;
+        this.cooldownMs = cooldownMs;
+    }
+    /** Check if request is allowed. Throws if circuit is open. */
+    check() {
+        if (this.state === "closed")
+            return;
+        if (this.state === "open") {
+            if (Date.now() - this.lastFailureTime >= this.cooldownMs) {
+                this.state = "half_open";
+                return; // Allow probe request
+            }
+            throw new CircuitOpenError(`Circuit breaker is OPEN. ${this.failureCount} consecutive failures. ` +
+                `Will retry in ${Math.ceil((this.cooldownMs - (Date.now() - this.lastFailureTime)) / 1000)}s.`);
+        }
+        // half_open — allow through
+    }
+    /** Record a successful response. Resets the breaker. */
+    recordSuccess() {
+        this.failureCount = 0;
+        this.state = "closed";
+    }
+    /**
+     * Record a failure. Does NOT count 429 as failure.
+     * Returns true if the circuit just opened.
+     */
+    recordFailure(statusCode) {
+        // 429 is rate limiting, not a server failure
+        if (statusCode === 429)
+            return false;
+        this.failureCount++;
+        this.lastFailureTime = Date.now();
+        // In half_open, any failure immediately reopens
+        if (this.state === "half_open") {
+            this.state = "open";
+            return true;
+        }
+        if (this.failureCount >= this.threshold) {
+            this.state = "open";
+            return true;
+        }
+        return false;
+    }
+    getState() {
+        return this.state;
+    }
+    getFailureCount() {
+        return this.failureCount;
+    }
+}
+export class CircuitOpenError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CircuitOpenError";
+    }
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/circuit-breaker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.js","sourceRoot":"","sources":["../src/circuit-breaker.ts"],"names":[],"mappings":"AAYA,MAAM,OAAO,cAAc;IACjB,KAAK,GAAiB,QAAQ,CAAC;IAC/B,YAAY,GAAG,CAAC,CAAC;IACjB,eAAe,GAAG,CAAC,CAAC;IACpB,SAAS,CAAS;IAClB,UAAU,CAAS;IAE3B,YAAY,SAAiB,EAAE,UAAkB;QAC/C,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;IAED,8DAA8D;IAC9D,KAAK;QACH,IAAI,IAAI,CAAC,KAAK,KAAK,QAAQ;YAAE,OAAO;QAEpC,IAAI,IAAI,CAAC,KAAK,KAAK,MAAM,EAAE,CAAC;YAC1B,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;gBACzD,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC;gBACzB,OAAO,CAAC,sBAAsB;YAChC,CAAC;YACD,MAAM,IAAI,gBAAgB,CACxB,4BAA4B,IAAI,CAAC,YAAY,yBAAyB;gBACpE,iBAAiB,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,UAAU,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CACjG,CAAC;QACJ,CAAC;QAED,4BAA4B;IAC9B,CAAC;IAED,wDAAwD;IACxD,aAAa;QACX,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;QACtB,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC;IACxB,CAAC;IAED;;;OAGG;IACH,aAAa,CAAC,UAAmB;QAC/B,6CAA6C;QAC7C,IAAI,UAAU,KAAK,GAAG;YAAE,OAAO,KAAK,CAAC;QAErC,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAElC,gDAAgD;QAChD,IAAI,IAAI,CAAC,KAAK,KAAK,WAAW,EAAE,CAAC;YAC/B,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC;YACpB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACxC,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC;YACpB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,eAAe;QACb,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;CACF;AAED,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACzC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF"}

package/dist/config.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Server configuration from environment variables.
+ */
+export interface Config {
+    /** Telegram Bot token from @BotFather */
+    botToken: string;
+    /** Default chat_id for all tools (optional) */
+    defaultChatId?: string;
+    /** Default message_thread_id for forum topics (optional) */
+    defaultThreadId?: number;
+    /** Global rate limit: max requests per second (default: 30, Telegram FAQ limit) */
+    globalRateLimit: number;
+    /** Per-chat rate limit: max messages per minute to same group (default: 20, Telegram FAQ limit) */
+    perChatRateLimit: number;
+    /** Max retry attempts on transient errors (default: 3) */
+    maxRetries: number;
+    /** Circuit breaker: consecutive failures to open circuit (default: 5) */
+    circuitBreakerThreshold: number;
+    /** Circuit breaker: cooldown in ms before half-open (default: 30000) */
+    circuitBreakerCooldown: number;
+    /** Allowed directories for file uploads (comma-separated, empty = no restriction) */
+    allowedUploadDirs: string[];
+    /** Max file size in bytes (default: 50MB) */
+    maxFileSize: number;
+    /** Run in meta-mode with 2 tools instead of all (default: false) */
+    metaMode: boolean;
+}
+export declare function loadConfig(): Config;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mFAAmF;IACnF,eAAe,EAAE,MAAM,CAAC;IACxB,mGAAmG;IACnG,gBAAgB,EAAE,MAAM,CAAC;IACzB,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,uBAAuB,EAAE,MAAM,CAAC;IAChC,wEAAwE;IACxE,sBAAsB,EAAE,MAAM,CAAC;IAC/B,qFAAqF;IACrF,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,UAAU,IAAI,MAAM,CAyBnC"}

package/dist/config.js

@@ -0,0 +1,22 @@
+export function loadConfig() {
+    const token = process.env.TELEGRAM_BOT_TOKEN;
+    if (!token) {
+        throw new Error("TELEGRAM_BOT_TOKEN is required. Get one from @BotFather: https://t.me/BotFather");
+    }
+    const threadId = process.env.TELEGRAM_DEFAULT_THREAD_ID;
+    const uploadDirs = process.env.TELEGRAM_ALLOWED_UPLOAD_DIRS;
+    return {
+        botToken: token,
+        defaultChatId: process.env.TELEGRAM_DEFAULT_CHAT_ID || undefined,
+        defaultThreadId: threadId ? parseInt(threadId, 10) : undefined,
+        globalRateLimit: parseInt(process.env.TELEGRAM_GLOBAL_RATE_LIMIT || "30", 10),
+        perChatRateLimit: parseInt(process.env.TELEGRAM_PER_CHAT_RATE_LIMIT || "20", 10),
+        maxRetries: parseInt(process.env.TELEGRAM_MAX_RETRIES || "3", 10),
+        circuitBreakerThreshold: parseInt(process.env.TELEGRAM_CB_THRESHOLD || "5", 10),
+        circuitBreakerCooldown: parseInt(process.env.TELEGRAM_CB_COOLDOWN || "30000", 10),
+        allowedUploadDirs: uploadDirs ? uploadDirs.split(",").map((d) => d.trim()) : [],
+        maxFileSize: parseInt(process.env.TELEGRAM_MAX_FILE_SIZE || String(50 * 1024 * 1024), 10),
+        metaMode: process.env.TELEGRAM_META_MODE === "true",
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AA4BA,MAAM,UAAU,UAAU;IACxB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;IAC7C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,iFAAiF,CAClF,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,0BAA0B,CAAC;IAExD,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,4BAA4B,CAAC;IAE5D,OAAO;QACL,QAAQ,EAAE,KAAK;QACf,aAAa,EAAE,OAAO,CAAC,GAAG,CAAC,wBAAwB,IAAI,SAAS;QAChE,eAAe,EAAE,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS;QAC9D,eAAe,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,0BAA0B,IAAI,IAAI,EAAE,EAAE,CAAC;QAC7E,gBAAgB,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,4BAA4B,IAAI,IAAI,EAAE,EAAE,CAAC;QAChF,UAAU,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,IAAI,GAAG,EAAE,EAAE,CAAC;QACjE,uBAAuB,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,qBAAqB,IAAI,GAAG,EAAE,EAAE,CAAC;QAC/E,sBAAsB,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,IAAI,OAAO,EAAE,EAAE,CAAC;QACjF,iBAAiB,EAAE,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE;QAC/E,WAAW,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,sBAAsB,IAAI,MAAM,CAAC,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC,EAAE,EAAE,CAAC;QACzF,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,kBAAkB,KAAK,MAAM;KACpD,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { loadConfig } from "./config.js";
+import { startServer } from "./server.js";
+async function main() {
+    try {
+        const config = loadConfig();
+        await startServer(config);
+    }
+    catch (error) {
+        process.stderr.write(`Fatal: ${error.message}\n`);
+        process.exit(1);
+    }
+}
+main();
+//# 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,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,KAAK,UAAU,IAAI;IACjB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;QAC5B,MAAM,WAAW,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,UAAW,KAAe,CAAC,OAAO,IAAI,CAAC,CAAC;QAC7D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC"}

package/dist/method-registry.d.ts

@@ -0,0 +1,78 @@
+import { z, ZodTypeAny } from "zod";
+/**
+ * Declarative method definition.
+ * Each Bot API method is described as data — not as a handler.
+ * The MCP server auto-generates tools from these definitions.
+ */
+export interface MethodDef {
+    /** Telegram Bot API method name (camelCase) */
+    apiMethod: string;
+    /** MCP tool name (snake_case) */
+    toolName: string;
+    /** Human-readable description for AI agents */
+    description: string;
+    /** Category for grouping and meta-mode search */
+    category: MethodCategory;
+    /** Parameter definitions */
+    params: ParamDef[];
+    /** Does this method need chat_id? (for rate limiting and defaults) */
+    needsChatId: boolean;
+    /** Can this method upload files? */
+    canUploadFiles: boolean;
+    /** Return type description */
+    returns: string;
+    /** MCP tool annotations — hints for clients about tool behavior */
+    annotations?: ToolAnnotations;
+}
+/** MCP Tool Annotations per spec 2025-06-18 */
+export interface ToolAnnotations {
+    /** Tool only reads data, doesn't modify anything */
+    readOnlyHint?: boolean;
+    /** Tool may perform destructive/irreversible actions (default: true!) */
+    destructiveHint?: boolean;
+    /** Calling with same args gives same result */
+    idempotentHint?: boolean;
+    /** Tool interacts with external entities */
+    openWorldHint?: boolean;
+}
+/** Common annotation presets for DRY */
+export declare const ANNOTATIONS: {
+    /** GET methods — read only, no side effects */
+    readonly readOnly: ToolAnnotations;
+    /** SEND methods — create content, not destructive */
+    readonly send: ToolAnnotations;
+    /** SET/EDIT methods — modify existing, idempotent */
+    readonly modify: ToolAnnotations;
+    /** DELETE/BAN methods — destructive, irreversible */
+    readonly destructive: ToolAnnotations;
+};
+export type MethodCategory = "updates" | "bot" | "messages" | "editing" | "forwarding" | "media" | "polls" | "chat" | "members" | "invite" | "forum" | "stickers" | "inline" | "payments" | "business" | "stories" | "gifts" | "games" | "passport" | "managed_bots" | "other";
+export interface ParamDef {
+    /** Parameter name as in Bot API */
+    name: string;
+    /** Zod type for validation */
+    type: ZodTypeAny;
+    /** Is this parameter required? */
+    required: boolean;
+    /** Human-readable description */
+    description: string;
+}
+export declare const ChatId: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
+export declare const MessageId: z.ZodNumber;
+export declare const UserId: z.ZodNumber;
+export declare const Text: z.ZodString;
+export declare const Caption: z.ZodString;
+export declare const ParseMode: z.ZodEnum<["HTML", "Markdown", "MarkdownV2"]>;
+export declare const FileInput: z.ZodString;
+export declare const ReplyMarkup: z.ZodAny;
+export declare const ReplyParameters: z.ZodAny;
+export declare const MessageEntities: z.ZodAny;
+export declare const LinkPreviewOptions: z.ZodAny;
+export declare const BooleanFlag: z.ZodBoolean;
+export declare const PositiveInt: z.ZodNumber;
+export declare function commonSendParams(): ParamDef[];
+export declare function commonMediaParams(): ParamDef[];
+export declare function commonEditParams(): ParamDef[];
+export declare function buildZodSchema(params: ParamDef[]): z.ZodObject<Record<string, ZodTypeAny>>;
+export declare function buildJsonSchema(params: ParamDef[]): Record<string, unknown>;
+//# sourceMappingURL=method-registry.d.ts.map

package/dist/method-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"method-registry.d.ts","sourceRoot":"","sources":["../src/method-registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AAEpC;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,QAAQ,EAAE,cAAc,CAAC;IACzB,4BAA4B;IAC5B,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnB,sEAAsE;IACtE,WAAW,EAAE,OAAO,CAAC;IACrB,oCAAoC;IACpC,cAAc,EAAE,OAAO,CAAC;IACxB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B;AAED,+CAA+C;AAC/C,MAAM,WAAW,eAAe;IAC9B,oDAAoD;IACpD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,yEAAyE;IACzE,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,+CAA+C;IAC/C,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,4CAA4C;IAC5C,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,wCAAwC;AACxC,eAAO,MAAM,WAAW;IACtB,+CAA+C;uBACwD,eAAe;IACtH,qDAAqD;mBACgD,eAAe;IACpH,qDAAqD;qBACiD,eAAe;IACrH,qDAAqD;0BACsD,eAAe;CAClH,CAAC;AAEX,MAAM,MAAM,cAAc,GACtB,SAAS,GACT,KAAK,GACL,UAAU,GACV,SAAS,GACT,YAAY,GACZ,OAAO,GACP,OAAO,GACP,MAAM,GACN,SAAS,GACT,QAAQ,GACR,OAAO,GACP,UAAU,GACV,QAAQ,GACR,UAAU,GACV,UAAU,GACV,SAAS,GACT,OAAO,GACP,OAAO,GACP,UAAU,GACV,cAAc,GACd,OAAO,CAAC;AAEZ,MAAM,WAAW,QAAQ;IACvB,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,IAAI,EAAE,UAAU,CAAC;IACjB,kCAAkC;IAClC,QAAQ,EAAE,OAAO,CAAC;IAClB,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;CACrB;AAID,eAAO,MAAM,MAAM,wCAA2E,CAAC;AAC/F,eAAO,MAAM,SAAS,aAA0C,CAAC;AACjE,eAAO,MAAM,MAAM,aAAuC,CAAC;AAC3D,eAAO,MAAM,IAAI,aAAsE,CAAC;AACxF,eAAO,MAAM,OAAO,aAA0D,CAAC;AAC/E,eAAO,MAAM,SAAS,+CAAyE,CAAC;AAChG,eAAO,MAAM,SAAS,aAAkE,CAAC;AACzF,eAAO,MAAM,WAAW,UAAoG,CAAC;AAC7H,eAAO,MAAM,eAAe,UAA6C,CAAC;AAC1E,eAAO,MAAM,eAAe,UAAqD,CAAC;AAClF,eAAO,MAAM,kBAAkB,UAAgD,CAAC;AAChF,eAAO,MAAM,WAAW,cAAc,CAAC;AACvC,eAAO,MAAM,WAAW,aAA8B,CAAC;AAIvD,wBAAgB,gBAAgB,IAAI,QAAQ,EAAE,CAW7C;AAED,wBAAgB,iBAAiB,IAAI,QAAQ,EAAE,CAM9C;AAED,wBAAgB,gBAAgB,IAAI,QAAQ,EAAE,CAO7C;AAID,wBAAgB,cAAc,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAQ1F;AAID,wBAAgB,eAAe,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgB3E"}