telegram-notify-mcp 1.0.0 → 2.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "telegram-notify-mcp",
-  "version": "1.0.0",
-  "description": "MCP connector/server that sends Telegram notifications via your own BotFather bot (BYOB).",
+  "version": "2.1.0",
+  "description": "MCP connector/server that sends Telegram notifications via your own BotFather bot (BYOB), with Phase 2 inbound reply routing and inline approval buttons.",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -10,7 +10,7 @@
   "scripts": {
     "build": "tsc",
     "start": "node dist/index.js",
-    "test": "node --import tsx --test tests/telegram.test.ts",
+    "test": "node --import tsx --test tests/telegram.test.ts tests/phase2.test.ts",
     "prepare": "tsc"
   },
   "engines": {
@@ -21,6 +21,7 @@
     "README.md",
     "LICENSE",
     "ROADMAP.md",
+    "ARCHITECTURE-PHASE2.md",
     "skill-snippet.md",
     ".env.example"
   ],

package/skill-snippet.md

@@ -1,13 +1,14 @@
-# Skill snippet — Telegram notify
+# Skill snippet — Telegram notify + inbound bridge
 
-Use when the user wants a Telegram ping after work completes, or to verify the bot.
+Use when the user wants a Telegram ping after work completes, or to route Telegram replies back to the originating agent.
 
-This package is an **MCP connector/server**, not a chat agent. Configure it in your MCP host (Cursor, Grok Bot, or similar), then call its tools.
+This package is an **MCP connector/server**, not a chat agent. Configure it in your MCP host, then call its tools.
 
 ## Preconditions
 
 - MCP server `telegram-notify` (or `telegram-notify-mcp`) is configured with `TELEGRAM_BOT_TOKEN`.
 - Prefer `TELEGRAM_CHAT_ID` in env; otherwise pass `chat_id` on each call.
+- For inbound: same chat must be allowlisted (`TELEGRAM_CHAT_ID` or `TELEGRAM_CHAT_ALLOWLIST`).
 
 ## Discover chat id (once)
 
@@ -15,20 +16,73 @@ This package is an **MCP connector/server**, not a chat agent. Configure it in y
 2. Call `telegram_get_updates`.
 3. Read `discovered_chats[].chat_id` and suggest setting `TELEGRAM_CHAT_ID`.
 
-## Notify on completion
+## Notify on completion (Phase 2)
 
 Call `telegram_notify` with:
 
 - `title`: short status (e.g. `Tests passed`, `PR ready`)
 - `body`: one or two lines of detail (paths, URLs, next step)
+- `source_agent_id`: **required** — stable id of this agent (used for reply routing)
+- `source_agent_name`: optional short label for the Telegram footer
 - `chat_id`: only if no default env chat
+- `approval_buttons`: optional boolean — default **true** (Accept / Decline / Custom keyboard)
+- `accept_command`: optional string — text enqueued when user taps Accept (e.g. `asmj11 بفرست`). Default: `Accept`
+- `decline_command`: optional string — text enqueued on Decline. Default: `Decline`
 
 Keep messages short. Do not put tokens or passwords in the body.
 
+When the user taps **Custom message**, the bot asks for a ForceReply; their next reply is enqueued for the same `source_agent_id` like a normal reply.
+
 ## Verify bot
 
 Call `telegram_get_me` if sends fail or after rotating the token.
 
 ## Raw send
 
-Use `telegram_send_message` when you need a custom `parse_mode` or non-notify wording.
+Use `telegram_send_message` when you need a custom `parse_mode` or non-notify wording. Pass optional `source_agent_id` if you want footer + reply mapping. Optional `approval_buttons` (default false), `accept_command`, `decline_command` work the same as on `telegram_notify` when `source_agent_id` is set.
+
+---
+
+## Host bridge skill (poll → SendToAgent → ack)
+
+MCP cannot push into sleeping agents. A host **routine / skill / daemon** must run this loop on a schedule (e.g. every 15–60s while the host is up):
+
+```text
+1. telegram_poll_inbound          # pull getUpdates, enqueue routed commands
+2. telegram_list_pending_commands # optional: filter by source_agent_id
+3. For each pending command:
+     - Deliver command.text to the agent with id = command.source_agent_id
+       using the host’s SendToAgent / channel / wake API
+     - telegram_ack_command { command_id: command.id }
+```
+
+### Pseudocode
+
+```javascript
+async function telegramInboundTick(mcp, sendToAgent) {
+  await mcp.call('telegram_poll_inbound', { limit: 50, timeout: 0 });
+  const listed = await mcp.call('telegram_list_pending_commands', {});
+  const commands = JSON.parse(listed).commands ?? [];
+  for (const cmd of commands) {
+    await sendToAgent(cmd.source_agent_id, {
+      text: cmd.text,
+      meta: {
+        from: 'telegram',
+        command_id: cmd.id,
+        chat_id: cmd.chat_id,
+        telegram_message_id: cmd.telegram_message_id,
+      },
+    });
+    await mcp.call('telegram_ack_command', { command_id: cmd.id });
+  }
+}
+```
+
+### Routing reminders for the user
+
+- Prefer **Accept / Decline / Custom** buttons, or **replying** to the notify message (maps to the originating agent).
+- Fallback: `/to <agent_id> <natural language command>`.
+- Unroutable messages are ignored (not executed).
+- Pending queue shape is unchanged — bridge/daemon needs no format change.
+
+Do **not** put `TELEGRAM_BOT_TOKEN` in prompts or Telegram bodies. Do **not** treat Telegram text as shell inside the MCP server — the **agent** decides actions under normal host policies.