cursor-telegram-mcp 0.5.0

package/dist/index.js

@@ -0,0 +1,334 @@
+/**
+ * Cursor <-> Telegram MCP server (stdio) - thin client.
+ *
+ * Holds NO Telegram connection. It forwards each tool call to the local worker
+ * (`npm run worker`) over a localhost HTTP API, tagging messages with this
+ * project's label (TG_PROJECT). Cursor can restart/reload this server freely
+ * without dropping the worker's Telegram connection.
+ *
+ * Tools:
+ *   - notify_human_task_complete : fire-and-forget completion message.
+ *   - ask_human_for_guidance     : send a question, return immediately with an id.
+ *   - ask_human_and_wait         : send a question and block until answered/timed_out.
+ *   - check_human_response       : poll for the human's reply by id.
+ *
+ * stdout is reserved for JSON-RPC; diagnostics go to stderr.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, openSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { configDir, getConfig } from "./config.js";
+function logErr(msg) {
+    process.stderr.write(`[telegram-mcp] ${msg}\n`);
+}
+function textResult(text, isError = false) {
+    return { content: [{ type: "text", text }], isError };
+}
+const WORKER_DOWN = "Cannot reach the Telegram worker. It should auto-start with this MCP server; " +
+    "if it doesn't, run `cursor-telegram-mcp setup` to configure your bot " +
+    "(TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID), then reload. `cursor-telegram-mcp doctor` " +
+    "diagnoses problems.";
+async function main() {
+    const config = getConfig(false);
+    const base = config.workerUrl;
+    async function callWorker(method, path, body) {
+        try {
+            const res = await fetch(`${base}${path}`, {
+                method,
+                headers: body ? { "content-type": "application/json" } : undefined,
+                body: body ? JSON.stringify(body) : undefined,
+            });
+            let parsed = {};
+            try {
+                parsed = (await res.json());
+            }
+            catch {
+                parsed = {};
+            }
+            return { status: res.status, body: parsed };
+        }
+        catch {
+            return null; // worker unreachable
+        }
+    }
+    /**
+     * Ensure a worker is running. If `/health` is unreachable, spawn a detached,
+     * background worker (a singleton: the worker's own port guard makes concurrent
+     * MCP instances safe) and poll until it is ready. In dev (running .ts via tsx)
+     * the compiled worker entry won't exist, so this is a no-op fallback and the
+     * worker is expected to be started manually.
+     */
+    async function ensureWorker() {
+        if (await callWorker("GET", "/health"))
+            return;
+        const workerEntry = fileURLToPath(new URL("./worker.js", import.meta.url));
+        if (!existsSync(workerEntry)) {
+            logErr(`Worker not auto-started (entry not found: ${workerEntry}). Start it manually.`);
+            return;
+        }
+        try {
+            mkdirSync(configDir(), { recursive: true });
+            const logPath = join(configDir(), "worker.log");
+            const logFd = openSync(logPath, "a");
+            const child = spawn(process.execPath, [workerEntry], {
+                detached: true,
+                stdio: ["ignore", logFd, logFd],
+                windowsHide: true,
+                env: process.env,
+            });
+            child.unref();
+            logErr(`Auto-started worker (pid ${child.pid ?? "?"}); logs: ${logPath}`);
+        }
+        catch (err) {
+            logErr(`Could not auto-start worker: ${String(err)}`);
+            return;
+        }
+        for (let i = 0; i < 30; i++) {
+            await new Promise((r) => setTimeout(r, 500));
+            if (await callWorker("GET", "/health")) {
+                logErr("Worker is up.");
+                return;
+            }
+        }
+        logErr("Worker did not become ready in time; tools will retry on use.");
+    }
+    async function pollResponse(questionId, waitMs = 0) {
+        const qs = waitMs > 0 ? `?waitMs=${waitMs}` : "";
+        return callWorker("GET", `/response/${encodeURIComponent(questionId)}${qs}`);
+    }
+    /**
+     * Long-poll the worker until the question is answered/timed_out or `maxWaitMs`
+     * elapses. Issues repeated long-poll requests in chunks of `config.defaultPollWaitMs`
+     * so a single fetch never sits open long enough to hit the client's headers
+     * timeout. Returns the last worker response (answered/timed_out, or pending if
+     * the budget runs out). Non-200 responses (e.g. 404) are returned immediately.
+     */
+    async function waitForHumanResponse(questionId, maxWaitMs, initialPollWaitMs = 0) {
+        const startedAt = Date.now();
+        let res = await pollResponse(questionId, initialPollWaitMs);
+        while (true) {
+            if (!res || res.status !== 200)
+                return res;
+            const status = String(res.body.status ?? "");
+            if (status === "answered" || status === "timed_out")
+                return res;
+            const remaining = maxWaitMs - (Date.now() - startedAt);
+            if (remaining <= 0)
+                return res;
+            res = await pollResponse(questionId, Math.min(config.defaultPollWaitMs, remaining));
+        }
+    }
+    function responseCheckError(questionId, res) {
+        if (res.status === 404) {
+            return textResult(`Unknown questionId "${questionId}". It may be from a previous session or mistyped.`, true);
+        }
+        if (res.status !== 200) {
+            return textResult(`Failed to check (status ${res.status}): ${String(res.body.error ?? "unknown")}`, true);
+        }
+        return null;
+    }
+    function formatResponseResult(questionId, body) {
+        const status = String(body.status ?? "");
+        const elapsedMin = Number(body.elapsedMin ?? 0);
+        if (status === "answered") {
+            const answer = String(body.answer ?? "");
+            const attachments = Array.isArray(body.attachments) ? body.attachments : [];
+            let text = `status: answered\nquestionId: ${questionId}\n\nHuman's answer:\n${answer}`;
+            if (attachments.length > 0) {
+                const paths = attachments
+                    .map((a) => (typeof a === "object" && a && "localPath" in a ? String(a.localPath) : ""))
+                    .filter(Boolean);
+                if (paths.length > 0) {
+                    text += `\n\nAttachments (${paths.length}):\n${paths.join("\n")}`;
+                }
+            }
+            return { text, isError: false };
+        }
+        if (status === "timed_out") {
+            return {
+                text: `status: timed_out\nquestionId: ${questionId}\nNo reply after ${elapsedMin} minutes.\n` +
+                    "Guidance: choose a safe default, or leave a TODO and continue, rather than waiting indefinitely.",
+                isError: false,
+            };
+        }
+        return {
+            text: `status: pending\nquestionId: ${questionId}\nElapsed ${elapsedMin} min. No reply yet. ` +
+                "Call check_human_response again with waitMs (e.g. 60000) to long-poll, " +
+                "or pass waitMs=0 for an instant status check.",
+            isError: false,
+        };
+    }
+    const server = new McpServer({ name: "cursor-telegram", version: "0.5.0" });
+    server.registerTool("notify_human_task_complete", {
+        title: "Notify human: task complete",
+        description: "Send the human a Telegram message reporting that the current task is " +
+            "finished. Use a concise summary of what was done. Fire-and-forget: " +
+            "returns immediately and does not wait for a reply.",
+        inputSchema: {
+            summary: z
+                .string()
+                .min(1)
+                .describe("Short summary of the completed work (what changed / result)."),
+        },
+    }, async ({ summary }) => {
+        const r = await callWorker("POST", "/notify", { summary, project: config.project });
+        if (!r)
+            return textResult(WORKER_DOWN, true);
+        if (r.status === 200)
+            return textResult("Completion message sent to the human via Telegram.");
+        if (r.status === 503)
+            return textResult("Telegram is not connected in the worker (check TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID and the worker terminal).", true);
+        if (r.status === 429) {
+            const waitMs = Number(r.body.waitMs ?? 0);
+            return textResult(`Rate limited: wait ${Math.ceil(waitMs / 1000)}s before sending another message.`, true);
+        }
+        return textResult(`Failed to send (status ${r.status}): ${String(r.body.error ?? "unknown")}`, true);
+    });
+    server.registerTool("ask_human_for_guidance", {
+        title: "Ask human for guidance",
+        description: "Send the human a question over Telegram and return immediately with a " +
+            "question id. Use this when you can do other work while waiting. To get " +
+            "the reply, call check_human_response with the returned id and waitMs " +
+            "(e.g. 60000) to long-poll until answered — the worker picks up the " +
+            "Telegram reply promptly and the tool returns right away (do NOT sleep " +
+            "on a fixed timer between checks). If the answer gates your next step, " +
+            "prefer ask_human_and_wait instead.",
+        inputSchema: {
+            question: z
+                .string()
+                .min(1)
+                .describe("The exact question to ask the human. Be specific and include the " +
+                "options/context needed to answer from a phone."),
+        },
+    }, async ({ question }) => {
+        const r = await callWorker("POST", "/ask", { question, project: config.project });
+        if (!r)
+            return textResult(WORKER_DOWN, true);
+        if (r.status === 200) {
+            const id = String(r.body.id ?? "");
+            return textResult(`Question sent to the human (id: ${id}).\n` +
+                `To get the reply, call check_human_response with questionId="${id}" and ` +
+                "waitMs (e.g. 60000) to long-poll until answered — returns the moment " +
+                "the human replies (do NOT sleep on a fixed timer between checks). Use " +
+                "ask_human_and_wait instead when the answer gates your next step.");
+        }
+        if (r.status === 503)
+            return textResult("Telegram is not connected in the worker (check TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID and the worker terminal).", true);
+        if (r.status === 429) {
+            const waitMs = Number(r.body.waitMs ?? 0);
+            return textResult(`Rate limited: wait ${Math.ceil(waitMs / 1000)}s before asking another question.`, true);
+        }
+        return textResult(`Failed to ask (status ${r.status}): ${String(r.body.error ?? "unknown")}`, true);
+    });
+    server.registerTool("ask_human_and_wait", {
+        title: "Ask human and wait for answer",
+        description: "Send the human a question over Telegram and block until they answer or " +
+            "the question times out. Prefer this over ask_human_for_guidance when you " +
+            "must have the human's reply before continuing. Long-polls the worker HTTP " +
+            "API and returns immediately when the human replies on Telegram (wakes on " +
+            "answer, not on the worker's getUpdates long-poll timeout).",
+        inputSchema: {
+            question: z
+                .string()
+                .min(1)
+                .describe("The exact question to ask the human. Be specific and include the " +
+                "options/context needed to answer from a phone."),
+            timeoutMin: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Maximum minutes to wait for a reply (default: TG_RESPONSE_TIMEOUT_MIN, " +
+                "usually 30). Returns timed_out if no reply within this window."),
+        },
+    }, async ({ question, timeoutMin }) => {
+        const maxWaitMin = timeoutMin ?? config.responseTimeoutMin;
+        const askRes = await callWorker("POST", "/ask", { question, project: config.project });
+        if (!askRes)
+            return textResult(WORKER_DOWN, true);
+        if (askRes.status === 503) {
+            return textResult("Telegram is not connected in the worker (check TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID and the worker terminal).", true);
+        }
+        if (askRes.status === 429) {
+            const waitMs = Number(askRes.body.waitMs ?? 0);
+            return textResult(`Rate limited: wait ${Math.ceil(waitMs / 1000)}s before asking another question.`, true);
+        }
+        if (askRes.status !== 200) {
+            return textResult(`Failed to ask (status ${askRes.status}): ${String(askRes.body.error ?? "unknown")}`, true);
+        }
+        const questionId = String(askRes.body.id ?? "");
+        const maxWaitMs = maxWaitMin * 60_000;
+        const pollRes = await waitForHumanResponse(questionId, maxWaitMs);
+        if (!pollRes)
+            return textResult(WORKER_DOWN, true);
+        const err = responseCheckError(questionId, pollRes);
+        if (err)
+            return err;
+        const { text, isError } = formatResponseResult(questionId, pollRes.body);
+        return textResult(text, isError);
+    });
+    server.registerTool("check_human_response", {
+        title: "Check human response",
+        description: "Poll for the human's reply to a previously asked question. Returns the " +
+            "answer if it has arrived, or a pending/timed-out status. RECOMMENDED: " +
+            "pass waitMs (e.g. 60000) to long-poll until answered or timed_out — the " +
+            "worker delivers Telegram replies promptly and this tool wakes immediately " +
+            "(do NOT sleep on a fixed timer between checks). Omit waitMs to long-poll " +
+            "until timed_out; pass waitMs=0 for an instant status-only check. Prefer " +
+            "ask_human_and_wait when you must block until the human replies.",
+        inputSchema: {
+            questionId: z
+                .string()
+                .min(1)
+                .describe('The question id returned by ask_human_for_guidance (e.g. "Q-1").'),
+            waitMs: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe("Long-poll budget in milliseconds (recommended, e.g. 60000). The tool " +
+                "returns immediately when the human replies. Omit to long-poll until " +
+                "timed_out; pass 0 for an immediate status-only check."),
+        },
+    }, async ({ questionId, waitMs }) => {
+        if (waitMs === 0) {
+            const r = await pollResponse(questionId, 0);
+            if (!r)
+                return textResult(WORKER_DOWN, true);
+            const err = responseCheckError(questionId, r);
+            if (err)
+                return err;
+            const { text, isError } = formatResponseResult(questionId, r.body);
+            return textResult(text, isError);
+        }
+        const maxWaitMs = waitMs ?? config.responseTimeoutMin * 60_000;
+        const r = await waitForHumanResponse(questionId, maxWaitMs);
+        if (!r)
+            return textResult(WORKER_DOWN, true);
+        const err = responseCheckError(questionId, r);
+        if (err)
+            return err;
+        const { text, isError } = formatResponseResult(questionId, r.body);
+        return textResult(text, isError);
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logErr(`MCP server started (stdio). Worker: ${base} project: ${config.project}`);
+    // Auto-start the worker if it isn't already running, then report status.
+    await ensureWorker();
+    const health = await callWorker("GET", "/health");
+    if (!health)
+        logErr(WORKER_DOWN);
+    else if (!health.body.connected)
+        logErr("Worker is up but Telegram is not connected yet.");
+    else
+        logErr("Worker reachable and Telegram connected.");
+}
+main().catch((err) => {
+    logErr(`Fatal: ${err?.stack ?? err}`);
+    process.exit(1);
+});

package/dist/login.js

@@ -0,0 +1,59 @@
+/**
+ * Find your Telegram chat id and save it to the user config file.
+ *
+ * Requires TELEGRAM_BOT_TOKEN to be set (via `setup`, the config file, or env):
+ *   1. validates the token (getMe) and prints the bot's @username, then
+ *   2. long-polls for a message. Open your bot in Telegram and send it any
+ *      message (e.g. /start). The chat id is saved to config.json.
+ *
+ * Run this only while the worker is stopped (both use getUpdates).
+ */
+import { configFilePath, getConfig, writeFileConfig } from "./config.js";
+import { GETUPDATES_LONG_POLL_SEC } from "./telegram.js";
+const log = (msg) => process.stderr.write(msg + "\n");
+async function call(base, method, params) {
+    const res = await fetch(`${base}/${method}`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(params ?? {}),
+    });
+    const data = (await res.json());
+    if (!data.ok) {
+        throw new Error(`Telegram ${method} failed: ${data.description ?? `HTTP ${res.status}`}`);
+    }
+    return data.result;
+}
+async function main() {
+    const config = getConfig(); // requires TELEGRAM_BOT_TOKEN
+    const base = `https://api.telegram.org/bot${config.botToken}`;
+    const me = await call(base, "getMe");
+    log(`Bot validated: @${me.username ?? me.id}`);
+    log("Now open your bot in Telegram and send it a message (e.g. /start).");
+    log("Waiting for an incoming message...\n");
+    let offset = 0;
+    for (;;) {
+        const updates = await call(base, "getUpdates", {
+            offset,
+            timeout: GETUPDATES_LONG_POLL_SEC,
+            allowed_updates: ["message"],
+        });
+        for (const update of updates) {
+            offset = update.update_id + 1;
+            const chat = update.message?.chat;
+            if (!chat)
+                continue;
+            const who = update.message?.from?.username ?? update.message?.from?.first_name ?? "unknown";
+            log("=== Found your chat ===");
+            log(`From: ${who}`);
+            log(`Chat id: ${chat.id}`);
+            writeFileConfig({ TELEGRAM_CHAT_ID: String(chat.id) });
+            log(`\nSaved TELEGRAM_CHAT_ID to ${configFilePath()}`);
+            log("Reload the MCP in Cursor (the worker auto-starts), or run the worker directly.");
+            process.exit(0);
+        }
+    }
+}
+main().catch((err) => {
+    process.stderr.write(`Setup failed: ${err?.message ?? err}\n`);
+    process.exit(1);
+});

