cursor-telegram-mcp 0.5.0

package/dist/cli.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+/**
+ * Single CLI entry point for the published package.
+ *
+ * Usage:
+ *   cursor-telegram-mcp            Start the MCP server (what Cursor runs).
+ *   cursor-telegram-mcp setup      Interactive first-time setup (bot + chat id).
+ *   cursor-telegram-mcp login      Find your chat id (token must be set).
+ *   cursor-telegram-mcp worker     Run the background worker in the foreground.
+ *   cursor-telegram-mcp doctor     Diagnose configuration / connectivity.
+ *
+ * Each subcommand is a module whose side-effecting `main()` runs on import.
+ */
+function printHelp() {
+    process.stderr.write([
+        "cursor-telegram-mcp - manage Cursor from your phone over Telegram",
+        "",
+        "Usage:",
+        "  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 your Telegram chat id",
+        "  cursor-telegram-mcp worker   Run the background worker in the foreground",
+        "  cursor-telegram-mcp doctor   Diagnose configuration and connectivity",
+        "  cursor-telegram-mcp help     Show this help",
+        "",
+        "Add to Cursor (mcp.json):",
+        '  { "mcpServers": { "telegram": { "command": "npx", "args": ["-y", "cursor-telegram-mcp"] } } }',
+        "",
+    ].join("\n"));
+}
+async function run() {
+    const sub = process.argv[2];
+    switch (sub) {
+        case undefined:
+        case "mcp":
+        case "start":
+            await import("./index.js");
+            break;
+        case "worker":
+            await import("./worker.js");
+            break;
+        case "setup":
+            await import("./setup.js");
+            break;
+        case "login":
+            await import("./login.js");
+            break;
+        case "doctor":
+            await import("./doctor.js");
+            break;
+        case "help":
+        case "-h":
+        case "--help":
+            printHelp();
+            break;
+        default:
+            process.stderr.write(`Unknown command: ${sub}\n\n`);
+            printHelp();
+            process.exit(1);
+    }
+}
+run().catch((err) => {
+    process.stderr.write(`Fatal: ${err?.stack ?? err}\n`);
+    process.exit(1);
+});
+export {};

package/dist/config.js

