mcgram 0.2.0__tar.gz

mcgram-0.2.0/.env.example

@@ -0,0 +1,3 @@
+# mcgram credentials — copy to ~/.mcgram/.env (never commit).
+# Get token from @BotFather on Telegram (/newbot).
+MCGRAM_BOT_TOKEN=

mcgram-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: py${{ matrix.python }} / ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.12"]
+        os: [ubuntu-latest, windows-latest]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install Python ${{ matrix.python }}
+        run: uv python install ${{ matrix.python }}
+
+      - name: Sync dependencies
+        run: uv sync --extra dev
+
+      - name: Lint (ruff)
+        run: uv run ruff check src/ tests/
+
+      - name: Type check (mypy)
+        run: uv run mypy src/mcgram
+        continue-on-error: true  # strict mode is opt-in; loosen later
+
+      - name: Run tests
+        run: uv run pytest --cov=mcgram --cov-report=xml --timeout=30
+
+      - name: Upload coverage to Codecov
+        if: matrix.python == '3.12' && matrix.os == 'ubuntu-latest'
+        uses: codecov/codecov-action@v4
+        with:
+          file: ./coverage.xml
+          fail_ci_if_error: false

mcgram-0.2.0/.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Build
+dist/
+build/
+*.whl
+
+# Local config / runtime
+.env
+*.local.yaml
+config.yaml
+audit.jsonl
+audit.jsonl.*
+.lock
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db

mcgram-0.2.0/CHANGELOG.md

