@deadragdoll/tellymcp 0.0.1

package/STANDALONE-ru.md

@@ -0,0 +1,266 @@
+# TellyMCP Standalone Guide
+
+[English](STANDALONE.md) | [Русский](STANDALONE-ru.md)
+
+Это пошаговая инструкция для самого простого сценария TellyMCP:
+
+- одна машина
+- один Telegram-бот
+- без shared gateway
+- без Postgres
+- без RabbitMQ
+
+Именно с этого режима лучше начинать.
+
+## Что понадобится
+
+Перед установкой нужны:
+
+1. Node.js 24+
+2. `tmux`
+3. Redis
+4. Telegram bot token из BotFather
+
+Зачем это нужно:
+
+- Node.js запускает сервис
+- `tmux` нужен для Live View, `nudge` и полноценной интерактивной работы
+- Redis хранит состояние сессий, inbox, pairing и меню
+- Telegram bot token связывает сервис с Telegram
+
+## Шаг 1. Установить зависимости
+
+Пример для Ubuntu / Debian:
+
+```bash
+sudo apt-get update
+sudo apt-get install -y tmux redis-server
+node -v
+tmux -V
+redis-cli ping
+```
+
+Ожидаемый результат:
+
+- Node версии `24.x` или новее
+- `tmux -V` показывает версию
+- `redis-cli ping` возвращает `PONG`
+
+## Шаг 2. Создать Telegram-бота
+
+В Telegram:
+
+1. Открой BotFather
+2. Выполни `/newbot`
+3. Выбери имя бота
+4. Выбери username бота
+5. Сохрани токен
+
+Тебе понадобятся:
+
+- `TELEGRAM_BOT_TOKEN`
+- `TELEGRAM_BOT_USERNAME`
+
+## Шаг 3. Установить TellyMCP
+
+```bash
+npm install -g @deadragdoll/tellymcp
+```
+
+Проверка CLI:
+
+```bash
+tellymcp help
+```
+
+## Шаг 4. Запустить агента в tmux
+
+Это важный момент.
+
+Для полноценной работы агент лучше запускать внутри `tmux`, а не в обычной shell-сессии.
+
+Создать tmux-сессию:
+
+```bash
+tmux new -s backend
+```
+
+Хорошие имена:
+
+- `backend`
+- `frontend`
+- `review`
+- `ops`
+
+Почему имя tmux-сессии важно:
+
+- по нему проще различать агентов
+- оно улучшает диагностику
+- в Telegram и Live View проще понимать, какая сессия открыта
+
+Если нужно выйти:
+
+```bash
+tmux detach
+```
+
+И вернуться:
+
+```bash
+tmux attach -t backend
+```
+
+## Шаг 5. Создать standalone-конфиг
+
+В рабочей директории:
+
+```bash
+tellymcp init client
+```
+
+Команда создаст локальный `.env`.
+
+## Шаг 6. Заполнить `.env`
+
+Минимум:
+
+```env
+TELEGRAM_BOT_TOKEN=...
+TELEGRAM_BOT_USERNAME=@your_bot
+REDIS_HOST=127.0.0.1
+REDIS_PORT=6379
+REDIS_DB=1
+MCP_HTTP_HOST=127.0.0.1
+MCP_HTTP_PORT=8787
+MCP_HTTP_PATH=/mcp
+MCP_HTTP_BEARER_TOKEN=choose-a-secret-token
+DISTRIBUTED_MODE=client
+WEBAPP_ENABLED=true
+```
+
+Если tmux использует нестандартный socket:
+
+```env
+TMUX_SOCKET_PATH=/tmp/tmux-1000/default
+```
+
+## Шаг 7. Проверить конфиг
+
+```bash
+tellymcp doctor --env .env
+```
+
+В standalone `client` режиме он должен проверить:
+
+- `tmux`
+- `.env`
+- Redis
+- локальный MCP bind
+
+## Шаг 8. Запустить сервис
+
+```bash
+tellymcp run --env .env
+```
+
+Обычный standalone MCP endpoint:
+
+- `http://127.0.0.1:8787/mcp`
+
+## Шаг 9. Подключить MCP к агенту
+
+Чтобы получить готовый snippet:
+
+```bash
+tellymcp mcp --help
+```
+
+Типичный локальный endpoint:
+
+- `http://127.0.0.1:8787/mcp`
+
+Если используешь bearer auth, агент должен подключаться с тем же токеном, что и в `.env`.
+
+## Шаг 10. Привязать агента к Telegram
+
+После подключения MCP можно просто написать агенту:
+
+- `привяжись к Telegram`
+- `подключись к Telegram`
+- `свяжи эту сессию с Telegram`
+- `создай код привязки к Telegram`
+
+Ожидаемый flow:
+
+1. агент вызывает `create_session_pair_code`
+2. отдаёт короткий код
+3. ты отправляешь боту `/start <code>` или `/link <code>`
+4. после успеха открываешь `/menu`
+
+Если агент работает внутри `tmux`, ему желательно передать:
+
+- `cwd`
+- имя tmux-сессии
+- tmux window/pane атрибуты
+
+Тогда `Live` и `nudge` заработают сразу.
+
+## Шаг 11. Что будет после pairing
+
+После привязки Telegram можно использовать для:
+
+- inbox
+- вопросов к человеку
+- local partner collaboration
+- переключения сессий
+- просмотра storage
+- Live View
+
+Агент сможет:
+
+- вызывать `ask_user_telegram`
+- читать несвязанные входящие сообщения
+- отправлять note и файлы
+- получать tmux `nudge`, когда появляется новая работа
+
+## Что работает без tmux
+
+TellyMCP можно запустить и без `tmux`, но это урезанный режим.
+
+Не будет:
+
+- Live View
+- tmux `nudge`
+- прямого управления из Telegram Mini App
+
+Такой режим стоит использовать только если тебя устраивает пассивная работа.
+
+## Troubleshooting
+
+Если `doctor` ругается:
+
+- проверь, что Redis запущен
+- проверь, что установлен `tmux`
+- проверь правильность bot token
+- проверь, что bearer token совпадает с MCP-конфигом агента
+
+Если pairing работает, а Live View нет:
+
+- убедись, что агент действительно запущен внутри `tmux`
+- убедись, что у tmux-сессии есть стабильное имя
+- при необходимости задай `TMUX_SOCKET_PATH`
+
+Если агент не может подключиться к MCP:
+
+- проверь, что `tellymcp run --env .env` действительно запущен
+- проверь endpoint `http://127.0.0.1:8787/mcp`
+- проверь bearer token
+
+## Следующий шаг
+
+Когда standalone уже работает, дальше можно переходить к:
+
+- `gateway`
+- или `both`
+
+Это нужно только если нужен `Collab` между машинами.

