@thxmxx/telegram-mcp 1.0.0 → 1.2.1

package/.github/workflows/publish.yaml

@@ -0,0 +1,68 @@
+name: Publish to npm
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    types: [closed]
+    branches: [main]
+
+jobs:
+  publish:
+    if: github.event_name == 'push' || github.event.pull_request.merged == true
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # needed to push the version bump commit
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Determine version bump
+        id: bump
+        run: |
+          # Get the commit message that triggered this run
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            MSG="${{ github.event.pull_request.title }}"
+          else
+            MSG="$(git log -1 --pretty=%s)"
+          fi
+
+          echo "Commit message: $MSG"
+
+          # Detect breaking change
+          if echo "$MSG" | grep -qiE "BREAKING CHANGE|!:"; then
+            echo "type=major" >> $GITHUB_OUTPUT
+          # feat → minor
+          elif echo "$MSG" | grep -qiE "^feat(\(.+\))?:"; then
+            echo "type=minor" >> $GITHUB_OUTPUT
+          # everything else → patch
+          else
+            echo "type=patch" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Bump version
+        run: |
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          npm version ${{ steps.bump.outputs.type }} --no-git-tag-version
+          VERSION=$(node -p "require('./package.json').version")
+          git add package.json
+          git commit -m "chore: bump version to $VERSION [skip ci]"
+          git push
+
+      - name: Publish
+        run: npm publish --access public --provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -12,7 +12,15 @@ The wizard asks for your Telegram bot token and user ID, registers the MCP serve
 
 ## Usage
 
