Content Publisher

MCP-сервер для публикации контента и сбора метрик на социальных платформах. Реализует протокол MCP (Model Context Protocol).

Платформы

Платформа	Публикация	Метрики	Статус
Telegram	✅ Bot API (sendMessage / sendPhoto)	🚧 Заглушка (V2: Telethon)	Работает, протестировано
YouTube	🚧 Заглушка	🚧 Заглушка	План
Instagram	🚧 Заглушка	🚧 Заглушка	План

Установка

# Установка через uv
uv sync

# С тестовыми зависимостями
uv sync --group test

Настройка

Скопируйте .env.example в .env и укажите токен бота:

cp .env.example .env

# TELEGRAM
TELEGRAM_BOT_TOKEN="токен_от_BotFather"

Токен создаётся через @BotFather в Telegram.

Запуск

# stdio (для интеграции с MCP-хостами — Claude Desktop, Cline и др.)
uv run mcp-content-publisher

# SSE (для отладки и удалённого доступа)
uv run mcp-content-publisher --transport sse --host 127.0.0.1 --port 8001

Деплой на VPS (Docker)

Локальная сборка и проверка

# Сборка образа
docker build -t mcp-content-publisher .

# Запуск контейнера (порт только на localhost)
docker run -d --name mcp-content-publisher \
  -p 127.0.0.1:8001:8001 \
  --env-file .env \
  mcp-content-publisher

# Проверка healthcheck
docker ps

Через docker-compose

# На VPS: скопировать проект, создать .env
cp .env.example .env
# → вписать TELEGRAM_BOT_TOKEN

# Сборка и запуск
docker compose up -d --build

# Логи
docker compose logs -f

# Остановка
docker compose down

Если VPS не достаёт до Telegram (прокси)

Симптом: publish_post возвращает HTTP request failed: (пустая ошибка), хотя остальной интернет с сервера работает. Часто это маршрутизация провайдера к подсетям Telegram, а не Docker. Быстрая проверка с хоста (таймаут → прокси нужен):

curl -s -o /dev/null -w "%{http_code}\n" https://api.telegram.org/bot<TOKEN>/getMe

Решение — направить исходящий HTTPS контейнера через прокси (должен принимать HTTP CONNECT или SOCKS5). Добавьте в .env:

HTTPS_PROXY="http://user:pass@proxy_host:port"
HTTP_PROXY="http://user:pass@proxy_host:port"
NO_PROXY="127.0.0.1,localhost"

NO_PROXY=127.0.0.1,localhost обязателен — иначе healthcheck (SSE на localhost) тоже уйдёт через прокси. Публикация медиа (multipart → Bot API) идёт тем же путём — прокси покрывает и её.

Пересоздать контейнер, чтобы применить .env:

docker compose up -d --force-recreate

Проверка изнутри контейнера (ожидается 200):

docker exec mcp-content-publisher python -c \
  "import urllib.request,os; r=urllib.request.urlopen('https://api.telegram.org/bot'+os.environ['TELEGRAM_BOT_TOKEN']+'/getMe', timeout=15); print(r.status)"

Подключение MCP-клиента (через SSH-туннель)

Безопасность: сервер не имеет аутентификации, поэтому не должен быть доступен снаружи. В Docker-конфиге порт проброшен только на 127.0.0.1, а сервер слушает только localhost. Доступ — исключительно через SSH-туннель.

На локальной машине поднимите туннель до VPS:

ssh -L 8001:127.0.0.1:8001 root@<IP-VPS>

После этого сервер доступен локально:

http://127.0.0.1:8001/sse

Пример конфигурации для Claude Desktop / Cline:

{
  "mcpServers": {
    "content-publisher": {
      "transport": "sse",
      "url": "http://127.0.0.1:8001/sse"
    }
  }
}

Внешний доступ (не рекомендуется)

Если всё же нужно открыть сервер наружу (например, за reverse-proxy с basic-auth), потребуется:

1. Пробросить порт на все интерфейсы в docker-compose.yml:

   ports:
     - "8001:8001"
   

