Open WebUI Knowledge MCP

Компактный MCP для Goose: управление знаниями и поиск в Qdrant через Open WebUI.

Goose / MCP client → этот MCP → Open WebUI → Qdrant
                                    ↓
                       настроенные embedding / reranking

MCP использует только Open WebUI HTTP API. Open WebUI отвечает за загрузку, chunking, embeddings, хранение оригиналов, векторов и поиск. MCP возвращает фрагменты, а не генерирует итоговый ответ. Прямых клиентов Qdrant/Ollama и ML-библиотек в зависимостях MCP нет.

Установка

Нужны Python 3.10+, uv и уже запущенный Open WebUI, настроенный на Qdrant. В каталоге репозитория:

uv venv --python 3.12
uv pip install --python .venv/bin/python -e '.[dev]'
cp .env.example .env

Укажите в .env URL и API key Open WebUI. Запуск из терминала:

set -a
. ./.env
set +a
.venv/bin/openwebui-rag-mcp

Сервер ожидает MCP-сообщения на stdin; произвольного вывода в stdout нет. Сам MCP не читает .env: пример выше экспортирует его значения в окружение. Для обычной установки без инструментов разработки замените '.[dev]' на ..

Related MCP server: Open WebUI Knowledge Base MCP Server

Настройка Open WebUI → Qdrant

Эти переменные задаются процессу/контейнеру Open WebUI, а не MCP:

VECTOR_DB=qdrant
QDRANT_URI=http://qdrant:6333
QDRANT_API_KEY=
RAG_EMBEDDING_ENGINE=ollama
RAG_OLLAMA_BASE_URL=http://ollama:11434
RAG_EMBEDDING_MODEL=your-installed-embedding-model

qdrant и ollama в примере — имена сервисов в одной контейнерной сети; замените адреса на доступные Open WebUI. Проверьте сохранённые настройки Documents в Admin Panel: часть параметров Open WebUI хранится в его БД. Модель выбирает администратор. Это настройка backend для баз, которыми управляет Open WebUI; существующие произвольные коллекции Qdrant автоматически базами Open WebUI не становятся. Описание переменных Open WebUI.

Hybrid search и reranker настраиваются в Open WebUI. MCP сохраняет выбранный режим и передаёт k/k_reranker для конкретного поиска. Совместимость reranker с Ollama зависит от возможностей Open WebUI и выбранного адаптера; MCP не эмулирует /rerank. Для первого запуска можно использовать обычный vector search без reranker.

В Open WebUI разрешите API keys и создайте ключ пользователя с нужными правами на Knowledge/Files/Retrieval API. Если включены ограничения endpoints, разрешите используемые ниже пути. rag_health проверяет только авторизованный Knowledge API, а не фактическую доступность Qdrant или моделей.

Окружение MCP

Усечение всегда обозначается truncated; у файла есть total_chars. RAG_SCORE_THRESHOLD старого прототипа удалён: MCP не может одинаково трактовать оценки всех режимов retrieval. Threshold задаётся в Open WebUI. Невалидная конфигурация завершает запуск с кодом 2 и сообщением в stderr. Недоступный Open WebUI при старте логируется; MCP остаётся запущен и может восстановиться при следующем вызове.

Goose

Добавьте stdio extension через интерфейс Goose или объедините этот блок со своим ~/.config/goose/config.yaml. Замените путь и ключ своими значениями:

extensions:
  openwebui_knowledge:
    name: openwebui_knowledge
    type: stdio
    enabled: true
    cmd: /absolute/path/to/GooseMCPopenwebui/.venv/bin/openwebui-rag-mcp
    args: []
    timeout: 600
    envs:
      OPENWEBUI_URL: http://localhost:3000
      OPENWEBUI_API_KEY: replace-with-your-key
      OPENWEBUI_TIMEOUT: "120"
      OPENWEBUI_VERIFY_TLS: "true"
      RAG_TOP_K: "8"