-In any Claude Code session, activate Telegram with the slash command:
+Start Claude Code without permission prompts so it can work autonomously:
+
+```bash
+claude --dangerously-skip-permissions
+```
+
+> ⚠️ This flag disables all tool confirmation prompts — file writes, shell commands, everything. Use only on your own machine for personal workflows.
+
+Then activate Telegram in any session:
 
 ```
 /use-telegram
@@ -85,4 +93,4 @@ On first use, Claude Code will ask you to approve the three tools this MCP serve
 
 ## License
 
-MIT
+MIT

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@thxmxx/telegram-mcp",
-  "version": "1.0.0",
+  "version": "1.2.1",
   "description": "Telegram bridge for Claude Code — notify, ask and choose via your phone",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thxmxx/telegram-mcp"
+  },
   "bin": {
     "telegram-mcp": "./src/cli.js"
   },
@@ -11,6 +15,8 @@
     "node-telegram-bot-api": "^0.66.0",
     "dotenv": "^16.0.0"
   },
-  "engines": { "node": ">=18" },
+  "engines": {
+    "node": ">=18"
+  },
   "license": "MIT"
 }

package/src/index.js

@@ -6,9 +6,8 @@
  *   telegram_notify  — send a message (fire and forget)
  *   telegram_ask     — ask a question, wait for text reply
  *   telegram_choose  — show buttons, wait for a tap
- *
- * Instance label is auto-generated from cwd + ppid.
- * No per-project configuration needed.
+ *   telegram_listen  — wait for user to address this instance by name,
+ *                      returns the next instruction so Claude can keep working
  */
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -36,35 +35,36 @@ if (existsSync(envPath)) {
   }
 }
 
-const TOKEN   = env.TELEGRAM_BOT_TOKEN;
+const TOKEN = env.TELEGRAM_BOT_TOKEN;
 const CHAT_ID = env.TELEGRAM_CHAT_ID;
 
 if (!TOKEN || !CHAT_ID) {
   process.stderr.write(
     "[telegram-mcp] Missing TELEGRAM_BOT_TOKEN or TELEGRAM_CHAT_ID.\n" +
-    "               Run: npx @thxmxx/telegram-mcp init\n"
+      "               Run: npx @thxmxx/telegram-mcp init\n",
   );
   exit(1);
 }
 
 // ── Auto instance label: folder#shortid ───────────────────────────────────────
 
-const folder    = process.cwd().split("/").pop() || "claude";
-const shortId   = randomBytes(2).toString("hex");           // e.g. "a3f2"
-const INSTANCE  = `${folder}#${shortId}`;
-const HDR       = `\`[${INSTANCE}]\``;
+const folder = process.cwd().split("/").pop() || "claude";
+const shortId = randomBytes(2).toString("hex");
+const INSTANCE = `${folder}#${shortId}`;
+const HDR = `\`[${INSTANCE}]\``;
 
 // ── Telegram client ───────────────────────────────────────────────────────────
 
 const bot = new TelegramBot(TOKEN, { polling: true });
 
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
 function waitForReply(timeoutMs = 300_000) {
   return new Promise((resolve, reject) => {
     const timer = setTimeout(() => {
       bot.removeListener("message", handler);
       reject(new Error("Timed out (5 min)"));
     }, timeoutMs);
-
     function handler(msg) {
       if (String(msg.chat.id) !== String(CHAT_ID)) return;
       if (msg.text?.startsWith("/")) return;
@@ -82,7 +82,6 @@ function waitForCallback(timeoutMs = 300_000) {
       bot.removeListener("callback_query", handler);
       reject(new Error("Timed out (5 min)"));
     }, timeoutMs);
-
     function handler(query) {
       if (String(query.from.id) !== String(CHAT_ID)) return;
       clearTimeout(timer);
@@ -94,11 +93,54 @@ function waitForCallback(timeoutMs = 300_000) {
   });
 }
 
+/**
+ * Wait for a message addressed to THIS instance.
+ * Format: "@instance-label <instruction>"
+ * e.g.   "@backend#a3f2 now refactor the auth module"
+ *
+ * Ignores messages addressed to other instances silently.
+ * Times out after `timeoutMs` (default: 1 hour).
+ */
+function waitForAddressedMessage(timeoutMs = 3_600_000) {
+  const mention = `@${INSTANCE}`.toLowerCase();
+
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      bot.removeListener("message", handler);
+      reject(new Error(`No message addressed to ${INSTANCE} within timeout`));
+    }, timeoutMs);
+
+    function handler(msg) {
+      if (String(msg.chat.id) !== String(CHAT_ID)) return;
+      if (!msg.text) return;
+
+      const text = msg.text.trim();
+      const lower = text.toLowerCase();
+
+      // Message must start with @instance-label
+      if (!lower.startsWith(mention)) return;
+
+      // Extract the instruction after the mention
+      const instruction = text.slice(mention.length).trim();
+      if (!instruction) return;
+
+      clearTimeout(timer);
+      bot.removeListener("message", handler);
+      resolve(instruction);
+    }
+
+    bot.on("message", handler);
+  });
+}
+
 function terminalPrompt(question) {
   return new Promise((resolve) => {
     const rl = createInterface({ input, output, terminal: true });
     process.stderr.write(`\n[${INSTANCE}] ${question}\n> `);
-    rl.once("line", (line) => { rl.close(); resolve(line.trim()); });
+    rl.once("line", (line) => {
+      rl.close();
+      resolve(line.trim());
+    });
   });
 }
 
