better-tg-cli 0.20.0 → 0.21.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +27 -2
- package/SKILL.md +1 -1
- package/dist/telegram.mjs +1 -1
- package/package.json +1 -1
- package/reference.md +25 -0
package/package.json
CHANGED
package/reference.md
CHANGED
|
@@ -102,6 +102,27 @@ Buttons that need 2FA take `--password`. `--no-wait` skips waiting for the bot's
|
|
|
102
102
|
- `sync --resume` is incremental. Checkpoints are per chat ID in `DIR/.sync-meta.json`. A resumed
|
|
103
103
|
run fetches everything after the checkpoint and ignores the default `--days` window.
|
|
104
104
|
|
|
105
|
+
## MCP server (`telegram mcp`)
|
|
106
|
+
|
|
107
|
+
- **Tools:**
|
|
108
|
+
- `telegram_help {grep?}`;
|
|
109
|
+
- `telegram_read {args}`, marked `readOnlyHint`;
|
|
110
|
+
- `telegram_write {args, stdin?}`, marked `destructiveHint`.
|
|
111
|
+
|
|
112
|
+
`args` is the CLI argv with the command first, for example `["read","@x","-n","20"]`. `stdin`
|
|
113
|
+
fills a `-` text argument.
|
|
114
|
+
- **What runs where:**
|
|
115
|
+
- Read tool: only the read commands.
|
|
116
|
+
- Write tool: everything that changes the account or writes local files (`download`, `sync`,
|
|
117
|
+
`avatar`).
|
|
118
|
+
- Never over MCP: `auth`, `logout`, `transfer-owner`, `update`, and changing `write-access`.
|
|
119
|
+
Showing its status is allowed.
|
|
120
|
+
- **Safety:** the read tool runs with `TG_READ_ONLY=1`, which blocks every guarded write even if a
|
|
121
|
+
command were misclassified.
|
|
122
|
+
- **Execution:** each call is a separate CLI process with no stdin. Calls run one at a time, time
|
|
123
|
+
out after 120 s, and output is capped at 100 KB. `watch` needs `-t` or `-n`.
|
|
124
|
+
- **Protocol:** MCP 2025-11-25 with the `initialize` handshake. Newer clients fall back to it.
|
|
125
|
+
|
|
105
126
|
## Chat identifiers
|
|
106
127
|
|
|
107
128
|
`me` / `self` / `saved` / `Saved Messages` / `Избранное` → your Saved Messages. A numeric ID must
|
|
@@ -125,6 +146,10 @@ matches titles.
|
|
|
125
146
|
as `(no text)`.
|
|
126
147
|
- `Write access is disabled`: the account is read-only on purpose, or a `--for` window expired. Ask
|
|
127
148
|
the user, then run `telegram write-access on --for 1h`; they confirm it in a dialog.
|
|
149
|
+
- `FLOOD_WAIT` (rate limit): waits of up to 60 s are retried automatically, and stderr says
|
|
150
|
+
`Telegram rate limit on <method>: waiting Ns`. Longer waits fail with the wait in the error
|
|
151
|
+
message. `TG_FLOOD_WAIT_MAX=<seconds>` changes the limit: `0` fails fast, a larger value suits
|
|
152
|
+
long `sync` runs. Don't retry in a loop, because Telegram extends the ban.
|
|
128
153
|
- `CHANNELS_TOO_MUCH` on `join`: the account hit Telegram's channel limit, so leave some first.
|
|
129
154
|
- `Could not find the input entity`: the ID is not in your dialogs. Use `@username` or open the
|
|
130
155
|
chat first.
|