Skip to content

README-ru.md

Latest commit

 

History

History
465 lines (325 loc) · 16.1 KB

README-ru.md

File metadata and controls

465 lines (325 loc) · 16.1 KB
Raw

TellyMCP

Telegram control plane для MCP-подключённых coding agents

English · Русский · Standalone · Standalone RU

npm version node license gateway--first telegram webhook

@deadragdoll/tellymcp — Telegram control plane для MCP-подключённых coding agents.

Текущая модель — gateway-first:

  • один gateway держит Telegram-бота, web app, проекты и live registry консолей
  • один или несколько agent-процессов подключаются к этому gateway
  • каждая запущенная консоль агента — отдельный routable target
  • пользователь работает через gateway-бота, а не через pairing отдельных сессий

Что умеет

  • даёт MCP tools для human-in-the-loop через Telegram
  • позволяет одной консоли агента ставить задачу другой консоли
  • позволяет MCP chat-клиенту получать проектный текст, изображения и артефакты выбранной консоли
  • хранит structured xchange records в .mcp-xchange
  • поддерживает browser automation через Playwright
  • умеет attach к уже открытому Firefox или Chrome через bundled local extensions
  • умеет писать structured browser bundles в .mcp-xchange/web/... с HTML, network и console артефактами
  • умеет инжектить helper scripts в attached tabs или Playwright pages через browser_inject_script
  • отдаёт Telegram Mini App / Live View с gateway
  • поддерживает polling и webhook на gateway
  • поставляет встроенный Codex plugin со skills под типовые workflow

Текущая модель

Схема:

Telegram user
    |
Telegram bot + WebApp
    |
Gateway
    |
    +-- Agent console A
    +-- Agent console B
    +-- Agent console C

Следствия:

  • обычный flow больше не использует pairing
  • /menu в gateway-боте показывает live-консоли напрямую
  • межсессионная маршрутизация идёт по canonical session_id = client_uuid:local_session_id
  • несвязанные задачи читаются через structured xchange records, а не через старые inbox APIs

Основные поверхности

Для человека:

  • telegram_message
  • notify_telegram
  • browser_screenshot(send_to_telegram=true)
  • get_file для возврата скриншотов и артефактов в MCP chat-клиент

Для agent-to-agent:

  • partner_note
  • send_partner_note
  • send_partner_file
  • list_gateway_sessions

Для диагностики:

  • get_runtime_diagnostics для безопасной end-to-end проверки gateway/client

Для браузера:

  • browser_open
  • browser_click
  • browser_fill
  • browser_inject_script
  • browser_press
  • browser_wait_for
  • browser_screenshot
  • browser_recording_start
  • browser_recording_stop
  • browser_recording_status

Файлы:

  • get_file_list(source=..., limit=...)
  • get_file(file_path=..., type="url")
  • get_file(file_path=..., type="image")
  • get_file(file_path=..., type="text")
  • get_file(file_path=..., type="base64")
  • get_file(selector="latest_screenshot")

Синхронизация инструкций:

  • refresh_tools_markdown
  • .mcpsession.json хранит startup identity и последний известный tools hash

Требования

  • Node.js >= 24
  • Python 3, make и C/C++ toolchain на Linux для локальной сборки native addon node-pty; npm lifecycle scripts должны быть включены
  • Redis только для режимов gateway и both; клиент Redis не использует
  • PostgreSQL для gateway mode
  • опционально RabbitMQ для durable gateway fanout
  • Playwright browser binaries, если нужны browser tools

Установка

На Debian/Ubuntu сначала установи зависимости для сборки native PTY:

sudo apt install -y python3 make g++
npm config set ignore-scripts false
npm install -g @deadragdoll/tellymcp --foreground-scripts

Опубликованная зависимость node-pty не содержит готового Linux ARM64 binary, поэтому install lifecycle собирает pty.node локально. Если пакет ранее установился без него, восстанови глобальную установку:

npm uninstall -g @deadragdoll/tellymcp
npm install -g @deadragdoll/tellymcp@latest --foreground-scripts
tellymcp doctor --env <file>

