Metadata-Version: 2.4
Name: st-mcp-habr
Version: 1.1.0
Summary: Keyless Habr MCP — поиск, чтение статей в Markdown, анализ дискуссий
License-File: LICENSE
Requires-Python: >=3.13
Requires-Dist: httpx==0.28.1
Requires-Dist: markdownify==1.2.2
Requires-Dist: mcp[cli]==1.27.2
Requires-Dist: python-dotenv==1.2.2
Provides-Extra: dev
Requires-Dist: ruff==0.15.17; extra == 'dev'
Requires-Dist: ty==0.0.49; extra == 'dev'
Description-Content-Type: text/markdown

# MCP Habr

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

[![FastMCP](https://img.shields.io/badge/FastMCP-1.27.2-000000)](https://github.com/modelcontextprotocol/python-sdk)
[![httpx](https://img.shields.io/badge/httpx-0.28.1-2A6DB2)](https://github.com/encode/httpx)
[![markdownify](https://img.shields.io/badge/markdownify-1.2.2-4B8BBE)](https://github.com/matthewwithanm/python-markdownify)

## 📑 Содержание

- [Возможности](#-возможности)
- [Быстрый старт](#-быстрый-старт)
- [Стек](#-стек)
- [Инструменты](#-инструменты)
- [Структура](#-структура)
- [Архитектура](#-архитектура)
- [Команды](#-команды)
- [Автор](#-автор)
- [Лицензия](#-лицензия)

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

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

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

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

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

`uvx` скачает пакет из forgejo registry. После регистрации инструменты доступны как `mcp__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`.
- **Автор** — аккаунт-человек со своей кармой, рейтингом, статьями и комментариями.
- **Компания** — корпоративный аккаунт-организация, чьи публикации помечены флагом корпоративности.
- **Комментарии** — дерево обсуждения под публикацией, ядро анализа в этом сервере.

## 🔧 Команды

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

## 👤 Автор

**Станислав Байков** ([@st.rnd](mailto:st.rnd@mail.ru))

## 📄 Лицензия

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