@deadragdoll/tellymcp 0.0.5 → 0.0.6

package/README-ru.md

@@ -7,16 +7,73 @@
 [![node >= 24](https://img.shields.io/badge/node-%3E%3D24-339933)](https://nodejs.org/)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-TellyMCP — это Telegram Human-in-the-Loop MCP server для coding agents.
+TellyMCP — это self-hosted Telegram control plane для coding agents.
 
-Он позволяет агенту:
+Он привязывает реальные agent-сессии к Telegram, делает их доступными с телефона и даёт им работать вместе между локальными и удалёнными машинами.
+
+Он не завязан на одного вендора или один coding assistant. Если агент умеет работать с MCP server, он может использовать TellyMCP.
+
+## Зачем он нужен
+
+Coding agents полезны ровно до того момента, пока они не остаются одни в терминале:
+
+- им нужно уточнение, пока тебя нет за компьютером
+- им нужен approval перед рискованным действием
+- им нужно передать скриншот, файл или note между сессиями
+- им нужно быстро подключить человека или другого агента, не ломая общий workflow
+
+TellyMCP даёт каждой сессии мобильную панель управления и collaboration layer:
+
+- `Live` tmux view и лёгкое управление из Telegram
+- session-scoped inbox и уведомления
+- workspace-aware handoff для файлов и note
+- локальную и удалённую коллаборацию между сессиями
+- поддержку mixed agent setups, если они умеют говорить по MCP
+
+## Ключевые идеи продукта
+
+- `Live` tmux view и управление внутри Telegram Mini App
+- `Collab`-сценарии для локальных и удалённых agent-сессий
+- `.mcp-xchange` как workspace-level handoff шина для note, файлов и скриншотов
+- MCP-native pairing сессий и session-scoped tools
+- optional gateway mode для multi-machine и multi-bot проектов
+
+## Human-in-the-loop — это только один слой системы
+
+Telegram HITL здесь тоже есть, но он не исчерпывает продукт:
 
 - задавать человеку уточняющие вопросы через Telegram
 - получать несвязанные входящие сообщения позже через inbox
-- привязывать несколько agent-сессий
-- работать с локальными и удалёнными партнёрскими сессиями
-- открывать Live tmux view внутри Telegram Mini App
-- обмениваться note, скриншотами и файлами через `.mcp-xchange`
+- уведомлять человека о прогрессе, blockers и approvals
+
+## Что отличает TellyMCP от простого Telegram bot bridge
+
+- он завязан на сессии, а не только на чат
+- он понимает локальные и удалённые collaboration targets
+- у него есть live terminal surface, а не только обмен сообщениями
+- он передаёт файлы через workspace-aware exchange paths, а не просто через ad hoc upload
+- он может работать как standalone node или как gateway-backed control plane
+
+## Типовые сценарии
+
+- держать долгоживущего агента доступным с телефона
+- запускать рядом разных агентов, если каждый умеет подключаться по MCP
+- подруливать tmux-сессией без ноутбука
+- маршрутизировать работу между `frontend`, `backend`, `review` и другими локальными сессиями
+- работать с удалёнными сессиями через gateway-backed project
+- передавать note, скриншоты и реальные файлы через `.mcp-xchange`
+- проверять локальный веб-интерфейс через `browser_*` tools и отправлять результат обратно в Telegram
+
+## Группы инструментов
+
+- pairing и session context
+- Telegram ask/notify/inbox
+- `Live` tmux control
+- browser inspection и screenshots
+- partner notes и partner files
+- tools sync и version checks
+
+Полный список MCP tools лучше держать ниже по README и в самом MCP server, а не на первом экране.
 
 ## Prerequisites
 

package/README.md

@@ -7,50 +7,73 @@
 [![node >= 24](https://img.shields.io/badge/node-%3E%3D24-339933)](https://nodejs.org/)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-TellyMCP is a Telegram Human-in-the-Loop MCP server for coding agents.
+TellyMCP is a self-hosted Telegram control plane for coding agents.
 
-It lets an agent:
+It pairs real agent sessions with Telegram, keeps them reachable from mobile, and lets them collaborate across local and remote machines.
+
+It is not tied to one vendor or one coding assistant. If your agent can talk to an MCP server, it can use TellyMCP.
+
+## Why it exists
+
+Coding agents are useful until they leave the terminal:
+
+- they need clarification while you are away from the desk
+- they need approval before doing something risky
+- they need screenshots, files, or notes passed between sessions
+- they need a human or another agent to unblock work without breaking flow
+
+TellyMCP gives each session a mobile control surface and a collaboration layer:
+
+- `Live` tmux view and light control from Telegram
+- session-scoped inbox and notifications
+- workspace-aware file and note handoffs
+- local and remote session collaboration
+- support for mixed agent setups, as long as they speak MCP
+
+## Core ideas
+
+- `Live` tmux view and control inside Telegram Mini App
+- `Collab` flows for local and remote agent sessions
+- `.mcp-xchange` as a workspace-level handoff bus for notes, files, and screenshots
+- MCP-native session pairing and session-scoped tools
+- optional gateway mode for cross-machine and cross-bot projects
+
+## Human-in-the-loop is one layer, not the whole product
+
+Telegram HITL is still supported, but it is not the whole story:
 
 - ask a human for clarification through Telegram
 - receive unsolicited Telegram messages later through an inbox
-- pair multiple agent sessions
-- collaborate across local and remote sessions
-- open a live tmux view inside Telegram Mini App
-- exchange notes, screenshots, and files through `.mcp-xchange`
-
-Current tools:
-
-- `create_session_pair_code`
-- `clear_session_pairing`
-- `set_session_context`
-- `set_tmux_target`
-- `get_tmux_target`
-- `get_session_context`
-- `clear_session_context`
-- `rename_session`
-- `notify_telegram`
-- `get_telegram_inbox_count`
-- `get_telegram_inbox`
-- `delete_telegram_inbox_message`
-- `ask_user_telegram`
-- `browser_open`
-- `browser_reload`
-- `browser_click`
-- `browser_fill`
-- `browser_press`
-- `browser_wait_for`
-- `browser_wait_for_url`
-- `browser_console`
-- `browser_errors`
-- `browser_network_failures`
-- `browser_clear_logs`
-- `browser_dom`
-- `browser_computed_style`
-- `browser_screenshot`
-- `browser_close`
-- `refresh_tools_markdown`
-- `send_partner_note`
-- `send_partner_file`
+- notify a human about progress, blockers, and approvals
+
+## What makes it different from a simple Telegram bot bridge
+
+- it is session-based, not just chat-based
+- it understands local and remote collaboration targets
+- it has a live terminal surface, not only message exchange
+- it moves files through workspace-aware exchange paths, not just ad hoc uploads
+- it can run as a standalone node or as a gateway-backed control plane
+
+## Typical use cases
+
+- keep a long-running agent reachable from your phone
+- run different agents side by side, as long as each one can connect over MCP
+- steer a tmux-based session without opening a laptop
+- route work between `frontend`, `backend`, `review`, or other local sessions
+- collaborate with remote sessions through a gateway-backed project
+- send notes, screenshots, and real files through `.mcp-xchange`
+- inspect or screenshot a local web app with `browser_*` tools and send results back to Telegram
+
+## Tool groups
+
+- session pairing and context
+- Telegram ask/notify/inbox
+- `Live` tmux control
+- browser inspection and screenshots
+- partner notes and partner files
+- tools sync and version checks
+
+The full MCP tool surface is documented later in this README and through the MCP server itself.
 
 ## Prerequisites
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deadragdoll/tellymcp",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "TellyMCP - Telegram Human-in-the-Loop MCP Server",
   "main": "dist/services/features/telegram-mcp/runtime.service.js",
   "bin": {