@@ -0,0 +1,160 @@
+/**
+ * Central configuration for the local, single-user setup.
+ *
+ * Resolution order for every value (highest priority first):
+ *   1. Real environment variables (e.g. set in your Cursor `mcp.json`).
+ *   2. The user config file written by `setup` / `login`
+ *      (`<configDir>/config.json`, keyed by the same names as the env vars).
+ *   3. A local `.env` in the working directory (developer convenience).
+ *   4. Built-in defaults.
+ *
+ * Worker needs:
+ *   TELEGRAM_BOT_TOKEN - bot token from @BotFather.
+ *   TELEGRAM_CHAT_ID   - the chat to message and accept replies from.
+ *
+ * MCP client needs:
+ *   TG_WORKER_URL - where the worker listens (default http://127.0.0.1:8787).
+ *   TG_PROJECT    - label for this project's messages (default "default").
+ *   TG_DEFAULT_POLL_WAIT_MS - long-poll chunk size check_human_response uses
+ *                             when no explicit waitMs is passed (default 120000).
+ *
+ * Command mode (optional, worker-side) needs:
+ *   CURSOR_API_KEY - enables texting tasks to the bot to run headless agents.
+ *   TG_AGENT_CWD   - directory the headless agent works in (default cwd).
+ *   TG_AGENT_MODEL - model id for the headless agent (default composer-2.5).
+ *   TG_AGENT_LOAD_SETTINGS - "1"/"true" to load this repo's .cursor settings.
+ *   TG_ROLLING     - "1"/"true" (default) to keep ONE rolling agent thread so
+ *                    knowledge carries across phone messages.
+ *   TG_TRANSCRIPT_PATH - markdown transcript file (default <cwd>/remote-chat.md).
+ *   TG_SESSION_PATH    - rolling-session state file (default
+ *                        <configDir>/rolling-session.json).
+ */
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
+// Best-effort load of a local .env (developer convenience). Real env vars and
+// the user config file both take precedence over anything it sets.
+try {
+    process.loadEnvFile?.();
+}
+catch {
+    // no .env file present - rely on real environment variables / config file
+}
+/** Cross-platform per-user config directory for this tool. */
+export function configDir() {
+    if (platform() === "win32") {
+        const appData = process.env.APPDATA ?? join(homedir(), "AppData", "Roaming");
+        return join(appData, "cursor-telegram");
+    }
+    const xdg = process.env.XDG_CONFIG_HOME?.trim();
+    const base = xdg && xdg !== "" ? xdg : join(homedir(), ".config");
+    return join(base, "cursor-telegram");
+}
+/** Path to the user config file (config.json) inside the config dir. */
+export function configFilePath() {
+    return join(configDir(), "config.json");
+}
+/** Read the user config file. Returns {} if missing or unreadable. */
+export function readFileConfig() {
+    try {
+        const raw = readFileSync(configFilePath(), "utf8");
+        const parsed = JSON.parse(raw);
+        const out = {};
+        for (const [k, v] of Object.entries(parsed)) {
+            if (v != null)
+                out[k] = String(v);
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+/** Merge `patch` into the user config file, creating it (0600) if needed. */
+export function writeFileConfig(patch) {
+    const dir = configDir();
+    mkdirSync(dir, { recursive: true });
+    const current = readFileConfig();
+    for (const [k, v] of Object.entries(patch)) {
+        if (v === undefined)
+            continue;
+        if (v === "")
+            delete current[k];
+        else
+            current[k] = v;
+    }
+    const path = configFilePath();
+    writeFileSync(path, JSON.stringify(current, null, 2) + "\n", "utf8");
+    if (platform() !== "win32") {
+        try {
+            chmodSync(path, 0o600);
+        }
+        catch {
+            // best-effort: secrets file permission tightening
+        }
+    }
+    return path;
+}
+let fileCfg = null;
+/** Resolve a single setting: real env > config file > undefined. */
+function raw(name) {
+    const fromEnv = process.env[name];
+    if (fromEnv !== undefined && fromEnv.trim() !== "")
+        return fromEnv;
+    if (fileCfg === null)
+        fileCfg = readFileConfig();
+    const fromFile = fileCfg[name];
+    if (fromFile !== undefined && String(fromFile).trim() !== "")
+        return String(fromFile);
+    return undefined;
+}
+function strOr(name, fallback) {
+    return (raw(name) ?? fallback).trim();
+}
+function intOr(name, fallback) {
+    const value = raw(name);
+    if (value === undefined)
+        return fallback;
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) ? parsed : fallback;
+}
+function boolOr(name, fallback) {
+    const value = raw(name)?.trim().toLowerCase();
+    if (value === undefined || value === "")
+        return fallback;
+    return value === "1" || value === "true" || value === "yes" || value === "on";
+}
+let cached = null;
+/**
+ * Build (and cache) the configuration. Throws if the bot token is missing,
+ * unless `requireToken` is false (used by the MCP client, which only needs the
+ * worker URL).
+ */
+export function getConfig(requireToken = true) {
+    if (cached)
+        return cached;
+    fileCfg = readFileConfig();
+    const botToken = strOr("TELEGRAM_BOT_TOKEN", "");
+    if (requireToken && botToken === "") {
+        throw new Error("TELEGRAM_BOT_TOKEN is not set. Run `cursor-telegram-mcp setup` (or set it in " +
+            'your mcp.json env), e.g. TELEGRAM_BOT_TOKEN="123456789:ABC-DEF...".');
+    }
+    const workerHost = strOr("TG_WORKER_HOST", "127.0.0.1");
+    const workerPort = intOr("TG_WORKER_PORT", 8787);
+    cached = {
+        botToken,
+        chatId: strOr("TELEGRAM_CHAT_ID", ""),
+        minSendGapMs: intOr("TG_MIN_SEND_GAP_MS", 3000),
+        responseTimeoutMin: intOr("TG_RESPONSE_TIMEOUT_MIN", 30),
+        workerHost,
+        workerPort,
+        workerUrl: strOr("TG_WORKER_URL", `http://${workerHost}:${workerPort}`).replace(/\/+$/, ""),
+        project: strOr("TG_PROJECT", "default"),
+        defaultPollWaitMs: intOr("TG_DEFAULT_POLL_WAIT_MS", 120_000),
+        cursorApiKey: strOr("CURSOR_API_KEY", ""),
+        agentCwd: strOr("TG_AGENT_CWD", process.cwd()),
+        agentModel: strOr("TG_AGENT_MODEL", "composer-2.5"),
+        agentLoadSettings: boolOr("TG_AGENT_LOAD_SETTINGS", false),
+    };
+    return cached;
+}

package/dist/doctor.js

@@ -0,0 +1,116 @@
+/**
+ * Diagnose configuration and connectivity. Prints PASS / WARN / FAIL lines with
+ * actionable fixes so users can self-serve "it's not working".
+ */
+import { spawnSync } from "node:child_process";
+import { delimiter, join } from "node:path";
+import { homedir, platform } from "node:os";
+import { existsSync } from "node:fs";
+import { configFilePath, getConfig } from "./config.js";
+function line(status, msg, fix) {
+    process.stdout.write(`[${status}] ${msg}\n`);
+    if (fix)
+        process.stdout.write(`       -> ${fix}\n`);
+}
+async function tgGetMe(token) {
+    try {
+        const res = await fetch(`https://api.telegram.org/bot${token}/getMe`, { method: "POST" });
+        const data = (await res.json());
+        if (!data.ok)
+            return { ok: false, error: data.description ?? `HTTP ${res.status}` };
+        return { ok: true, username: data.result?.username };
+    }
+    catch (err) {
+        return { ok: false, error: String(err) };
+    }
+}
+async function workerHealth(url) {
+    try {
+        const res = await fetch(`${url}/health`);
+        return (await res.json());
+    }
+    catch {
+        return null;
+    }
+}
+/** Find the Cursor CLI on PATH (or in ~/.local/bin), returns the version line. */
+function cursorAgentVersion() {
+    const candidates = ["cursor-agent", "agent"];
+    const localBin = join(homedir(), ".local", "bin");
+    if (!(process.env.PATH ?? "").split(delimiter).includes(localBin)) {
+        process.env.PATH = `${localBin}${delimiter}${process.env.PATH ?? ""}`;
+    }
+    for (const cmd of candidates) {
+        try {
+            const r = spawnSync(cmd, ["--version"], { encoding: "utf8" });
+            if (r.status === 0 && r.stdout)
+                return r.stdout.trim().split("\n")[0];
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    return null;
+}
+function installHint() {
+    if (platform() === "win32") {
+        return "Install the Cursor CLI (PowerShell): irm 'https://cursor.com/install?win32=true' | iex";
+    }
+    return "Install the Cursor CLI: curl https://cursor.com/install -fsS | bash (then ensure ~/.local/bin is on PATH)";
+}
+async function main() {
+    process.stdout.write("cursor-telegram-mcp doctor\n==========================\n\n");
+    const config = getConfig(false);
+    const cfgPath = configFilePath();
+    if (existsSync(cfgPath))
+        line("PASS", `Config file present: ${cfgPath}`);
+    else
+        line("WARN", `No config file at ${cfgPath}`, "Run `cursor-telegram-mcp setup` (or set env in mcp.json).");
+    // Bot token.
+    if (!config.botToken) {
+        line("FAIL", "TELEGRAM_BOT_TOKEN is not set.", "Run `cursor-telegram-mcp setup`.");
+    }
+    else {
+        const me = await tgGetMe(config.botToken);
+        if (me.ok)
+            line("PASS", `Bot token valid (@${me.username ?? "?"}).`);
+        else
+            line("FAIL", `Bot token rejected: ${me.error}`, "Re-check the token from @BotFather; run setup again.");
+    }
+    // Chat id.
+    if (!config.chatId)
+        line("FAIL", "TELEGRAM_CHAT_ID is not set.", "Run `cursor-telegram-mcp login` and message your bot.");
+    else
+        line("PASS", `Chat id set (${config.chatId}).`);
+    // Worker.
+    const health = await workerHealth(config.workerUrl);
+    if (!health) {
+        line("WARN", `Worker not reachable at ${config.workerUrl}.`, "It auto-starts with the MCP server; or run `cursor-telegram-mcp worker`.");
+    }
+    else {
+        line("PASS", `Worker reachable at ${config.workerUrl}.`);
+        if (health.connected)
+            line("PASS", "Worker is connected to Telegram.");
+        else
+            line("WARN", "Worker is up but not connected to Telegram yet.", "Check the token/chat id; see the worker log.");
+        if (health.commandMode)
+            line("PASS", "Command mode is ON in the running worker.");
+    }
+    // Command mode prerequisites.
+    if (!config.cursorApiKey) {
+        line("WARN", "CURSOR_API_KEY not set (command mode disabled).", "Optional: add it via setup to text tasks to your bot.");
+    }
+    else {
+        line("PASS", "CURSOR_API_KEY is set.");
+        const version = cursorAgentVersion();
+        if (version)
+            line("PASS", `Cursor CLI found (${version}).`);
+        else
+            line("FAIL", "Cursor CLI (cursor-agent) not found on PATH.", installHint());
+    }
+    process.stdout.write("\nDone.\n");
+}
+main().catch((err) => {
+    process.stdout.write(`Doctor failed: ${err?.message ?? err}\n`);
+    process.exit(1);
+});

package/dist/formatTelegram.js

@@ -0,0 +1,28 @@
+/**
+ * Convert agent Markdown to plain text suitable for Telegram (no parse_mode).
+ */
+export function toPlainTelegram(text) {
+    let s = text;
+    // Fenced code blocks: drop fences, keep inner content.
+    s = s.replace(/```[^\n]*\n?([\s\S]*?)```/g, (_, code) => code.trimEnd());
+    // Inline code.
+    s = s.replace(/`([^`\n]+)`/g, "$1");
+    // Links: [label](url) -> label (url)
+    s = s.replace(/\[([^\]]+)\]\(([^)]+)\)/g, "$1 ($2)");
+    // Bold / strong.
+    s = s.replace(/\*\*([^*\n]+)\*\*/g, "$1");
+    s = s.replace(/__([^_\n]+)__/g, "$1");
+    // Italic (after bold so ** is handled first).
+    s = s.replace(/(?<!\*)\*([^*\n]+)\*(?!\*)/g, "$1");
+    s = s.replace(/(?<!_)_([^_\n]+)_(?!_)/g, "$1");
+    // Strikethrough.
+    s = s.replace(/~~([^~\n]+)~~/g, "$1");
+    // ATX headings -> uppercase words (no #).
+    s = s.replace(/^#{1,6}\s+(.+)$/gm, (_, heading) => heading.trim().toUpperCase());
+    // Lone asterisks at line edges (unmatched markdown noise).
+    s = s.replace(/^\s*\*{1,2}\s*/gm, "");
+    s = s.replace(/\s*\*{1,2}\s*$/gm, "");
+    // Orphaned ** left in the middle of a line.
+    s = s.replace(/\*\*/g, "");
+    return s;
+}