vector-mcp

Управляемые через маршрутизацию действий интерфейсы MCP и агентов для управляемого управления векторными коллекциями и их поиска. Нативный режим по умолчанию — epistemic-graph. Безопасные опциональные провайдеры охватывают PostgreSQL/pgvector, Qdrant и MongoDB Atlas.

Версия: 3.1.0

Управляемые возможности

• Инструменты MCP: vector_collection_management и vector_search

• Провайдер навыков: консолидированный рабочий процесс vector-mcp-operations

• Провайдер онтологии: упакованная онтология векторного поиска

• Провайдер коннектора источников: предустановленный инвентарь векторных коллекций только для чтения

• Конфигурация времени выполнения: AgentConfig, переменные окружения и ссылки на секреты

• Политика конфиденциальности: отсутствуют закоммиченные конечные точки, учётные данные, персональные данные или пути хоста

Related MCP server: production-grade-mcp-agentic-system

Установка

Используйте минимальный дополнительный набор, необходимый для развёртывания:

uvx --from 'vector-mcp[mcp]' vector-mcp

Среда выполнения требует agent-utilities>=2.0.0 и его автономный полный контракт движка epistemic-graph. Профиль движка только с числовыми значениями или частичный не является поддерживаемым развёртыванием.

Для выбранного провайдера хранилища:

uv add 'vector-mcp[postgres]'
uv add 'vector-mcp[qdrant]'
uv add 'vector-mcp[mongodb]'

Дополнение all включает все поддерживаемые опциональные провайдеры, а также среду выполнения агента, Langfuse и Logfire. Производственные образы должны устанавливать только те провайдеры, которые они используют.

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

Пакет включает нейтральную конфигурацию запуска агента, содержащую только команду, сжатый режим инструментов и переключатели инструментов. Значения времени выполнения наследуются из AgentConfig или вводятся оператором. Подробные инструкции по использованию базовых обёрток API, расширенных привязок схем и справочников разработчика SDK приведены в docs/index.md.

MCP

Этот сервер использует динамические инструменты с маршрутизацией действий для оптимизации расхода токенов и максимальной совместимости с IDE.

Доступные инструменты MCP

Автоматически сгенерировано из работающего MCP-сервера — не редактировать вручную.

Сжатые инструменты с маршрутизацией действий (MCP_TOOL_MODE=condensed)

2 инструмента с маршрутизацией действий · 0 подробных инструментов 1:1. Каждый включён, если его переключатель <DOMAIN>TOOL не установлен в false; MCP_TOOL_MODE выбирает поверхность (**intent по умолчанию* — шесть глагольных инструментов, детальный набор загружается по требованию · condensed с маршрутизацией действий · verbose 1:1 · both). Автоматически сгенерировано — не редактировать.*

Подробные схемы инструментов, формы параметров и ограничения валидации сохранены в руководстве по использованию.

Динамический выбор и видимость инструментов

Этот MCP-сервер поддерживает динамический выбор набора инструментов и фильтрацию видимости во время выполнения. Это позволяет ограничить набор доступных инструментов, чтобы не раздувать контекстное окно LLM.

Вы можете настроить фильтрацию инструментов через несколько каналов ввода:

• Аргументы CLI: Передайте --tools или --toolsets (или их отключающие аналоги --disabled-tools и --disabled-toolsets) при запуске.

• Переменные окружения: Определите стандартные переменные окружения:

  • MCP_ENABLED_TOOLS / MCP_DISABLED_TOOLS

  • MCP_ENABLED_TAGS / MCP_DISABLED_TAGS

• Заголовки HTTP SSE-запросов: Передайте пользовательские заголовки при инициализации транспорта:

  • x-mcp-enabled-tools / x-mcp-disabled-tools

  • x-mcp-enabled-tags / x-mcp-disabled-tags

• Параметры запроса HTTP SSE: Добавьте параметры запроса непосредственно к URL вашего транспортного соединения:

  • ?tools=tool1,tool2

  • ?tags=tag1

Когда указаны строки запроса или параметры, уровень разрешения графа знаний без LLM (с использованием DynamicToolOrchestrator) сопоставляет намерения запроса с известными тегами, именами или описаниями инструментов, с безопасным резервным вариантом и автоматическим фоновым обновлением кэша каждые 24 часа.

Примеры конфигурации MCP

Установите дополнительный пакет [mcp], ориентированный на коннекторы. В примерах используется vector-mcp[mcp] для добавления FastMCP / FastAPI через agent-utilities[mcp]; обязательное ядро Agent Utilities по-прежнему включает epistemic-graph[full]. Дополнительный пакет [agent-runtime] дополнительно включает оркестрацию моделей.

