MCP поиска по базе знаний MaxKB

Сервис MCP на основе MaxKB Admin API, выполняющий поиск сегментов базы знаний по запросу пользователя. Поддерживает векторный поиск, гибридный поиск и полнотекстовый поиск. По умолчанию Top K равен 10, режим поиска — векторный.

По умолчанию предоставляется через Streamable HTTP:

• Адрес MCP: http://<хост>:8000/mcp

• Проверка работоспособности: http://<хост>:8000/health

Возможности

search_mode (если не указан в инструменте, используется переменная окружения, по умолчанию — векторный поиск):

• 向量 / 向量检索 / embedding — векторный

• 混合 / 混合检索 / blend — гибридный

• 全量 / 全量检索 / keywords — полнотекстовый

• auto: гибридный поиск → векторный поиск → полнотекстовый поиск, до первого результата

Если knowledge_ids не указаны, поиск выполняется по всем базам знаний текущего рабочего пространства, для которых настроена векторная модель.

Related MCP server: mcp-rag-bridge

Переменные окружения

Скопируйте пример файла и измените под своё окружение:

cp .env.example .env

Если при одиночном вызове search_knowledge передать top_n или search_mode, они переопределят значения по умолчанию на сервере.

Локальный запуск

Требуется Python 3.10+ и uv.

cp .env.example .env
uv sync
uv run maxkb-mcp

После запуска:

• MCP: http://127.0.0.1:8000/mcp

• Проверка работоспособности: http://127.0.0.1:8000/health

• Файл журнала: logs/mcp.log (ежедневная ротация, по умолчанию хранится 7 дней)

Пример подключения клиента:

{
  "mcpServers": {
    "maxkb-knowledge": {
      "transport": "streamable_http",
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "你的 MaxKB API Key"
      },
      "disabled": false
    }
  }
}

Authorization может быть как исходным ключом, так и Bearer <ключ>.

Для режима stdio:

MCP_TRANSPORT=stdio uv run maxkb-mcp

Сборка Docker-образа

Требуется Docker 20.10+.

docker build -t maxkb-mcp:latest .

Для сетей в Китае рекомендуется указать зеркало PyPI:

docker build \
  --build-arg PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple \
  -t maxkb-mcp:latest .

Отправка в реестр образов (необязательно):

docker tag maxkb-mcp:latest <registry>/<namespace>/maxkb-mcp:0.1.0
docker push <registry>/<namespace>/maxkb-mcp:0.1.0

Развёртывание Docker

docker-compose.yml не собирает образ, а только запускает уже существующий. Перед развёртыванием выполните локальную сборку или загрузите образ из реестра.

cp .env.example .env
docker-compose up -d
docker-compose logs -f maxkb-mcp

При использовании удалённого образа:

MAXKB_MCP_IMAGE=<registry>/<namespace>/maxkb-mcp:0.1.0 docker-compose up -d

После запуска:

• MCP: http://<хост>:8000/mcp

• Проверка работоспособности: http://<хост>:8000/health

• Директория журналов: ./logs на хосте (в контейнере — /app/logs)

После обратного проксирования через HTTPS измените url клиента на https://your-domain/mcp.

Если MaxKB развёрнут на хосте, укажите MAXKB_BASE_URL как http://host.docker.internal:<порт>.

Остановка сервиса:

docker-compose down

Журналы

Все HTTP-запросы и вызовы инструментов MCP записываются в локальный журнал, Authorization маскируется.

• Файл: {MAXKB_LOG_DIR}/mcp.log, ежедневно ротируется в mcp.log.YYYY-MM-DD

• При запуске один раз удаляются просроченные файлы, затем очистка выполняется каждые 6 часов

• Журналы старше MAXKB_LOG_RETENTION_DAYS (по умолчанию 7 дней) удаляются

Частые вопросы

• API Key не указан: передайте пользовательский ключ MaxKB в headers.Authorization клиента или настройте MAXKB_API_KEY в .env

• Медленная сборка или таймаут: при сборке добавьте --build-arg PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple

• Контейнер не может получить доступ к MaxKB: проверьте MAXKB_BASE_URL, сеть и необходимость host.docker.internal

• Ошибка проверки сертификата: установите MAXKB_VERIFY_SSL=false