@@ -0,0 +1,127 @@
+# Changelog
+
+All notable changes to mcgram will be documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
+this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.2.0] — 2026-05-22
+
+### Added
+- **ntfy.sh transport** — one-way push notifications via the [ntfy.sh](https://ntfy.sh) HTTP API.
+  No bot, no token: subscribe to a topic in the ntfy mobile app and receive pings.
+  Useful for machines where `api.telegram.org` is blocked.
+- `NtfyClient` async HTTP wrapper (`src/mcgram/ntfy_client.py`)
+- `NtfyError` exception type
+- `dispatch.py` — transport-aware send helpers (`send_text` / `send_document` / `send_video_file`)
+- `Settings.ntfy: NtfyConfig | None` — optional `ntfy` config section with
+  `server`, `default_topic`, `access_token_env`
+- `ChannelConfig.transport: telegram | ntfy` — every named channel declares its transport
+- `Settings.resolve_destination(name)` — returns a `Destination` dataclass
+  carrying chat_id (telegram) or topic+server (ntfy). `resolve_channel()`
+  preserved as legacy alias for telegram-only callers.
+- `BotConfig.disable_polling: bool` — keep `bot:` section but skip Telegram
+  long-poll on a specific machine (e.g. when api.telegram.org is blocked).
+  Eliminates poll-loop log spam in send-only deployments.
+- `LimitsConfig.ntfy_file_max_bytes: int = 15728640` — effective `send_file` /
+  `send_video` cap for ntfy channels (15 MB matches public free tier).
+  Telegram channels keep using `file_max_bytes` (50 MB).
+- CLI:
+  - `mcgram init` now generates a random ntfy topic (`mcgram-<16-hex>`) and writes
+    it to `ntfy.default_topic` in the scaffolded config
+  - `mcgram channel add-ntfy NAME [--topic T] [-d DESC]` — declare a ntfy channel
+  - `mcgram channel list` shows a transport column
+  - `mcgram doctor` runs per-transport checks (telegram + ntfy independent),
+    catches `httpx.HTTPError` (SSL/network) and reports as FAIL instead of crashing
+  - `mcgram clear-lock` — remove `~/.mcgram/.lock` after a crashed instance.
+    Use when MCP fails to start with error -32000 due to a stale PID-recycling
+    collision (see Known issues).
+- Companion Claude Code skill (`SKILL.md`) rewritten to be transport-aware:
+  - Per-tool transport matrix (✅ / ❌ on telegram vs ntfy)
+  - Explicit guidance: `ask` is Telegram-only; on ntfy channels, return
+    `transport_unsupported` without retry — fall back to `send_message`
+  - PII/secrets warning for public ntfy topics
+  - Vietnamese trigger phrases added: "gửi qua ntfy", "push to my phone"
+- Tests: +57 unit + integration tests (NtfyClient, ntfy config resolution,
+  transport branching in tools, ntfy CLI subcommands, doctor per-transport,
+  per-transport file size cap). Suite now at 223 tests.
+
+### Changed
+- `Settings.bot` is now optional. Config must declare AT LEAST ONE of
+  `bot` or `ntfy`; both is valid. Telegram-only configs (pre-0.2 format)
+  continue to work unchanged.
+- Tool responses now include a `transport` field (`"telegram"` | `"ntfy"`)
+  so callers know which backend handled the request.
+- Audit log entries gain a `transport` field for the same reason.
+- README quickstart now leads with ntfy (faster setup, no token);
+  Telegram retained as Option B for `ask` 2-way input.
+- `_NEXT_STEPS` printed by `mcgram init` uses ASCII arrows (`->`) instead of
+  Unicode `→` for Windows console compatibility on legacy code pages.
+- `mcgram init` idempotent path now reads `ntfy.default_topic` from the
+  EXISTING config when skipping, so the printed topic always matches what's
+  actually on disk.
+
+### Fixed
+- `mcgram doctor` previously crashed with an uncaught `httpx.ConnectError`
+  when `api.telegram.org` was unreachable. Now reports `[FAIL] telegram ...
+  network/SSL error` and continues to check ntfy.
+
+### Security
+- ntfy public topics are URL-discoverable. Generated topics use 64-bit
+  entropy (16 hex chars). Documentation in README + SKILL.md warns against
+  sending PII/secrets unless self-hosting ntfy with auth.
+- `ntfy.access_token_env` supports Bearer token auth for paid/self-hosted
+  ntfy servers (unit tests cover the path; integration test against a real
+  authed server tracked in `TODO(ntfy-auth-e2e)` in `ntfy_client.py`).
+
+### Known issues
+- **PID-recycling collision on Windows** — the single-instance lock at
+  `~/.mcgram/.lock` stores only the owner PID. If mcgram is killed ungracefully
+  (e.g. host reboot) and Windows later assigns the same PID to a different
+  long-running process (Python, IDE, etc.), the next `mcgram` invocation will
+  see the lock as "held" and refuse to start with error -32000 from Claude
+  Code's MCP layer. Workaround: run `mcgram clear-lock`. Proper fix (storing
+  process creation time alongside the PID) deferred.
+
+### Migration notes
+- 0.1.x configs (`bot:` only) load unchanged on 0.2.0.
+- To add ntfy on top of a working 0.1.x setup: either run `mcgram init --force`
+  (regenerates config, **erases your operator_chat_id**), or manually append an
+  `ntfy:` section to `~/.mcgram/config.yaml` (preserves bot config).
+- On machines that block Telegram, set `bot.disable_polling: true` to stop the
+  poll loop without removing the bot section.
+
+[0.2.0]: https://github.com/tvtdev94/mcgram/releases/tag/v0.2.0
+
+## [0.1.0] — 2026-05-22
+
+### Added
+- MCP stdio server (`mcgram`) exposing 6 tools:
+  - `send_message(text, silent?, parse_mode?)` — post text to operator chat
+  - `send_file(path, caption?, silent?)` — upload file (≤50 MB, CWD-guarded)
+  - `ask(question, options?, timeout_s?)` — block until reply (button/freetext/timeout)
+  - `set_reminder(text, delay_s)` — in-process scheduler (≤10 pending, ≤24h)
+  - `cancel_reminder(reminder_id)`
+  - `list_reminders()`
+- Async Telegram Bot API client (`httpx` wrapper, long-poll loop with backoff)
+- Operator allowlist enforced at dispatcher entry (rejects non-`operator_chat_id` updates)
+- Per-tool token-bucket rate limiter (default 20/min)
+- JSONL audit log with `fsync`, 3-backup rotation, optional `redact_text`,
+  optional `retention_days` pruning
+- Single-instance PID-file lock (cross-platform: Windows + POSIX)
+- CLI: `mcgram init`, `mcgram doctor`, `mcgram audit`, `mcgram install-skill`
+- Bundled companion Claude Code skill (`SKILL.md`) — installed by `mcgram init`,
+  recognizes both English and Vietnamese trigger phrases
+- Docs: `README.md`, `docs/architecture.md`, `docs/security-threat-model.md`,
+  `docs/manual-smoke-test.md`
+- GitHub Actions CI matrix: Python 3.11 + 3.12 × Ubuntu + Windows
+- ≥80% test coverage with `pytest` + `pytest-httpx`
+
+### Security
+- Bot token loaded from env var, never written to logs / audit / stdout
+- `mcgram doctor` masks token to `***<last-4>`
+- `send_file` rejects paths outside CWD by default; opt-in `allow_outside_cwd`
+- Hard caps on `ask` timeout, reminder count + delay + text length, file size
+- Full STRIDE analysis published before v0.1 release
+
+[0.1.0]: https://github.com/tvtdev94/mcgram/releases/tag/v0.1.0