2. Разрешить внешний Host-заголовок в .env (MCP SDK блокирует незнакомые Host заголовки кодом 421 — защита от DNS-rebinding):

   MCP_ALLOWED_HOSTS="<IP-или-домен>:*"
   

   • Несколько хостов — через запятую: "5.129.207.137:*,mcp.example.com:*"
   • MCP_ALLOWED_HOSTS="*" — отключить защиту (любой Host)
   • Не задано — только localhost (по умолчанию)

127.0.0.1, localhost, [::1] разрешены всегда (нужны для healthcheck).

Инструменты MCP

publish_post

Опубликовать пост на указанной платформе.

Параметры:

• platform (str): telegram | youtube | instagram
• text (str): Текст поста. Поддерживает HTML-разметку (<b>, <i>, <code>, <a href="...">)
• channel (str): Канал для публикации — @username, chat ID или invite link
• media_urls (list[str], optional): изображение/видео — URL (https://…), локальный путь (/app/output/cover.png) или file:// URL
• schedule_at (str, optional): Время публикации в ISO-8601

Пример:

{
  "platform": "telegram",
  "text": "<b>Привет!</b> Это тестовый пост из MCP сервера",
  "channel": "-1001234567890"
}

Ответ:

{
  "post_id": "42",
  "status": "published",
  "url": "https://t.me/channel/42",
  "error": null
}

Медиа (фото): если передать в media_urls локальный путь или file:// URL — файл загружается в Telegram через multipart (sendPhoto с files), внешние URL и публичный хостинг не нужны. Это важно на серверах, где Telegram заблокирован (см. секцию про прокси) и для локально-генерируемых обложек. HTTP(S)-URL и file_id по-прежнему передаются как есть.

get_metrics

Получить метрики опубликованного поста.

Параметры:

• platform (str): Платформа
• post_id (str): ID поста на платформе

Ответ:

{
  "post_id": "42",
  "platform": "telegram",
  "views": 150,
  "reactions": 12,
  "reposts": 3,
  "comments": 2
}

Примечание: Telegram Bot API не отдаёт реальные просмотры/реакции. В MVP возвращаются mock-данные. В V2 планируется Telethon (MTProto) для реальных метрик.

get_channel_stats

Получить общую статистику канала.

Параметры:

• platform (str): Платформа
• channel (str): Имя/ID канала

Ответ:

{
  "platform": "telegram",
  "channel": "@channel",
  "subscribers": 1000,
  "posts_this_week": 5,
  "avg_views": 200
}

Форматирование текста

Telegram провайдер автоматически определяет режим разметки:

• HTML — если в тексте есть HTML-теги (<b>, <i>, <code>, <a>)
• HTML (по умолчанию) — для обычного текста (не требует экранирования)

Поддерживаемые HTML-теги в Telegram: <b>, <i>, <u>, <s>, <code>, <pre>, <a href="...">

Тестирование

# Запуск всех тестов
uv run pytest tests/ -v

# Только unit-тесты
uv run pytest tests/test_publish_server.py -v

# Только интеграционные тесты (MCP протокол)
uv run pytest tests/test_mcp_server_integration.py -v

Что тестируется

• Модели — Pydantic-схемы (PublishContent, PublishResult, PostMetrics, ChannelStats)
• Провайдеры — Telegram (токен, публикация, метрики), YouTube/Instagram (mock)
• Реестр провайдеров — синглтон, неизвестные платформы
• MCP сервер — регистрация инструментов, вызов через MCP протокол

Структура проекта

mcp-content-publisher/
├── src/mcp_content_publisher/
│   ├── server.py          # MCP сервер (точка входа)
│   ├── models.py          # Pydantic-схемы
│   └── providers/
│       ├── base.py        # Базовый класс PublishProvider
│       ├── telegram.py    # Telegram Bot API
│       ├── youtube.py     # YouTube (заглушка)
│       └── instagram.py   # Instagram (заглушка)
├── tests/
│   ├── test_server.py              # Тесты MCP сервера
│   ├── test_publish_server.py      # Тесты провайдеров и моделей
│   └── test_mcp_server_integration.py  # Интеграционные тесты
├── .env.example
└── pyproject.toml

Разработка

# Установка с dev-зависимостями
uv sync --group test

# Запуск тестов
uv run pytest

# Проверка типов
uv run mypy src/