@overpod/mcp-telegram 1.35.0 → 1.36.1

package/CHANGELOG.md

@@ -5,6 +5,62 @@ 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.1] — 2026-05-04
+
+### Fixed
+
+- Add `big-integer` as a direct dependency. Previously it was imported by `src/telegram-client.ts` and `src/telegram-helpers.ts` but only resolved transitively, which broke `tsc --noEmit` on strict-hoisting installers like pnpm.
+
+### Changed
+
+- Dependency updates (no behavioral changes):
+  - `zod` `^4.3.6` → `^4.4.3` (patch bump, runtime backward-compatible)
+  - `@biomejs/biome` `^2.4.13` → `^2.4.14` (devDep, lint/format only)
+
+## [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

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/package.json

@@ -1,15 +1,17 @@
 {
   "name": "@overpod/mcp-telegram",
-  "version": "1.35.0",
+  "version": "1.36.1",
   "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/",
@@ -57,13 +59,14 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "big-integer": "^1.6.52",
     "dotenv": "^17.4.2",
     "qrcode": "^1.5.4",
     "telegram": "^2.26.22",
-    "zod": "^4.3.6"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.13",
+    "@biomejs/biome": "^2.4.14",
     "@types/node": "^25.6.0",
     "@types/qrcode": "^1.5.6",
     "c8": "^11.0.0",