cursor-telegram-mcp 0.6.0 → 0.7.0

package/README.md

@@ -32,21 +32,40 @@ Prefer it under "Plugin MCP Servers" / the Cursor marketplace? See
 
 ## Quick start
 
-### 1. Configure your bot (one time)
+The goal: your bot is online whenever your computer is on — no need to open
+Cursor or start anything by hand.
+
+### 1. Install (one time)
+
+```bash
+npm i -g cursor-telegram-mcp
+```
+
+A global install gives the always-on service a stable location. (You can also
+run everything via `npx cursor-telegram-mcp …`, but the always-on installer
+needs a global install so its launch agent doesn't point at a temporary cache.)
+
+### 2. Configure + go always-on
 
 ```bash
-npx cursor-telegram-mcp setup
+cursor-telegram-mcp setup
 ```
 
-The wizard walks you through creating a bot with [@BotFather](https://t.me/BotFather),
-validates the token, captures your chat id (you message the bot once), and
-optionally enables command mode with a Cursor API key. It saves everything to a
-local config file (`~/.config/cursor-telegram/config.json`, or
+The wizard creates a bot with [@BotFather](https://t.me/BotFather), validates
+the token, captures your chat id (you message the bot once), optionally enables
+command mode with a Cursor API key, and then offers to install the **always-on
+service** (macOS launchd: starts at login, restarts itself, plus a watchdog).
+Config is saved to `~/.config/cursor-telegram/config.json` (or
 `%APPDATA%\cursor-telegram\config.json` on Windows).
 
-### 2. Add it to Cursor
+That's it — text your bot to test it. Run `cursor-telegram-mcp doctor` anytime
+to check status, and `cursor-telegram-mcp install` / `uninstall` to toggle the
+always-on service.
+
+### 3. (optional) Let Cursor agents message you
 
-Add this to your project's `.cursor/mcp.json` (or Cursor Settings -> Tools & MCP):
+Add this to a project's `.cursor/mcp.json` (or Cursor Settings -> Tools & MCP),
+then reload MCP:
 
 ```json
 {
@@ -59,8 +78,8 @@ Add this to your project's `.cursor/mcp.json` (or Cursor Settings -> Tools & MCP
 }
 ```
 
-Reload MCP in Cursor. That's it - the MCP server auto-starts the background
-worker. Run `npx cursor-telegram-mcp doctor` anytime to check status.
+The bot itself runs from the always-on service regardless of Cursor; this step
+just lets in-IDE agents send you notifications and questions.
 
 ## Architecture
 
@@ -174,6 +193,20 @@ current Node and the installed CLI — no hardcoded paths — runs the worker un
 (`KeepAlive`). Logs go to `~/Library/Logs/cursor-telegram-worker.log`. Keep the
 Mac on AC power so a closed lid does not fully sleep.
 
+`install` also sets up a **watchdog** (`com.cursor-telegram.watchdog`, every
+120s) that checks the worker's `/health` and restarts it if it is unreachable
+or its poll loop has wedged. Combined with the worker's own retry/backoff (every
+Bot API call has a hard abort timeout, so a stale socket after sleep/wake can't
+silently hang it), the bot stays online as long as the Mac is on.
+
+To stay online the Mac must not fully sleep. The worker runs under `caffeinate`
+so idle sleep is prevented while it's up, but a closed lid on battery still
+sleeps. For a machine you want always-on:
+
+- Keep it on **AC power**.
+- Optionally allow it to run with the lid closed on AC:
+  `sudo pmset -c sleep 0 disablesleep 1` (revert with `sudo pmset -c disablesleep 0`).
+
 On Linux/Windows, run `cursor-telegram-mcp worker` under your own service
 manager (systemd / Task Scheduler). (Note: on macOS, launchd agents cannot read
 files under `~/Desktop`/`~/Documents`/`~/Downloads`; install the package or
@@ -210,8 +243,9 @@ cursor-telegram-mcp [mcp]    Start the MCP server (default; Cursor runs this)
 cursor-telegram-mcp setup    First-time setup: create/link your bot
 cursor-telegram-mcp login    Print and save your Telegram chat id
 cursor-telegram-mcp worker   Run the background worker in the foreground
-cursor-telegram-mcp install  Install the always-on worker (macOS launchd)
-cursor-telegram-mcp uninstall Remove the always-on worker
+cursor-telegram-mcp install  Install the always-on worker + watchdog (macOS launchd)
+cursor-telegram-mcp uninstall Remove the always-on worker + watchdog
+cursor-telegram-mcp watchdog One-shot health check; restarts the worker if down
 cursor-telegram-mcp doctor   Diagnose configuration and connectivity
 ```
 
@@ -308,7 +342,8 @@ src/
   session.ts    # persist the rolling agent id across worker restarts
   transcript.ts # append-only remote-chat.md transcript of the rolling chat
   store.ts      # pending-question store (persisted to disk) + reply matching
-  install.ts    # `install`/`uninstall`: generate a per-user launchd agent (macOS)
+  install.ts    # `install`/`uninstall`: generate per-user launchd worker + watchdog (macOS)
+  watchdog.ts   # `watchdog`: one-shot /health check that restarts a wedged worker
   parseInbound.ts / splitMessage.ts / taskQueue.ts / formatTelegram.ts
   answerWaiters.ts  # wake-on-answer for long-polling GET /response/:id
 .cursor/

package/dist/cli.js

@@ -47,6 +47,9 @@ async function run() {
         case "uninstall":
             await import("./install.js");
             break;
+        case "watchdog":
+            await import("./watchdog.js");
+            break;
         case "setup":
             await import("./setup.js");
             break;

package/dist/install.js

@@ -12,14 +12,17 @@
  */
 import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
-import { homedir, platform } from "node:os";
-import { dirname, join } from "node:path";
+import { homedir, platform, tmpdir } from "node:os";
+import { dirname, join, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 const LABEL = "com.cursor-telegram.worker";
+const WATCHDOG_LABEL = "com.cursor-telegram.watchdog";
 /** Older label used by the in-repo dev scripts; booted out on install to avoid a double-run. */
 const LEGACY_LABEL = "com.cursor-remote-chat.worker";
-function plistPath() {
-    return join(homedir(), "Library", "LaunchAgents", `${LABEL}.plist`);
+/** How often (seconds) the watchdog checks worker /health. */
+const WATCHDOG_INTERVAL_SEC = 120;
+function plistPath(label = LABEL) {
+    return join(homedir(), "Library", "LaunchAgents", `${label}.plist`);
 }
 function logPaths() {
     const dir = join(homedir(), "Library", "Logs");
@@ -38,6 +41,21 @@ function xmlEscape(s) {
 function cliEntry() {
     return fileURLToPath(import.meta.url).replace(/install\.js$/, "cli.js");
 }
+/**
+ * Whether this package lives in a stable location. `npx -y cursor-telegram-mcp`
+ * runs from an ephemeral cache that npm may garbage-collect, which would leave
+ * the launch agent pointing at a path that disappears. A global install
+ * (`npm i -g`) is durable. We refuse to install a launch agent from an
+ * ephemeral path unless explicitly forced.
+ */
+function isDurableInstall() {
+    const p = fileURLToPath(import.meta.url);
+    if (p.includes(`${sep}_npx${sep}`))
+        return false;
+    if (p.startsWith(tmpdir()))
+        return false;
+    return true;
+}
 function buildProgramArguments() {
     const node = process.execPath;
     const cli = cliEntry();
@@ -89,6 +107,45 @@ ${argXml}
 </plist>
 `;
 }
+function buildWatchdogPlist() {
+    const node = process.execPath;
+    const cli = cliEntry();
+    const nodeDir = dirname(process.execPath);
+    const pathEnv = [nodeDir, "/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin"].join(":");
+    const { out, err } = logPaths();
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${WATCHDOG_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${xmlEscape(node)}</string>
+    <string>${xmlEscape(cli)}</string>
+    <string>watchdog</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${xmlEscape(pathEnv)}</string>
+    <key>TG_WORKER_LABEL</key>
+    <string>${LABEL}</string>
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>StartInterval</key>
+  <integer>${WATCHDOG_INTERVAL_SEC}</integer>
+  <key>ProcessType</key>
+  <string>Background</string>
+  <key>StandardOutPath</key>
+  <string>${xmlEscape(out)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xmlEscape(err)}</string>
+</dict>
+</plist>
+`;
+}
 function domain() {
     return `gui/${process.getuid?.() ?? 501}`;
 }
@@ -108,8 +165,22 @@ function requireMac() {
         process.exit(1);
     }
 }
-function install() {
+export function runInstall() {
     requireMac();
+    if (!isDurableInstall() && process.env.TG_FORCE_INSTALL !== "1") {
+        process.stderr.write([
+            "This looks like a temporary (npx) copy, which npm may delete later —",
+            "an always-on launch agent must point at a stable install.",
+            "",
+            "Install it globally first, then run install:",
+            "  npm i -g cursor-telegram-mcp",
+            "  cursor-telegram-mcp install",
+            "",
+            "(Set TG_FORCE_INSTALL=1 to override, not recommended.)",
+            "",
+        ].join("\n"));
+        process.exit(1);
+    }
     const path = plistPath();
     mkdirSync(dirname(path), { recursive: true });
     mkdirSync(join(homedir(), "Library", "Logs"), { recursive: true });
@@ -118,9 +189,16 @@ function install() {
     launchctl(["bootout", domain(), path]);
     launchctl(["bootout", domain(), join(homedir(), "Library", "LaunchAgents", `${LEGACY_LABEL}.plist`)]);
     execFileSync("launchctl", ["bootstrap", domain(), path], { stdio: "inherit" });
+    // Watchdog: restarts the worker if it ever goes unreachable or its poll loop
+    // wedges, so the bot is never silently offline while the Mac is on.
+    const wdPath = plistPath(WATCHDOG_LABEL);
+    writeFileSync(wdPath, buildWatchdogPlist(), "utf8");
+    launchctl(["bootout", domain(), wdPath]);
+    execFileSync("launchctl", ["bootstrap", domain(), wdPath], { stdio: "inherit" });
     const { out } = logPaths();
     process.stdout.write([
         `Installed always-on worker: ${path}`,
+        `Installed watchdog (every ${WATCHDOG_INTERVAL_SEC}s): ${wdPath}`,
         `Logs: ${out}`,
         "",
         "It will start now and at every login. To stop it:",
@@ -130,13 +208,24 @@ function install() {
         "",
     ].join("\n"));
 }
-function uninstall() {
+export function runUninstall() {
     requireMac();
+    const wdPath = plistPath(WATCHDOG_LABEL);
+    launchctl(["bootout", domain(), wdPath]);
+    if (existsSync(wdPath))
+        rmSync(wdPath);
     const path = plistPath();
     launchctl(["bootout", domain(), path]);
     if (existsSync(path))
         rmSync(path);
-    process.stdout.write("Uninstalled always-on worker.\n");
+    process.stdout.write("Uninstalled always-on worker and watchdog.\n");
+}
+// Only act when invoked directly as the `install`/`uninstall` subcommand, so
+// other modules (e.g. setup) can import runInstall() without side effects.
+const sub = process.argv[2];
+if (sub === "install" || sub === "uninstall") {
+    if (sub === "uninstall")
+        runUninstall();
+    else
+        runInstall();
 }
-const action = process.argv[2] === "uninstall" ? uninstall : install;
-action();

package/dist/setup.js

@@ -9,7 +9,9 @@
  */
 import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
+import { platform } from "node:os";
 import { configFilePath, readFileConfig, writeFileConfig } from "./config.js";
+import { runInstall } from "./install.js";
 async function tg(token, method, params) {
     const res = await fetch(`https://api.telegram.org/bot${token}/${method}`, {
         method: "POST",
@@ -101,21 +103,39 @@ async function main() {
             out("Skipped. Notifications and questions still work; enable later by re-running setup.");
         }
         out("");
-        out("Done. Config saved to:");
+        out("Config saved to:");
         out(`  ${configFilePath()}`);
         out("");
-        out("Add this to your project's .cursor/mcp.json (or Cursor Settings -> MCP):");
+        out("Step 4 (recommended): keep your bot online whenever your computer is on.");
+        out("This runs a tiny background worker that starts at login and restarts");
+        out("itself if it ever stops - no need to open Cursor or run anything.");
+        if (platform() === "darwin") {
+            const yes = (await rl.question("Install the always-on service now? [Y/n]: ")).trim().toLowerCase();
+            if (yes === "" || yes === "y" || yes === "yes") {
+                try {
+                    runInstall();
+                }
+                catch (err) {
+                    out(`Could not install the service automatically: ${String(err)}`);
+                    out("You can run it later with: cursor-telegram-mcp install");
+                }
+            }
+            else {
+                out("Skipped. Enable it later with: cursor-telegram-mcp install");
+            }
+        }
+        else {
+            out("On Linux/Windows, run `cursor-telegram-mcp worker` under your service");
+            out("manager (systemd / Task Scheduler) so it starts at boot.");
+        }
+        out("");
+        out("Optional: to let Cursor agents message you, add this to a project's");
+        out(".cursor/mcp.json (or Cursor Settings -> MCP), then reload MCP:");
         out("");
-        out('  {');
-        out('    "mcpServers": {');
-        out('      "telegram": {');
-        out('        "command": "npx",');
-        out('        "args": ["-y", "cursor-telegram-mcp"]');
-        out('      }');
-        out('    }');
-        out('  }');
+        out('  { "mcpServers": { "telegram": { "command": "npx",');
+        out('      "args": ["-y", "cursor-telegram-mcp"] } } }');
         out("");
-        out("Then reload MCP in Cursor. The worker auto-starts with the MCP server.");
+        out("You're set - text your bot to test it.");
     }
     finally {
         rl.close();

package/dist/telegram.js

@@ -59,6 +59,8 @@ export class TelegramClient {
     stopping = false;
     offset = 0;
     me = null;
+    /** Last time getUpdates returned successfully (ms epoch); liveness signal. */
+    lastPollOkAt = Date.now();
     constructor(opts) {
         this.opts = opts;
         this.logger = opts.logger ?? silentLogger();
@@ -70,23 +72,46 @@ export class TelegramClient {
     isOpen() {
         return this.open;
     }
+    /**
+     * Milliseconds since getUpdates last returned successfully. A large value
+     * while `open` means the poll loop is stuck (e.g. a stale socket after the
+     * Mac slept) even though the connection looks up — used by /health and the
+     * watchdog to detect a silently-offline worker.
+     */
+    lastPollAgeMs() {
+        return Date.now() - this.lastPollOkAt;
+    }
     username() {
         return this.me?.username;
     }
     onIncoming(handler) {
         this.handlers.push(handler);
     }
-    async call(method, params) {
-        const res = await fetch(`${this.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}`}`);
+    /**
+     * Call a Bot API method with a hard client-side timeout. Without this, a
+     * socket left half-open by a sleep/wake could make `fetch` hang forever and
+     * silently take the bot offline. On timeout the call rejects (AbortError) and
+     * the caller retries.
+     */
+    async call(method, params, timeoutMs = 20_000) {
+        const ac = new AbortController();
+        const timer = setTimeout(() => ac.abort(), timeoutMs);
+        try {
+            const res = await fetch(`${this.base}/${method}`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify(params ?? {}),
+                signal: ac.signal,
+            });
+            const data = (await res.json());
+            if (!data.ok) {
+                throw new Error(`Telegram ${method} failed: ${data.description ?? `HTTP ${res.status}`}`);
+            }
+            return data.result;
+        }
+        finally {
+            clearTimeout(timer);
         }
-        return data.result;
     }
     async connect() {
         await mkdir(this.mediaDir, { recursive: true });
@@ -100,13 +125,19 @@ export class TelegramClient {
         sweep.unref?.();
     }
     async pollLoop() {
+        // Abort getUpdates a bit after the server-side long-poll window so a dead
+        // socket (e.g. after sleep/wake) can't wedge the loop indefinitely.
+        const pollTimeoutMs = (GETUPDATES_LONG_POLL_SEC + 15) * 1000;
+        let backoffMs = 1000;
         while (!this.stopping) {
             try {
                 const updates = await this.call("getUpdates", {
                     offset: this.offset,
                     timeout: GETUPDATES_LONG_POLL_SEC,
                     allowed_updates: ["message"],
-                });
+                }, pollTimeoutMs);
+                this.lastPollOkAt = Date.now();
+                backoffMs = 1000;
                 for (const update of updates) {
                     this.offset = update.update_id + 1;
                     const msg = await this.toIncoming(update.message);
@@ -118,8 +149,9 @@ export class TelegramClient {
             catch (err) {
                 if (this.stopping)
                     break;
-                this.logger.warn(`getUpdates error (retrying): ${String(err)}`);
-                await new Promise((r) => setTimeout(r, 3000));
+                this.logger.warn(`getUpdates error (retry in ${backoffMs}ms): ${String(err)}`);
+                await new Promise((r) => setTimeout(r, backoffMs));
+                backoffMs = Math.min(backoffMs * 2, 30_000);
             }
         }
     }
@@ -145,10 +177,18 @@ export class TelegramClient {
             throw new Error(`Attachment too large (${file.file_size} bytes, max ${this.maxAttachmentBytes})`);
         }
         const url = `https://api.telegram.org/file/bot${this.opts.botToken}/${file.file_path}`;
-        const res = await fetch(url);
-        if (!res.ok)
-            throw new Error(`Download failed: HTTP ${res.status}`);
-        const buf = Buffer.from(await res.arrayBuffer());
+        const ac = new AbortController();
+        const timer = setTimeout(() => ac.abort(), 60_000);
+        let buf;
+        try {
+            const res = await fetch(url, { signal: ac.signal });
+            if (!res.ok)
+                throw new Error(`Download failed: HTTP ${res.status}`);
+            buf = Buffer.from(await res.arrayBuffer());
+        }
+        finally {
+            clearTimeout(timer);
+        }
         if (buf.length > this.maxAttachmentBytes) {
             throw new Error(`Attachment too large (${buf.length} bytes, max ${this.maxAttachmentBytes})`);
         }

package/dist/watchdog.js

@@ -0,0 +1,62 @@
+/**
+ * `cursor-telegram-mcp watchdog` — one-shot liveness check.
+ *
+ * Meant to be run on a short interval by launchd (or cron). It hits the
+ * worker's /health and, if the worker is unreachable OR its poll loop looks
+ * wedged (pollAgeSec too high — e.g. a stale socket the abort timeout somehow
+ * missed), it kicks the worker's launch agent so launchd restarts it. The
+ * worker's own retry/backoff handles the common cases; this is the belt-and-
+ * suspenders layer so the bot is never silently offline while the Mac is on.
+ *
+ * Exits 0 always (a transient blip should not spam launchd error logs).
+ */
+import { execFileSync } from "node:child_process";
+import { getConfig } from "./config.js";
+/** launchd label to restart; overridable so it works for legacy installs too. */
+const WORKER_LABEL = process.env.TG_WORKER_LABEL?.trim() || "com.cursor-telegram.worker";
+/** Restart if getUpdates has not returned successfully for this many seconds. */
+const MAX_POLL_AGE_SEC = Number.parseInt(process.env.TG_WATCHDOG_MAX_POLL_AGE_SEC ?? "120", 10);
+function log(msg) {
+    process.stderr.write(`[watchdog] ${new Date().toISOString()} ${msg}\n`);
+}
+function kick() {
+    const uid = process.getuid?.() ?? 501;
+    try {
+        execFileSync("launchctl", ["kickstart", "-k", `gui/${uid}/${WORKER_LABEL}`], {
+            stdio: "ignore",
+        });
+        log(`restarted ${WORKER_LABEL}`);
+    }
+    catch (err) {
+        log(`failed to restart ${WORKER_LABEL}: ${String(err)}`);
+    }
+}
+async function main() {
+    const url = `${getConfig(false).workerUrl}/health`;
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), 5000);
+    try {
+        const res = await fetch(url, { signal: ac.signal });
+        const body = (await res.json());
+        if (!body.ok || body.connected === false) {
+            log(`unhealthy (ok=${body.ok}, connected=${body.connected}); restarting`);
+            kick();
+            return;
+        }
+        const age = body.pollAgeSec ?? 0;
+        if (age > MAX_POLL_AGE_SEC) {
+            log(`poll loop wedged (pollAgeSec=${age} > ${MAX_POLL_AGE_SEC}); restarting`);
+            kick();
+            return;
+        }
+        log(`ok (pollAgeSec=${age})`);
+    }
+    catch (err) {
+        log(`worker unreachable at ${url}: ${String(err)}; restarting`);
+        kick();
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+await main();

package/dist/worker.js

@@ -652,6 +652,7 @@ async function main() {
                     queue: taskQueue.length(),
                     version: WORKER_VERSION,
                     uptimeSec: Math.floor((Date.now() - startedAt) / 1000),
+                    pollAgeSec: Math.floor(client.lastPollAgeMs() / 1000),
                     lastError: lastError ?? null,
                 });
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cursor-telegram-mcp",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Manage Cursor from your phone over Telegram: an MCP server + auto-spawned local worker that notifies you, asks you questions, and (optionally) runs headless Cursor agents you text it. Local, bring-your-own-bot, runs entirely on your machine.",
   "type": "module",
   "license": "MIT",