Timeout Goose учитывает, что запись состоит из нескольких HTTP-запросов. Используйте абсолютный путь: запуск уже установленного пакета не требует PyPI. Формат конфигурации Goose.

Tools

knowledge_id — ID базы Open WebUI; file_id — ID документа. Это разные сущности.

Старые имена rag_list_knowledge, rag_search, rag_get_file сохранены как aliases с теми же входными параметрами. Формат результатов обновлён; это не полная обратная совместимость старого прототипа.

Пример последовательности arguments:

{"name":"Рабочие заметки","description":"Решения команды"}

Из ответа knowledge_create возьмите knowledge_id:

{"knowledge_id":"<id-базы>","text":"Согласовали выпуск в пятницу.","title":"Решение","metadata":{"project":"demo"}}

Из ответа knowledge_add возьмите file_id для чтения, обновления или удаления. Поиск:

{"query":"Когда выпуск?","knowledge_ids":["<id-базы>"],"top_k":5}

knowledge_ids=null ищет во всех доступных базах, [] — ни в одной. MCP отправляет один retrieval-запрос для выбранного набора и сохраняет порядок Open WebUI. Каждый результат содержит text, truncated, chunk_id, file_id, knowledge_id, title, source, metadata, score, distance. Отсутствующие upstream поля — null. Score/distance сохраняются без преобразований: поле distances в разных режимах Open WebUI может содержать разные типы оценок. Отдельные vector/reranker scores и достоверное число chunks API не гарантирует. Embeddings из ответов исключаются.

Контракт API и ограничения MVP

Контракт сверялся с официальным исходным кодом Open WebUI main 22.09.2026: Knowledge API, Files API, Retrieval API. Live-совместимость с конкретным установленным релизом пока не проверена.

Список баз поддерживает items/total, data/total и старый плоский массив. Файлы читаются из вложенного files старых ответов либо из отдельного paginated API. Retrieval поддерживает одну вложенную строку результатов и плоский массив. Это совместимость форматов, а не обещание поддержки любого релиза. Для мутаций нужны перечисленные endpoints и поддержка delete_file=false установленной версией.

• Записи неатомарны. Ошибка возвращается с MCP isError=true, ok=false, stage, известным file_id и outcome=partial_or_unknown. При timeout запрос мог завершиться: сначала проверьте Open WebUI, затем решайте, повторять ли операцию. Автоповторов нет.

• При сбое привязки загруженный файл сохраняется в Open WebUI; его можно проверить и прикрепить через UI. MCP не удаляет его автоматически.

• Update меняет общий файл. Другие базы, использующие его, могут измениться; поведение обновления их индексов зависит от версии Open WebUI. Индекс указанной базы обновляется отдельным вызовом. Исходный скачиваемый файл и извлечённый текст могут отличаться после редактирования — MCP читает именно извлечённый текст.

• Delete удаляет связь и поручает удаление векторов Open WebUI. Сам файл и другие базы сохраняются. Некоторые ошибки очистки/поиска Open WebUI скрывает внутри успешного HTTP-ответа; MCP не может независимо подтвердить состояние Qdrant.

• Source/title/metadata передаются как metadata загрузки (Open WebUI сохраняет их в file.meta.data); попадание произвольных полей в retrieval metadata зависит от backend. Изменение metadata, metadata-filter, удаление всей базы и внешние read-only Knowledge Sources не входят в CRUD MVP.

• Конкурирующие записи сериализуются внутри одного MCP-процесса. Транзакций между несколькими MCP или пользователями Open WebUI нет.

Разработка и проверки

.venv/bin/pytest -q
.venv/bin/ruff check src/openwebui_rag_mcp tests
.venv/bin/ruff format --check src/openwebui_rag_mcp tests

Все HTTP-вызовы тестов mock'аются через httpx. Отдельный тест запускает реальный stdio subprocess, выполняет MCP initialize/list_tools/call_tool и проверяет восстановление после ошибки tool. Qdrant/Ollama/Open WebUI для unit-тестов не нужны. План и оценка исходного кода — TODO.md, инструкции — AGENTS.md.