tellymcp --help и setup-команды не загружают native PTY. Runtime проверяет модуль перед запуском и вместо сырого stack trace выводит те же инструкции по восстановлению.

Если нужны browser tools:

tellymcp browser install

Если нужны attach extensions для существующего Firefox/Chrome:

tellymcp extension firefox
tellymcp extension chrome

Команда выгружает готовые unpacked bundles в текущий каталог:

  • ./tellymcp-firefox-attach
  • ./tellymcp-chrome-attach

Если используешь Codex:

tellymcp codex-plugin install

Быстрый старт

1. Gateway

Создай workspace и env:

mkdir -p ~/telly-gateway
cd ~/telly-gateway
tellymcp configure

Команда открывает защищённую одноразовым токеном локальную страницу на 127.0.0.1. Выбери в wizard роль Gateway, заполни и проверь настройки, затем сохрани .env-gateway обычным browser download. Перед использованием выставь файлу права 0600. tellymcp init gateway остаётся вариантом для ручного редактирования шаблона.

Публичный origin или API base вводится один раз. Wizard сам формирует gateway HTTP, WebSocket, Mini App, webhook, root-prefix и опциональные OAuth URL. На ключевых этапах доступны реальные проверки Telegram, Redis, PostgreSQL, gateway HTTP/WebSocket и опционального RabbitMQ.

Или возьми sample:

Минимально важные значения:

  • TELEGRAM_BOT_TOKEN
  • REDIS_HOST
  • DB_HOST
  • DB_USER
  • DB_PASSWORD
  • DB_NAME
  • GATEWAY_PUBLIC_URL
  • GATEWAY_WS_URL
  • GATEWAY_SCOPE_TOKEN
  • GATEWAY_AUTH_TOKEN

Запуск:

tellymcp run --env .env

2. Agent

Для каждой консоли лучше отдельный workspace:

mkdir -p ~/agent-a
cd ~/agent-a
tellymcp configure

Выбери в wizard роль Client. В форме есть подключение к gateway, identity консоли, terminal, browser, MCP и расширенные runtime-настройки. После валидации браузер скачает .env-client. Флаг --no-open выводит локальный URL без автоматического открытия браузера.

Для клиента тот же Public base URL автоматически формирует GATEWAY_PUBLIC_URL, GATEWAY_WS_URL и GATEWAY_WS_PATH.

Или используй sample:

Минимально важные значения:

  • GATEWAY_PUBLIC_URL
  • GATEWAY_WS_URL
  • GATEWAY_SCOPE_TOKEN
  • GATEWAY_AUTH_TOKEN (тот же transport-токен, который задан на gateway)
  • GATEWAY_USER_UUID, если консоль должна быть видна конкретному владельцу в gateway-боте

Рекомендуется:

  • по умолчанию используется встроенный PTY terminal runtime
  • на первом запуске явно задать TELLYMCP_SESSION_ID и TELLYMCP_SESSION_LABEL

Первый запуск:

tellymcp run --env .env -s NEW

После первого запуска .mcpsession.json хранит:

  • local_session_id
  • session_label
  • env_file
  • gateway_client_uuid

Runtime-состояние клиента локальное и не требует Redis. Сохранённый gateway_client_uuid обеспечивает стабильную идентичность после перезапуска.

Поэтому дальше в том же каталоге обычно достаточно:

tellymcp run

Webhook

Gateway умеет работать через Telegram webhook.

Если nginx уже проксирует весь /api/ на standalone HTTP listener gateway, отдельный location для webhook не обязателен. Route такой:

  • /api/telegram/webhook

Нужные env:

TELEGRAM_WEBHOOK_ENABLED=true
TELEGRAM_WEBHOOK_PATH=/telegram/webhook
TELEGRAM_WEBHOOK_PUBLIC_URL=https://your-domain.example/api/telegram/webhook
TELEGRAM_WEBHOOK_SECRET=change_me_webhook_secret

