@overpod/mcp-telegram 1.34.0 → 1.36.0

package/CHANGELOG.md

@@ -5,6 +5,89 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.36.0] — 2026-04-28
+
+### Added
+
+**Tool manifest export — introspect the catalog without standing up an MCP transport.**
+
+A new `@overpod/mcp-telegram/manifest` subpath export and `mcp-telegram-manifest` bin entry let consumers (and downstream cloud distributions) ask the package "what tools do you register, and at what risk tier?" without booting a real Telegram session.
+
+```ts
+import { getToolManifest } from "@overpod/mcp-telegram/manifest";
+
+const m = getToolManifest();
+// {
+//   generatedAt: "2026-04-28T...Z",
+//   toolCount: 181,
+//   tiers: { "read-only": 74, write: 96, destructive: 11 },
+//   tools: [{ name: "telegram-status", tier: "read-only", description: "...", hasInput: false }, ...]
+// }
+```
+
+CLI variant:
+
+```bash
+mcp-telegram-manifest                # writes manifest.json
+mcp-telegram-manifest path/out.json  # writes to path/out.json
+mcp-telegram-manifest -               # writes JSON to stdout
+```
+
+How it works: instantiates an `McpServer`, calls the existing `registerTools()` with a stub service (only types matter — every `telegram.*` call lives inside async tool callbacks, not the registration phase), then introspects the SDK's registered tools and classifies each by `annotations`:
+
+- `destructiveHint: true` → `destructive`
+- `readOnlyHint: true` → `read-only`
+- otherwise → `write`
+
+Opt-in env flags (`MCP_TELEGRAM_ENABLE_STARS`, `MCP_TELEGRAM_ENABLE_GROUP_CALLS`, `MCP_TELEGRAM_ENABLE_QUICK_REPLIES`) are forced ON during introspection so consumers always see the full catalog, then restored to the caller's prior values. The result is cached for the process lifetime.
+
+This is the foundation for upstream parity gates (e.g. cloud distributions that ship a curated whitelist can detect drift in CI by comparing their whitelist against `getToolManifest().tools`).
+
+### Notes
+
+- New public API surface; no breaking changes to existing exports.
+- `src/manifest.ts` and 13 new tests added; total test count: 505.
+- Build now sets executable bits on all `dist/*-cli.js` outputs (was npm-install-time only for `bin` entries).
+
+## [1.35.0] — 2026-04-25
+
+### Changed
+
+**Rate limiter — structured stderr events for retries.**
+
+The internal `RateLimiter` previously logged `FLOOD_WAIT` and network retries as
+human-readable strings via `console.error`, and the temporary-server-error
+branch (5xx, etc.) was silent. All three retry branches now emit a single
+structured stderr line per event:
+
+```
+[rate-limiter] event {"event":"flood_wait","context":"list-chats","seconds":30,"attempt":1,"maxRetries":3}
+```
+
+Event types: `flood_wait`, `network_retry`, `temporary_retry`. Each event
+carries:
+
+- `event` — event class (string literal)
+- `context` — caller-supplied operation name (never user input / PII)
+- `attempt` / `maxRetries` — retry counters
+- `seconds` (flood_wait only) or `delayMs` (network/temporary)
+- `error` (network/temporary only) — the upstream Telegram error message
+
+This is a logging contract change, not a behaviour change: retry timing,
+backoff, and error-throwing semantics are identical to 1.34.0.
+
+### Why this matters
+
+Downstream log collectors can now aggregate retry rates by event class and
+caller without parsing free-form English. `mcp-telegram-cloud` v1.12.0+ wires
+this into SigNoz directly. Self-hosters can `grep '\[rate-limiter\] event'` or
+pipe into any structured log pipeline.
+
+### Compatibility
+
+No breaking changes. No new dependencies. No new environment variables.
+Tests: 490/490 pass.
+
 ## [1.34.0] — 2026-04-24
 
 ### Added

