@thxmxx/telegram-mcp 1.0.0

package/README.md

@@ -0,0 +1,88 @@
+# @thxmxx/telegram-mcp
+
+Telegram bridge for Claude Code. While Claude runs tasks on your machine, it notifies you, asks questions and shows option buttons — on your phone **and** on the terminal simultaneously. Whichever you answer first wins.
+
+## Install (one-time, global)
+
+```bash
+npx @thxmxx/telegram-mcp init
+```
+
+The wizard asks for your Telegram bot token and user ID, registers the MCP server globally in Claude Code, and installs the `/use-telegram` slash command. You never need to run this again.
+
+## Usage
+
+In any Claude Code session, activate Telegram with the slash command:
+
+```
+/use-telegram
+```
+
+Or just mention it naturally in your prompt:
+
+```
+Refactor the auth module and notify me on Telegram when done.
+Deploy to staging — ask me on Telegram if anything is unclear.
+```
+
+### Modes
+
+```
+/use-telegram            Full mode — notify + ask + choose
+/use-telegram notify     Notifications only, no questions
+```
+
+### Combining with other slash commands
+
+Slash commands are independent and composable:
+
+```
+/deploy staging
+/use-telegram notify
+```
+
+## How it works
+
+```
+Claude Code runs a task
+    ↓ calls telegram_choose("Which DB?", ["PostgreSQL", "MySQL", "SQLite"])
+You get buttons on Telegram AND a numbered list on the terminal
+    ↓ you tap PostgreSQL on your phone (or type 1 in the terminal)
+Claude receives "PostgreSQL" and continues
+```
+
+Every message is tagged with an auto-generated instance label like `[backend#a3f2]` or `[frontend#9c11]` — so when you have multiple Claude Code sessions open you always know which one is talking.
+
+If you answer from the terminal, Telegram confirms it:
+```
+[backend#a3f2] ✅ PostgreSQL (via terminal)
+```
+
+## Tools Claude gains
+
+| Tool | Description |
+|---|---|
+| `telegram_notify` | Send a progress update. No reply needed. |
+| `telegram_ask` | Ask a free-form question. Waits for reply. |
+| `telegram_choose` | Show option buttons. Waits for a tap. |
+
+## Requirements
+
+- Node.js 18+
+- [Claude Code](https://docs.claude.ai/claude-code) installed and logged in
+- A Telegram bot token — get one free from [@BotFather](https://t.me/botfather)
+- Your Telegram user ID — message [@userinfobot](https://t.me/userinfobot)
+
+## Permissions
+
+On first use, Claude Code will ask you to approve the three tools this MCP server registers (`telegram_notify`, `telegram_ask`, `telegram_choose`). This is standard Claude Code behaviour — you can review exactly what is being granted before accepting.
+
+## Security
+
+- The MCP server only accepts responses from your configured Telegram user ID
+- Credentials are stored in `~/.claude.json` by Claude Code — never in this repo
+- If your token is ever exposed, revoke it immediately via @BotFather `/revoke` then re-run `init`
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@thxmxx/telegram-mcp",
+  "version": "1.0.0",
+  "description": "Telegram bridge for Claude Code — notify, ask and choose via your phone",
+  "type": "module",
+  "bin": {
+    "telegram-mcp": "./src/cli.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "node-telegram-bot-api": "^0.66.0",
+    "dotenv": "^16.0.0"
+  },
+  "engines": { "node": ">=18" },
+  "license": "MIT"
+}

package/src/cli.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * @thxmxx/telegram-mcp
+ *
+ * npx @thxmxx/telegram-mcp init    — one-time global setup
+ * npx @thxmxx/telegram-mcp start   — start MCP server manually (for testing)
+ */
+
+const cmd = process.argv[2];
+
+if (cmd === "init") {
+  await import("./setup.js");
+} else if (cmd === "start") {
+  await import("./index.js");
+} else {
+  console.log(`
+  @thxmxx/telegram-mcp
+
+  npx @thxmxx/telegram-mcp init     One-time setup — registers MCP in Claude Code globally
+  npx @thxmxx/telegram-mcp start    Start MCP server manually (for testing)
+
+  After init, use in any Claude Code session:
+    /use-telegram                   Full mode (notify + ask + choose)
+    /use-telegram notify            Notifications only
+`);
+  process.exit(0);
+}

package/src/index.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+/**
+ * @thxmxx/telegram-mcp — MCP server
+ *
+ * Tools:
+ *   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.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import TelegramBot from "node-telegram-bot-api";
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output, env, exit } from "node:process";
+import { randomBytes } from "node:crypto";
+
+// ── Config ────────────────────────────────────────────────────────────────────
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const envPath = join(__dirname, "../.env");
+
+if (existsSync(envPath)) {
+  for (const line of readFileSync(envPath, "utf8").split("\n")) {
+    const [k, ...v] = line.split("=");
+    if (k && v.length && !env[k.trim()]) {
+      env[k.trim()] = v.join("=").trim();
+    }
+  }
+}
+
+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"
+  );
+  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}]\``;
+
+// ── Telegram client ───────────────────────────────────────────────────────────
+
+const bot = new TelegramBot(TOKEN, { polling: true });
+
+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;
+      clearTimeout(timer);
+      bot.removeListener("message", handler);
+      resolve({ source: "telegram", value: msg.text || "" });
+    }
+    bot.on("message", handler);
+  });
+}
+
+function waitForCallback(timeoutMs = 300_000) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      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);
+      bot.removeListener("callback_query", handler);
+      bot.answerCallbackQuery(query.id);
+      resolve({ source: "telegram", value: query.data || "" });
+    }
+    bot.on("callback_query", 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()); });
+  });
+}
+
+function raceReply(question) {
+  return Promise.race([
+    waitForReply(),
+    terminalPrompt(question).then((v) => ({ source: "terminal", value: v })),
+  ]);
+}
+
+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) => {
+      const idx = parseInt(v, 10) - 1;
+      return { source: "terminal", value: options[idx] ?? v };
+    }),
+  ]);
+}
+
+// ── MCP server ────────────────────────────────────────────────────────────────
+
+const server = new McpServer({ name: "telegram-mcp", version: "1.0.0" });
+
+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" });
+    process.stderr.write(`[${INSTANCE}] notify: ${message}\n`);
+    return { content: [{ type: "text", text: "Sent." }] };
+  }
+);
+
+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.",
+  { question: z.string().describe("The question to ask") },
+  async ({ question }) => {
+    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" });
+    }
+    process.stderr.write(`[${INSTANCE}] ask (${source}): ${value}\n`);
+    return { content: [{ type: "text", text: value }] };
+  }
+);
+
+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)"),
+  },
+  async ({ question, options }) => {
+    const keyboard = {
+      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" });
+    process.stderr.write(`[${INSTANCE}] choose (${source}): ${value}\n`);
+    return { content: [{ type: "text", text: value }] };
+  }
+);
+
+// ── Start ─────────────────────────────────────────────────────────────────────
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+process.stderr.write(`[telegram-mcp] Ready — instance: ${INSTANCE}\n`);

package/src/setup.js

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+/**
+ * npx @thxmxx/telegram-mcp init
+ *
+ * One-time global setup:
+ *  1. Asks for bot token and chat ID
+ *  2. Registers the MCP server globally in Claude Code (~/.claude.json)
+ *  3. Installs the /use-telegram slash command in ~/.claude/commands/
+ *
+ * Instance names are auto-generated per session — no need to configure them.
+ */
+
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output, exit } from "node:process";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const rl  = createInterface({ input, output });
+const ask = (q) => rl.question(q);
+
+const BOLD  = "\x1b[1m";
+const GREEN = "\x1b[32m";
+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); };
+
+// ── Pre-flight ────────────────────────────────────────────────────────────────
+
+console.log(`\n${BOLD}@thxmxx/telegram-mcp — one-time setup${RESET}\n`);
+
+const [major] = process.versions.node.split(".").map(Number);
+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();
+  ok(`Claude Code: ${ver}`);
+} catch {
+  die("`claude` not found. Install: https://docs.claude.ai/claude-code");
+}
+
+// ── Step 1: Bot token ─────────────────────────────────────────────────────────
+
+console.log(`
+${BOLD}Step 1 — Bot token${RESET}
+  ${DIM}Open Telegram → @BotFather → /newbot${RESET}
+`);
+const token = (await ask("  Bot token: ")).trim();
+if (!token) die("Token is required.");
+
+// ── Step 2: Chat ID ───────────────────────────────────────────────────────────
+
+console.log(`
+${BOLD}Step 2 — Your Telegram user ID${RESET}
+  ${DIM}Message @userinfobot on Telegram to get your numeric ID.${RESET}
+`);
+const chatId = (await ask("  Your Telegram user ID: ")).trim();
+if (!chatId) die("User ID is required.");
+
+rl.close();
+
+// ── Register MCP globally in Claude Code ─────────────────────────────────────
+
+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" });
+} 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" });
+  } 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}`
+    );
+  }
+}
+
+ok("MCP server registered globally.");
+
+// ── Install /use-telegram slash command ───────────────────────────────────────
+
+const commandsDir = join(homedir(), ".claude", "commands");
+mkdirSync(commandsDir, { recursive: true });
+
+const commandPath = join(commandsDir, "use-telegram.md");
+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.
+
+The instance name is derived automatically from the current folder and
+session ID, so messages on Telegram always show which session is talking.
+
+## Modes
+
+- \`/use-telegram\` — full interactive mode (notify + ask + choose)
+- \`/use-telegram notify\` — notifications only, no questions
+
+## 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
+
+## Instance naming
+
+Generate the instance label as: \`{folder-name}#{short-session-id}\`
+Example: \`backend#a3f2\`, \`frontend#9c11\`
+
+Use the same label for the entire session.
+`);
+
+ok(`Slash command installed → ${commandPath}`);
+
+// ── Done ──────────────────────────────────────────────────────────────────────
+
+console.log(`
+${GREEN}${BOLD}All done!${RESET}
+
+  Restart Claude Code. From now on, in any session:
+
+    ${BOLD}/use-telegram${RESET}           full mode (notify + ask + choose)
+    ${BOLD}/use-telegram notify${RESET}    notifications only
+
+  Or just tell Claude in the prompt:
+    ${DIM}"refactor this and notify me on telegram when done"${RESET}
+    ${DIM}"deploy to staging, ask me via telegram if anything is unclear"${RESET}
+
+  Each session auto-identifies itself as ${BOLD}[folder#id]${RESET} in Telegram.
+  ${DIM}No need to run init again unless you change your bot token.${RESET}
+`);