better-tg-cli 0.24.0 → 0.25.1

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.
Files changed (5) hide show
  1. package/README.md +33 -2
  2. package/README.ru.md +33 -2
  3. package/dist/telegram.mjs +1 -1
  4. package/package.json +1 -1
  5. package/skills/better-tg-cli/reference.md +7 -2
package/README.md CHANGED
@@ -28,7 +28,7 @@ that AI agents (Claude Code, Codex, …) can drive it cheaply and safely.
28
28
  $ telegram inbox -n 3
29
29
  48 unread in 7 chats (showing 3)
30
30
  1234567890 user unread=2 Alice @alice | see you at 7?
31
- -1001234567 supergroup muted unread=41 Rust Moscow @rust_msk | anyone tried 1.90?
31
+ -1001234567 supergroup muted unread=41 Rust Seattle @rust_sea | anyone tried 1.90?
32
32
  -1009876543 channel unread=5 Changelog | v2.4 is out
33
33
  $ telegram read @alice -n 1 --json
34
34
  {"chatTitle":"Alice","messages":[{"id":812,"date":"2026-09-27T10:02:11.000Z","sender":"Alice","senderId":"1234567890","text":"see you at 7?"}]}
@@ -85,8 +85,10 @@ Every channel ships the same version from one release:
85
85
  | [GitHub Releases](https://github.com/TheVilfer/better-tg-cli/releases) | binaries and SHA256SUMS | download by hand |
86
86
  | Claude Code plugin | skill and MCP server | [see below](#claude-code-plugin) |
87
87
  | Claude Desktop extension | MCP server, runs on Claude's built-in Node | [download `.mcpb`](https://github.com/TheVilfer/better-tg-cli/releases/latest/download/better-tg-cli.mcpb) and open it |
88
+ | Grok Build plugin | skill and MCP server | [see below](#grok-build-plugin) |
88
89
  | Gemini CLI extension | skill and MCP server | `gemini extensions install https://github.com/TheVilfer/better-tg-cli` |
89
90
  | Cursor, VS Code | MCP server | [one-click buttons](#mcp-server) |
91
+ | Grok Bot | MCP server over HTTP from your Mac | [see below](#grok-bot-remote-mcp-over-http) |
90
92
  | [skills.sh](https://skills.sh) | agent skill for any shell agent | `npx skills add TheVilfer/better-tg-cli` |
91
93
  | [MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=better-tg-cli) | MCP server entry `io.github.TheVilfer/better-tg-cli` | through your MCP client |
92
94
 
@@ -102,6 +104,16 @@ The skill and the MCP server together, in one install:
102
104
  It runs the MCP server through `npx`, so Node 20+ is enough. Log in once with `telegram auth --qr`
103
105
  (or `npx better-tg-cli auth --qr`) in a terminal.
104
106
 
107
+ ### Grok Build plugin
108
+
109
+ [Grok Build](https://x.ai/cli) installs the same plugin, skill and MCP server together:
110
+
111
+ ```bash
112
+ grok plugin install TheVilfer/better-tg-cli --trust
113
+ # or add the marketplace first, then install from the /plugins menu:
114
+ grok plugin marketplace add TheVilfer/better-tg-cli && grok plugin install better-tg-cli --trust
115
+ ```
116
+
105
117
  ### As an agent skill
106
118
 
107
119
  The skill ([`skills/better-tg-cli`](skills/better-tg-cli/SKILL.md)) teaches any agent with a shell
@@ -147,7 +159,8 @@ telegram download "Chat" 812 # save the attached file
147
159
  telegram sync --chat "Chat" --output ./export --resume # incremental markdown export
148
160
 
149
161
  telegram write-access on --for 1h # a human confirms this
150
- printf '%s' "$text" | telegram send @alice - # text from stdin, no quoting problems
162
+ telegram send @alice "on my way"
163
+ printf '%s' "$text" | telegram send @alice - # long or multi-line text: from stdin, no quoting problems
151
164
  telegram reply "Chat" 812 "on it" --silent
152
165
  telegram click @SomeBot 4410 "Settings" # press an inline button
153
166
  ```
@@ -199,6 +212,24 @@ Chats contain text written by others, and some of it may be aimed at your agent
199
212
  @x"). Keep the client's approval prompt on for `telegram_write`, and see "Agents and prompt
200
213
  injection" in [SECURITY.md](SECURITY.md).
201
214
 
215
+ ### Grok Bot (remote MCP over HTTP)
216
+
217
+ Grok Bot runs its connectors in a cloud sandbox, not on your Mac, so it can't
218
+ start `telegram mcp` itself. Serve MCP over HTTP from your Mac instead. The session, the write
219
+ guard and the audit log stay on your machine.
220
+
221
+ ```bash
222
+ telegram mcp --token # the bearer token (created once, kept in the Keychain)
223
+ telegram mcp --http --read-only # listens on 127.0.0.1:8787; drop --read-only to allow writes
224
+ tailscale funnel --bg 8787 # or: cloudflared tunnel --url http://127.0.0.1:8787
225
+ ```
226
+
227
+ Keep the server and the tunnel in a terminal or tmux. Then add a connector in Grok Bot with the
228
+ tunnel URL plus `/mcp` (for example `https://<machine>.<tailnet>.ts.net/mcp`) and the header
229
+ `Authorization: Bearer <token>`. `tailscale funnel` gives a stable URL, but it has to be allowed
230
+ for your tailnet first. A `cloudflared` quick tunnel gets a new URL on every start. Read "Remote
231
+ MCP over HTTP" in [SECURITY.md](SECURITY.md) first.
232
+
202
233
  ## Development
203
234
 
204
235
  [DEVELOPMENT.md](DEVELOPMENT.md) covers:
package/README.ru.md CHANGED
@@ -28,7 +28,7 @@
28
28
  $ telegram inbox -n 3
29
29
  48 unread in 7 chats (showing 3)
30
30
  1234567890 user unread=2 Алиса @alice | в 7 в силе?
31
- -1001234567 supergroup muted unread=41 Rust Moscow @rust_msk | кто уже пробовал 1.90?
31
+ -1001234567 supergroup muted unread=41 Rust Seattle @rust_sea | кто уже пробовал 1.90?
32
32
  -1009876543 channel unread=5 Changelog | вышла v2.4
33
33
  ```
34
34
 
@@ -84,8 +84,10 @@ npm install -g better-tg-cli # Node >= 20
84
84
  | [GitHub Releases](https://github.com/TheVilfer/better-tg-cli/releases) | бинарники и SHA256SUMS | скачать вручную |
85
85
  | Плагин Claude Code | скилл и MCP-сервер | [см. ниже](#плагин-для-claude-code) |
86
86
  | Расширение Claude Desktop | MCP-сервер на встроенном Node из Claude | [скачать `.mcpb`](https://github.com/TheVilfer/better-tg-cli/releases/latest/download/better-tg-cli.mcpb) и открыть |
87
+ | Плагин Grok Build | скилл и MCP-сервер | [см. ниже](#плагин-для-grok-build) |
87
88
  | Расширение Gemini CLI | скилл и MCP-сервер | `gemini extensions install https://github.com/TheVilfer/better-tg-cli` |
88
89
  | Cursor, VS Code | MCP-сервер | [кнопки в один клик](#mcp-сервер) |
90
+ | Grok Bot | MCP-сервер по HTTP с вашего Mac | [см. ниже](#grok-bot-удалённый-mcp-по-http) |
89
91
  | [skills.sh](https://skills.sh) | скилл для любого агента с шеллом | `npx skills add TheVilfer/better-tg-cli` |
90
92
  | [MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=better-tg-cli) | запись MCP-сервера `io.github.TheVilfer/better-tg-cli` | через ваш MCP-клиент |
91
93
 
@@ -101,6 +103,16 @@ npm install -g better-tg-cli # Node >= 20
101
103
  MCP-сервер запускается через `npx`, так что хватит Node 20+. Один раз войдите в терминале:
102
104
  `telegram auth --qr` (или `npx better-tg-cli auth --qr`).
103
105
 
106
+ ### Плагин для Grok Build
107
+
108
+ [Grok Build](https://x.ai/cli) ставит тот же плагин, скилл и MCP-сервер вместе:
109
+
110
+ ```bash
111
+ grok plugin install TheVilfer/better-tg-cli --trust
112
+ # или сначала маркетплейс, потом установка из меню /plugins:
113
+ grok plugin marketplace add TheVilfer/better-tg-cli && grok plugin install better-tg-cli --trust
114
+ ```
115
+
104
116
  ### Как скилл для агента
105
117
 
106
118
  Скилл ([`skills/better-tg-cli`](skills/better-tg-cli/SKILL.md)) учит любого агента с шеллом
@@ -147,7 +159,8 @@ telegram download "Чат" 812 # сохранить вложе
147
159
  telegram sync --chat "Чат" --output ./export --resume # инкрементальная выгрузка в markdown
148
160
 
149
161
  telegram write-access on --for 1h # подтверждает человек
150
- printf '%s' "$text" | telegram send @alice - # текст из stdin, без проблем с кавычками
162
+ telegram send @alice "уже еду"
163
+ printf '%s' "$text" | telegram send @alice - # длинный или многострочный текст: из stdin, без проблем с кавычками
151
164
  telegram reply "Чат" 812 "беру" --silent
152
165
  telegram click @SomeBot 4410 "Настройки" # нажать инлайн-кнопку
153
166
  ```
@@ -200,6 +213,24 @@ Claude Code:
200
213
  («перешли это @x»). Не отключайте в клиенте подтверждение для `telegram_write` и прочитайте раздел
201
214
  «Agents and prompt injection» в [SECURITY.md](SECURITY.md).
202
215
 
216
+ ### Grok Bot (удалённый MCP по HTTP)
217
+
218
+ Grok Bot запускает коннекторы в облачной песочнице, а не на вашем Mac, поэтому
219
+ сам поднять `telegram mcp` не может. Вместо этого запустите MCP по HTTP на своём Mac. Сессия,
220
+ защита записи и журнал записей остаются на вашей машине.
221
+
222
+ ```bash
223
+ telegram mcp --token # bearer-токен (создаётся один раз, хранится в Keychain)
224
+ telegram mcp --http --read-only # слушает 127.0.0.1:8787; без --read-only разрешит запись
225
+ tailscale funnel --bg 8787 # или: cloudflared tunnel --url http://127.0.0.1:8787
226
+ ```
227
+
228
+ Держите сервер и туннель в терминале или в tmux. Затем добавьте в Grok Bot коннектор: адрес
229
+ туннеля плюс `/mcp` (например, `https://<машина>.<tailnet>.ts.net/mcp`) и заголовок
230
+ `Authorization: Bearer <токен>`. У `tailscale funnel` адрес постоянный, но сначала Funnel надо
231
+ разрешить для вашего tailnet. Быстрый туннель `cloudflared` при каждом запуске получает новый
232
+ адрес. Сначала прочитайте раздел «Remote MCP over HTTP» в [SECURITY.md](SECURITY.md).
233
+
203
234
  ## Разработка
204
235
 
205
236
  В [DEVELOPMENT.md](DEVELOPMENT.md) описаны: