@dikacode/telegram-mcp 1.0.0 → 1.0.1

package/README.md

@@ -11,7 +11,6 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@dikacode/telegram-mcp"><img alt="npm" src="https://img.shields.io/npm/v/@dikacode/telegram-mcp?style=flat-square&color=5eead4&label=npm"></a>
-  <a href="https://www.npmjs.com/package/@dikacode/telegram-mcp"><img alt="downloads" src="https://img.shields.io/npm/dm/@dikacode/telegram-mcp?style=flat-square&color=38bdf8"></a>
   <a href="https://github.com/dikaglorya/telegram-mcp/actions/workflows/ci.yml"><img alt="ci" src="https://github.com/dikaglorya/telegram-mcp/actions/workflows/ci.yml/badge.svg"></a>
   <img alt="node" src="https://img.shields.io/badge/node-%E2%89%A5%2020-0ea5e9?style=flat-square">
   <img alt="tools" src="https://img.shields.io/badge/tools-69-a78bfa?style=flat-square">
@@ -78,6 +77,7 @@ The server speaks MCP over stdio, so the last command is only a manual check. Th
 - [Architecture](#architecture)
 - [Requirements](#requirements)
 - [Install](#install)
+- [Updating](#updating)
 - [Credentials](#credentials)
 - [First login — from chat](#first-login--from-chat)
 - [Connect your agent](#connect-your-agent)
@@ -150,7 +150,7 @@ telegram-mcp
 }
 ```
 
-Pin a version if you want reproducible installs: `npx -y @dikacode/telegram-mcp@1.0.0`.
+Pin a version if you want reproducible installs: `npx -y @dikacode/telegram-mcp@1.0.1`.
 
 ### 2. Clone and link
 
@@ -170,7 +170,7 @@ npm link             # optional: makes `telegram-mcp` available on PATH
 Download the tarball attached to the latest release and install it globally:
 
 ```bash
-npm install -g https://github.com/dikaglorya/telegram-mcp/releases/download/v1.0.0/dikacode-telegram-mcp-1.0.0.tgz
+npm install -g https://github.com/dikaglorya/telegram-mcp/releases/download/v1.0.1/dikacode-telegram-mcp-1.0.1.tgz
 telegram-mcp
 ```
 
@@ -186,6 +186,38 @@ npx -y github:dikaglorya/telegram-mcp
 
 npm fetches the repository, installs dependencies, runs the `prepare` build, and starts the launcher.
 
+## Updating
+
+How you installed it decides whether you have to do anything.
+
+| Installed with | Behaviour |
+| --- | --- |
+| `npx -y @dikacode/telegram-mcp` (unpinned) | **Automatic.** npm resolves `latest` on every start, so the next client restart picks up a new release. |
+| `npx -y @dikacode/telegram-mcp@1.0.1` (pinned) | **Never.** That is the point of pinning. |
+| `npm install -g @dikacode/telegram-mcp` | **Manual**, one command: `npm update -g @dikacode/telegram-mcp` |
+| Release tarball | **Manual.** Reinstall from the newer tarball. |
+| `npx -y github:dikaglorya/telegram-mcp` | **Not automatic.** npm caches the fetched repo; clear the cache or pin a ref (`#main`) to move forward. |
+
+Check what you are running:
+
+```bash
+telegram-mcp --version
+npm outdated -g @dikacode/telegram-mcp     # global installs only
+```
+
+The server also tells you. When a newer release exists it prints one line to
+stderr at startup, after the MCP transport is already serving:
+
+```
+[telegram-mcp] update available: 1.0.1 -> 1.0.2. Run `npm install -g @dikacode/telegram-mcp@latest`, or set TELEGRAM_UPDATE_CHECK=0 to silence this.
+```
+
+That check is a single request to the npm registry with an 800 ms timeout,
+cached for 24 hours, and it never blocks startup or writes to stdout. If you
+want zero outbound traffic that is not Telegram itself, set
+`TELEGRAM_UPDATE_CHECK=0`. `telegram_doctor` shows the version it knows about
+without touching the network.
+
 ## Credentials
 
 1. Open [my.telegram.org/apps](https://my.telegram.org/apps) and log in with your phone number.
@@ -477,6 +509,8 @@ All settings are environment variables. The server also loads a `.env` next to t
 | `TELEGRAM_EXPORT_DIR` | `~/.telegram-mcp/exports` | History exports. |
 | `TELEGRAM_AUDIT_LOG` | `~/.telegram-mcp/audit.log` | Call log. |
 | `TELEGRAM_MAX_DOWNLOAD_BYTES` | `0` (unlimited) | Hard cap for one download. A non-numeric value is refused rather than treated as unlimited. |
+| `TELEGRAM_UPDATE_CHECK` | `true` | Set to `0` to stop the startup check for a newer npm release. |
+| `TELEGRAM_UPDATE_CHECK_TIMEOUT_MS` | `800` | Timeout for that check, capped at 10 s. |
 | `TELEGRAM_MCP_NODE` | current Node | Launcher override, for exotic Node installs. |
 
 `~` and `~\` are both expanded. Relative paths resolve against the current working directory.
@@ -494,6 +528,8 @@ All settings are environment variables. The server also loads a `.env` next to t
 | `Cannot find module .../dist/index.js` | The package was installed without building. Run `npm run build`, or use the release tarball. |
 | Login works, then the next run asks again | `TELEGRAM_SESSION_PATH` changed between runs. Keep it stable, or leave it unset. |
 | Window/terminal closes when started by hand | Expected: the server speaks MCP on stdio. Start it through a client, or use `npm run login` for the standalone CLI. |
+| `update available: …` on every start | A newer release is on npm. Run the upgrade command it prints, or set `TELEGRAM_UPDATE_CHECK=0` if you pin versions on purpose. |
+| `telegram-mcp --version` prints nothing | You are on `1.0.0`, which predates the flag. Upgrade to `1.0.1` or newer. |
 
 ## Development
 
@@ -503,7 +539,7 @@ The repository ships with a unit suite and a real MCP harness that spawns the bu
 npm install
 npm run build
 
-npm run test:unit          # 64 offline checks
+npm run test:unit          # 72 offline checks
 npm run test:mcp           # read-only end-to-end pass
 npm run test:mcp:write     # + self-cleaning writes
 npm run test:destructive   # + disposable chats (opt-in, flood-limited)
@@ -556,7 +592,8 @@ The TypeScript is built with `tsc` to `dist/`. There is no bundler; the publishe
 
 ## Release
 
-**v1.0.0** is the first public release.
+**v1.0.1** is the current release, published to npm as
+[`@dikacode/telegram-mcp`](https://www.npmjs.com/package/@dikacode/telegram-mcp).
 
 - 69 MCP tools, all registered with strict input schemas.
 - In-chat login, including two-step verification.
@@ -564,6 +601,7 @@ The TypeScript is built with `tsc` to `dist/`. There is no bundler; the publishe
 - Read-back verification for state-changing tools.
 - Optional allowlist, audited calls, redacted secrets.
 - Cross-platform launcher; no hardcoded paths.
+- `--version` / `--help`, and a startup notice when a newer release exists.
 - End-to-end harness with paging, policy probes and artifact cleanup.
 
 See [CHANGELOG.md](https://github.com/dikaglorya/telegram-mcp/blob/main/CHANGELOG.md) for the full release notes. Release artifacts are on the [releases page](https://github.com/dikaglorya/telegram-mcp/releases).

package/dist/config.js

@@ -11,8 +11,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { lockDir, lockFile } from "./perms.js";
-export const SERVER_NAME = "telegram-mcp";
-export const SERVER_VERSION = "1.0.0";
+export { SERVER_NAME, SERVER_VERSION } from "./version.js";
 export class ConfigError extends Error {
     constructor(message) {
         super(message);

package/dist/index.js

@@ -2,6 +2,9 @@
 /**
  * Entrypoint. Loads .env, builds the MCP server, serves over stdio.
  * stdout = MCP protocol only; diagnostics go to stderr.
+ *
+ * Exception: `--version` / `--help` are plain CLI invocations. They answer on
+ * stdout and exit before the transport is created, so nothing is corrupted.
  */
 import "./stream-guard.js";
 import "./env.js";
@@ -9,6 +12,41 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { buildServer } from "./server.js";
 import { ensureDirs, getConfig, redact } from "./config.js";
 import { shutdownLogin } from "./login-tools.js";
+import { PACKAGE_NAME, SERVER_NAME, SERVER_VERSION } from "./version.js";
+import { warnIfOutdated } from "./update-check.js";
+const HELP = `${SERVER_NAME} ${SERVER_VERSION}
+
+An MCP server for a personal Telegram account, spoken over stdio.
+
+Usage:
+  telegram-mcp                 serve MCP on stdio (what an MCP client runs)
+  telegram-mcp --version, -v   print the version and exit
+  telegram-mcp --help, -h      print this help and exit
+
+Setup:
+  1. Get api_id and api_hash from https://my.telegram.org/apps
+  2. Provide them as TELEGRAM_API_ID / TELEGRAM_API_HASH, or let the agent call
+     telegram_setup
+  3. Log in with telegram_login_start (the agent can do this for you)
+
+Updating:
+  npx -y ${PACKAGE_NAME}@latest               # npx, always current
+  npm install -g ${PACKAGE_NAME}@latest       # global install
+
+Docs: https://github.com/dikaglorya/telegram-mcp
+`;
+function handleCliFlags(argv) {
+    const flags = new Set(argv.slice(2));
+    if (flags.has("--version") || flags.has("-v")) {
+        process.stdout.write(`${SERVER_VERSION}\n`);
+        return true;
+    }
+    if (flags.has("--help") || flags.has("-h")) {
+        process.stdout.write(HELP);
+        return true;
+    }
+    return false;
+}
 async function main() {
     // A missing .env must NOT be fatal: the user needs telegram_setup (and the
     // doctor) to be reachable so they can fix it from chat. Only a genuinely
@@ -28,6 +66,9 @@ async function main() {
     process.stderr.write(config
         ? `[telegram-mcp] serving over stdio (allowAll=${config.allowAllChats}, allowlist=${config.allowlist.length})\n`
         : `[telegram-mcp] serving over stdio (unconfigured — telegram_setup required)\n`);
+    // After the transport is live, so a slow or unreachable registry can never
+    // delay the first tool call.
+    warnIfOutdated();
     const shutdown = async (signal) => {
         process.stderr.write(`[telegram-mcp] ${signal}, shutting down\n`);
         try {
@@ -42,7 +83,9 @@ async function main() {
     process.on("SIGINT", () => void shutdown("SIGINT"));
     process.on("SIGTERM", () => void shutdown("SIGTERM"));
 }
-main().catch((err) => {
-    process.stderr.write(`[telegram-mcp] fatal: ${redact(err instanceof Error ? err.stack ?? err.message : String(err))}\n`);
-    process.exit(1);
-});
+if (!handleCliFlags(process.argv)) {
+    main().catch((err) => {
+        process.stderr.write(`[telegram-mcp] fatal: ${redact(err instanceof Error ? err.stack ?? err.message : String(err))}\n`);
+        process.exit(1);
+    });
+}

package/dist/setup-tools.js

@@ -23,6 +23,8 @@ import { getClient } from "./telegram.js";
 import { lockFile } from "./perms.js";
 import { normalizeError } from "./errors.js";
 import { ok, guard } from "./util.js";
+import { PACKAGE_NAME, SERVER_VERSION } from "./version.js";
+import { getUpdateInfo } from "./update-check.js";
 /** Keys this module owns when writing `.env`; everything else is preserved. */
 const MANAGED_KEYS = [
     "TELEGRAM_API_ID",
@@ -131,10 +133,11 @@ function buildEnvBody(values) {
 export function registerSetupTools(server) {
     server.registerTool("telegram_doctor", {
         title: "Telegram health check",
-        description: "Read-only health check: config, state dir, session presence, session file permissions " +
-            "(auto-repaired to 0600), and live authorization. Returns { healthy, checks[], account }. " +
+        description: "Read-only health check: config, installed version, state dir, session presence, session file " +
+            "permissions (auto-repaired to 0600), and live authorization. Returns { healthy, checks[], account }. " +
             "A missing or unauthorized session is reported as a failed check, not an error — call " +
-            "telegram_login_start to fix it. Never returns the api_hash or the session string.",
+            "telegram_login_start to fix it. An available update is informational and never fails the check. " +
+            "Never returns the api_hash or the session string.",
         inputSchema: {},
         annotations: { readOnlyHint: true, openWorldHint: false },
     }, async () => guard(async () => {
@@ -153,6 +156,23 @@ export function registerSetupTools(server) {
         catch (err) {
             checks.push({ name: "config", pass: false, detail: normalizeError(err).message });
         }
+        // 2. version — always informational, never a failure. An available
+        //    update is not a health problem, so it must not flip `healthy` to
+        //    false and send an agent chasing a working install. Cache-only:
+        //    a health check must not wait on the network.
+        try {
+            const info = await getUpdateInfo({ allowNetwork: false });
+            checks.push({
+                name: "version",
+                pass: true,
+                detail: info.updateAvailable
+                    ? `${info.current} (${info.latest} available — \`npm install -g ${PACKAGE_NAME}@latest\`)`
+                    : `${info.current} (latest known)`,
+            });
+        }
+        catch {
+            checks.push({ name: "version", pass: true, detail: SERVER_VERSION });
+        }
         if (!config) {
             // Without credentials there is no session path to inspect and no client
             // to connect: report the remaining checks as failed-with-reason rather

package/dist/update-check.js

@@ -0,0 +1,151 @@
+/**
+ * "A newer version exists" notice.
+ *
+ * Why it exists: the package is distributed through npx, where the version is
+ * resolved on every run, and through `npm i -g`, where it is not. A user who
+ * installed globally has no way to learn that a fix shipped unless they think
+ * to run `npm outdated -g`. This module prints one line to stderr when the
+ * registry has something newer.
+ *
+ * Design constraints, all deliberate:
+ *   - stderr only. stdout belongs to the JSON-RPC transport; a stray line there
+ *     would make the agent drop the server.
+ *   - never fatal, never blocking. The check runs after the server is already
+ *     serving; a timeout, an offline machine or a broken proxy just means no
+ *     notice.
+ *   - cached for a day, so restarting the client five times does not mean five
+ *     registry requests.
+ *   - opt out with TELEGRAM_UPDATE_CHECK=0. This is a local-first tool and a
+ *     user is entitled to zero outbound traffic that is not Telegram itself.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { PACKAGE_NAME, SERVER_VERSION, VERSION_IS_KNOWN, compareVersions } from "./version.js";
+const DEFAULT_TIMEOUT_MS = 800;
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+function enabled() {
+    const raw = process.env.TELEGRAM_UPDATE_CHECK;
+    if (raw === undefined || raw.trim() === "")
+        return true;
+    return !/^(0|false|no|off)$/i.test(raw.trim());
+}
+function timeoutMs() {
+    const raw = process.env.TELEGRAM_UPDATE_CHECK_TIMEOUT_MS;
+    if (!raw)
+        return DEFAULT_TIMEOUT_MS;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0)
+        return DEFAULT_TIMEOUT_MS;
+    return Math.min(n, 10_000);
+}
+/**
+ * Cache location. Deliberately independent of `getConfig()`: the notice must
+ * work before api_id/api_hash are set, and it must not create the state dir
+ * just to write a version number.
+ */
+function cachePath() {
+    const configured = process.env.TELEGRAM_STATE_DIR?.trim();
+    const base = configured
+        ? path.resolve(configured.replace(/^~(?=$|[\\/])/, os.homedir()))
+        : path.join(os.homedir(), ".telegram-mcp");
+    return path.join(base, "update-check.json");
+}
+function readCache() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(cachePath(), "utf8"));
+        if (typeof parsed.latest !== "string" || typeof parsed.checkedAt !== "string")
+            return null;
+        if (Date.now() - Date.parse(parsed.checkedAt) > CACHE_TTL_MS)
+            return null;
+        return { latest: parsed.latest, checkedAt: parsed.checkedAt };
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(latest) {
+    try {
+        const file = cachePath();
+        fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+        const tmp = `${file}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify({ checkedAt: new Date().toISOString(), latest }, null, 2), { encoding: "utf8", mode: 0o600 });
+        fs.renameSync(tmp, file);
+    }
+    catch {
+        /* a cache we cannot write is not a failure — it just means we ask again */
+    }
+}
+/** Ask the registry for `dist-tags.latest`. Returns null on any problem. */
+async function fetchLatest() {
+    try {
+        const res = await fetch(`https://registry.npmjs.org/${encodeURIComponent(PACKAGE_NAME)}/latest`, {
+            headers: { accept: "application/json" },
+            signal: AbortSignal.timeout(timeoutMs()),
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        return typeof body.version === "string" && body.version.trim() ? body.version.trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve the current state. `allowNetwork: false` reads only the cache, which
+ * is what `telegram_doctor` uses so a health check never waits on the network.
+ */
+export async function getUpdateInfo(opts = {}) {
+    const current = SERVER_VERSION;
+    // Without a trustworthy local version, "newer" has no meaning: skip the
+    // notice rather than telling every user to upgrade to something.
+    if (!VERSION_IS_KNOWN)
+        return { current, latest: current, updateAvailable: false, source: "unknown" };
+    if (!enabled())
+        return { current, latest: current, updateAvailable: false, source: "disabled" };
+    const cached = readCache();
+    if (cached) {
+        return {
+            current,
+            latest: cached.latest,
+            updateAvailable: compareVersions(cached.latest, current) > 0,
+            source: "cache",
+        };
+    }
+    if (opts.allowNetwork === false) {
+        return { current, latest: current, updateAvailable: false, source: "unknown" };
+    }
+    const latest = await fetchLatest();
+    if (!latest)
+        return { current, latest: current, updateAvailable: false, source: "unknown" };
+    writeCache(latest);
+    return {
+        current,
+        latest,
+        updateAvailable: compareVersions(latest, current) > 0,
+        source: "registry",
+    };
+}
+/** The single line users see. Shaped to be actionable, not just informative. */
+export function formatNotice(info) {
+    const upgrade = process.env.npm_config_global === "true"
+        ? `npm install -g ${PACKAGE_NAME}@latest`
+        : `npx -y ${PACKAGE_NAME}@latest`;
+    return (`[telegram-mcp] update available: ${info.current} -> ${info.latest}. ` +
+        `Run \`${upgrade}\`, or set TELEGRAM_UPDATE_CHECK=0 to silence this.\n`);
+}
+/**
+ * Fire-and-forget: called after the server is already serving, so a slow
+ * registry can never delay the first tool call.
+ */
+export function warnIfOutdated() {
+    void getUpdateInfo()
+        .then((info) => {
+        if (info.updateAvailable)
+            process.stderr.write(formatNotice(info));
+    })
+        .catch(() => {
+        /* the notice is best-effort by definition */
+    });
+}

package/dist/version.js

@@ -0,0 +1,76 @@
+/**
+ * The one place the version number comes from.
+ *
+ * `package.json` is the source of truth: npm writes the version it publishes,
+ * so reading it back means the MCP `serverInfo`, `--version` and the update
+ * check can never drift from the artifact that was actually shipped.
+ *
+ * Resolution walks up from this file, which covers every layout:
+ *   <root>/dist/version.js   (published / built)
+ *   <root>/version.ts        (tsx, dev)
+ *   <root>/node_modules/@dikacode/telegram-mcp/dist/version.js
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+export const SERVER_NAME = "telegram-mcp";
+export const PACKAGE_NAME = "@dikacode/telegram-mcp";
+/**
+ * Last resort when package.json is unreadable. Deliberately not a plausible
+ * version: a guess here would make the update check nag about a release the
+ * user may already be running, so an unknown version disables the notice.
+ */
+const FALLBACK_VERSION = "0.0.0-unknown";
+function readVersion() {
+    let dir = path.dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 6; i++) {
+        try {
+            const raw = fs.readFileSync(path.join(dir, "package.json"), "utf8");
+            const parsed = JSON.parse(raw);
+            if (typeof parsed.version === "string" && parsed.version.trim()) {
+                return parsed.version.trim();
+            }
+        }
+        catch {
+            /* keep walking: this directory is not the package root */
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return FALLBACK_VERSION;
+}
+export const SERVER_VERSION = readVersion();
+/** True when package.json could not be read, so the version is not trustworthy. */
+export const VERSION_IS_KNOWN = SERVER_VERSION !== "0.0.0-unknown";
+/** Dotted-numeric comparison, prerelease-aware, with no dependency. */
+export function compareVersions(a, b) {
+    const split = (v) => {
+        const cleaned = v.trim().replace(/^v/i, "").split("+")[0];
+        const dash = cleaned.indexOf("-");
+        const core = dash === -1 ? cleaned : cleaned.slice(0, dash);
+        const pre = dash === -1 ? "" : cleaned.slice(dash + 1);
+        const nums = core.split(".").map((part) => {
+            const n = Number.parseInt(part, 10);
+            return Number.isFinite(n) ? n : 0;
+        });
+        while (nums.length < 3)
+            nums.push(0);
+        return { nums, pre };
+    };
+    const left = split(a);
+    const right = split(b);
+    for (let i = 0; i < 3; i++) {
+        if (left.nums[i] !== right.nums[i])
+            return left.nums[i] < right.nums[i] ? -1 : 1;
+    }
+    // Same core: a release outranks any prerelease of it.
+    if (!left.pre && right.pre)
+        return 1;
+    if (left.pre && !right.pre)
+        return -1;
+    if (left.pre === right.pre)
+        return 0;
+    return left.pre < right.pre ? -1 : 1;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dikacode/telegram-mcp",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Local MCP server that connects CLI agents (OpenCode, Codex CLI, Claude Code, ...) to a personal Telegram account over MTProto.",
   "type": "module",
   "bin": {