Skip to content

Latest commit

 

History

History
397 lines (328 loc) · 16.4 KB

mcp.md

File metadata and controls

397 lines (328 loc) · 16.4 KB

MCP-инструменты

MCP-сервер предоставляет 132 инструмента для интеграции с LLM.

Работает по двум протоколам:

  • stdio — стандартный MCP-транспорт для Claude и других LLM
  • HTTP — REST API на порту 3335

HTTP API

Базовый URL: http://<host>:3335

Эндпоинты

Метод Путь Описание
GET /health Проверка работоспособности
GET /tools Список всех инструментов
POST /tools/:name Вызов инструмента

Аутентификация

Если задана переменная MCP_HTTP_TOKEN, все запросы к /tools требуют Bearer-токен:

curl http://127.0.0.1:3335/tools \
  -H "Authorization: Bearer your-token"

Список инструментов

Сообщения (13)

Инструмент Описание
messages.send Отправить текстовое сообщение (текст или шаблон)
messages.edit Редактировать сообщение по внутреннему ID
messages.delete Удалить сообщение по внутреннему ID
messages.fetch Получить сообщения с фильтрацией
messages.delete_batch Массовое удаление до 100 сообщений (Bot API 7.0)
messages.forward_batch Массовая пересылка до 100 сообщений (Bot API 7.0)
messages.copy_batch Массовое копирование до 100 сообщений (Bot API 7.0)
messages.edit_caption Редактировать подпись к медиа-сообщению
messages.edit_markup Изменить inline-клавиатуру сообщения
messages.edit_media Заменить медиа в сообщении
messages.draft Отправить черновик сообщения (Bot API 9.3)
messages.edit_live_location Обновить живую геолокацию
messages.stop_live_location Остановить живую геолокацию

Медиа (15)

Инструмент Описание
media.send_photo Отправить фото (URL или file_id)
media.send_document Отправить документ/файл
media.send_video Отправить видео
media.send_animation Отправить GIF-анимацию
media.send_audio Отправить аудио с метаданными
media.send_voice Отправить голосовое сообщение
media.send_sticker Отправить стикер
media.send_media_group Отправить альбом (2-10 элементов)
media.get_file Получить file_path для скачивания
media.send_location Отправить геолокацию (живая с live_period)
media.send_venue Отправить место с названием и адресом
media.send_contact Отправить контакт (телефон + имя)
media.send_dice Отправить эмодзи-кубик
media.send_video_note Отправить видео-кружок
media.send_paid_media Отправить платный медиа-контент (Bot API 7.6)

Шаблоны и команды (5)

Инструмент Описание
templates.list Список Jinja2-шаблонов
templates.render Отрендерить шаблон с переменными
commands.create Создать набор команд для скоупа
commands.list Получить все наборы команд
commands.sync Синхронизировать с Telegram

Чаты и участники (18)

Инструмент Описание
chats.get Информация о чате
chats.member Статус участника чата
chats.list Список чатов из локальной БД
chats.alias Установить алиас для чата
chats.history История сообщений чата из БД
chats.set_title Установить название чата
chats.set_description Установить описание чата
chats.delete_photo Удалить фото чата
chats.leave Выйти из чата
chats.unpin_all Открепить все сообщения
chats.create_invite_link Создать пригласительную ссылку
chats.edit_invite_link Редактировать пригласительную ссылку
chats.revoke_invite_link Отозвать пригласительную ссылку
chats.export_invite_link Экспорт основной пригласительной ссылки
chats.create_subscription_invite_link Подписочная ссылка (Bot API 7.9)
chats.edit_subscription_invite_link Редактировать подписочную ссылку
callbacks.answer Ответить на нажатие inline-кнопки
callbacks.list Список полученных callback queries

Боты (7)