@@ -113,7 +155,9 @@ function raceCallback(question, options) {
   const numbered = options.map((o, i) => `  ${i + 1}. ${o}`).join("\n");
   return Promise.race([
     waitForCallback(),
-    terminalPrompt(`${question}\n${numbered}\nChoose (1-${options.length})`).then((v) => {
+    terminalPrompt(
+      `${question}\n${numbered}\nChoose (1-${options.length})`,
+    ).then((v) => {
       const idx = parseInt(v, 10) - 1;
       return { source: "terminal", value: options[idx] ?? v };
     }),
@@ -124,52 +168,111 @@ function raceCallback(question, options) {
 
 const server = new McpServer({ name: "telegram-mcp", version: "1.0.0" });
 
+// ── telegram_notify ───────────────────────────────────────────────────────────
+
 server.tool(
   "telegram_notify",
   "Send a Telegram notification to the user. Use for progress updates and task completions. Does NOT wait for a reply.",
   { message: z.string().describe("The message to send") },
   async ({ message }) => {
-    await bot.sendMessage(CHAT_ID, `${HDR} ${message}`, { parse_mode: "Markdown" });
+    await bot.sendMessage(CHAT_ID, `${HDR} ${message}`, {
+      parse_mode: "Markdown",
+    });
     process.stderr.write(`[${INSTANCE}] notify: ${message}\n`);
     return { content: [{ type: "text", text: "Sent." }] };
-  }
+  },
 );
 
+// ── telegram_ask ──────────────────────────────────────────────────────────────
+
 server.tool(
   "telegram_ask",
-  "Ask the user a free-form question via Telegram and wait for their reply. The same question is shown on the terminal — whoever answers first wins.",
+  "Ask the user a free-form question via Telegram and wait for their reply. The same question appears on the terminal — whoever answers first wins.",
   { question: z.string().describe("The question to ask") },
   async ({ question }) => {
-    await bot.sendMessage(CHAT_ID, `${HDR} ❓ ${question}`, { parse_mode: "Markdown" });
+    await bot.sendMessage(CHAT_ID, `${HDR} ❓ ${question}`, {
+      parse_mode: "Markdown",
+    });
     const { source, value } = await raceReply(question);
     if (source === "terminal") {
-      await bot.sendMessage(CHAT_ID, `${HDR} ✅ Answered from terminal: *${value}*`, { parse_mode: "Markdown" });
+      await bot.sendMessage(
+        CHAT_ID,
+        `${HDR} ✅ Answered from terminal: *${value}*`,
+        { parse_mode: "Markdown" },
+      );
     }
     process.stderr.write(`[${INSTANCE}] ask (${source}): ${value}\n`);
     return { content: [{ type: "text", text: value }] };
-  }
+  },
 );
 
+// ── telegram_choose ───────────────────────────────────────────────────────────
+
 server.tool(
   "telegram_choose",
   "Ask the user to pick one option. Shows inline buttons on Telegram and a numbered list on the terminal. Whoever responds first wins.",
   {
     question: z.string().describe("The question or prompt"),
-    options: z.array(z.string()).min(2).max(10).describe("Options to present (2–10)"),
+    options: z
+      .array(z.string())
+      .min(2)
+      .max(10)
+      .describe("Options to present (2–10)"),
   },
   async ({ question, options }) => {
     const keyboard = {
-      inline_keyboard: options.map((opt) => [{ text: opt, callback_data: opt }]),
+      inline_keyboard: options.map((opt) => [
+        { text: opt, callback_data: opt },
+      ]),
     };
     await bot.sendMessage(CHAT_ID, `${HDR} 🔘 ${question}`, {
       parse_mode: "Markdown",
       reply_markup: keyboard,
     });
     const { source, value } = await raceCallback(question, options);
-    await bot.sendMessage(CHAT_ID, `${HDR} ✅ *${value}* _(via ${source})_`, { parse_mode: "Markdown" });
+    await bot.sendMessage(CHAT_ID, `${HDR} ✅ *${value}* _(via ${source})_`, {
+      parse_mode: "Markdown",
+    });
     process.stderr.write(`[${INSTANCE}] choose (${source}): ${value}\n`);
     return { content: [{ type: "text", text: value }] };
-  }
+  },
+);
+
+// ── telegram_listen ───────────────────────────────────────────────────────────
+
+server.tool(
+  "telegram_listen",
+  `Wait for the user to send a new instruction addressed to this instance on Telegram.
+   Call this after completing a task to stay available for follow-up work.
+   The user must address messages as: @${INSTANCE} <instruction>
+   Returns the instruction text when received. Times out after 1 hour of inactivity.
+   When this tool returns, execute the instruction and call telegram_listen again when done.`,
+  {},
+  async () => {
+    await bot.sendMessage(
+      CHAT_ID,
+      `${HDR} ✅ Task complete — waiting for your next instruction.\n` +
+        `_Address me as_ \`@${INSTANCE} <your instruction>\``,
+      { parse_mode: "Markdown" },
+    );
+
+    process.stderr.write(`[${INSTANCE}] listening for @${INSTANCE} ...\n`);
+
+    try {
+      const instruction = await waitForAddressedMessage();
+      process.stderr.write(`[${INSTANCE}] received: ${instruction}\n`);
+      return { content: [{ type: "text", text: instruction }] };
+    } catch (err) {
+      await bot.sendMessage(
+        CHAT_ID,
+        `${HDR} 💤 Timed out after 1 hour of inactivity.`,
+        {
+          parse_mode: "Markdown",
+        },
+      );
+      return { content: [{ type: "text", text: `timeout: ${err.message}` }] };
+    }
+  },
 );
 
 // ── Start ─────────────────────────────────────────────────────────────────────
@@ -177,3 +280,6 @@ server.tool(
 const transport = new StdioServerTransport();
 await server.connect(transport);
 process.stderr.write(`[telegram-mcp] Ready — instance: ${INSTANCE}\n`);
+process.stderr.write(
+  `[telegram-mcp] Address messages as: @${INSTANCE} <instruction>\n`,
+);

package/src/setup.js

@@ -17,17 +17,21 @@ import { mkdirSync, writeFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 
-const rl  = createInterface({ input, output });
+const rl = createInterface({ input, output });
 const ask = (q) => rl.question(q);
 
-const BOLD  = "\x1b[1m";
+const BOLD = "\x1b[1m";
 const GREEN = "\x1b[32m";
-const CYAN  = "\x1b[36m";
-const DIM   = "\x1b[2m";
+const CYAN = "\x1b[36m";
+const DIM = "\x1b[2m";
 const RESET = "\x1b[0m";
 
-const ok  = (msg) => console.log(`${GREEN}✔${RESET}  ${msg}`);
-const die = (msg) => { console.error(`\x1b[31m✘${RESET}  ${msg}`); rl.close(); exit(1); };
+const ok = (msg) => console.log(`${GREEN}✔${RESET}  ${msg}`);
+const die = (msg) => {
+  console.error(`\x1b[31m✘${RESET}  ${msg}`);
+  rl.close();
+  exit(1);
+};
 
 // ── Pre-flight ────────────────────────────────────────────────────────────────
 
@@ -38,7 +42,9 @@ if (major < 18) die(`Node.js 18+ required (you have ${process.versions.node})`);
 ok(`Node.js ${process.versions.node}`);
 
 try {
-  const ver = execFileSync("claude", ["--version"], { encoding: "utf8" }).trim();
+  const ver = execFileSync("claude", ["--version"], {
+    encoding: "utf8",
+  }).trim();
   ok(`Claude Code: ${ver}`);
 } catch {
   die("`claude` not found. Install: https://docs.claude.ai/claude-code");
@@ -71,31 +77,51 @@ console.log(`\n${BOLD}Registering MCP server globally…${RESET}`);
 const serverPath = new URL("./index.js", import.meta.url).pathname;
 
 try {
-  execFileSync("claude", [
-    "mcp", "add", "--scope", "user",   // global, persists across all projects
-    "telegram-mcp",
-    "-e", `TELEGRAM_BOT_TOKEN=${token}`,
-    "-e", `TELEGRAM_CHAT_ID=${chatId}`,
-    "--", "node", serverPath,
-  ], { stdio: "inherit" });
+  execFileSync(
+    "claude",
+    [
+      "mcp",
+      "add",
+      "--scope",
+      "user", // global, persists across all projects
+      "telegram-mcp",
+      "-e",
+      `TELEGRAM_BOT_TOKEN=${token}`,
+      "-e",
+      `TELEGRAM_CHAT_ID=${chatId}`,
+      "--",
+      "node",
+      serverPath,
+    ],
+    { stdio: "inherit" },
+  );
 } catch {
   // Fallback: older Claude Code versions without --scope flag
   try {
-    execFileSync("claude", [
-      "mcp", "add",
-      "telegram-mcp",
-      "-e", `TELEGRAM_BOT_TOKEN=${token}`,
-      "-e", `TELEGRAM_CHAT_ID=${chatId}`,
-      "--", "node", serverPath,
-    ], { stdio: "inherit" });
+    execFileSync(
+      "claude",
+      [
+        "mcp",
+        "add",
+        "telegram-mcp",
+        "-e",
+        `TELEGRAM_BOT_TOKEN=${token}`,
+        "-e",
+        `TELEGRAM_CHAT_ID=${chatId}`,
+        "--",
+        "node",
+        serverPath,
+      ],
+      { stdio: "inherit" },
+    );
   } catch {
     die(
       "`claude mcp add` failed.\n" +
-      "  Update Claude Code: https://docs.claude.ai/claude-code\n\n" +
-      "  Manual config:\n" +
-      `    TELEGRAM_BOT_TOKEN=${token}\n` +
-      `    TELEGRAM_CHAT_ID=${chatId}\n` +
-      `    command: node ${serverPath}`
+        "  Update Claude Code: https://docs.claude.ai/claude-code\n\n" +
+        "  Manual config:\n" +
+        `    TELEGRAM_BOT_TOKEN=${token}\n` +
+        `    TELEGRAM_CHAT_ID=${chatId}\n` +
+        `    command: node ${serverPath}`,
     );
   }
 }
@@ -108,17 +134,19 @@ const commandsDir = join(homedir(), ".claude", "commands");
 mkdirSync(commandsDir, { recursive: true });
 
 const commandPath = join(commandsDir, "use-telegram.md");
-writeFileSync(commandPath, `# use-telegram
+writeFileSync(
+  commandPath,
+  `# use-telegram
 
 Activate Telegram integration for this Claude Code session.
 
 ## What this does
 
-Enables the telegram_notify, telegram_ask and telegram_choose tools so you
-can be notified and asked questions on your phone while Claude works.
+Enables telegram_notify, telegram_ask and telegram_choose so the user
+receives updates and can respond from their phone or terminal.
 
-The instance name is derived automatically from the current folder and
-session ID, so messages on Telegram always show which session is talking.
+This session runs with --dangerously-skip-permissions so Claude never
+interrupts the task to ask for tool confirmations in the terminal.
 
 ## Modes
 
@@ -127,21 +155,35 @@ session ID, so messages on Telegram always show which session is talking.
 
 ## Behaviour
 
-When this command is active:
-- Use telegram_notify for progress updates and completed tasks
-- Use telegram_ask when you need a free-form answer from the user
-- Use telegram_choose when the user must pick from known options
-- Always prefix messages with the auto-generated instance label
-- Mirror every question to the terminal too — whoever answers first wins
-- After any long-running task, send a completion summary via telegram_notify
+You MUST use the Telegram tools for this session. Specifically:
+
+- Call telegram_notify **immediately** to confirm Telegram is active
+- Call telegram_notify for every meaningful progress update
+- Call telegram_notify when any task is fully complete, with a summary
+- Call telegram_ask whenever you need a free-form answer from the user
+- Call telegram_choose whenever the user must pick from known options
+- Do NOT ask questions in the terminal — always use telegram_ask or telegram_choose
 
 ## Instance naming
 
-Generate the instance label as: \`{folder-name}#{short-session-id}\`
-Example: \`backend#a3f2\`, \`frontend#9c11\`
+At the start of this session, generate a label: \`{folder-name}#{4-char-random-hex}\`
+Examples: \`backend#a3f2\`, \`frontend#9c11\`
 
-Use the same label for the entire session.
-`);
+Use this exact label in every Telegram message for the entire session.
+Send as first message: \`[label] ✅ Telegram active — ready.\`
+  Also tell the user: _Address me as_ \`@[label] <instruction>\` for follow-up tasks.
+
+## Staying alive after a task
+
+After completing any task, ALWAYS call telegram_listen (no arguments).
+- It will notify the user the task is done and wait for the next instruction
+- When it returns, execute the new instruction
+- Then call telegram_listen again
+- This keeps the session alive indefinitely until timeout (1 hour of inactivity)
+
+Never exit or stop after a task — always loop back to telegram_listen.
+`,
+);
 
 ok(`Slash command installed → ${commandPath}`);
 
@@ -150,7 +192,11 @@ ok(`Slash command installed → ${commandPath}`);
 console.log(`
 ${GREEN}${BOLD}All done!${RESET}
 
-  Restart Claude Code. From now on, in any session:
+  Start Claude Code with:
+
+    ${BOLD}claude --dangerously-skip-permissions${RESET}
+
+  Then activate Telegram in any session:
 
     ${BOLD}/use-telegram${RESET}           full mode (notify + ask + choose)
     ${BOLD}/use-telegram notify${RESET}    notifications only