Транспорт stdio (локальные IDE — Cursor, Claude Desktop, VS Code)

{
  "mcpServers": {
    "vector-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "vector-mcp[mcp]",
        "vector-mcp"
      ],
      "env": {
        "MCP_TOOL_MODE": "intent",
        "COLLECTION_MANAGEMENTTOOL": "True",
        "DATABASE_TYPE": "epistemic_graph",
        "LLM_SSL_VERIFY": "False",
        "SEARCHTOOL": "True",
        "VECTOR_DB_TYPE": "epistemic_graph"
      }
    }
  }
}

Ссылки на среду выполнения требуют запуска с поддержкой псевдонимов, такого как GraphOS. Другие запускающие программы должны опускать эти записи и внедрять разрешённые значения через собственную границу секретов среды выполнения.

Транспорт Streamable-HTTP (сетевой / производственный)

{
  "mcpServers": {
    "vector-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "vector-mcp[mcp]",
        "vector-mcp",
        "--transport",
        "streamable-http",
        "--port",
        "8000"
      ],
      "env": {
        "TRANSPORT": "streamable-http",
        "HOST": "127.0.0.1",
        "PORT": "8000",
        "MCP_TOOL_MODE": "intent",
        "COLLECTION_MANAGEMENTTOOL": "True",
        "DATABASE_TYPE": "epistemic_graph",
        "LLM_SSL_VERIFY": "False",
        "SEARCHTOOL": "True",
        "VECTOR_DB_TYPE": "epistemic_graph"
      }
    }
  }
}

В качестве альтернативы подключитесь к предварительно развёрнутому экземпляру Streamable-HTTP по url:

{
  "mcpServers": {
    "vector-mcp": {
      "url": "http://localhost:8000/vector-mcp/mcp"
    }
  }
}

Запустите проверенный образ контейнера как дочерний процесс stdio с минимальными привилегиями (без прослушивателя или опубликованного порта):

docker run -i --rm \
  --read-only \
  --cap-drop=ALL \
  --security-opt=no-new-privileges \
  --pids-limit=256 \
  --tmpfs /tmp:rw,noexec,nosuid,nodev,size=64m \
  -e TRANSPORT=stdio \
  -e MCP_TOOL_MODE=intent \
  -e COLLECTION_MANAGEMENTTOOL=True \
  -e DATABASE_TYPE=epistemic_graph \
  -e LLM_SSL_VERIFY=False \
  -e SEARCHTOOL=True \
  -e VECTOR_DB_TYPE=epistemic_graph \
  registry.example.invalid/vector-mcp@sha256:<digest> vector-mcp

Для контейнерного сетевого HTTP укажите аутентифицированный входящий TLS-трафик (или прямой TLS сервера), точные MCP_ALLOWED_HOSTS и точную политику CIDR доверенного прокси через профиль развёртывания, принадлежащий оператору. Генератор не создаёт неаутентифицированный прослушиватель вне loopback.

Автоматически сгенерировано из поверхности окружения, считываемой из кода (MCP_TOOL_MODE + переменные пакета) — не редактировать.

Дополнительные варианты развёртывания

vector-mcp также может работать как локальный контейнер (Docker / Podman / uv) или использоваться из удалённого развёртывания. В руководстве по развёртыванию приведены полные готовые mcp_config.json для всех четырёх транспортов — stdio, streamable-http, локальный контейнер / uv и удалённый URL:

• Локальный контейнер / uv — запустите сервер из mcp_config.json через uvx, docker run или podman run, либо укажите локальный контейнер streamable-http по url.

• Удалённый URL — подключитесь к серверу, развёрнутому за Caddy по адресу https://vector-mcp.example.invalid/mcp, используя ключ "url".

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

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

Наследуемые переменные agent-utilities (применяются к каждому коннектору)

31 пакет + 20 наследуемых переменных. Автоматически сгенерировано из .env.example + общего набора agent-utilities — не редактировать.

Каждая переменная, которую читает сервер, сгруппирована по назначению. См. .env.example для канонического списка «копировать-вставить» — включая параметры подключения DATABASE_TYPE / GRAPH_SERVICE_SOCKET / GRAPH_SERVICE_AUTH_SECRET для встроенного бэкенда epistemic-graph. Конечные точки бэкенда, расположения баз данных и учётные данные для опциональных провайдеров (Postgres/Qdrant/Mongo/Chroma/Couchbase) никогда не документируются в README как литеральные значения или аргументы MCP-инструментов — они разрешаются через AgentConfig и ссылки secret:///env:///vault:// во время выполнения.

MCP-сервер / транспорт

Переключатели инструментов

Каждый инструмент с маршрутизацией действий можно отключить индивидуально через его переменную-переключатель (установите значение false). Полный список приведён в таблице Доступные MCP-инструменты выше.