package/STANDALONE.md

@@ -0,0 +1,266 @@
+# TellyMCP Standalone Guide
+
+[English](STANDALONE.md) | [Русский](STANDALONE-ru.md)
+
+This guide explains the simplest TellyMCP setup:
+
+- one machine
+- one Telegram bot
+- no shared gateway
+- no Postgres
+- no RabbitMQ
+
+This is the best way to start.
+
+## What you need
+
+Before installation, make sure you have:
+
+1. Node.js 24+
+2. `tmux`
+3. Redis
+4. a Telegram bot token from BotFather
+
+Why these matter:
+
+- Node.js runs the service
+- `tmux` enables Live View, nudges, and direct Telegram-side interaction
+- Redis stores session state, inbox, pairing state, and menu state
+- Telegram bot token connects your bot to Telegram
+
+## Step 1. Install prerequisites
+
+Ubuntu / Debian example:
+
+```bash
+sudo apt-get update
+sudo apt-get install -y tmux redis-server
+node -v
+tmux -V
+redis-cli ping
+```
+
+Expected:
+
+- Node version is `24.x` or newer
+- `tmux -V` prints a version
+- `redis-cli ping` returns `PONG`
+
+## Step 2. Create a Telegram bot
+
+In Telegram:
+
+1. Open BotFather
+2. Run `/newbot`
+3. Choose a bot name
+4. Choose a bot username
+5. Save the token
+
+You will need:
+
+- `TELEGRAM_BOT_TOKEN`
+- `TELEGRAM_BOT_USERNAME`
+
+## Step 3. Install TellyMCP
+
+```bash
+npm install -g @deadragdoll/tellymcp
+```
+
+Check that the CLI works:
+
+```bash
+tellymcp help
+```
+
+## Step 4. Start a tmux session for the agent
+
+This part is important.
+
+Run the agent inside `tmux`, not in a plain shell, if you want the full experience.
+
+Create a session:
+
+```bash
+tmux new -s backend
+```
+
+Good session names:
+
+- `backend`
+- `frontend`
+- `review`
+- `ops`
+
+Why the session name matters:
+
+- it helps identify the agent in practice
+- it improves diagnostics
+- it makes Telegram and Live View easier to understand
+
+If you later detach:
+
+```bash
+tmux detach
+```
+
+and return:
+
+```bash
+tmux attach -t backend
+```
+
+## Step 5. Create the standalone config
+
+Inside the workspace where you want to run TellyMCP:
+
+```bash
+tellymcp init client
+```
+
+This creates a local `.env`.
+
+## Step 6. Fill `.env`
+
+At minimum, set:
+
+```env
+TELEGRAM_BOT_TOKEN=...
+TELEGRAM_BOT_USERNAME=@your_bot
+REDIS_HOST=127.0.0.1
+REDIS_PORT=6379
+REDIS_DB=1
+MCP_HTTP_HOST=127.0.0.1
+MCP_HTTP_PORT=8787
+MCP_HTTP_PATH=/mcp
+MCP_HTTP_BEARER_TOKEN=choose-a-secret-token
+DISTRIBUTED_MODE=client
+WEBAPP_ENABLED=true
+```
+
+If your tmux server uses a non-default socket:
+
+```env
+TMUX_SOCKET_PATH=/tmp/tmux-1000/default
+```
+
+## Step 7. Validate the setup
+
+```bash
+tellymcp doctor --env .env
+```
+
+In standalone `client` mode it should verify:
+
+- `tmux`
+- `.env`
+- Redis
+- local MCP bind
+
+## Step 8. Run the service
+
+```bash
+tellymcp run --env .env
+```
+
+Standalone MCP endpoint is normally:
+
+- `http://127.0.0.1:8787/mcp`
+
+## Step 9. Add MCP to your agent
+
+To get a ready-to-paste config snippet:
+
+```bash
+tellymcp mcp --help
+```
+
+Typical local MCP config target:
+
+- `http://127.0.0.1:8787/mcp`
+
+If you use bearer auth, configure your agent with the same token from `.env`.
+
+## Step 10. Pair the agent with Telegram
+
+Once MCP is connected, tell the agent something like:
+
+- `pair with Telegram`
+- `link to Telegram`
+- `connect this session to Telegram`
+- `create a Telegram pairing code`
+
+Expected flow:
+
+1. the agent calls `create_session_pair_code`
+2. it gives you a short code
+3. you send `/start <code>` or `/link <code>` to the bot
+4. after success, open `/menu`
+
+If the agent is running inside `tmux`, it should pass:
+
+- `cwd`
+- tmux session name
+- tmux window/pane attributes
+
+This lets Live View and tmux nudges work immediately.
+
+## Step 11. What you get after pairing
+
+After pairing, Telegram can be used for:
+
+- inbox messages
+- clarifying questions
+- local partner collaboration
+- session switching
+- storage inspection
+- Live View
+
+The agent can:
+
+- call `ask_user_telegram`
+- read unsolicited inbox messages
+- send notes and files
+- receive tmux nudges when new work arrives
+
+## What works without tmux
+
+TellyMCP can still run without `tmux`, but this is a reduced mode.
+
+You lose:
+
+- Live View
+- tmux nudges
+- direct Telegram Mini App controls
+
+Use this only if you accept a passive workflow.
+
+## Troubleshooting
+
+If `doctor` fails:
+
+- verify Redis is running
+- verify `tmux` is installed
+- verify the bot token is correct
+- verify your bearer token matches the MCP client config
+
+If pairing works but Live View does not:
+
+- make sure the agent is really inside `tmux`
+- make sure the tmux session has a stable name
+- if needed, set `TMUX_SOCKET_PATH`
+
+If the agent cannot connect to MCP:
+
+- confirm `tellymcp run --env .env` is running
+- confirm the endpoint is `http://127.0.0.1:8787/mcp`
+- confirm the bearer token matches
+
+## Next step
+
+After standalone is working, the next upgrade path is:
+
+- `gateway`
+- or `both`
+
+Use that only when you need cross-machine collaboration.