better-tg-cli 0.20.0 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "better-tg-cli",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Unofficial agent-friendly Telegram client for the command line (MTProto, layer 229)",
   "type": "module",
   "main": "dist/telegram.mjs",
@@ -47,6 +47,7 @@
     "teleproto": "^1.229.0",
     "tsx": "^4.23.15",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "uqr": "^0.1.3",
     "vitest": "^5.0.2"
   },
   "engines": {

package/reference.md

@@ -102,6 +102,27 @@ Buttons that need 2FA take `--password`. `--no-wait` skips waiting for the bot's
 - `sync --resume` is incremental. Checkpoints are per chat ID in `DIR/.sync-meta.json`. A resumed
   run fetches everything after the checkpoint and ignores the default `--days` window.
 
+## MCP server (`telegram mcp`)
+
+- **Tools:**
+  - `telegram_help {grep?}`;
+  - `telegram_read {args}`, marked `readOnlyHint`;
+  - `telegram_write {args, stdin?}`, marked `destructiveHint`.
+
+  `args` is the CLI argv with the command first, for example `["read","@x","-n","20"]`. `stdin`
+  fills a `-` text argument.
+- **What runs where:**
+  - Read tool: only the read commands.
+  - Write tool: everything that changes the account or writes local files (`download`, `sync`,
+    `avatar`).
+  - Never over MCP: `auth`, `logout`, `transfer-owner`, `update`, and changing `write-access`.
+    Showing its status is allowed.
+- **Safety:** the read tool runs with `TG_READ_ONLY=1`, which blocks every guarded write even if a
+  command were misclassified.
+- **Execution:** each call is a separate CLI process with no stdin. Calls run one at a time, time
+  out after 120 s, and output is capped at 100 KB. `watch` needs `-t` or `-n`.
+- **Protocol:** MCP 2025-11-25 with the `initialize` handshake. Newer clients fall back to it.
+
 ## Chat identifiers
 
 `me` / `self` / `saved` / `Saved Messages` / `Избранное` → your Saved Messages. A numeric ID must
@@ -116,8 +137,9 @@ matches titles.
 ## Troubleshooting
 
 - `Not configured`: the user must log in themselves with `telegram auth` (their own keys from
-  my.telegram.org) or `telegram auth --invite` (a token from the maintainer). It is interactive:
-  it needs a phone code and 2FA, so never run it for them.
+  my.telegram.org) or `telegram auth --invite` (a token from the maintainer). It is interactive,
+  so never run it for them. `--qr` logs in by scanning a QR code in the Telegram app instead of
+  typing a code (`TG_QR_INVERT=1` for light terminals).
 
 - `command not found: telegram`: run `brew install thevilfer/tap/better-tg-cli` or `npm install -g better-tg-cli`, or build this folder (`npm install && npm run build && npm install -g .`, needs Bun)
   `telegram update` upgrades an existing install (brew, npm or git checkout); `update --check` only reports.
@@ -125,6 +147,10 @@ matches titles.
   as `(no text)`.
 - `Write access is disabled`: the account is read-only on purpose, or a `--for` window expired. Ask
   the user, then run `telegram write-access on --for 1h`; they confirm it in a dialog.
+- `FLOOD_WAIT` (rate limit): waits of up to 60 s are retried automatically, and stderr says
+  `Telegram rate limit on <method>: waiting Ns`. Longer waits fail with the wait in the error
+  message. `TG_FLOOD_WAIT_MAX=<seconds>` changes the limit: `0` fails fast, a larger value suits
+  long `sync` runs. Don't retry in a loop, because Telegram extends the ban.
 - `CHANNELS_TOO_MUCH` on `join`: the account hit Telegram's channel limit, so leave some first.
 - `Could not find the input entity`: the ID is not in your dialogs. Use `@username` or open the
   chat first.