@dikacode/telegram-mcp 1.0.0 → 1.0.2

package/dist/ui.js

@@ -0,0 +1,237 @@
+/**
+ * Terminal presentation: colour, symbols, a banner and small animations.
+ *
+ * Rules this module enforces, in order of importance:
+ *
+ *   1. **stdout is never touched.** Only stderr goes through here. stdout is the
+ *      MCP JSON-RPC channel, and a single ANSI escape sequence written there
+ *      corrupts the stream and gets the server dropped by the client.
+ *   2. **Degrade silently.** Colour needs a TTY, a terminal that is not dumb,
+ *      and no NO_COLOR. Piped output, CI logs and `npx ... > file` get plain
+ *      text with no escape codes at all.
+ *   3. **Animation is optional and cannot hang.** Every animation has a hard
+ *      time cap and is skipped when `TERM=dumb`, when stderr is not a TTY, when
+ *      the terminal is narrow, or when TELEGRAM_NO_ANIMATION is set.
+ *
+ * The exported surface is small on purpose: the rest of the codebase should not
+ * be threading `isTTY` checks through every message.
+ */
+import { SERVER_NAME, SERVER_VERSION } from "./version.js";
+/* ------------------------------------------------------------------ */
+/* Capability detection                                                */
+/* ------------------------------------------------------------------ */
+const isWindows = process.platform === "win32";
+function stderrIsTty() {
+    return Boolean(process.stderr.isTTY);
+}
+/**
+ * Colour support. `NO_COLOR` is the de-facto standard opt-out and takes
+ * priority over everything (https://no-color.org). `FORCE_COLOR` exists for the
+ * case where output is piped into a colour-aware pager.
+ */
+export function colorEnabled() {
+    if (process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== "")
+        return false;
+    const forced = process.env.FORCE_COLOR;
+    if (forced !== undefined && forced !== "" && forced !== "0")
+        return true;
+    if (forced === "0")
+        return false;
+    if (!stderrIsTty())
+        return false;
+    if (process.env.TERM === "dumb")
+        return false;
+    // Windows Terminal and VS Code advertise themselves; plain conhost does not
+    // reliably handle SGR, so it stays plain unless FORCE_COLOR says otherwise.
+    if (isWindows && !process.env.WT_SESSION && !process.env.TERM_PROGRAM)
+        return false;
+    return true;
+}
+/** Whether the fancy stuff (banner frame, spinner) should run at all. */
+export function animationEnabled() {
+    if (process.env.TELEGRAM_NO_ANIMATION && process.env.TELEGRAM_NO_ANIMATION !== "0")
+        return false;
+    if (!stderrIsTty())
+        return false;
+    if (process.env.TERM === "dumb")
+        return false;
+    const columns = process.stderr.columns ?? 0;
+    if (columns > 0 && columns < 60)
+        return false;
+    return colorEnabled();
+}
+function sgr(open, close = 0) {
+    return (text) => (colorEnabled() ? `\u001b[${open}m${text}\u001b[${close}m` : text);
+}
+/** 256-colour foreground, falling back to cyan when colour is off. */
+function c256(code, fallback) {
+    return (text) => colorEnabled() ? `\u001b[38;5;${code}m${text}\u001b[0m` : `\u001b[${fallback}m${text}\u001b[0m`;
+}
+const basic = !process.env.TELEGRAM_256_COLORS;
+/**
+ * Low-level painters, for the rare call that needs one word emphasised inside a
+ * sentence. Prefer `theme` in new code; these are aliases kept small on purpose.
+ */
+export const paint = {
+    bold: sgr(1, 22),
+    dim: sgr(2, 22),
+    underline: sgr(4, 24),
+};
+/**
+ * The palette: cool cyan/teal for structure, warm accents for emphasis.
+ * Names are semantic (`success`, `fail`) so call sites read as intent.
+ */
+export const theme = {
+    bold: paint.bold,
+    dim: paint.dim,
+    underline: paint.underline,
+    border: basic ? sgr(90) : c256(244, 90),
+    title: basic ? sgr(96) : c256(51, 96),
+    label: basic ? sgr(97) : c256(252, 97),
+    accent: basic ? sgr(96) : c256(45, 96),
+    success: basic ? sgr(92) : c256(48, 92),
+    fail: basic ? sgr(91) : c256(203, 91),
+    warn: basic ? sgr(93) : c256(214, 93),
+    muted: basic ? sgr(90) : c256(242, 90),
+};
+/* ------------------------------------------------------------------ */
+/* Symbols                                                             */
+/* ------------------------------------------------------------------ */
+// Unicode box drawing and symbols are fine on every modern terminal, but
+// Windows conhost with a legacy code page mangles them, so ASCII is used there.
+const unicodeSymbols = !isWindows || Boolean(process.env.WT_SESSION);
+export const sym = {
+    ok: unicodeSymbols ? "✔" : "v",
+    fail: unicodeSymbols ? "✖" : "x",
+    warn: unicodeSymbols ? "▲" : "!",
+    arrow: unicodeSymbols ? "→" : "->",
+    bullet: unicodeSymbols ? "·" : "-",
+    bar: unicodeSymbols ? "│" : "|",
+    tl: unicodeSymbols ? "╭" : "+",
+    tr: unicodeSymbols ? "╮" : "+",
+    bl: unicodeSymbols ? "╰" : "+",
+    br: unicodeSymbols ? "╯" : "+",
+    h: unicodeSymbols ? "─" : "-",
+};
+/* ------------------------------------------------------------------ */
+/* Message helpers — stderr only                                       */
+/* ------------------------------------------------------------------ */
+function write(text) {
+    process.stderr.write(text);
+}
+/** The canonical diagnostic line. `[telegram-mcp] ...` stays greppable. */
+export function info(message) {
+    write(`${theme.title(`[${SERVER_NAME}]`)} ${message}\n`);
+}
+export function muted(message) {
+    write(`${theme.muted(`[${SERVER_NAME}]`)} ${message}\n`);
+}
+export function success(message) {
+    write(`${theme.success(sym.ok)} ${message}\n`);
+}
+export function warn(message) {
+    write(`${theme.warn(`${sym.warn} ${message}`)}\n`);
+}
+export function error(message) {
+    write(`${theme.fail(`${sym.fail} ${message}`)}\n`);
+}
+export function hint(message) {
+    write(`  ${theme.muted(`${sym.bullet} ${message}`)}\n`);
+}
+/** A blank line, but only when the terminal can afford it. */
+export function gap() {
+    if (animationEnabled())
+        write("\n");
+}
+/* ------------------------------------------------------------------ */
+/* Banner                                                              */
+/* ------------------------------------------------------------------ */
+/** Two-row block wordmark: readable at small widths, unlike a huge figlet. */
+const WORDMARK = [
+    "▀█▀ █▀▀ █░░ █▀▀ █▀▀ █▀█ ▄▀█ █▀▄▀█",
+    "░█░ █▀▀ █░░ ██▄ █▄█ █▀▄ █▀█ █░▀░█",
+];
+/**
+ * Print the banner. Deliberately quiet on repeated runs: the full frame is for
+ * CLI commands (login, doctor, --help), while a server start uses the compact
+ * form so an agent's log does not fill up with art.
+ */
+export function banner(opts = {}) {
+    const version = opts.version ?? SERVER_VERSION;
+    const subtitle = opts.subtitle ?? "your Telegram account, as an MCP server";
+    if (opts.compact || !animationEnabled()) {
+        write(`${theme.title(SERVER_NAME)} ${theme.muted(version)} ${theme.muted(sym.bullet)} ${theme.label(subtitle)}\n`);
+        return;
+    }
+    const width = Math.max(...WORDMARK.map((row) => [...row].length)) + 4;
+    write(`${theme.border(`${sym.tl}${sym.h.repeat(width)}${sym.tr}`)}\n`);
+    for (const row of WORDMARK)
+        write(`${theme.border(sym.bar)}  ${theme.title(row)}\n`);
+    write(`${theme.border(sym.bar)}  ${theme.muted(version)} ${theme.muted(sym.bullet)} ${theme.label(subtitle)}\n`);
+    write(`${theme.border(`${sym.bl}${sym.h.repeat(width)}${sym.br}`)}\n`);
+}
+/* ------------------------------------------------------------------ */
+/* Spinner                                                             */
+/* ------------------------------------------------------------------ */
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+/** Redraw the current line in place. Only valid when animation is on. */
+function redraw(text) {
+    write(`\u001b[2K\r${text}`);
+}
+function clearLine() {
+    write("\u001b[2K\r");
+}
+/**
+ * A one-line spinner with a hard time cap, so a stuck network call cannot leave
+ * something spinning in a log forever. `stop()` erases the line and optionally
+ * replaces it with a final message.
+ */
+export function spinner(text, opts = {}) {
+    const maxMs = opts.maxMs ?? 6000;
+    if (!animationEnabled()) {
+        write(`${theme.muted(`${sym.bullet} ${text}`)}\n`);
+        return { stop: () => undefined };
+    }
+    let frame = 0;
+    const started = Date.now();
+    let stopped = false;
+    const stop = (final) => {
+        if (stopped)
+            return;
+        stopped = true;
+        clearInterval(timer);
+        clearLine();
+        if (final)
+            write(`${final}\n`);
+    };
+    const draw = () => redraw(`${theme.accent(FRAMES[frame++ % FRAMES.length])} ${text}`);
+    draw();
+    const timer = setInterval(() => {
+        if (Date.now() - started > maxMs) {
+            // Give up quietly: the caller still prints its own outcome line.
+            stop();
+            return;
+        }
+        draw();
+    }, 90);
+    // Never let the animation be the reason the process stays alive.
+    timer.unref?.();
+    return { stop };
+}
+/** A numbered step header, e.g. `[1/3] Connecting to Telegram`. */
+export function step(index, total, text) {
+    write(`${theme.accent(`[${theme.muted(`${index}/${total}`)}]`)} ${theme.bold(text)}\n`);
+}
+/**
+ * The three-step onboarding footer shown once credentials are written. It is
+ * the answer to "ok, and now what?" — the most common question after setup.
+ */
+export function nextSteps(steps) {
+    if (!steps.length)
+        return;
+    gap();
+    write(`${theme.label(theme.bold("Next"))}\n`);
+    steps.forEach((text, i) => {
+        write(`  ${theme.accent(String(i + 1))}${theme.muted(".")} ${text}\n`);
+    });
+}

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.2",
   "description": "Local MCP server that connects CLI agents (OpenCode, Codex CLI, Claude Code, ...) to a personal Telegram account over MTProto.",
   "type": "module",
   "bin": {
@@ -18,6 +18,7 @@
     "start": "node dist/index.js",
     "login": "tsx cli/login.ts",
     "doctor": "tsx cli/doctor.ts",
+    "preview": "node harness/preview.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "login:force": "tsx cli/login.ts --force",
     "test": "npm run build && node harness/unit.mjs",