Channel-MCP

Автономный MCP-сервис для сбора постов из Telegram-каналов, нормализации метаданных, тегирования и семантического поиска с dual-backend (llm-mcp default, Ollama fallback).

✨ Возможности

📥 Ingest каналов

• Сбор постов из публичных каналов через https://t.me/s/<channel>.
• Плановые циклы загрузки + управляемый backfill истории.
• Нормализация текста, ссылок, реакций и служебных метаданных.

🧠 LLM-ready слой

• Теги на русском с канонизацией и алиасами (TAG_ALIASES_JSON).
• emoji_line и code_json для компактной структуризации сигнала.
• Векторный поиск по сообщениям на базе pgvector + backend strategy (llm_mcp|ollama).

🤖 Интеграция с Telegram

• Progress-уведомления в Telegram во время циклов worker.
• Режим маршрутизации через telegram-mcp (TELEGRAM_USE_MCP=1).
• Fallback на direct Telegram при TELEGRAM_MCP_FALLBACK_DIRECT=1.

🧱 Архитектура

┌─────────────────────┐      ┌──────────────────────┐
│ Telegram Channels   │─────▶│ chmcp (Node.js MCP)  │
│ public t.me/s       │      │ :3334                │
└─────────────────────┘      └──────────┬───────────┘
                                         │
                                 ┌───────▼────────┐
                                 │ worker (Python) │
                                 │ ingest/tags/vec │
                                 └───────┬────────┘
                                         │
                               ┌─────────▼─────────┐
                               │ chdb (PostgreSQL) │
                               │ :5434 + pgvector  │
                               └────────────────────┘

Компонент	Порт	Назначение
chmcp	3334	MCP HTTP/stdio инструменты
chdb	5434	Каналы, сообщения, теги, embeddings

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

cd channel-mcp
cp .env.example .env

docker compose -f compose.yml up -d --build

Проверка:

curl -fsS http://127.0.0.1:3334/health
curl -fsS http://127.0.0.1:3334/tools

🧰 MCP-инструменты (основные)

• channels.list — список каналов и статусы.
• messages.fetch — выборка сообщений по периоду/каналу/тегам.
• tags.top — агрегаты тегов за период.
• messages.search — семантический поиск по embeddings.

🔧 Ключевые переменные окружения

• CHANNEL_USERNAMES — каналы через запятую (без @).
• BACKFILL_ON_START, BACKFILL_DAYS, BACKFILL_MAX_PAGES — историческая подгрузка.
• OLLAMA_TAG_MODEL, OLLAMA_EMBED_MODEL — модели тегов/эмбеддингов.
• MCP_HTTP_TOKEN — токен защиты HTTP инструментов.
• TELEGRAM_USE_MCP, TELEGRAM_MCP_BASE_URL, TELEGRAM_MCP_BOT_ID, TELEGRAM_MCP_CHAT_ID.
• LLM_BACKEND=llm_mcp|ollama, LLM_MCP_BASE_URL, LLM_MCP_PROVIDER, LLM_BACKEND_FALLBACK_OLLAMA.

Если TELEGRAM_MCP_BASE_URL не задан, default route: http://tgapi:8000. На 1 релиз включён legacy retry на http://telegram-api:8000 с warning в логах.

📁 Структура

channel-mcp/
├── server/         # MCP server (Node.js)
├── worker/         # ingest/tagging/embeddings (Python)
├── db/init/        # SQL init
├── compose.yml
└── Dockerfile

🧭 Public Git Standards

• Версия в VERSION строго в формате YYYY.MM.x.
• Любое изменение фиксируется в CHANGELOG.md.
• Секреты не коммитятся: только .env.example, рабочие значения в локальном .env.
• Перед релизом обязательны docker compose config и smoke-проверка health/tools.

🔐 Ограничения

• Текущая реализация ориентирована на публичные каналы через t.me/s.
• Для приватных каналов потребуется отдельный MTProto-контур.