package/dist/parseInbound.js

@@ -0,0 +1,93 @@
+/**
+ * Split compound Telegram inbound messages into ordered action segments.
+ *
+ * Handles leading YES/NO with trailing content, multi-line messages, and
+ * /ask or /plan on any line. Reply-to HITL answers should bypass splitting
+ * (caller passes the full text as a single answer).
+ */
+/** Standard plan-approval footer sent after Plan (C-n). */
+const APPROVAL_FOOTER_RE = /^\s*reply\s+yes\s+to\s+run\b[\s\S]*\bno\s+to\s+cancel\.?\s*$/i;
+/** True when text is (or ends with) the plan YES/NO footer — not a new task. */
+export function isPlanApprovalFooter(text) {
+    const t = text.trim();
+    if (t === "")
+        return false;
+    if (APPROVAL_FOOTER_RE.test(t))
+        return true;
+    const lines = t.split(/\n/).map((l) => l.trim()).filter(Boolean);
+    const last = lines[lines.length - 1] ?? "";
+    return APPROVAL_FOOTER_RE.test(last);
+}
+const STATUS_RE = /^\s*status\s*$/i;
+const YES_WORDS = "yes|yea|yeah|y|approve|approved|ok|okay|go|do it|כן|אישור|בצע";
+const NO_WORDS = "no|n|cancel|stop|reject|nope|לא|ביטול|עצור";
+const YES_ONLY_RE = new RegExp(`^\\s*(${YES_WORDS})\\s*[!.]?\\s*$`, "i");
+const NO_ONLY_RE = new RegExp(`^\\s*(${NO_WORDS})\\s*[!.]?\\s*$`, "i");
+const YES_LEADING_RE = new RegExp(`^\\s*(${YES_WORDS})\\b\\s*,?\\s*also\\b\\s*(.*)$`, "is");
+const NO_LEADING_RE = new RegExp(`^\\s*(${NO_WORDS})\\b\\s*,?\\s*also\\b\\s*(.*)$`, "is");
+/** Split body on newlines and ", also" / "Also," boundaries. */
+function splitParts(text) {
+    const parts = [];
+    for (const line of text.split(/\n/)) {
+        const chunks = line.split(/\s*,\s*also\s*,?\s*|\s+also\s*:\s*/i);
+        for (const chunk of chunks) {
+            const trimmed = chunk.trim();
+            if (trimmed !== "")
+                parts.push(trimmed);
+        }
+    }
+    return parts;
+}
+function parseCommandLine(part) {
+    const m = part.match(/^\s*\/(ask|plan)(?:\s+(.*))?$/is);
+    if (!m)
+        return null;
+    const mode = m[1].toLowerCase();
+    const rest = (m[2] ?? "").trim();
+    if (mode === "ask") {
+        return rest === "" ? { kind: "ask_empty" } : { kind: "ask", text: rest };
+    }
+    return rest === "" ? { kind: "plan_empty" } : { kind: "plan", text: rest };
+}
+function classifyPart(part) {
+    if (STATUS_RE.test(part))
+        return [{ kind: "status" }];
+    if (YES_ONLY_RE.test(part))
+        return [{ kind: "approve" }];
+    if (NO_ONLY_RE.test(part))
+        return [{ kind: "reject" }];
+    const yesLead = part.match(YES_LEADING_RE);
+    if (yesLead) {
+        const rest = (yesLead[2] ?? "").trim();
+        if (rest === "")
+            return [{ kind: "approve" }];
+        return [{ kind: "approve" }, ...splitInboundMessage(rest)];
+    }
+    const noLead = part.match(NO_LEADING_RE);
+    if (noLead) {
+        const rest = (noLead[2] ?? "").trim();
+        if (rest === "")
+            return [{ kind: "reject" }];
+        return [{ kind: "reject" }, ...splitInboundMessage(rest)];
+    }
+    const cmd = parseCommandLine(part);
+    if (cmd)
+        return [cmd];
+    if (isPlanApprovalFooter(part))
+        return [{ kind: "approval_footer" }];
+    return [{ kind: "plain", text: part }];
+}
+/** Parse inbound text into ordered segments (approve/reject first per part). */
+export function splitInboundMessage(text) {
+    const trimmed = text.trim();
+    if (trimmed === "")
+        return [];
+    if (isPlanApprovalFooter(trimmed)) {
+        return [{ kind: "approval_footer" }];
+    }
+    const segments = [];
+    for (const part of splitParts(trimmed)) {
+        segments.push(...classifyPart(part));
+    }
+    return segments;
+}