mcgram-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tvtdev94
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcgram-0.2.0/PKG-INFO

@@ -0,0 +1,311 @@
+Metadata-Version: 2.4
+Name: mcgram
+Version: 0.2.0
+Summary: Notification bridge for Claude Code (Telegram + ntfy.sh) — send notifications, ask short questions, set reminders via Telegram bot or ntfy.sh topic.
+Project-URL: Homepage, https://github.com/tvtdev94/mcgram
+Project-URL: Repository, https://github.com/tvtdev94/mcgram
+Project-URL: Issues, https://github.com/tvtdev94/mcgram/issues
+Project-URL: Documentation, https://github.com/tvtdev94/mcgram#readme
+Author: tvtdev94
+License: MIT
+License-File: LICENSE
+Keywords: ai,bot,claude,claude-code,mcp,model-context-protocol,notifications,ntfy,push-notifications,reminders,telegram
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<2.0,>=1.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.5
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tzdata>=2024.1; sys_platform == 'win32'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<img src="docs/images/logo.png" alt="mcgram logo" width="120" />
+
+# mcgram
+
+**Notification bridge for Claude Code** — Telegram **and** ntfy.sh. Claude can ping you, ask you, and remind you on your phone.
+
+[![CI](https://github.com/tvtdev94/mcgram/actions/workflows/ci.yml/badge.svg)](https://github.com/tvtdev94/mcgram/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/mcgram.svg)](https://pypi.org/project/mcgram/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-153%20passing-brightgreen.svg)](#)
+[![Coverage](https://img.shields.io/badge/coverage-84%25-brightgreen.svg)](#)
+
+<img src="docs/images/hero.png" alt="mcgram hero" width="720" />
+
+</div>
+
+---
+
+## What it does
+
+Walk away from a long-running task. mcgram lets Claude **tap you on the shoulder** through Telegram or ntfy.sh — and lets you tap back (Telegram only).
+
+| | |
+|---|---|
+| 📣 **Notify** | "Build passed in 3m12s ✅" / send the failing log as attachment |
+| ❓ **Ask & wait** | Inline buttons (Approve / Cancel) with a timeout — Telegram only |
+| ⏰ **Remind** | "nhắc tôi sau 30 phút check container logs" |
+| 🎥 **Send video** | Demo recordings play right in-chat |
+| 🛰 **Multi-channel** | Route messages to named destinations across both transports |
+| 🌐 **No-token mode** | Use ntfy.sh on machines where `api.telegram.org` is blocked |
+
+Single process, no daemon, no VPS, no webhook setup. Lives inside the MCP server while Claude Code is open.
+
+## How it fits together
+
+<div align="center">
+<img src="docs/images/flow.png" alt="Architecture flow" width="720" />
+</div>
+
+Claude Code spawns `mcgram` over stdio. mcgram opens a long-poll to the Telegram Bot API. When you tap a button or type a reply, the update lands on your phone-out / mcgram-in side, the operator allowlist filters non-you traffic, and the answer flows back to Claude as the tool result.
+
+## Quickstart
+
+> **Prereqs:** Python 3.11+, [`uv`](https://docs.astral.sh/uv/) or `pipx`. Pick ONE transport below (or set up both).
+
+### Option A — ntfy.sh (fastest, no token, ~30 seconds)
+
+Best for: machines where `api.telegram.org` is blocked, or you just want 1-way pings to your phone.
+
+```bash
+# 1) Install + scaffold (generates a random ntfy topic for you)
+uv tool install git+https://github.com/tvtdev94/mcgram     # or: pipx install ...
+mcgram init                                                # writes ~/.mcgram/config.yaml with a unique topic
+
+# 2) Install the ntfy mobile app: https://ntfy.sh/  (iOS / Android / Web)
+#    In the app, subscribe to the topic printed by `mcgram init` (e.g. mcgram-a1b2c3d4...)
+
+# 3) Verify
+mcgram doctor    # ✅ ntfy health, ✅ test message delivered
+
+# 4) Restart Claude Code → /mcp → mcgram appears → done
+```
+
+That's it. **No bot, no token, no chat ID.** Now in Claude Code: *"báo cho tôi qua ntfy khi xong"* or *"push log to my phone"* — Claude knows what to do.
+
+> ⚠️ ntfy.sh topics are URL-addressable. Anyone who knows the topic name can subscribe and read your messages. Topics generated by `mcgram init` use 64-bit entropy (16 hex chars), which is fine for casual notifications but **don't send secrets / PII** unless you self-host ntfy.
+
+### Option B — Telegram (required for 2-way `ask`)
+
+Best for: you want Claude to wait for your Approve/Cancel button before deploying.
+
+```bash
+# 1) Install + scaffold
+uv tool install git+https://github.com/tvtdev94/mcgram
+mcgram init
+
+# 2) Create a bot with @BotFather → /newbot → copy token
+#    Find your chat ID:  /start the bot, then visit
+#    https://api.telegram.org/bot<TOKEN>/getUpdates  → copy chat.id
+
+# 3) Paste credentials and uncomment the bot section
+#    Edit ~/.mcgram/.env       → MCGRAM_BOT_TOKEN=...
+#    Edit ~/.mcgram/config.yaml → uncomment `bot:` block, set operator_chat_id
+
+# 4) Verify
+mcgram doctor    # ✅ get_me OK, ✅ test message delivered
+
+# 5) Restart Claude Code → /mcp → mcgram appears → done
+```
+
+### Both transports
+
+Declare both `ntfy:` and `bot:` in config — each named channel picks its own transport.
+
+## The 7 tools
+
+| Tool | Telegram | ntfy.sh | When to use |
+|---|:---:|:---:|---|
+| **`send_message`** | ✅ | ✅ | Notify on completion / send a status update |
+| **`send_file`** | ✅ | ✅ | Send logs, screenshots, generated artifacts |
+| **`send_video`** | ✅ | ✅ | Send a video that **plays in-chat** (mp4/mov/mkv/webm/m4v) |
+| **`ask`** | ✅ | ❌ | Question with inline buttons OR freetext, blocks until reply. Telegram-only |
+| **`set_reminder`** | ✅ | ✅ | Schedule an in-process reminder (lost on restart) |
+| **`cancel_reminder`** | — | — | Cancel a pending reminder |
+| **`list_reminders`** | — | — | List currently pending reminders |
+
+ntfy.sh has no 2-way input, so `ask` returns `transport_unsupported` on ntfy channels. The companion [Claude Code skill](src/mcgram/data/skill/SKILL.md) (installed by `mcgram init`) teaches Claude when to call which tool — both **English** and **Vietnamese** trigger phrases are recognized.
+
+## Channels
+
+Route messages to different destinations across both transports:
+
+```bash
+mcgram channel add oncall -1001234567890 -d "Pager rotation"        # Telegram
+mcgram channel add-ntfy alerts -d "Build alerts"                     # ntfy.sh — auto-generates topic
+mcgram channel add-ntfy alerts --topic mcgram-myalerts -d "..."      # explicit topic
+mcgram channel list
+#   alerts   ntfy      topic=mcgram-a1b2c3d4e5f6g7h8   Build alerts
+#   default  ntfy      topic=mcgram-xxxxxxxxxxxxxxxx   Auto-created from ntfy.default_topic
+#   oncall   telegram  chat_id=-1001234567890           Pager rotation
+```
+
+Then in Claude Code: *"send the failing log to the alerts channel"* → `send_file(path="…", channel="alerts")`.
+
+## CLI
+
+```bash
+mcgram                          # MCP stdio server (Claude Code calls this)
+mcgram init [--force]           # scaffold ~/.mcgram/ + skill + auto-register MCP (generates ntfy topic)
+mcgram doctor                   # config + connectivity check (per-transport)
+mcgram audit [opts]             # analyze audit.jsonl: --since 1h, --tool ask, --rejected, --tail
+mcgram channel <action>         # list | add NAME CHAT_ID | add-ntfy NAME [--topic T] | remove NAME
+mcgram install-skill [--force]  # reinstall ~/.claude/skills/mcgram/SKILL.md
+```
+
+## Config example
+
+`~/.mcgram/config.yaml` — declare at least one of `ntfy` / `bot`:
+
+```yaml
+ntfy:                              # Transport A — fast, no token
+  server: https://ntfy.sh
+  default_topic: mcgram-a1b2c3d4e5f6g7h8     # generated by `mcgram init`
+  # access_token_env: NTFY_TOKEN   # optional, for paid/self-hosted
+
+bot:                               # Transport B — required for `ask`
+  token_env: MCGRAM_BOT_TOKEN      # token loaded from ~/.mcgram/.env
+  operator_chat_id: 123456789      # your personal chat ID
+
+defaults:
+  parse_mode: plain                # plain | markdown_v2
+  ask_timeout_s: 120
+  rate_limit_per_min: 20
+
+limits:
+  ask_timeout_max_s: 600
+  reminder_max_delay_s: 86400      # 24h
+  reminder_max_pending: 10
+  file_max_bytes: 52428800         # 50 MB
+  ask_options_max: 6
+
+channels:                          # optional named destinations
+  oncall:                          # Telegram channel
+    transport: telegram
+    chat_id: -1001234567890
+    description: Pager rotation
+  alerts:                          # ntfy.sh channel
+    transport: ntfy
+    ntfy_topic: mcgram-alerts-x9k2
+    description: Build alerts
+
+audit:
+  path: ~/.mcgram/audit.jsonl
+  rotate_mb: 25
+  redact_text: false               # true → outbound `text` masked in audit
+  retention_days: null             # e.g. 14
+  timezone: UTC
+
+allow_outside_cwd: false           # send_file restricted to CWD by default
+```
+
+## Security model
+
+| Layer | Mitigation |
+|---|---|
+| 🔐 **Token** | Loaded from env var; never logged; masked in `mcgram doctor` |
+| 🚪 **Operator filter** | Non-`operator_chat_id` updates rejected at dispatcher entry — never reach tool handlers |
+| 🛡 **`send_file` traversal** | Path resolved + checked against CWD; size capped at `file_max_bytes` |
+| ⚡ **Rate limit** | Per-tool token bucket (default 20/min) |
+| 🔒 **Single instance** | PID-file lock at `~/.mcgram/.lock`; second `mcgram` exits with `LockHeldError` |
+| 📜 **Audit trail** | Every call logged JSONL with `fsync`; survives `kill -9` |
+| 🛌 **Reminder spam** | Max 10 pending, 24h delay cap, 1000-char text cap |
+| ⏱ **`ask` DoS** | Hard timeout cap (600s) so a forgetful user can't freeze Claude forever |
+| 🔁 **Polling conflict** | Telegram 409 caught with clean error — no crash loop |
+
+Full STRIDE analysis: [docs/security-threat-model.md](docs/security-threat-model.md).
+
+## Audit
+
+```bash
+mcgram audit                     # summary: counts by status + by tool
+mcgram audit --since 1h          # last hour only
+mcgram audit --tool send_file    # filter by tool
+mcgram audit --rejected          # group rejections by reason
+mcgram audit --tail              # follow new entries (Ctrl-C to stop)
+```
+
+Sample lines:
+
+```jsonc
+{"ts":"2026-05-21T10:00:00+00:00","tool":"send_message","status":"ok","chat_id":123,"channel":"default","text":"build passed","text_len":12,"ms":150}
+{"ts":"2026-05-21T10:00:05+00:00","tool":"ask","status":"ok","channel":"oncall","question_id":"q_a1","source":"button","ms":3200}
+{"ts":"2026-05-21T10:00:10+00:00","tool":"send_file","status":"rejected","reason":"file_too_large","bytes":62914560}
+```
+
+## Known limitations
+
+- **No persistent reminders** — schedules live in process memory. Restart = lost.
+- **`ask` blocks the MCP call** — keep timeouts short or Claude waits idle.
+- **`ask` is Telegram-only** — ntfy.sh has no 2-way input. On ntfy channels, `ask` returns `transport_unsupported` without contacting the network.
+- **ntfy.sh public topics are URL-discoverable** — anyone with the topic name can subscribe. mcgram generates 64-bit-entropy topics, but **don't send secrets / PII** unless you self-host ntfy with auth.
+- **ntfy.sh file size cap** — public free tier ~15 MB (vs Telegram's 50 MB). Self-hosted ntfy can raise the cap.
+- **No remote control** — Claude can send, but the bot doesn't accept arbitrary commands FROM Telegram. (Future v0.2.)
+- **No webhook / VPS support** — Telegram uses long-poll only.
+- **Same Telegram token on 2 machines** → 409 Conflict (only one poller per bot). mcgram backs off cleanly; use different bots for different machines. (When `bot:` is omitted, Telegram polling is fully disabled — no 409, no log spam.)
+
+## Architecture
+
+Full module map, lifecycle diagram, and data flow: [docs/architecture.md](docs/architecture.md).
+
+```
+src/mcgram/
+├── cli.py · cli_init · cli_doctor · cli_audit · cli_channel · skill_installer
+├── config · errors · audit · lock · rate_limiter
+├── tg_client · ntfy_client · dispatch · update_dispatcher · polling · server · runtime
+├── ask_registry · reminders
+└── tools/  send_message · send_file · send_video · ask · set_reminder · cancel_reminder · list_reminders
+```
+
+All modules <200 LOC, 153 tests, ruff clean, py3.11/3.12 × ubuntu/windows in CI.
+
+## Update / uninstall
+
+```bash
+uv tool upgrade mcgram          # or: pipx upgrade mcgram
+mcgram install-skill --force    # refresh bundled Claude skill if changed
+claude mcp remove mcgram        # unregister from Claude Code
+uv tool uninstall mcgram        # remove binary
+rm -rf ~/.mcgram ~/.claude/skills/mcgram   # remove config + skill
+```
+
+## Develop
+
+```bash
+git clone https://github.com/tvtdev94/mcgram && cd mcgram
+uv sync --extra dev
+uv run pytest -q
+uv run ruff check src/ tests/
+```
+
+## Credits
+
+- Patterns mirrored from sister project [dbread](https://github.com/tvtdev94/dbread) (read-only DB MCP).
+- Built around the [Model Context Protocol](https://modelcontextprotocol.io/) and the Telegram Bot API.
+
+## License
+
+MIT — see [LICENSE](LICENSE).