Инструмент Описание
bots.list Список зарегистрированных ботов
bots.register Зарегистрировать нового бота по токену
bots.default Получить или установить бота по умолчанию
bot.info Информация о боте (имя, username, фичи)
bots.set_profile_photo Установить фото профиля бота (Bot API 9.4)
bots.remove_profile_photo Удалить фото профиля бота (Bot API 9.4)
bots.user_profile_audios Аудио профиля пользователя (Bot API 9.4)

Вебхук (3)

Инструмент Описание
webhook.setup Настроить вебхук
webhook.info Текущая конфигурация вебхука
webhook.delete Удалить вебхук

Опросы, реакции и обновления (5)

Инструмент Описание
polls.send Создать опрос или викторину
polls.stop Остановить опрос и показать результаты
polls.list Получить список опросов
reactions.set Установить реакцию на сообщение
updates.fetch Получить входящие обновления

Чек-листы (2)

Инструмент Описание
checklists.send Отправить чек-лист с задачами (Bot API 9.1)
checklists.edit Редактировать существующий чек-лист

Stars, подарки и платежи (11)

Инструмент Описание
stars.balance Баланс звёзд бота (Bot API 9.1)
stars.invoice Создать счёт на оплату Stars
stars.refund Возврат Stars платежа
stars.transactions История транзакций Stars
stars.edit_subscription Редактировать Star-подписку (Bot API 8.0)
gifts.premium Подарить премиум-подписку (Bot API 9.3)
gifts.user Подарки пользователя (Bot API 9.3)
gifts.chat Подарки чата (Bot API 9.3)
gifts.send Отправить подарок (Bot API 8.0)
gifts.available Список доступных подарков (Bot API 8.0)
stories.repost Репост истории (Bot API 9.3)

Предсказания (7)

Инструмент Описание
predictions.create_event Создать событие для ставок (Polymarket-style)
predictions.place_bet Разместить ставку
predictions.resolve Разрешить событие и выплатить выигрыши
predictions.list Список событий
predictions.get Детали события с коэффициентами
predictions.user_bets Ставки пользователя
predictions.currencies Доступные валюты (XTR, AC, TON)

Баланс (4)

Инструмент Описание
balance.get Баланс пользователя
balance.deposit Пополнить баланс
balance.history История транзакций баланса
balance.top Топ пользователей по балансу

Форум-топики (6)

Инструмент Описание
forums.create Создать топик в форум-группе
forums.edit Редактировать имя/иконку топика
forums.close Закрыть топик
forums.reopen Повторно открыть топик
forums.delete Удалить топик со всеми сообщениями
forums.unpin_all Открепить все сообщения в топике

Истории (3)

Инструмент Описание
stories.post Опубликовать историю в канал (Bot API 9.0)
stories.edit Редактировать опубликованную историю
stories.delete Удалить историю

Предложенные посты (2)

Инструмент Описание
suggested_posts.approve Одобрить предложенный пост (Bot API 9.2)
suggested_posts.decline Отклонить предложенный пост (Bot API 9.2)

Календарь (20)

Инструмент Описание
calendar.create Создать календарь
calendar.list Список календарей
calendar.create_entry Создать запись (событие, задача, триггер, монитор)
calendar.list_entries Записи с фильтрацией по дате, статусу, тегам
calendar.get_entry Получить запись по ID
calendar.get_chain Цепочка связанных событий
calendar.update_entry Обновить запись
calendar.move_entry Переместить запись
calendar.set_status Установить статус
calendar.delete_entry Удалить запись
calendar.entry_history История изменений записи
calendar.bulk_create Массовое создание (до 100)
calendar.bulk_delete Массовое удаление (до 100)
calendar.upcoming Предстоящие события
calendar.get_due Записи, готовые к исполнению
calendar.fire Результат исполнения триггера
calendar.tick Тик монитора
calendar.budget Сводка бюджета за период
calendar.create_trigger Создать одноразовый триггер
calendar.create_monitor Создать периодический монитор

Иконки (1)

Инструмент Описание
icons.resolve Проверить доступность SVG-иконки (3300+ брендов)

Web-UI (10)

