# Beit-MCP
 
Быстроразвёртываемый локальный MCP-сервер, который выполняет поиск документации по библиотекам и API в интернете, векторизует и записывает её в локальную базу знаний, доступную любому coding-агенту (Cursor, Claude Code и др.) через протокол **MCP**.
 
## Проблема
 
Coding-агенты обучены на данных с фиксированной датой отсечения и не знают о последних версиях библиотек и API. Из-за этого они:
 
- предлагают устаревший синтаксис или методы, которых уже нет в новой версии библиотеки;
- **придумывают несуществующие функции и параметры** («галлюцинируют»);
- не знают о библиотеках, появившихся после даты обучения.

Разработчику приходится вручную проверять и исправлять такой код — то есть агент зачастую не решает задачу полностью, а создаёт дополнительную работу.

Существующие решения (по типу Context7) подразумевают открытость документации анализируемых библиотек и централизованное хранилище и имеют свои закрытые правила оценки источников, в то время как в разработке часто требуется знание документации проприетарных библиотек и использование закрытого исходного кода.

## Решение
 
Проект строит для агента «внешнюю память» — векторную базу данных с актуальной документацией, к которой агент обращается вместо того, чтобы полагаться на устаревшие знания из обучения.

Также отличительной особенностью является то, что агент (с разрешения пользователя) может самостоятельно наполнять базу данных нужной документацией из различных источников.

## Архитектура
 
| Компонент | Инструмент | Роль |
|---|---|---|
| Получение страницы | `crawl4ai` | Рендерит JS-сайты, обрабатывает PDF, отдаёт чистый Markdown |
| Разбиение на чанки | `unstructured` | Категоризирует элементы (`Title`, `NarrativeText`, `CodeSnippet`), пары код+описание |
| Векторизация | `sentence-transformers` (`nomic-ai/nomic-embed-code`) | Эмбеддинги текста и кода |
| Хранилище | `ChromaDB` (persistent, cosine) | Локальная векторная база |
| Выдача агенту | `FastMCP` | MCP-сервер с инструментами поиска и загрузки документации |
 
## Установка
 
```bash
pip install chromadb sentence-transformers "mcp[cli]" unstructured crawl4ai
crawl4ai-setup   # ставит headless-браузер для рендеринга JS-страниц
```
 
## Использование
 
Запуск MCP-сервера:
 
```bash
python main.py
```
 
Сервер поднимается на `streamable-http` транспорте, на порте **8000** и предоставляет агенту следующие инструменты:
 
**Поиск (read-only, вызывается свободно)**
- `get_relevant_docs(query, n_results)` — семантический поиск по уже загруженной документации.
**Загрузка документации (требует явного подтверждения пользователя)**
- `add_documentation_from_url(source)` — проиндексировать документацию по одному URL.
- `add_documentation_from_urls_in_file(filename)` — проиндексировать список URL из текстового файла (по одному на строку).
- `add_documentation_from_file(filepath)` — проиндексировать локальный `.html`/`.md`/`.txt` файл.
- `add_crawled_documentation_from_url'` - **рекурсивно собрать документацию от всех ближайших страниц, на которые можно перейти с исходной ссылки**. Полезно для парсинга больших объёмов документации
Инструменты записи явно помечены аннотациями `destructiveHint=True` — MCP-клиент (Cursor, Claude Desktop) должен запрашивать подтверждение перед их вызовом, а не выполнять автоматически в рамках обычной работы агента. Это осознанное архитектурное решение: поиск по базе и наполнение базы — разные по риску операции, и не должны иметь одинаковый уровень автономности.
 
Поддерживаемые источники документации:
- одиночный URL (включая PDF — определяется по расширению и обрабатывается отдельной стратегией);
- текстовый файл со списком URL, по одному на строку;
- локальный `.html`, `.md` или `.txt` файл.
`.docx` и другие офисные форматы намеренно не поддерживаются — реальный код в них почти никогда не размечен как код семантически (только сменой шрифта), что делает автоматическое извлечение ненадёжным.
 
## Структура проекта
 
```
main.py                          # MCP-сервер: регистрация инструментов
text_parsing_and_vectorizing.py  # пайплайн: fetch → parse → embed → store
chroma_db/                       # локальная персистентная векторная БД (создаётся автоматически)
```