overpod/mcp-telegram

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.

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.

Why

Foundation for upstream parity gates. A cloud distribution that ships a curated tool whitelist can detect drift in CI by comparing its whitelist against getToolManifest().tools — when this package adds a new tool in a future release, a downstream's CI step will refuse to merge until the whitelist is updated (either to allow or to explicitly exclude the new tool with a reason).

Notes

• New public API surface; no breaking changes to existing exports.
• 13 new tests; total test count: 505.
• Build now sets executable bits on all dist/*-cli.js outputs (was npm-install-time only for bin entries).
• Snapshot at this release: 181 tools (74 read-only, 96 write, 11 destructive).