RAG Blob MCP

Сервер Model Context Protocol (MCP), который предоставляет RAG-агенту поисковый доступ к библиотеке документов, хранящейся в Azure Blob Storage, а также приложение Streamlit для загрузки документов и общения с ними.

• MCP-сервер — FastMCP поверх Streamable HTTP, владеет всем доступом к Azure Blob Storage, предоставляет 4 инструмента и 3 шаблона подсказок, хранит векторный индекс в памяти (эмбеддинги OpenAI), пересобираемый из Blob Storage при каждом запуске.

• Приложение Streamlit — вкладка «Библиотека» (загрузка / список / удаление документов) и вкладка «Чат» (задавайте вопросы, на которые отвечает агент LangGraph ReAct, вызывающий инструмент поиска сервера).

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

1. Предварительные требования

• Python 3.11+ (разрабатывалось на 3.13)

• Учетная запись Azure Storage с контейнером Blob (см. Настройка Azure ниже, если у вас её нет)

• Ключ API OpenAI

2. Установка

Из корня репозитория:

python -m venv .venv
.venv\Scripts\activate          # Windows
pip install -r requirements.txt

3. Настройка

Скопируйте .env.example (в корне репозитория) в .env и заполните свои значения:

OPENAI_API_KEY=sk-...
AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;EndpointSuffix=core.windows.net
AZURE_STORAGE_CONTAINER_NAME=rag-documents

Всё остальное (OPENAI_MODEL, OPENAI_EMBEDDING_MODEL, MCP_SERVER_HOST/PORT/URL) имеет рабочие значения по умолчанию — см. Конфигурация.

4. Запуск

Два процесса, два терминала, оба из корня репозитория:

# Terminal 1 — MCP server
python server/mcp_server.py

# Terminal 2 — Streamlit app
streamlit run app/streamlit_app.py

Откройте http://localhost:8501. Загрузите файл PDF/DOCX/TXT/MD на вкладке Библиотека, затем задайте вопрос о нём на вкладке Чат.

Related MCP server: Legal MCP Server

Настройка Azure

Если у вас ещё нет учетной записи хранения:

1. Портал Azure → Создать ресурс → Учетная запись хранения. Стандартная производительность, избыточность LRS подойдёт для личного использования.

2. В новой учетной записи: Хранилище данных → Контейнеры → + Контейнер, назовите его (например, rag-documents), уровень доступа — Private.

3. Безопасность и сеть → Ключи доступа → Показать ключи, скопируйте строку подключения.

4. Вставьте её в .env как AZURE_STORAGE_CONNECTION_STRING и установите AZURE_STORAGE_CONTAINER_NAME на имя выбранного контейнера.

Структура проекта

.
├── server/
│   ├── mcp_server.py      # FastMCP server: tools, prompts, index rebuild, __main__ entrypoint
│   ├── blob_store.py      # Azure Blob Storage wrapper
│   ├── indexing.py        # text extraction (pdf/docx/txt/md) + chunking
│   ├── vector_index.py    # in-memory vector store wrapper
│   └── test_*.py          # automated tests (pytest)
├── agent/
│   └── rag_agent.py       # LangGraph ReAct agent used by the Chat tab
├── app/
│   ├── mcp_client.py      # direct MCP tool-call helpers used by the Library tab
│   └── streamlit_app.py   # the UI
├── scripts/
│   └── smoke_test_server.py  # manual end-to-end smoke test against a running server
├── docs_build/            # scripts that generate PROJECT.docx / PROJECT.pdf
└── pytest.ini

Конфигурация

Все переменные находятся в файле .env в корне репозитория:

Использование

Вкладка «Библиотека» — загружайте файлы PDF/DOCX/TXT/MD (лимит 200 МБ, задаётся Streamlit). Каждая загрузка разбивается на фрагменты, эмбеддится и добавляется в поисковый индекс; список документов показывает статус indexed / failed / pending с количеством фрагментов. Удаление убирает документ и из Blob Storage, и из индекса.

Вкладка «Чат» — задайте вопрос на простом английском. Агент решает, когда вызывать инструмент поиска, извлекает релевантные фрагменты и отвечает, ссылаясь на исходный документ по имени файла. При пустой или нерелевантной библиотеке он сообщает об этом, а не угадывает.

Тестирование

pytest server/ -v

29 тестов покрывают извлечение текста/разбиение на фрагменты, векторный индекс, обёртку Azure Blob Storage (мок) и все 4 инструмента MCP + подсказки (через fastmcp.Client в процессе, с использованием заглушек — без реальных вызовов Azure/OpenAI). Автоматического покрытия для UI Streamlit или живой связки агент/сервер нет; см. scripts/smoke_test_server.py для ручного смоук-теста против реально запущенного сервера.

Известные ограничения

• Индекс в памяти, без персистентности. Каждый перезапуск сервера заново скачивает, извлекает и эмбеддит каждый документ в контейнере. Подходит для небольшой личной библиотеки; требует реальных вызовов API OpenAI и времени на запуск по мере роста библиотеки.

• Однопользовательский, только локально. Нет аутентификации, нет защиты от одновременных записей, нигде не развёрнут.

• Оба процесса (MCP-сервер, приложение Streamlit) должны быть запущены для работы приложения — см. полную документацию проекта для подробностей.

Полную картину — архитектуру, проектные решения, известные ошибки и следующие шаги — см. в PROJECT.md (также доступен как PROJECT.docx / PROJECT.pdf).