Когда webhook mode включён:

  • gateway вызывает setWebhook(...) на старте
  • polling не запускается
  • секрет проверяется через x-telegram-bot-api-secret-token

MCP

Local HTTP

В client mode локальный MCP endpoint обычно:

http://127.0.0.1:8787/mcp

Helper:

tellymcp mcp --url http://127.0.0.1:8787/mcp

Для Codex и похожих агентов используй MCP HTTP endpoint, который поднимает tellymcp run.

Codex Plugin

Пакет включает локальный Codex plugin со skills для:

  • ответов человеку в Telegram
  • partner_note
  • browser screenshot задач
  • artifact-return flow

Команды:

tellymcp codex-plugin status
tellymcp codex-plugin install

Installer:

  • копирует bundled plugin в managed local Codex path
  • обновляет personal marketplace manifest
  • ставит или обновляет plugin, если найден Codex CLI

Browser Workflow

Browser tools используют Playwright Chromium.

Предпочтительный путь:

  1. browser_open
  2. browser_screenshot
  3. дальше либо:
    • send_to_telegram=true для ответа человеку
    • send_partner_file для возврата артефакта другой консоли

Если browser runtime не установлен:

tellymcp browser install

Не подменяй browser workflow ad hoc shell-командами с Playwright, кроме случаев, когда ты отлаживаешь сам browser runtime.

Terminal Blockers

Gateway prompt scanner теперь живёт от live-client lifecycle:

  • на старте gateway scanner только armed, но не крутится вхолостую
  • реальная работа начинается после подключения live client
  • relay console materialization идёт из hello и owner-route hydration, а не из /menu
  • детект работает по хвосту захваченного terminal buffer

Основная эвристика blocker-а:

  • подряд идущие numbered choices: 1., 2., 3.
  • рядом есть action hints вроде press, input, choose, enter, esc, yes, no
  • в Telegram notice попадают и 1-2 строки контекста выше menu block

Когда blocker найден, gateway может отправить inline-кнопки:

  • 1..N
  • Enter
  • Esc

Эти кнопки отправляют в консоль ровно цифру или terminal action. Навигация маркером не используется.

Операционные заметки:

  • одинаковый blocker fingerprint не перевысылается повторно
  • relay capture miss для offline agent считается debug-only шумом
  • Storage и Screenshots на gateway теперь relay-aware и читают metadata через gateway routes, а не через filesystem самого gateway

Collaboration

Проекты:

  • live presence консолей идёт из gateway live registry
  • membership проекта хранится отдельно от live presence
  • один client может иметь несколько live консолей одновременно
  • console participation в проекте хранится отдельно

Ожидаемое поведение агента:

  • target резолвится через list_gateway_sessions
  • входящая работа читается через list_xchange_records и get_xchange_record
  • реальные файлы возвращаются через send_partner_file
  • mark_xchange_record_read вызывается только после успешного outbound reply

Файлы конфигурации

Канонические стартовые точки:

Bundled templates:

Samples уже вычищены под текущий runtime:

  • убраны старые inbox-only настройки
  • убраны obsolete pairing-oriented тексты
  • убраны неиспользуемые секреты вроде SESSION_SECRET
  • убран неиспользуемый APP_NAME
  • неоднозначные старые имена заменены на TERMINAL_*, GATEWAY_SCOPE_TOKEN, TELEGRAM_REQUEST_MODE, DB_SCHEMA и LOGFEED_ENABLED

Операционные команды

Проверка окружения:

tellymcp doctor --env .env

Разрушительная очистка local+gateway state:

tellymcp system-prune --env .env --yes

Миграция старого env в текущий ролевой контракт:

tellymcp migrate-env ./old.env > ./.migrated-env

Fallback на старую схему отсутствует. Если найдены legacy-ключи, запуск останавливается и выводит команду миграции.

Карта документации

Статус

Этот README описывает текущую gateway-first модель.

Legacy concepts, которые не стоит использовать в новых setup:

  • pairing codes
  • session inbox APIs
  • Local partner menu
  • linked-session flows вне partner_note / project collaboration