Инструмент Описание
webui.create_page Создать страницу (page/survey/prediction/calendar)
webui.list_pages Список страниц
webui.create_link Создать индивидуальную ссылку
webui.get_submissions Получить ответы формы
webui.create_prediction Создать страницу предсказания (shortcut)
webui.create_survey Создать опросник (shortcut)
webui.list_roles Список ролей (опционально user_id)
webui.grant_role Назначить роль {user_id, role, granted_by, note}
webui.revoke_role Отозвать роль {user_id, role}
webui.check_access Проверить доступ {user_id, slug} → {has_access, reasons}

Примеры вызовов

Отправка сообщения

curl -X POST http://127.0.0.1:3335/tools/messages.send \
  -H 'content-type: application/json' \
  -d '{
    "chat_id": -100123456,
    "text": "<b>Привет от LLM!</b>",
    "parse_mode": "HTML"
  }'

Отправка фото

curl -X POST http://127.0.0.1:3335/tools/media.send_photo \
  -H 'content-type: application/json' \
  -d '{
    "chat_id": -100123456,
    "photo": "https://example.com/img.jpg",
    "caption": "Описание"
  }'

Создание команд

curl -X POST http://127.0.0.1:3335/tools/commands.create \
  -H 'content-type: application/json' \
  -d '{
    "scope_type": "default",
    "commands": [
      {"command": "start", "description": "Начать"},
      {"command": "help", "description": "Справка"}
    ]
  }'

Стилизованные кнопки (Bot API 9.4)

curl -X POST http://127.0.0.1:3335/tools/messages.send \
  -H 'content-type: application/json' \
  -d '{
    "chat_id": -100123456,
    "text": "Выберите действие:",
    "reply_markup": {
      "inline_keyboard": [[
        {"text": "Подтвердить", "callback_data": "ok", "button_style": "success"},
        {"text": "Отменить", "callback_data": "cancel", "button_style": "danger"}
      ]]
    }
  }'

Создание опроса

curl -X POST http://127.0.0.1:3335/tools/polls.send \
  -H 'content-type: application/json' \
  -d '{
    "chat_id": -100123456,
    "question": "Какой язык программирования вы предпочитаете?",
    "options": ["Python", "JavaScript", "Go", "Rust"],
    "type": "quiz",
    "correct_option_id": 0,
    "explanation": "Python — самый популярный язык для ML и data science",
    "open_period": 300
  }'

Установка реакции

curl -X POST http://127.0.0.1:3335/tools/reactions.set \
  -H 'content-type: application/json' \
  -d '{
    "chat_id": -100123456,
    "message_id": 42,
    "reaction": [{"type": "emoji", "emoji": "👍"}],
    "is_big": false
  }'

Управление ботами

# Список ботов
curl http://127.0.0.1:3335/tools/bots.list

# Информация о текущем боте
curl -X POST http://127.0.0.1:3335/tools/bot.info \
  -H 'content-type: application/json' \
  -d '{}'

Подключение к Claude

В claude_desktop_config.json:

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["/path/to/Telegram-MCP/mcp/dist/index.js"],
      "env": {
        "TELEGRAM_API_URL": "http://localhost:8081",
        "MCP_HTTP_PORT": "3335"
      }
    }
  }
}

Или через Docker:

{
  "mcpServers": {
    "telegram": {
      "command": "docker",
      "args": ["exec", "-i", "tgmcp", "node", "dist/index.js"]
    }
  }
}

Архитектура

LLM (Claude)
    │ MCP stdio
    ▼
telegram-mcp / tgmcp (Node.js :3335)
    │ HTTP
    ▼
tgapi (FastAPI :8081)
    │ httpx
    ▼
Telegram Bot API

MCP-сервер — тонкий прокси. Он не содержит бизнес-логики: валидирует параметры (zod) и перенаправляет запросы к HTTP API.

По умолчанию MCP использует http://tgapi:8000. Если URL не задан явно и основной хост недоступен, на 1 релиз включён legacy retry на http://telegram-api:8000.