better-tg-cli 0.19.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "better-tg-cli",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "Unofficial agent-friendly Telegram client for the command line (MTProto, layer 229)",
   "type": "module",
   "main": "dist/telegram.mjs",
@@ -40,12 +40,13 @@
     "url": "https://github.com/TheVilfer/better-tg-cli/issues"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
+    "@types/node": "^26.6.2",
+    "@typescript/native": "npm:typescript@^7.0.2",
     "big-integer": "^1.6.52",
-    "commander": "^14.0.0",
+    "commander": "^15.0.0",
     "teleproto": "^1.229.0",
     "tsx": "^4.23.15",
-    "typescript": "^5.7.0",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
     "vitest": "^5.0.2"
   },
   "engines": {

package/reference.md

@@ -102,11 +102,37 @@ 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
 exactly match a dialog ID (the `id` from `chats`). `@username` resolves exactly. Anything else
-matches titles: exact first, then substring. For writes, prefer an ID or @username.
+matches titles.
+
+- **Reads:** an exact title first, then a substring.
+- **Writes** (every command gated by write access) accept only an exact, unique title. A substring
+  or a title shared by several chats is refused with up to 5 candidates (`id type title @username`).
+  Retry with the ID.
 
 ## Troubleshooting
 
@@ -120,6 +146,10 @@ matches titles: exact first, then substring. For writes, prefer an ID or @userna
   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.