MCP Habr

Keyless MCP-сервер для чтения и анализа Хабра без авторизации. Личный инструмент, который даёт агенту доступ к статьям и к структуре обсуждений: топ-комментарии, дерево вложенности и сводка дискуссии с выявлением спорных веток.

📑 Содержание

• Возможности
• Быстрый старт
• Стек
• Инструменты
• Структура
• Архитектура
• Команды
• Автор
• Лицензия

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

• Доступ к контенту Хабра в режиме чтения через публичный API kek/v2 без авторизации
• Тело статьи в чистом Markdown, комментарии в JSON
• Анализ дискуссий: топ-комментарии по рейтингу, полное дерево вложенности, сводка с топ-заплюсованными и самыми горячими ветками (спорами)
• Информирование о полноте: везде, где данные режутся, в ответе поля returned/total/has_more/next_offset/filtered_out — агент видит, что получил не всё, и дозапрашивает
• Экономия контекста: по умолчанию отдаётся отфильтрованное (топ по рейтингу), сырой дамп — только по явному limit/offset
• Поиск статей и хабов, ленты и топ по рейтингу (хаба или всего Хабра), свежая лента через RSS, профили пользователей

⚡ Быстрый старт

Регистрация сервера в Claude Code:

claude mcp add habr -s user -- uvx --from st-mcp-habr --index https://forgejo.emptyvessel.ru/api/packages/st/pypi/simple st-mcp-habr

Подключение к opencode — секция mcp в opencode.json:

{
  "mcp": {
    "habr": {
      "type": "local",
      "command": [
        "uvx",
        "--from",
        "st-mcp-habr",
        "--index",
        "https://forgejo.emptyvessel.ru/api/packages/st/pypi/simple",
        "st-mcp-habr",
      ],
      "enabled": true,
    },
  },
}

uvx скачает пакет из forgejo registry. В Claude Code инструменты доступны как mcp__habr__*, в opencode — habr_*. Авторизация не требуется.

🛠️ Стек

Технология	Версия	Назначение
Python	3.13+	Язык разработки
mcp[cli]	1.27.2	FastMCP, транспорт stdio
httpx	0.28.1	HTTP-клиент к kek/v2 и RSS
markdownify	1.2.2	Конвертация HTML в Markdown

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

Инструмент	Назначение
search_articles	Поиск статей по ключевым словам, опционально в хабе
hub_articles	Лента хаба по сортировке (top/new) за период
feed_fresh	Свежая лента (RSS): только что вышедшие статьи
top_articles	Лучшие статьи за период по рейтингу — топ по всему Хабру
top_discussed	Самые обсуждаемые статьи — вход в анализ дискуссий
get_article	Полная статья: тело в Markdown и метаданные
get_top_comments	Топ комментариев по рейтингу с информированием о полноте
get_comment_tree	Дерево вложенности (ветка или вся дискуссия)
get_discussion_summary	Сводка обсуждения: топ-заплюсованные и горячие ветки
get_hub	Инфо о хабе: описание, подписчики, рейтинг
search_hubs	Поиск хабов по теме
get_user	Профиль: карма, рейтинг, последние статьи и комментарии

📁 Структура

mcp.habr/
├── src/st_mcp_habr/
│   ├── main.py          Точка входа: запуск сервера
│   ├── server.py        FastMCP и регистрация инструментов
│   ├── client.py        HabrClient (httpx) и обработка ошибок
│   ├── config.py        Чтение настроек из окружения
│   ├── format.py        Форматтеры статей и комментариев, HTML→Markdown
│   ├── tools.py         Поиск, ленты, чтение статьи
│   ├── discussion.py    Ядро: топ-комментарии, дерево, сводка дискуссии
│   └── catalog.py       Хабы и пользователи
├── scripts/
│   └── check.py         E2E-прогон инструментов через MCP-клиент
├── .env.example
├── Makefile
└── pyproject.toml

🏗️ Архитектура

Сервер читает контентную модель Хабра через kek/v2. Сущности связаны так:

Поток ─────► Хаб ─────► Публикация ─────► Комментарии
                       (статья │ новость)
                              ▲
                              │
                       Автор │ Компания

• Поток — крупная надкатегория Хабра (Разработка, Администрирование, Дизайн, Менеджмент, Научпоп), объединяющая хабы.
• Хаб — тематическая рубрика (python, infosecurity), к которой привязываются публикации; единица подписки и навигации.
• Публикация — общий контейнер материала с заголовком и телом; обиходно зовётся «постом».
• Статья — полноценный материал (туториал, разбор, обзор, перевод) с телом, хабами, тегами и рейтингом.
• Новость — короткое сообщение о событии в IT со своей лентой; в топе по рейтингу отсекается флагом include_news.
• Автор — аккаунт-человек со своей кармой, рейтингом, статьями и комментариями.
• Компания — корпоративный аккаунт-организация, чьи публикации помечены флагом корпоративности.
• Комментарии — дерево обсуждения под публикацией, ядро анализа в этом сервере.

🔧 Команды

make install      Установка зависимостей
make e2e          Прогон инструментов через MCP-клиент
make lint         Проверка линтером
make fix          Автоисправление и проверка типов
make format       Форматирование кода
make clean        Очистка кэша
make purge        Удаление окружения и кэшей

👤 Автор

Станислав Байков (@st.rnd)

📄 Лицензия

Распространяется под лицензией MIT. Подробности в LICENSE.