package/dist/session.js

@@ -0,0 +1,49 @@
+/**
+ * Persist the "rolling" command-mode conversation across worker restarts.
+ *
+ * Command mode keeps ONE long-lived Cursor agent so knowledge carries across
+ * every phone message. The agent's id is written here so that, after the worker
+ * restarts (manually or via the self-update logic in worker.ts), the next
+ * message resumes the same conversation instead of starting fresh.
+ *
+ * State lives in a small JSON file (default `<configDir>/rolling-session.json`).
+ */
+import { mkdirSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import { dirname } from "node:path";
+/** Read the rolling session file. Returns undefined if missing/unreadable. */
+export function loadRollingSession(path) {
+    try {
+        const raw = readFileSync(path, "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.agentId === "string" &&
+            parsed.agentId.trim() !== "" &&
+            typeof parsed.model === "string" &&
+            typeof parsed.cwd === "string" &&
+            typeof parsed.startedAt === "number") {
+            return parsed;
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Write the rolling session file (creating the parent dir if needed). */
+export function saveRollingSession(path, session) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(session, null, 2) + "\n", "utf8");
+    }
+    catch {
+        // Best-effort: losing the file just means the next restart starts fresh.
+    }
+}
+/** Remove the rolling session file (used when starting a new thread). */
+export function clearRollingSession(path) {
+    try {
+        rmSync(path, { force: true });
+    }
+    catch {
+        // Best-effort.
+    }
+}

package/dist/setup.js

@@ -0,0 +1,127 @@
+/**
+ * Interactive first-time setup (bring-your-own-bot).
+ *
+ * Walks the user through:
+ *   1. Creating a bot with @BotFather and pasting the token (validated).
+ *   2. Capturing their chat id by messaging the bot.
+ *   3. Optionally enabling command mode with a Cursor API key.
+ * Writes everything to the user config file and prints the mcp.json snippet.
+ */
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { configFilePath, readFileConfig, writeFileConfig } from "./config.js";
+async function tg(token, method, params) {
+    const res = await fetch(`https://api.telegram.org/bot${token}/${method}`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(params ?? {}),
+    });
+    const data = (await res.json());
+    if (!data.ok)
+        throw new Error(data.description ?? `HTTP ${res.status}`);
+    return data.result;
+}
+function out(msg = "") {
+    stdout.write(msg + "\n");
+}
+async function main() {
+    const rl = createInterface({ input: stdin, output: stdout });
+    try {
+        const existing = readFileConfig();
+        out("cursor-telegram-mcp setup");
+        out("=========================");
+        out("");
+        out("Step 1: Create your Telegram bot (free, ~2 min).");
+        out("  - Open Telegram and message @BotFather: https://t.me/BotFather");
+        out("  - Send /newbot, choose a name and a username ending in 'bot'.");
+        out("  - BotFather replies with a token like 123456789:ABC-DEF...");
+        out("");
+        // Token (validate via getMe).
+        let token = existing.TELEGRAM_BOT_TOKEN ?? "";
+        let username;
+        for (;;) {
+            const def = token ? ` [${token.slice(0, 6)}...]` : "";
+            const answer = (await rl.question(`Paste your bot token${def}: `)).trim();
+            const candidate = answer || token;
+            if (!candidate) {
+                out("A token is required. (Ctrl-C to abort.)");
+                continue;
+            }
+            try {
+                const me = await tg(candidate, "getMe");
+                username = me.username;
+                token = candidate;
+                out(`Validated bot: @${username ?? me.id}`);
+                writeFileConfig({ TELEGRAM_BOT_TOKEN: token });
+                break;
+            }
+            catch (err) {
+                out(`That token did not validate (${String(err)}). Try again.`);
+                token = "";
+            }
+        }
+        out("");
+        out("Step 2: Capture your chat id.");
+        out(`  - Open your bot${username ? ` (https://t.me/${username})` : ""} in Telegram.`);
+        out("  - Press Start, or send it any message (e.g. 'hi').");
+        await rl.question("Press Enter once you've sent your bot a message... ");
+        out("Looking for your message...");
+        let chatId = "";
+        let offset = 0;
+        const deadline = Date.now() + 120_000;
+        while (Date.now() < deadline && !chatId) {
+            const updates = await tg(token, "getUpdates", { offset, timeout: 20, allowed_updates: ["message"] });
+            for (const u of updates) {
+                offset = u.update_id + 1;
+                const chat = u.message?.chat;
+                if (chat) {
+                    chatId = String(chat.id);
+                    const who = u.message?.from?.username ?? u.message?.from?.first_name ?? "you";
+                    out(`Found chat id ${chatId} (from ${who}).`);
+                    break;
+                }
+            }
+        }
+        if (!chatId) {
+            out("No message detected. Re-run `cursor-telegram-mcp setup` (or `login`) and message your bot.");
+            process.exitCode = 1;
+            return;
+        }
+        writeFileConfig({ TELEGRAM_CHAT_ID: chatId });
+        out("");
+        out("Step 3 (optional): Command mode lets you TEXT tasks to the bot and have a");
+        out("headless Cursor agent plan + execute them. It needs a Cursor API key");
+        out("(https://cursor.com/dashboard/integrations) and the Cursor CLI installed.");
+        const key = (await rl.question("Cursor API key (Enter to skip): ")).trim();
+        if (key) {
+            writeFileConfig({ CURSOR_API_KEY: key });
+            out("Command mode enabled. Run `cursor-telegram-mcp doctor` to verify the Cursor CLI.");
+        }
+        else {
+            out("Skipped. Notifications and questions still work; enable later by re-running setup.");
+        }
+        out("");
+        out("Done. Config saved to:");
+        out(`  ${configFilePath()}`);
+        out("");
+        out("Add this to your project's .cursor/mcp.json (or Cursor Settings -> MCP):");
+        out("");
+        out('  {');
+        out('    "mcpServers": {');
+        out('      "telegram": {');
+        out('        "command": "npx",');
+        out('        "args": ["-y", "cursor-telegram-mcp"]');
+        out('      }');
+        out('    }');
+        out('  }');
+        out("");
+        out("Then reload MCP in Cursor. The worker auto-starts with the MCP server.");
+    }
+    finally {
+        rl.close();
+    }
+}
+main().catch((err) => {
+    stdout.write(`Setup failed: ${err?.message ?? err}\n`);
+    process.exit(1);
+});