tgcloud — Telegram serverless bots

tgcloud-mcp — MCP-сервер для Telegram serverless bots

[CI] [npm] [skills.sh] [ghcr]

Учит AI-ассистента управлять serverless-ботами Telegram (core.telegram.org/bots/serverless): вы говорите ассистенту «создай бота», «задеплой», «покажи статус вебхука» — а он выполняет это через tgcloud CLI, не трогая терминал руками.

Работает с любым MCP-клиентом: opencode, Claude Code, Claude Desktop, Cursor, VS Code (Copilot), Windsurf, Zed.

Что умеет

14 инструментов — полный срез команд tgcloud CLI:

Плюс MCP-ресурсы tgcloud://docs/* — встроенная справка платформы (структура проекта, правила импортов, sdk/db, sdk/api, sdk/fetch, CLI).

Безопасность

• Деструктивное требует подтверждения. reset, push --force, webhook sync --drop-pending и применение миграций отказываются работать без confirm: true — ассистент сначала покажет, что будет изменено, и спросит согласие.
• Токены не утекают. Токен бота передаётся в CLI через stdin и маскируется во всех выводах — ассистент никогда его не видит в ответах инструментов.

Установка

Требуется Node.js 20+ (CLI платформы tgcloud требует 18+).

Из npm:

npm install -g tgcloud-mcptgcloud-mcp setup     # мастер: настройка MCP-клиента

В одну команду (macOS / Linux / WSL) — клон в ~/.tgcloud-mcp + мастер:

curl -fsSL https://raw.githubusercontent.com/sdamarketing/tgcloud_mcp/main/install.sh | bash

Docker:

docker run -i --rm ghcr.io/sdamarketing/tgcloud-mcp

Из исходников:

git clone https://github.com/sdamarketing/tgcloud_mcp.gitcd tgcloud_mcpnpm install && npm test    # build + smoke + e2e

Подробно (токены, клиенты, переменные, решение проблем) — docs/SETUP.md.

Подключение к агенту

Конфиг MCP-клиента (пример для opencode / Claude Code / Cursor — формат mcpServers одинаковый):

{  "mcpServers": {    "tgcloud": {      "command": "tgcloud-mcp"    }  }}

Переменные окружения (опционально):

Пример диалога

Вы: создай эхо-бота в ~/bots/echo
Агент: create_project → login_bot (спросит токен у @BotFather) → правит handlers/message.js → push → webhook_sync — бот жив.
Вы: напиши тест и проверь
Агент: run_handler с payload { chat: { id: 1 }, text: "hi" } — показывает вывод и логи.

Кукбук

📗 Serverless-бот с мини-аппом за вечер — пошаговый рецепт на примере реального бота «Дневник обучения»: скаффолд, токены, база и миграции, inline-кнопки, Mini App с endpoints. Самоснятые форматы CLI и грабли включены.

Скилл для агентов

В репозитории лежит скилл skills/tgcloud — процедурные знания для агента: структура проекта, правила импортов, рецепты (create → login → run → push), guardrails платформы. Установка во все обнаруженные агенты:

npx skills add sdamarketing/tgcloud_mcp

Структура репозитория

src/├─ index.ts            # сервер, регистрация инструментов/ресурсов├─ config.ts           # env-конфиг├─ runner.ts           # запуск tgcloud CLI: spawn, таймауты, маскировка секретов├─ utils.ts            # runTool/result-хелперы, dangerTool (confirm-guard)└─ tools/              # lifecycle, sync, data, webhookresources/docs/        # справка платформы → MCP-ресурсыskills/tgcloud/        # скилл для AI-агентовscripts/smoke-test.mjs # stdio smoke-тест

Лицензия

MIT