Телеметрия и управление

CLI агента (только полный рантайм [agent])

См. .env.example для отправной точки «копировать-вставить».

Интеграция провайдера и онтологии

Пакет предоставляет свои навыки, подсказки, онтологию и исходный коннектор через точки входа Python. Коннектор инвентаризации коллекций намеренно доступен только для чтения и регистрирует метаданные коллекций, а не полезные данные документов или эмбеддингов.

Сгенерированные сигнатуры коннекторов должны воссоздаваться только после того, как установленная схема MCP будет наблюдаема и ключ подписи релиза будет предоставлен во время выполнения. Сигнатура из более старой схемы инструментов или онтологии никогда не должна копироваться вперёд.

Проверки разработки

Недорогие проверки, которые не запускают провайдеров:

python scripts/security_sanitizer.py
python scripts/security_contract.py --contract .security/security-contract.json validate
python -m compileall -q vector_mcp

Тесты провайдеров используют мокированные границы SDK и не выполняют сетевых вызовов. Живая квалификация — это отдельный шлюз развёртывания и должна использовать AgentConfig и секреты, предоставленные оператором.

Документация

• Установка

• Конфигурация и конфиденциальность

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

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

• Обзор архитектуры

Тонкий контейнер :mcp streamable-http (docker/mcp.compose.yml) публикует :8000 с проверкой /health; см. Развёртывание для полного определения сервиса compose.

Лицензия

См. LICENSE.

Развёртывание с agent-utilities-deployment

Подготовьте этот пакет с помощью консолидированного рабочего процесса agent-utilities-deployment. Он выбирает путь установленного пакета, редактируемого исходного кода или неизменяемого контейнера; записывает только ссылки на секреты времени выполнения и TLS-профили в AgentConfig; и запускает шлюзы doctor, регистрации, политик, наблюдаемости и отката. Попросите вашего агента «развернуть vector-mcp с agent-utilities-deployment».

Репозиторий не содержит профиля развёртывания, значения учётных данных, пути к сертификату или конечной точки, зависящей от окружения. Предоставьте их во время выполнения через AgentConfig и настроенный провайдер секретов.

Установка

Выберите дополнительный пакет, соответствующий тому, что вы хотите запустить:

# MCP server only (recommended for tool hosting — slim deps)
uv pip install "vector-mcp[mcp]"

# Full agent runtime (Pydantic AI + epistemic-graph engine)
uv pip install "vector-mcp[agent]"

# Everything (development)
uv pip install "vector-mcp[all]"      # or: python -m pip install "vector-mcp[all]"

Образы контейнеров (:mcp против :agent)

Один многоступенчатый docker/Dockerfile собирает два образа правильного размера, выбираемых через --target:

docker build --target mcp   -t knucklessg1/vector-mcp:mcp    docker/   # slim MCP server
docker build --target agent -t knucklessg1/vector-mcp:latest docker/   # full agent

docker/mcp.compose.yml запускает облегчённый сервер :mcp; docker/agent.compose.yml запускает агента (:latest) с совмещённым сайдкаром :mcp.

База данных графа знаний (epistemic-graph)

Полный агент ([agent] / :latest) встраивает движок epistemic-graph (подтягиваемый транзитивно через agent-utilities[agent]). Для продакшена — или чтобы разделять один граф знаний между несколькими агентами — запускайте epistemic-graph как отдельный контейнер базы данных и укажите агенту на него вместо встраивания. Рецепты развёртывания (один узел + Raft HA), конфигурация подключения и полная архитектура базы данных (со схемами) описаны в руководстве по развёртыванию epistemic-graph. Облегчённому серверу [mcp] база данных не требуется.

Владельцы репозитория

Вклад

Вклад приветствуется! Пожалуйста, обеспечьте качество кода, запустив локальные проверки перед отправкой pull request'ов:

• Форматируйте код с помощью ruff format .

• Проверяйте код линтером с помощью ruff check .

• Проверяйте типовую безопасность с помощью mypy .

• Запускайте тестовые наборы с помощью pytest

Развёртывание с помощью agent-os-genesis

Этот пакет может быть подготовлен для вас — под руководством навыка — универсальным навыком agent-os-genesis (в его режиме развёртывания одного пакета): он выбирает ваш способ установки, сохраняет секреты в OpenBao/Vault (или .env), доверяет вашему корпоративному CA, регистрирует MCP-сервер и проверяет его — тот же механизм, который поднимает всю Agent OS, но ограниченный только этим пакетом. Попросите своего агента "развернуть vector-mcp с помощью agent-os-genesis".

Секреты считываются (если уже есть) + записываются через vault_sync — запрашиваются только отсутствующие.