telegram-notify-mcp 1.0.0 → 2.0.0

package/.env.example

@@ -1,3 +1,7 @@
 # Copy to your MCP host env — do not commit real values
 TELEGRAM_BOT_TOKEN=
 TELEGRAM_CHAT_ID=
+# Optional comma-separated inbound allowlist (defaults to TELEGRAM_CHAT_ID if unset)
+# TELEGRAM_CHAT_ALLOWLIST=123456789,987654321
+# Optional local store directory for mappings + pending commands (default: ./.telegram-notify-data)
+# TELEGRAM_NOTIFY_DATA_DIR=

package/ARCHITECTURE-PHASE2.md

@@ -0,0 +1,324 @@
+# Architecture — Phase 2: Bidirectional Telegram ↔ MCP Host
+
+Publisher-neutral design notes for **`telegram-notify-mcp`**. Phase 1 already ships outbound notify tools over stdio MCP. Phase 2 adds **inbound** text commands from Telegram that route back to the **same agent** that sent a given notify. Voice/audio is deferred to Phase 2b after a text MVP.
+
+This document describes architecture only. It is not an implementation plan with code.
+
+---
+
+## 1. Goals & non-goals
+
+### Goals
+
+- When the host sends a Telegram notify, the user can **reply in Telegram** and command the **same** Grok Bot / MCP-host agent that originated that notify.
+- Every outbound notify must carry (or be mapped to) a stable **`source_agent_id`** so replies route only to that agent.
+- Inbound text should support **full natural-language commands**, equivalent in intent to typing in the in-app chat box (subject to host delivery APIs).
+- Keep **BYOB** (bring-your-own BotFather token) via process env; no mandatory hosted SaaS.
+- Remain local-first: mapping store and pending queue live with the MCP process (or a small colocated bridge).
+- Preserve **agent isolation**: a reply to agent A’s message must never wake agent B.
+
+### Non-goals
+
+- Replacing the in-app chat UI or becoming a full Telegram client.
+- Executing shell, file writes, or arbitrary code **inside** the MCP server based on Telegram text.
+- Shipping or collecting BotFather tokens in the package; marketplace “plugin secret UI” is separate future work.
+- Native voice STT inside the MCP package (host transcribes after download).
+- Multi-tenant hosted bridging, public webhooks on the open internet without the user’s own infra, or group-admin bot features.
+- Guaranteeing delivery if the MCP host process is stopped (queue persists locally; delivery waits for a poller).
+
+---
+
+## 2. Actors
+
+| Actor | Role |
+|-------|------|
+| **User (Telegram)** | Receives notifies; replies with text (MVP) or later voice. Only allowlisted chat(s) may command. |
+| **BotFather bot** | User-owned Telegram bot; HTTP API token stays in env (`TELEGRAM_BOT_TOKEN`). |
+| **MCP server (`telegram-notify-mcp`)** | stdio tools: outbound notify, mapping persistence, pending-command queue, ack, optional getFile metadata. Does **not** wake agents by itself. |
+| **MCP host / Grok Bot agents** | Multiple concurrent agents may share one MCP server instance. Each agent has an id used as `source_agent_id`. Host provides SendToAgent / channel / routine hooks. |
+| **Optional bridge** | Host skill/routine or small daemon that polls Telegram (or receives webhook), feeds updates into MCP queue tools, then delivers pending commands to the correct agent. |
+
+---
+
+## 3. Why MCP alone is not enough for push-inbound
+
+MCP tools over **stdio** are **pull**: the host invokes a tool, the server returns a result, then the turn ends. There is no standard MCP mechanism for the server to asynchronously push “user replied on Telegram” into a sleeping agent.
+
+Telegram inbound is either:
+
+- **Long-poll** `getUpdates`, or
+- **Webhook** HTTP callbacks,
+
+both of which require a process that is awake and can **deliver** into the host’s agent runtime.
+
+Grok Bot-style **wake / `[inbound]`** (or equivalent host channels) are **host-side** concerns. The MCP package can:
+
+1. Record outbound message → agent mappings,
+2. Ingest updates into a **pending commands** queue,
+3. Expose `list` / `get` / `ack` tools,
+
+but something on the host (routine, skill, or bridge daemon) must poll those tools (or call Telegram and then the tools) and invoke **SendToAgent** (or the host’s equivalent) for the mapped `source_agent_id`.
+
+**Implication:** Phase 2 is a **two-layer** design. Shipping only new MCP tools without a host poller does not complete the user story.
+
+---
+
+## 4. Recommended architecture — two layers
+
+```text
+┌─────────────┐     Bot API      ┌──────────────────────┐     stdio      ┌─────────────────┐
+│  Telegram   │ ◀──────────────▶ │  telegram-notify-mcp │ ◀────────────▶ │  MCP host       │
+│  (user)     │                  │  (tools + local DB)  │                │  agents +       │
+└─────────────┘                  └──────────────────────┘                │  routine/bridge │
+                                                                         └────────┬────────┘
+                                                                                  │
+                                                                         SendToAgent / channel
+                                                                                  │
+                                                                         ┌────────┴────────┐
+                                                                         │ target agent    │
+                                                                         │ (by source_id)  │
+                                                                         └─────────────────┘
+```
+
+### Layer A — MCP package
+
+- Extend outbound notify to require **`source_agent_id`** (optional display name).
+- Persist mapping: Telegram `message_id` + `chat_id` → agent metadata.
+- Ingest allowlisted inbound text (and later voice file refs) into a **pending commands** queue.
+- Expose tools to list/get/ack pending commands; no agent wake logic inside MCP.
+
+### Layer B — Host / bridge
+
+- Prefer a **Grok Bot routine or skill** that periodically:
+
+  1. Ensures Telegram updates are pulled (either host calls `telegram_get_updates` / ingest helper, or MCP does opportunistic poll on tool call — see open questions),
+  2. Calls `telegram_list_pending_commands` (or get),
+  3. Delivers each item to the mapped agent via host API,
+  4. Acks successful delivery.
+
+- Alternative: a small local daemon with the same poll → deliver → ack loop if the host has no scheduler.
+
+**Do not** put BotFather tokens in Telegram message bodies or in agent prompts.
+
+---
+
+## 5. Outbound notify changes
+
+### Tool contract (conceptual)
+
+`telegram_notify` (and optionally `telegram_send_message`) gains:
+
+| Field | Required | Purpose |
+|-------|----------|---------|
+| `source_agent_id` | **Yes** (Phase 2) | Stable id of the originating agent |
+| `source_agent_name` | No | Short human label for footer / debugging |
+| existing `title` / `body` / `chat_id` | as today | Unchanged semantics |
+
+### User-visible attribution
+
+Append a **short footer** on the Telegram message, for example:
+
+```text
+— from agent <source_agent_name or truncated source_agent_id>
+Reply to this message to continue with this agent.
+```
+
+Optional later: Telegram reply keyboard / force-reply hints. Footer alone is enough for MVP clarity.
+
+### Mapping store
+
+On successful `sendMessage`, persist:
+
+```text
+{ telegram_message_id, chat_id } → {
+  source_agent_id,
+  source_agent_name?,
+  conversation_hint?,   // optional host conversation / thread id
+  created_at
+}
+```
+
+Storage: local file or embedded store beside the MCP process (path configurable). Entries may TTL/expire; see open questions.
+
+Routing key is **`reply_to_message.message_id` + `chat.id`**, not the free-text footer (footer is UX only).
+
+---
+
+## 6. Inbound path MVP (text)
+
+1. **Prefer Telegram reply** to the notify message. If `message.reply_to_message` is present, look up mapping; if found, enqueue a pending command for that `source_agent_id`.
+2. **Fallback:** if there is no reply context, accept an explicit `/to <agent_id_or_name> …` only when unambiguous; otherwise reject with a short Telegram error reply (optional) or drop with log.
+3. **Allowlist:** only updates from configured `TELEGRAM_CHAT_ID` (or an allowlist env) may create commands. Other chats are ignored.
+4. Payload to the agent is the user’s natural-language text (plus optional metadata: telegram message id, timestamp, reply-to notify id). Treat it like an in-app user message, not a restricted verb DSL — verbs like `/status` may still be conveniences but are not required for MVP.
+5. After enqueue, the host poller delivers and **acks**; MCP does not interpret command semantics.
+
+---
+
+## 7. Delivery into Grok Bot (ranked options)
+
+| Rank | Option | Notes |
+|------|--------|-------|
+| **A (recommended)** | Host **routine/skill** polls `telegram_list_pending_commands` / get, then **SendToAgent** (or host channel) for `source_agent_id`, then `telegram_ack_command` | Works with BYOB MCP today; no product webhook dependency |
+| **B** | Webhook trigger if the host supports HTTP wake endpoints | Faster; needs user-exposed HTTPS and host support |
+| **C** | Native Telegram channel if the product adds one later | Best UX long-term; out of package scope |
+
+**Recommendation for BYOB MCP today: A.**
+
+---
+
+## 8. New MCP tools sketch (names + purpose only)
+
+| Tool | Purpose |
+|------|---------|
+| `telegram_notify` | Extended: require `source_agent_id`; optional `source_agent_name`; write mapping; footer |
+| `telegram_send_message` | Same attribution/mapping when used as a notify-equivalent |
+| `telegram_list_pending_commands` | List unacked pending commands (filter by agent optional) |
+| `telegram_get_pending_commands` | Alias or fetch+claim variant for pollers (exact semantics TBD) |
+| `telegram_ack_command` | Mark command delivered / drop after host success or poison |
+| `telegram_ingest_updates` | Optional: pull `getUpdates`, apply allowlist + mapping, enqueue (keeps poll logic in one place) |
+| `telegram_get_file` | Phase 2b: resolve Telegram `file_id` → download path/URL metadata for host STT |
+
+Phase 1 tools (`telegram_get_me`, `telegram_get_updates`) remain for setup and diagnostics.
+
+---
+
+## 9. Data model — pending commands queue
+
+Logical record (illustrative fields):
+
+```text
+PendingCommand {
+  id: string                 // opaque local id
+  source_agent_id: string
+  source_agent_name?: string
+  conversation_hint?: string
+  chat_id: string | number
+  telegram_message_id: number
+  reply_to_telegram_message_id?: number
+  text: string               // user command text (MVP)
+  voice_file_id?: string     // Phase 2b
+  created_at: string         // ISO-8601
+  status: "pending" | "delivered" | "acked" | "rejected"
+  error?: string
+}
+```
+
+Mapping table (outbound):
+
+```text
+OutboundMapping {
+  chat_id
+  telegram_message_id
+  source_agent_id
+  source_agent_name?
+  conversation_hint?
+  created_at
+}
+```
+
+Concurrency: ack should be idempotent; list should not lose items if the poller crashes before ack (at-least-once delivery; host should tolerate duplicates or use `id` for dedupe).
+
+---
+
+## 10. Security
+
+- **Token:** `TELEGRAM_BOT_TOKEN` only via env / secret store; never log full token; never put token in Telegram bodies or tool results shown to the user.
+- **Chat allowlist:** inbound commands only from configured chat id(s); reject others silently or with minimal log.
+- **No shell from Telegram inside MCP:** the server only enqueues text/metadata; the **host agent** decides what to do under its normal policies.
+- **Rate limits:** per-chat and global caps on enqueue and outbound replies to avoid loops / floods.
+- **Secrets in bodies:** notify templates must not embed tokens, API keys, or private paths.
+- **Agent isolation:** routing strictly by mapping / `/to`; never broadcast a command to all agents.
+- **Least privilege:** bridge/routine only needs MCP tool access + host SendToAgent; it should not re-export the bot token to agents’ prompts.
+
+---
+
+## 11. Voice — Phase 2b
+
+After text MVP:
+
+1. User replies with a voice message (preferably as reply-to notify).
+2. Ingest stores `voice_file_id` (and duration/mime if available) on the pending command; `text` may be empty.
+3. Host (or bridge) calls `telegram_get_file`, downloads bytes locally, **transcribes** with a host-chosen STT service.
+4. Host writes transcript into the same delivery path (SendToAgent) as text commands, then acks.
+
+MCP does not embed a cloud STT vendor; transcription is host-side so BYOB and privacy choices stay with the operator.
+
+---
+
+## 12. Sequence diagrams
+
+### Outbound notify
+
+```mermaid
+sequenceDiagram
+  participant Agent as Source agent
+  participant Host as MCP host
+  participant MCP as telegram-notify-mcp
+  participant TG as Telegram Bot API
+  participant User as User Telegram
+
+  Agent->>Host: request notify (body, source_agent_id)
+  Host->>MCP: telegram_notify(...)
+  MCP->>TG: sendMessage (body + footer)
+  TG-->>MCP: message_id, chat_id
+  MCP->>MCP: persist mapping message_id->source_agent_id
+  MCP-->>Host: ok + message_id
+  TG-->>User: notification visible
+```
+
+### Inbound reply → agent
+
+```mermaid
+sequenceDiagram
+  participant User as User Telegram
+  participant TG as Telegram Bot API
+  participant MCP as telegram-notify-mcp
+  participant Bridge as Host routine / bridge
+  participant Agent as Mapped agent
+
+  User->>TG: reply text to notify message
+  Bridge->>MCP: telegram_ingest_updates / getUpdates path
+  MCP->>TG: getUpdates (if not webhook)
+  TG-->>MCP: update with reply_to_message
+  MCP->>MCP: allowlist check + mapping lookup
+  MCP->>MCP: enqueue PendingCommand
+  Bridge->>MCP: telegram_list_pending_commands
+  MCP-->>Bridge: [{ id, source_agent_id, text, ... }]
+  Bridge->>Agent: SendToAgent / channel (natural language)
+  Bridge->>MCP: telegram_ack_command(id)
+```
+
+---
+
+## 13. MVP milestones
+
+| Milestone | Scope |
+|-----------|--------|
+| **M1** | Mapping store + `source_agent_id` on notify + footer attribution |
+| **M2** | Pending commands queue + list/get/ack (+ optional ingest) tools |
+| **M3** | Grok Bot routine/skill (or daemon) poll → SendToAgent → ack |
+| **M4** | Voice Phase 2b: `telegram_get_file` + host transcription into same queue |
+
+Exit criteria for text MVP: reply-to a notify in the allowlisted chat reliably wakes **only** the originating agent with the user’s full text.
+
+---
+
+## 14. Open questions for the publisher
+
+1. **Mapping TTL / retention** — How long to keep outbound mappings and pending rows? Bound disk use vs. late replies.
+2. **Who calls `getUpdates`?** — Host-only vs. `telegram_ingest_updates` inside MCP on each poll tick (single consumer offset / `offset` management).
+3. **Claim vs. list** — Soft-claim (`delivered`) before SendToAgent to reduce double-delivery races across multiple pollers.
+4. **`conversation_hint` schema** — Opaque string vs. structured host conversation id; required or optional for MVP.
+5. **Failure UX** — Auto-reply on Telegram when mapping missing / agent unknown / rate limited?
+6. **Multi-instance MCP** — If two host processes share one bot token, how is update offset and queue ownership coordinated? (Recommend single consumer.)
+7. **Webhook mode** — Document as optional bridge feature only, or first-class in package later?
+8. **Marketplace secret UI** — Explicitly out of band; any interim docs for Cursor/Grok env wiring only?
+9. **Name collision** — Unscoped npm name vs. existing third-party scoped packages; confirm publish name/scope before M3 docs ship install lines.
+10. **Host API stability** — Exact SendToAgent / routine primitives available to third-party skills; may require bridge daemon if APIs are not public.
+
+---
+
+## Related
+
+- Phase 1 tools and BYOB setup: [README.md](./README.md)
+- High-level phases: [ROADMAP.md](./ROADMAP.md)

