@dikacode/telegram-mcp 1.0.0 → 1.0.2

package/dist/cli/update.js

@@ -0,0 +1,293 @@
+#!/usr/bin/env node
+/**
+ * `telegram-mcp update` — bring the installed copy up to date.
+ *
+ * The hard part is not the upgrade, it is knowing *how* this copy was
+ * installed. A global npm install is upgraded with `npm i -g`, an npx run is
+ * replaced by asking npx for @latest, and a git checkout is updated with
+ * `git pull` plus a rebuild. Guessing wrong either does nothing (npm refuses
+ * to touch a package it does not own) or silently reinstalls the same version.
+ *
+ * So detection is made from the filesystem, not from a flag the user has to
+ * remember:
+ *   - the real path of this file lives under node_modules   -> npm package
+ *     - under a global prefix (`npm root -g`)               -> global install
+ *     - anywhere else (npx cache, local dep)                -> npx
+ *   - a sibling `.git` directory                            -> git checkout
+ *
+ * With `--check` nothing is installed; it only reports. That is what
+ * `telegram-mcp update --check` and the doctor use, and it never writes.
+ */
+import "../env.js";
+import { spawn, execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { PACKAGE_NAME, SERVER_VERSION, compareVersions } from "../version.js";
+import { getUpdateInfo } from "../update-check.js";
+import { banner, gap, hint, info, sym, theme } from "../ui.js";
+const out = (text) => void process.stdout.write(text);
+/**
+ * Where npm puts globally installed packages. Asking npm is more reliable than
+ * reconstructing `process.execPath`, which differs between Homebrew, nvm,
+ * Volta and the Windows installer. `NPM_CONFIG_PREFIX` still applies, so a
+ * custom prefix is detected too.
+ */
+function npmGlobalRoot() {
+    try {
+        const root = execFileSync("npm", ["root", "-g"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 10_000,
+            shell: process.platform === "win32",
+        }).trim();
+        return root || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Candidates for the global prefix. `npm root -g` is authoritative, but it is
+ * skipped when npm is not on PATH (clients do strip it), and an explicit
+ * `npm i -g --prefix <dir>` is easy to miss. The real path of this file gives
+ * the answer either way: it ends in
+ *   <prefix>/lib/node_modules/<name>/dist/cli/update.js   (POSIX)
+ *   <prefix>/node_modules/<name>/dist/cli/update.js       (Windows)
+ */
+function globalRoots() {
+    const candidates = new Set();
+    const fromNpm = npmGlobalRoot();
+    if (fromNpm)
+        candidates.add(fromNpm);
+    const marker = process.platform === "win32" ? "/node_modules/" : "/lib/node_modules/";
+    const here = fileURLToPath(import.meta.url).replace(/\\/g, "/");
+    const at = here.lastIndexOf(marker);
+    if (at !== -1)
+        candidates.add(here.slice(0, at + marker.length - 1));
+    return [...candidates].map((dir) => path.resolve(dir)).filter((dir) => fs.existsSync(dir));
+}
+/** Walk up looking for a package root (a directory with package.json + .git or dist). */
+function findPackageRoot(start) {
+    let dir = start;
+    for (let i = 0; i < 6; i++) {
+        if (fs.existsSync(path.join(dir, "package.json")))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+    return null;
+}
+export function detectInstall() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const root = findPackageRoot(here) ?? here;
+    const normalized = root.replace(/\\/g, "/");
+    // A git checkout is the only layout that carries its own .git.
+    if (fs.existsSync(path.join(root, ".git"))) {
+        return { kind: "source", location: root };
+    }
+    if (/\/node_modules\//.test(`${normalized}/`)) {
+        const global = globalRoots().map((p) => p.replace(/\\/g, "/").replace(/\/+$/, ""));
+        if (global.some((g) => normalized === g || normalized.startsWith(`${g}/`))) {
+            return { kind: "global", location: root };
+        }
+        // Anything else under node_modules was put there by npx, or by a project
+        // that lists this package as a dependency, and both are refreshed by
+        // asking npm for @latest rather than by a -g install.
+        return { kind: "npx", location: root };
+    }
+    return { kind: "unknown", location: root };
+}
+export async function plan(allowNetwork = true) {
+    const { kind, location } = detectInstall();
+    const info = await getUpdateInfo({ allowNetwork });
+    const latest = info.source === "disabled" ? null : info.latest;
+    const outdated = latest !== null ? compareVersions(latest, SERVER_VERSION) > 0 : false;
+    const base = {
+        kind,
+        location,
+        current: SERVER_VERSION,
+        latest: latest ?? null,
+        outdated,
+    };
+    if (kind === "source") {
+        // A detached HEAD, a shallow clone or a checkout without an upstream all
+        // fail `pull --ff-only`. Ask git about the tracked upstream instead of
+        // assuming `origin/main` exists.
+        const upstream = git(location, ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"]);
+        if (!upstream) {
+            return {
+                ...base,
+                command: null,
+                note: "this checkout has no upstream branch; update it with `git pull` yourself, then npm install && npm run build",
+            };
+        }
+        return {
+            ...base,
+            command: ["git", "-C", location, "pull", "--ff-only"],
+            note: "then rebuild: npm install && npm run build",
+        };
+    }
+    if (kind === "global") {
+        // Respect a custom prefix: `npm i -g --prefix /opt/x` is a global install
+        // too, and upgrading it with a plain `npm i -g` would land in a different
+        // tree and leave the old copy in place.
+        const prefix = globalPrefix();
+        return {
+            ...base,
+            command: prefix
+                ? ["npm", "install", "-g", "--prefix", prefix, `${PACKAGE_NAME}@latest`]
+                : ["npm", "install", "-g", `${PACKAGE_NAME}@latest`],
+        };
+    }
+    if (kind === "npx") {
+        return {
+            ...base,
+            command: null,
+            note: `this copy was loaded from a node_modules folder; restart with \`npx -y ${PACKAGE_NAME}@latest\` and npx will fetch the newest release`,
+        };
+    }
+    return { ...base, command: null, note: "cannot tell how this copy was installed; use npm install -g @latest" };
+}
+/** Run git and return trimmed stdout, or null when it fails. Never throws. */
+function git(cwd, args) {
+    try {
+        const result = execFileSync("git", ["-C", cwd, ...args], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 5_000,
+        }).trim();
+        return result || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The prefix a global install lives under, or null when it is the default one.
+ * Read from the resolved global root (`<prefix>/lib/node_modules` on POSIX,
+ * `<prefix>/node_modules` on Windows) so no extra npm call is needed.
+ */
+function globalPrefix() {
+    // Applies to the global root that contains the running copy: a custom
+    // prefix must be reused, or the upgrade would install next to it instead of
+    // over it.
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const normalized = here.replace(/\\/g, "/");
+    for (const root of globalRoots()) {
+        const g = root.replace(/\\/g, "/").replace(/\/+$/, "");
+        if (normalized.startsWith(`${g}/`)) {
+            return process.platform === "win32" ? path.dirname(root) : path.dirname(path.dirname(root));
+        }
+    }
+    return null;
+}
+function run(command) {
+    return new Promise((resolve) => {
+        const child = spawn(command[0], command.slice(1), {
+            stdio: "inherit",
+            shell: process.platform === "win32",
+        });
+        child.on("error", () => resolve(1));
+        child.on("exit", (code) => resolve(code ?? 1));
+    });
+}
+function printPlan(p, checkOnly) {
+    const label = p.kind === "global"
+        ? "global npm package"
+        : p.kind === "npx"
+            ? "npx or project dependency"
+            : p.kind === "source"
+                ? "git checkout"
+                : "unknown";
+    out(`\n  ${theme.label("installed")}   ${theme.bold(p.current)}  ${theme.muted(p.location)}\n`);
+    out(`  ${theme.label("latest")}      ${p.latest ? theme.bold(p.latest) : theme.muted("unknown")}\n`);
+    out(`  ${theme.label("install")}     ${label}\n`);
+    if (p.latest === null) {
+        hint("could not reach the npm registry; check the network or TELEGRAM_UPDATE_CHECK");
+        return;
+    }
+    if (!p.outdated) {
+        out(`\n  ${theme.success(`${sym.ok} already up to date`)}\n\n`);
+        return;
+    }
+    out(`\n  ${theme.warn(`${sym.warn} ${theme.bold(`${p.current} -> ${p.latest}`)} available`)}\n`);
+    if (p.note)
+        hint(p.note);
+    if (checkOnly) {
+        if (p.command)
+            hint(`to upgrade, run ${theme.label(p.command.join(" "))}`);
+        hint("run without --check to apply it");
+        out("\n");
+        return;
+    }
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const checkOnly = argv.includes("--check") || argv.includes("--dry-run");
+    if (argv.includes("--help") || argv.includes("-h")) {
+        out([
+            "",
+            `  ${theme.bold("telegram-mcp update")}          upgrade this install to the latest release`,
+            `  ${theme.bold("telegram-mcp update --check")}  report only; install nothing`,
+            "",
+            "  The command is chosen from how this copy was installed:",
+            `    ${theme.accent("global install")}  npm install -g ${PACKAGE_NAME}@latest`,
+            `    ${theme.accent("npx run")}         restart with npx -y ${PACKAGE_NAME}@latest`,
+            `    ${theme.accent("git checkout")}    git pull --ff-only, then npm install && npm run build`,
+            "",
+        ].join("\n"));
+        return;
+    }
+    banner({ subtitle: "update", compact: true });
+    const p = await plan(true);
+    printPlan(p, checkOnly);
+    if (checkOnly || !p.outdated || !p.command) {
+        if (!checkOnly && p.outdated && !p.command && p.note) {
+            gap();
+            hint("nothing was installed; this copy is refreshed by the command above");
+            out("\n");
+        }
+        return;
+    }
+    info(`${theme.label("running")} ${p.command.join(" ")}`);
+    const code = await run(p.command);
+    if (code !== 0) {
+        out(`\n  ${theme.fail(`${sym.fail} update command exited with ${code}`)}\n\n`);
+        process.exitCode = code;
+        return;
+    }
+    if (p.kind === "source") {
+        info(`${theme.label("rebuilding")} npm install && npm run build`);
+        const install = await run(["npm", "install"]);
+        if (install === 0)
+            await run(["npm", "run", "build"]);
+    }
+    gap();
+    out(`  ${theme.success(`${sym.ok} updated to ${p.latest}`)}\n`);
+    hint("restart your MCP client so it spawns the new copy");
+    out("\n");
+}
+/**
+ * Only run when this file is the entrypoint. `detectInstall` is imported by the
+ * unit checks, and importing a module must not print a report or spawn npm.
+ */
+function invokedDirectly() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return path.resolve(entry) === fileURLToPath(import.meta.url);
+    }
+    catch {
+        return false;
+    }
+}
+if (invokedDirectly()) {
+    void main().catch((err) => {
+        process.stderr.write(`${theme.fail(`${sym.fail} update failed: ${err instanceof Error ? err.message : String(err)}`)}\n`);
+        process.exit(1);
+    });
+}

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,27 +12,123 @@ 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_VERSION } from "./version.js";
+import { warnIfOutdated } from "./update-check.js";
+import { banner, gap, hint, info, muted, sym, theme } from "./ui.js";
+function help() {
+    const rows = [
+        ["telegram-mcp", "serve MCP on stdio (what an MCP client runs)"],
+        ["telegram-mcp --version", "print the version and exit"],
+        ["telegram-mcp --help", "print this help and exit"],
+        ["telegram-mcp login", "log in from this terminal instead of chat"],
+        ["telegram-mcp doctor", "check config, session and connectivity"],
+        ["telegram-mcp update", "upgrade this install to the latest release"],
+        ["telegram-mcp update --check", "report the available version, install nothing"],
+    ];
+    const width = Math.max(...rows.map(([cmd]) => cmd.length));
+    const usage = rows
+        .map(([cmd, desc]) => `  ${theme.accent(cmd.padEnd(width))}  ${theme.muted(desc)}`)
+        .join("\n");
+    return [
+        `${theme.title("▀█▀ █▀▀ █░░ █▀▀ █▀▀ █▀█ ▄▀█ █▀▄▀█")}`,
+        `${theme.title("░█░ █▀▀ █░░ ██▄ █▄█ █▀▄ █▀█ █░▀░█")}  ${theme.muted(SERVER_VERSION)}`,
+        "",
+        theme.label("An MCP server for a personal Telegram account, over MTProto."),
+        "",
+        theme.bold("Usage"),
+        usage,
+        "",
+        theme.bold("Setup"),
+        `  ${theme.accent("1.")} Get api_id and api_hash from ${theme.underline("https://my.telegram.org/apps")}`,
+        `  ${theme.accent("2.")} Provide them as ${theme.label("TELEGRAM_API_ID")} / ${theme.label("TELEGRAM_API_HASH")},`,
+        `     or let the agent call ${theme.label("telegram_setup")}`,
+        `  ${theme.accent("3.")} Log in with ${theme.label("telegram_login_start")} (the agent can do it),`,
+        `     or run ${theme.label("telegram-mcp login")} in a terminal`,
+        "",
+        theme.bold("Updating"),
+        `  ${theme.accent("telegram-mcp update".padEnd(42))} ${theme.muted("detects how it was installed")}`,
+        `  ${theme.accent("telegram-mcp update --check".padEnd(42))} ${theme.muted("report only")}`,
+        `  ${theme.accent(`npx -y ${PACKAGE_NAME}@latest`.padEnd(42))} ${theme.muted("npx, always current")}`,
+        `  ${theme.accent(`npm install -g ${PACKAGE_NAME}@latest`.padEnd(42))} ${theme.muted("global install")}`,
+        "",
+        `${theme.muted("Docs")}  ${theme.underline("https://github.com/dikaglorya/telegram-mcp")}`,
+        "",
+    ].join("\n");
+}
+/** Subcommands that act like a CLI instead of serving stdio. */
+function dispatchSubcommand(argv) {
+    const command = argv[0];
+    if (command !== "login" && command !== "doctor" && command !== "update")
+        return false;
+    // Each module runs its own main() on import; they keep the same behaviour as
+    // `npm run login` and `npm run doctor`, just reachable from one binary.
+    const targets = {
+        login: "./cli/login.js",
+        doctor: "./cli/doctor.js",
+        update: "./cli/update.js",
+    };
+    const target = targets[command];
+    void import(target).catch((err) => {
+        process.stderr.write(`${theme.fail(`${sym.fail} cannot start ${command}: ${err instanceof Error ? err.message : String(err)}`)}\n`);
+        process.exit(1);
+    });
+    return true;
+}
+/** Handled before the transport is created, so stdout stays parseable. */
+function handleCliFlags(argv) {
+    // Claude Desktop (and a few other clients) launch the server with
+    // `mcp-server-<name>` as an argument. That is not a subcommand, so anything
+    // unrecognised must fall through to serving rather than be interpreted.
+    const args = argv.slice(2).filter((a) => !/^mcp-server-/.test(a));
+    if (args.includes("--version") || args.includes("-v")) {
+        process.stdout.write(`${SERVER_VERSION}\n`);
+        return true;
+    }
+    if (args.includes("--help") || args.includes("-h") || args[0] === "help") {
+        process.stdout.write(help());
+        return true;
+    }
+    return dispatchSubcommand(args);
+}
+function startupBanner(configured, allowAll, allowlist) {
+    if (configured) {
+        banner({ subtitle: "your Telegram account, as an MCP server", compact: true });
+        info(`${theme.success(sym.ok)} serving over stdio ${theme.muted(`(allowAll=${allowAll}, allowlist=${allowlist})`)}`);
+        return;
+    }
+    banner({ subtitle: "not configured yet", compact: true });
+    info(`${theme.warn(`${sym.warn} ${theme.bold("not configured")} — no api_id/api_hash yet`)}`);
+    hint(`get them from ${theme.underline("https://my.telegram.org/apps")}`);
+    hint(`then call ${theme.label("telegram_setup")} from chat, or run ${theme.label("telegram-mcp login")}`);
+    gap();
+    muted(`serving anyway — waiting for the agent`);
+}
 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
     // broken server would exit here.
     let config = null;
+    let reason = "";
     try {
         config = getConfig();
         ensureDirs(config);
     }
     catch (err) {
-        process.stderr.write(`[telegram-mcp] not configured yet: ${err instanceof Error ? err.message : String(err)}\n` +
-            `[telegram-mcp] serving anyway — call telegram_setup to create .env, then telegram_login_start.\n`);
+        reason = redact(err instanceof Error ? err.message : String(err));
     }
     const server = buildServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    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`);
+    startupBanner(Boolean(config), config?.allowAllChats ?? false, config?.allowlist.length ?? 0);
+    if (!config && reason) {
+        hint(theme.muted(reason.split(".")[0]));
+        hint(theme.muted("this server keeps running so the agent can call telegram_setup"));
+    }
+    // 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`);
+        muted(`${signal}, shutting down`);
         try {
             // Drops any half-finished login socket too, not just the main client.
             await shutdownLogin();
@@ -42,7 +141,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(`${theme.fail(`${sym.fail} 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