package/dist/manifest.d.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+export type ToolTier = "read-only" | "write" | "destructive";
+export interface ToolManifestEntry {
+    name: string;
+    tier: ToolTier;
+    description: string;
+    hasInput: boolean;
+}
+export interface ToolManifest {
+    generatedAt: string;
+    toolCount: number;
+    tiers: {
+        "read-only": number;
+        write: number;
+        destructive: number;
+    };
+    tools: ToolManifestEntry[];
+}
+/**
+ * Build a manifest of every tool the package can register. Forces all opt-in
+ * env flags ON during introspection so consumers see the full catalog, not
+ * the runtime-filtered subset. Cached for the process lifetime — invocations
+ * are cheap and idempotent.
+ */
+export declare function getToolManifest(): ToolManifest;
+/** Test-only: discard cache and force a fresh introspection. */
+export declare function _resetManifestCache(): void;

package/dist/manifest.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+import { writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerTools } from "./tools/index.js";
+function classify(name, annotations) {
+    if (annotations === undefined) {
+        console.warn(`[manifest] Tool '${name}' has no annotations — defaulting to 'write'. Add READ_ONLY/WRITE/DESTRUCTIVE.`);
+        return "write";
+    }
+    if (annotations.destructiveHint === true)
+        return "destructive";
+    if (annotations.readOnlyHint === true)
+        return "read-only";
+    return "write";
+}
+const OPT_IN_FLAGS = [
+    "MCP_TELEGRAM_ENABLE_STARS",
+    "MCP_TELEGRAM_ENABLE_GROUP_CALLS",
+    "MCP_TELEGRAM_ENABLE_QUICK_REPLIES",
+];
+/** Cache: introspection is deterministic + cheap, but env save/restore is not reentrant. */
+let cached = null;
+/**
+ * Build a manifest of every tool the package can register. Forces all opt-in
+ * env flags ON during introspection so consumers see the full catalog, not
+ * the runtime-filtered subset. Cached for the process lifetime — invocations
+ * are cheap and idempotent.
+ */
+export function getToolManifest() {
+    if (cached)
+        return cached;
+    cached = introspect();
+    return cached;
+}
+/** Test-only: discard cache and force a fresh introspection. */
+export function _resetManifestCache() {
+    cached = null;
+}
+function introspect() {
+    const restore = {};
+    for (const key of OPT_IN_FLAGS) {
+        restore[key] = process.env[key];
+        process.env[key] = "1";
+    }
+    try {
+        const server = new McpServer({ name: "manifest-introspect", version: "0.0.0" });
+        registerTools(server, {});
+        return buildManifest(server);
+    }
+    finally {
+        for (const key of OPT_IN_FLAGS) {
+            if (restore[key] === undefined)
+                delete process.env[key];
+            else
+                process.env[key] = restore[key];
+        }
+    }
+}
+function buildManifest(server) {
+    const registered = server._registeredTools;
+    if (!registered || typeof registered !== "object") {
+        throw new Error("Failed to introspect MCP server: _registeredTools is missing. " +
+            "The @modelcontextprotocol/sdk shape may have changed — please file an issue at " +
+            "https://github.com/mcp-telegram/mcp-telegram/issues");
+    }
+    const tools = Object.entries(registered)
+        .map(([name, tool]) => ({
+        name,
+        tier: classify(name, tool.annotations),
+        description: tool.description ?? "",
+        hasInput: tool.inputSchema !== undefined,
+    }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    const tiers = { "read-only": 0, write: 0, destructive: 0 };
+    for (const t of tools)
+        tiers[t.tier]++;
+    return {
+        generatedAt: new Date().toISOString(),
+        toolCount: tools.length,
+        tiers,
+        tools,
+    };
+}
+if (import.meta.url === `file://${process.argv[1]}` || fileURLToPath(import.meta.url) === process.argv[1]) {
+    const manifest = getToolManifest();
+    const output = process.argv[2] ?? "manifest.json";
+    if (output === "-") {
+        process.stdout.write(`${JSON.stringify(manifest, null, 2)}\n`);
+    }
+    else {
+        writeFileSync(output, `${JSON.stringify(manifest, null, 2)}\n`);
+        console.error(`[manifest] Wrote ${manifest.toolCount} tools to ${output}`);
+    }
+}

package/dist/rate-limiter.d.ts

@@ -1,6 +1,10 @@
 /**
  * Rate limiter and retry logic for Telegram API calls.
  * Handles FLOOD_WAIT errors and implements exponential backoff.
+ *
+ * Emits structured events on stderr so downstream log collectors (e.g. cloud
+ * SigNoz) can aggregate by `event` and `context`. Format:
+ *   [rate-limiter] event {"event":"flood_wait","context":"X","seconds":N,...}
  */
 export interface RateLimiterOptions {
     /** Maximum number of requests per second (default: 20) */

package/dist/rate-limiter.js

@@ -1,6 +1,10 @@
 /**
  * Rate limiter and retry logic for Telegram API calls.
  * Handles FLOOD_WAIT errors and implements exponential backoff.
+ *
+ * Emits structured events on stderr so downstream log collectors (e.g. cloud
+ * SigNoz) can aggregate by `event` and `context`. Format:
+ *   [rate-limiter] event {"event":"flood_wait","context":"X","seconds":N,...}
  */
 export class RateLimiter {
     minInterval;
@@ -41,7 +45,13 @@ export class RateLimiter {
                 if (attempt >= this.maxRetries) {
                     throw new Error(`Rate limit exceeded after ${this.maxRetries} retries. Telegram requires ${waitSeconds}s wait. Try again later.`);
                 }
-                console.error(`[rate-limiter] FLOOD_WAIT for ${context}. Waiting ${waitSeconds}s (attempt ${attempt + 1}/${this.maxRetries})`);
+                logEvent({
+                    event: "flood_wait",
+                    context,
+                    seconds: waitSeconds,
+                    attempt: attempt + 1,
+                    maxRetries: this.maxRetries,
+                });
                 await sleep(waitSeconds * 1000);
                 return this.executeWithRetry(fn, context, attempt + 1, options);
             }
@@ -51,7 +61,14 @@ export class RateLimiter {
                     throw new Error(`Network error after ${this.maxRetries} retries: ${errorMessage}. Check your connection.`);
                 }
                 const delay = Math.min(this.initialRetryDelay * 2 ** attempt, this.maxRetryDelay);
-                console.error(`[rate-limiter] Network error for ${context}. Retrying in ${delay}ms (attempt ${attempt + 1}/${this.maxRetries})`);
+                logEvent({
+                    event: "network_retry",
+                    context,
+                    delayMs: delay,
+                    attempt: attempt + 1,
+                    maxRetries: this.maxRetries,
+                    error: errorMessage,
+                });
                 await sleep(delay);
                 return this.executeWithRetry(fn, context, attempt + 1, options);
             }
@@ -61,6 +78,14 @@ export class RateLimiter {
                     throw new Error(`Temporary error after ${this.maxRetries} retries: ${errorMessage}`);
                 }
                 const delay = Math.min(this.initialRetryDelay * 2 ** attempt, this.maxRetryDelay);
+                logEvent({
+                    event: "temporary_retry",
+                    context,
+                    delayMs: delay,
+                    attempt: attempt + 1,
+                    maxRetries: this.maxRetries,
+                    error: errorMessage,
+                });
                 await sleep(delay);
                 return this.executeWithRetry(fn, context, attempt + 1, options);
             }
@@ -85,3 +110,6 @@ function isTemporaryError(msg) {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function logEvent(payload) {
+    console.error(`[rate-limiter] event ${JSON.stringify(payload)}`);
+}

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "@overpod/mcp-telegram",
-  "version": "1.34.0",
+  "version": "1.36.0",
   "description": "MCP server for Telegram userbot — messages, media, reactions, polls & more. Built on GramJS/MTProto.",
   "type": "module",
   "main": "dist/index.js",
   "exports": {
     ".": "./dist/index.js",
-    "./service": "./dist/telegram-client.js"
+    "./service": "./dist/telegram-client.js",
+    "./manifest": "./dist/manifest.js"
   },
   "bin": {
-    "mcp-telegram": "dist/cli.js"
+    "mcp-telegram": "dist/cli.js",
+    "mcp-telegram-manifest": "dist/manifest.js"
   },
   "files": [
     "dist",
@@ -21,7 +23,7 @@
     "dev": "tsx watch src/index.ts",
     "start": "node dist/index.js",
     "login": "node dist/qr-login-cli.js",
-    "build": "tsc",
+    "build": "tsc && chmod +x dist/cli.js dist/manifest.js dist/qr-login-cli.js",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run build",
     "lint": "biome check src/",
@@ -63,7 +65,7 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.12",
+    "@biomejs/biome": "^2.4.13",
     "@types/node": "^25.6.0",
     "@types/qrcode": "^1.5.6",
     "c8": "^11.0.0",