# TG Analytics MCP — аналитика Telegram-каналов как инструмент для LLM-агента

**MCP-сервер**, который даёт Claude (Desktop / Code) и любому MCP-клиенту инструменты для оценки
Telegram-каналов перед закупом рекламы. Агент сам вызывает их, когда ты просишь «проверь канал».

[MCP (Model Context Protocol)](https://modelcontextprotocol.io) — открытый стандарт, по которому
LLM-агенты получают доступ к внешним инструментам. Здесь показано, как обернуть свою логику в MCP-tool.

---

## Инструменты (MCP tools)
| Tool | Что делает |
|---|---|
| `check_channel(channel, price?, max_cpm?)` | охват (медиана просмотров), %живого охвата, CPM, вердикт 🟢/🟡/🔴 |
| `compare_channels(channels[], price?)` | сравнить несколько каналов, отсортировать по охвату |

Данные — с публичной страницы `t.me/s/<канал>`, **без токенов**.

## Зачем это как MCP
Вместо отдельного приложения логика становится **инструментом прямо в твоём AI-агенте**:
просишь Claude «сравни вот эти 3 канала под закуп за 5000» — он сам дёргает `compare_channels`
и отвечает разбором. Это и есть «личные AI-агенты под свои задачи».

## Запуск и подключение
```bash
python -m venv .venv && .venv\Scripts\activate
pip install -r requirements.txt

# 1) Отладка в MCP Inspector
mcp dev app/server.py

# 2) Установить в Claude Desktop одной командой
mcp install app/server.py --name tg-analytics
```

Либо вручную в `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "tg-analytics": {
      "command": "python",
      "args": ["-m", "app.server"],
      "cwd": "/абсолютный/путь/к/03-tg-analytics-mcp"
    }
  }
}
```

## Пример запроса к агенту (после подключения)
```
Ты: проверь @durov, цена поста 50000
Claude → вызывает check_channel → "🟢 брать: охват 47% от подписчиков, CPM 9 ₽"
```

## Стек
Python · **MCP Python SDK (FastMCP)** · requests + selectolax (скрапинг)

## Архитектура
```
LLM-агент (Claude) ⇄ [MCP server, stdio] ── tools ──► checker (scrape t.me/s/ → анализ → вердикт)
```

## Ограничения
- Публичный превью ТГ без лайков/комментов → главный сигнал это охват и %охвата.
- Вердикт вероятностный, пороги калибруются.

## Лицензия
MIT