package/README.md

@@ -2,27 +2,57 @@
 
 **MCP connector / server** (stdio) that talks to the [Telegram Bot HTTP API](https://core.telegram.org/bots/api) using **your own** bot from [@BotFather](https://t.me/BotFather) (BYOB — bring your own bot).
 
-This package is **not** a Grok Bot agent, chat persona, or hosted SaaS. It is a local Model Context Protocol server you run under Cursor, Grok Bot, or any MCP host. No secrets ship in the repo; configuration is environment-only.
+This package is **not** a chat persona or hosted SaaS. It is a local Model Context Protocol server you run under Cursor, Grok Bot, or any MCP host. No secrets ship in the repo; configuration is environment-only.
 
-**Publisher:** Ehsan Eskandari pour
+**Publisher:** Ehsan Eskandari pour  
+**Version:** 2.0.0 (Phase 2 text MVP — breaking: `source_agent_id` required on `telegram_notify`)
 
 ## How it works
 
 1. You create a Telegram bot with BotFather and receive an HTTP API token.
 2. You run this MCP server with `TELEGRAM_BOT_TOKEN` (and optionally `TELEGRAM_CHAT_ID`) in the process environment.
-3. Your MCP host (Cursor / Grok Bot / etc.) lists the tools and can call them over stdio.
-4. Tools call `api.telegram.org` to verify the bot, discover chat ids, and send notifications.
+3. Your MCP host lists the tools and can call them over stdio.
+4. **Outbound:** notify tools send messages, append an agent footer, and persist `message_id → source_agent_id` mappings locally.
+5. **Inbound (Phase 2):** a host poller calls `telegram_poll_inbound` → `telegram_list_pending_commands` → delivers via the host’s **SendToAgent** (or equivalent) → `telegram_ack_command`.
 
-Phase 1 is outbound notify only — no inbound webhooks.
+MCP alone cannot wake agents asynchronously (stdio is pull-only). See [ARCHITECTURE-PHASE2.md](./ARCHITECTURE-PHASE2.md).
 
-## Tools (Phase 1)
+## Tools
+
+### Phase 1 (still available)
 
 | Tool | Purpose |
 |------|---------|
 | `telegram_get_me` | `getMe` — verify token; return bot id/username |
-| `telegram_send_message` | Send text (`chat_id` optional if env default set) |
-| `telegram_notify` | Short completion notification (`title?` + `body`) |
-| `telegram_get_updates` | List recent updates to discover `chat_id` after `/start` |
+| `telegram_send_message` | Send text (`chat_id` optional if env default set). Optional `source_agent_id` / `source_agent_name` for footer + mapping |
+| `telegram_get_updates` | List recent updates to discover `chat_id` after `/start` (does **not** enqueue commands) |
+
+### Phase 2 — notify + inbound queue
+
+| Tool | Purpose |
+|------|---------|
+| `telegram_notify` | Completion notification (`title?` + `body`). **Requires** `source_agent_id`; optional `source_agent_name`. Appends footer; persists mapping |
+| `telegram_poll_inbound` | `getUpdates` + allowlist + route into pending queue; returns summary counts |
+| `telegram_list_pending_commands` | List pending commands (optional `source_agent_id` filter) |
+| `telegram_ack_command` | Ack/delete by `command_id` after host delivery |
+
+### Inbound routing rules
+
+1. Only messages from allowlisted chats (`TELEGRAM_CHAT_ALLOWLIST` or `TELEGRAM_CHAT_ID`) are considered.
+2. If the message is a **Telegram reply** to a mapped outbound `message_id`, enqueue for that `source_agent_id`.
+3. Else if text starts with `/to <agent_id> <command…>`, enqueue for that agent (fallback).
+4. Else **ignore** (counted as `ignored_unroutable` in the poll result). No shell execution inside MCP.
+
+## Host poller responsibilities (M3 bridge)
+
+A host **routine / skill / daemon** must periodically:
+
+1. Call `telegram_poll_inbound` (fills the queue; advances update offset).
+2. Call `telegram_list_pending_commands`.
+3. For each command, deliver `text` to the agent identified by `source_agent_id` via **SendToAgent** (or the host’s equivalent channel).
+4. Call `telegram_ack_command` with that command’s `id` after successful delivery.
+
+Without this loop, pending commands sit on disk and no agent wakes. See [`skill-snippet.md`](./skill-snippet.md) for a copy-paste host-bridge sketch.
 
 ## BotFather setup
 
@@ -39,7 +69,7 @@ Phase 1 is outbound notify only — no inbound webhooks.
 2. In Telegram, open your bot and tap **Start** (or send `/start`).
 3. Call tool `telegram_get_updates` (optional `limit`).
 4. Read `discovered_chats[].chat_id` from the result.
-5. Set `TELEGRAM_CHAT_ID` to that value so `telegram_notify` / `telegram_send_message` can omit `chat_id`.
+5. Set `TELEGRAM_CHAT_ID` to that value so send/notify can omit `chat_id`, and inbound allowlisting works.
 
 Private chats use a numeric id (e.g. `123456789`). Groups/channels may use negative ids.
 
@@ -61,10 +91,14 @@ Environment variables (see [`.env.example`](./.env.example)):
 | Variable | Required | Description |
 |----------|----------|-------------|
 | `TELEGRAM_BOT_TOKEN` | Yes (for tool calls) | BotFather HTTP API token |
-| `TELEGRAM_CHAT_ID` | No | Default chat for send/notify |
+| `TELEGRAM_CHAT_ID` | No | Default chat for send/notify; also used as inbound allowlist |
+| `TELEGRAM_CHAT_ALLOWLIST` | No | Comma-separated chat ids allowed for inbound commands |
+| `TELEGRAM_NOTIFY_DATA_DIR` | No | Directory for mapping + pending JSON (default `./.telegram-notify-data`) |
 
 The process starts even if `TELEGRAM_BOT_TOKEN` is missing (so the host can list tools); tool calls then return a clear error until the token is set.
 
+Local data under `.telegram-notify-data/` is **gitignored** and **not** included in the npm `files` list.
+
 ## Add MCP in Cursor / Grok Bot
 
 Use a **local** command + env. Example with a built clone:
@@ -110,38 +144,44 @@ If your host UI has **Add MCP** fields instead of raw JSON:
 
 - **command:** `node`
 - **args:** `/absolute/path/to/telegram-notify-mcp/dist/index.js`
-- **env:** `TELEGRAM_BOT_TOKEN`, optional `TELEGRAM_CHAT_ID`
+- **env:** `TELEGRAM_BOT_TOKEN`, optional `TELEGRAM_CHAT_ID` / `TELEGRAM_CHAT_ALLOWLIST` / `TELEGRAM_NOTIFY_DATA_DIR`
 
-## Example notify flow
+## Example notify flow (Phase 2)
 
-1. Configure token (+ optional default chat id) as above; reload MCP.
+1. Configure token (+ default chat id) as above; reload MCP.
 2. `telegram_get_me` → confirm username.
-3. If needed: message the bot, then `telegram_get_updates` → set `TELEGRAM_CHAT_ID`.
-4. When a task finishes, call `telegram_notify` with title/body. Example payload:
+3. When a task finishes, call `telegram_notify` with **required** `source_agent_id`:
 
 ```json
 {
   "title": "Deploy finished",
-  "body": "staging is live; smoke tests passed."
+  "body": "staging is live; smoke tests passed.",
+  "source_agent_id": "agent-deploy-1",
+  "source_agent_name": "Deploy helper"
 }
 ```
 
-You should receive a Telegram message like:
+Telegram shows something like:
 
 ```text
 ✅ Deploy finished
 
 staging is live; smoke tests passed.
+
+— from agent Deploy helper
+Reply to this message to continue with this agent.
 ```
 
-See also [`skill-snippet.md`](./skill-snippet.md) for agent-oriented usage notes.
+4. User **replies** to that message in Telegram (or sends `/to agent-deploy-1 …`).
+5. Host poller: `telegram_poll_inbound` → list → SendToAgent → `telegram_ack_command`.
 
 ## Security notes
 
-- Token grants full control of the bot — treat it like a password.
-- This server only calls `api.telegram.org`; it does not open inbound webhooks in Phase 1.
+- Token grants full control of the bot — treat it like a password. **Do not log tokens.**
+- This server does **not** execute shell or arbitrary code from Telegram text; it only enqueues text/metadata for the host.
+- Inbound commands are restricted to the chat allowlist.
 - Configuration is **env-only** for the published server. Do not commit tokens or chat ids.
-- No secrets are stored in this repository.
+- Mapping/pending data stays local; do not publish `.telegram-notify-data` in releases.
 
 ## Contact
 
@@ -156,4 +196,4 @@ MIT — see [LICENSE](./LICENSE).
 
 ## Roadmap
 
-Phase 2 ideas (inbound / control) are sketched in [ROADMAP.md](./ROADMAP.md).
+Milestones and remaining work: [ROADMAP.md](./ROADMAP.md). Architecture detail: [ARCHITECTURE-PHASE2.md](./ARCHITECTURE-PHASE2.md).

package/ROADMAP.md

@@ -1,21 +1,29 @@
 # Roadmap
 
-## Phase 1 (this release)
+## Phase 1
 
 - [x] stdio MCP connector/server
 - [x] `telegram_get_me`, `telegram_send_message`, `telegram_notify`, `telegram_get_updates`
 - [x] BYOB BotFather token via env only
 - [x] Unit tests with mocked fetch
-- [ ] Publish to npm (`telegram-notify-mcp`)
+- [x] Publish to npm (`telegram-notify-mcp`) — 1.0.0 shipped; 2.0.0 Phase 2 text MVP
 - [ ] Optional Cursor / MCP marketplace plugin listing
 
-## Phase 2 (later) — inbound / control
+## Phase 2 — inbound / control (text MVP)
 
-Not implemented yet. Possible directions:
+Architecture: [ARCHITECTURE-PHASE2.md](./ARCHITECTURE-PHASE2.md).
 
-- Optional long-poll or webhook receiver so hosts can **read** user replies / commands from Telegram
-- Simple allowlisted control verbs (e.g. `/status`, `/cancel`) mapped to host-side hooks
-- Multi-chat routing and per-chat rate limits
-- Richer notify templates (progress, failure, links) without embedding secrets
+- [x] **M1** — Mapping store + required `source_agent_id` on `telegram_notify` + footer attribution
+- [x] **M2** — Pending commands queue + `telegram_poll_inbound` / `telegram_list_pending_commands` / `telegram_ack_command`; reply + `/to` routing; chat allowlist
+- [x] **M3** — Host routine/skill (or daemon) poll → SendToAgent → ack (documented; host-provided)
+- [ ] **M4** — Voice Phase 2b: `telegram_get_file` + host transcription into same queue
 
-Phase 2 must remain local-first (no mandatory hosted SaaS) and keep the BotFather BYOB model.
+Notes:
+
+- Two layers: MCP tools + mapping/pending queue; host routine/bridge delivers to the originating agent
+- Unroutable allowlisted inbound text (no reply mapping and no `/to <agent_id> …`) is **ignored** (counted in poll summary)
+- Delivery: recommend host poll of pending-command tools + SendToAgent (webhook / native channel later)
+- Voice/audio after text MVP (Phase 2b / M4)
+- BYOB token remains env-only (marketplace secret UI is separate)
+
+Phase 2 remains local-first (no mandatory hosted SaaS) and keeps the BotFather BYOB model.

package/dist/index.d.ts

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 /**
  * telegram-notify-mcp — stdio MCP server for Telegram Bot API notifications.
- * Env: TELEGRAM_BOT_TOKEN (required for tool calls), TELEGRAM_CHAT_ID (optional default).
+ * Env: TELEGRAM_BOT_TOKEN (required for tool calls), TELEGRAM_CHAT_ID (optional default),
+ * TELEGRAM_CHAT_ALLOWLIST (optional inbound), TELEGRAM_NOTIFY_DATA_DIR (optional store path).
  * Starts cleanly without a token; tools fail with a clear error when invoked.
  * Public release is env-only — no disk/secret-store token loading.
+ * Phase 2: outbound mapping + inbound pending queue (host must poll + SendToAgent + ack).
  */
 export {};