@thxmxx/telegram-mcp 1.2.0 → 1.2.2

package/.github/workflows/publish.yaml

@@ -12,7 +12,7 @@ jobs:
     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
+      contents: write
       id-token: write
 
     steps:
@@ -26,33 +26,44 @@ jobs:
           node-version: 20
           registry-url: https://registry.npmjs.org
 
-      - name: Install dependencies
-        run: npm install
-
-      - name: Determine version bump
-        id: bump
+      - name: Get commit message
+        id: msg
         run: |
-          # Get the commit message that triggered this run
           if [ "${{ github.event_name }}" = "pull_request" ]; then
-            MSG="${{ github.event.pull_request.title }}"
+            echo "value=${{ github.event.pull_request.title }}" >> $GITHUB_OUTPUT
           else
-            MSG="$(git log -1 --pretty=%s)"
+            echo "value=$(git log -1 --pretty=%s)" >> $GITHUB_OUTPUT
           fi
 
-          echo "Commit message: $MSG"
+      - name: Skip if docs-only
+        id: skip
+        run: |
+          MSG="${{ steps.msg.outputs.value }}"
+          if echo "$MSG" | grep -qiE "^docs(\(.+\))?:|^\[skip ci\]|^chore: bump version"; then
+            echo "skip=true" >> $GITHUB_OUTPUT
+          else
+            echo "skip=false" >> $GITHUB_OUTPUT
+          fi
 
-          # Detect breaking change
+      - name: Determine version bump
+        id: bump
+        if: steps.skip.outputs.skip == 'false'
+        run: |
+          MSG="${{ steps.msg.outputs.value }}"
           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: Install dependencies
+        if: steps.skip.outputs.skip == 'false'
+        run: npm install
+
       - name: Bump version
+        if: steps.skip.outputs.skip == 'false'
         run: |
           git config user.name  "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
@@ -63,6 +74,7 @@ jobs:
           git push
 
       - name: Publish
+        if: steps.skip.outputs.skip == 'false'
         run: npm publish --access public --provenance
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -74,6 +74,14 @@ If you answer from the terminal, Telegram confirms it:
 | `telegram_ask` | Ask a free-form question. Waits for reply. |
 | `telegram_choose` | Show option buttons. Waits for a tap. |
 
+## Updating
+
+```bash
+npx @thxmxx/telegram-mcp@latest init
+```
+
+Re-runs the setup with the latest version — updates the MCP server and the `/use-telegram` slash command automatically.
+
 ## Requirements
 
 - Node.js 18+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thxmxx/telegram-mcp",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Telegram bridge for Claude Code — notify, ask and choose via your phone",
   "type": "module",
   "repository": {

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

@@ -171,6 +171,17 @@ Examples: \`backend#a3f2\`, \`frontend#9c11\`
 
 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.
 `,
 );