vector-mcp

Interfaces MCP y de agente con enrutamiento por acciones para la gestión y recuperación de colecciones vectoriales gobernadas. El valor predeterminado nativo es epistemic-graph. Los proveedores opcionales seguros cubren PostgreSQL/pgvector, Qdrant y MongoDB Atlas.

Versión: 3.1.0

Capacidad gobernada

• Herramientas MCP: vector_collection_management y vector_search

• Proveedor de habilidades: el flujo de trabajo consolidado vector-mcp-operations

• Proveedor de ontología: la ontología de recuperación vectorial empaquetada

• Proveedor de conector de origen: un inventario de colecciones vectoriales de solo lectura preestablecido

• Configuración en tiempo de ejecución: AgentConfig, variables de entorno y referencias secretas

• Postura de privacidad: sin endpoints, credenciales, identidad personal ni rutas de host verificadas

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

Instalación

Use el conjunto adicional más pequeño requerido por el despliegue:

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

El tiempo de ejecución requiere agent-utilities>=2.0.0 y su contrato completo de motor epistemic-graph autocontenido. Un perfil de motor solo numérico o parcial no es un despliegue compatible.

Para un proveedor de almacenamiento seleccionado:

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

El extra all habilita todos los proveedores opcionales compatibles, además de los tiempos de ejecución de agente, Langfuse y Logfire. Las imágenes de producción deben instalar solo los proveedores que operan.

Configuración de MCP

El paquete incluye una configuración de lanzamiento de agente neutral que contiene solo el comando, el modo de herramienta condensado y los conmutadores de herramientas. Los valores en tiempo de ejecución se heredan de AgentConfig o los inyecta el operador. Las instrucciones detalladas sobre cómo usar los envoltorios de API subyacentes, los enlaces de esquema extendidos y las referencias del SDK para desarrolladores se mantienen en docs/index.md.

MCP

Este servidor utiliza herramientas dinámicas con enrutamiento por acciones para optimizar la sobrecarga de tokens y maximizar la compatibilidad con IDE.

Herramientas MCP disponibles

Generado automáticamente desde el servidor MCP en vivo: no editar a mano.

Herramientas condensadas con enrutamiento por acciones (MCP_TOOL_MODE=condensed)

2 herramienta(s) con enrutamiento por acciones · 0 herramienta(s) verbosa(s) 1:1. Cada una está habilitada a menos que su conmutador <DOMINIO>TOOL se establezca en falso; MCP_TOOL_MODE selecciona la superficie (**intent predeterminado* — las seis herramientas verbales, conjunto granular cargado bajo demanda · condensed con enrutamiento por acciones · verbose 1:1 · both). Generado automáticamente: no editar.*

Los esquemas detallados de las herramientas, las formas de los parámetros y las restricciones de validación se conservan en la guía de uso.

Selección dinámica de herramientas y visibilidad

Este servidor MCP admite la selección dinámica de conjuntos de herramientas y el filtrado de visibilidad en tiempo de ejecución. Esto le permite restringir el conjunto de herramientas expuestas para evitar saturar la ventana de contexto del LLM.

Puede configurar el filtrado de herramientas a través de múltiples canales de entrada:

• Argumentos de CLI: Pase --tools o --toolsets (o sus contrapartes deshabilitadas --disabled-tools y --disabled-toolsets) durante el inicio.

• Variables de entorno: Defina variables de entorno estándar:

  • MCP_ENABLED_TOOLS / MCP_DISABLED_TOOLS

  • MCP_ENABLED_TAGS / MCP_DISABLED_TAGS

• Encabezados de solicitud HTTP SSE: Pase encabezados personalizados durante la inicialización del transporte:

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

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

• Parámetros de consulta de solicitud HTTP SSE: Agregue parámetros de consulta directamente a la URL de conexión de su transporte:

  • ?tools=tool1,tool2

  • ?tags=tag1

Cuando se proporcionan cadenas de consulta o parámetros, una capa de resolución de Knowledge Graph sin LLM (usando DynamicToolOrchestrator) compara las intenciones de consulta con etiquetas, nombres o descripciones de herramientas conocidas, con un respaldo seguro y un refresco automático de caché en segundo plano cada 24 horas.

Ejemplos de configuración de MCP

Instale el extra [mcp] centrado en el conector. Los ejemplos usan vector-mcp[mcp] para agregar FastMCP / FastAPI a través de agent-utilities[mcp]; el núcleo requerido de Agent Utilities aún incluye epistemic-graph[full]. El extra [agent-runtime] además habilita la orquestación de modelos.

Transporte stdio (IDEs locales: 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"
      }
    }
  }
}

Las referencias en tiempo de ejecución requieren un lanzador consciente de alias como GraphOS. Otros lanzadores deben omitir esas entradas e inyectar los valores resueltos a través de su propio límite de secretos en tiempo de ejecución.

Transporte Streamable-HTTP (red / producción)

{
  "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"
      }
    }
  }
}

Alternativamente, conéctese a una instancia Streamable-HTTP preimplementada mediante url:

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

Ejecute una imagen de contenedor revisada como un hijo stdio de privilegios mínimos (sin listener ni puerto publicado):

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

Para HTTP de red contenerizado, proporcione una entrada TLS autenticada (o TLS directo del servidor), MCP_ALLOWED_HOSTS exacto y una política CIDR de proxy de confianza exacta a través del perfil de despliegue propiedad del operador. El generador no emite un listener no autenticado fuera de loopback.

Generado automáticamente desde la superficie de entorno de lectura de código (MCP_TOOL_MODE + variables del paquete) — no editar.

Opciones de despliegue adicionales

vector-mcp también puede ejecutarse como un contenedor local (Docker / Podman / uv) o consumirse desde un despliegue remoto. La guía de despliegue tiene mcp_config.json completo, listo para copiar y pegar, para los cuatro transportes: stdio, streamable-http, contenedor local / uv y URL remota:

• Contenedor local / uv — inicie el servidor desde mcp_config.json mediante uvx, docker run o podman run, o apunte a un contenedor streamable-http local mediante url.

• URL remota — conéctese a un servidor implementado detrás de Caddy en https://vector-mcp.example.invalid/mcp usando la clave "url".

Variables de entorno

Variables de entorno del paquete

Variables heredadas de agent-utilities (aplican a cada conector)

31 paquete + 20 variable(s) heredadas. Generado automáticamente desde .env.example + el conjunto compartido de agent-utilities — no editar.

Cada variable que el servidor lee, agrupada por propósito. Consulte .env.example para la lista canónica de copiar y pegar, incluidos los ajustes de conexión DATABASE_TYPE / GRAPH_SERVICE_SOCKET / GRAPH_SERVICE_AUTH_SECRET para el backend epistémico-graph nativo. Los endpoints de backend, las ubicaciones de bases de datos y las credenciales para proveedores opcionales (Postgres/Qdrant/Mongo/Chroma/Couchbase) nunca son valores literales documentados en el README ni argumentos de herramientas MCP; se resuelven a través de AgentConfig y referencias secret:///env:///vault:// en tiempo de ejecución.

Servidor MCP / transporte

Conmutadores de herramientas

Cada herramienta enrutada por acción se puede deshabilitar individualmente mediante su variable de entorno de conmutación (establecida en false). La lista completa está en la tabla Herramientas MCP disponibles anterior.

Telemetría y gobernanza

CLI del agente (solo tiempo de ejecución [agent] completo)

Consulte .env.example para un punto de partida de copiar y pegar.

Integración de proveedor y ontología

El paquete contribuye con sus habilidades, indicaciones, ontología y conector de origen a través de puntos de entrada de Python. El conector de inventario de colecciones es intencionalmente de solo lectura y registra metadatos de colecciones, no cargas útiles de documentos o incrustaciones.

Las firmas de conector generadas deben recrearse solo después de observar el esquema MCP instalado y de que se proporcione una clave de firma de versión en tiempo de ejecución. Una firma de un esquema de herramienta u ontología anterior nunca debe copiarse hacia adelante.

Comprobaciones de desarrollo

Comprobaciones de bajo costo que no lanzan proveedores:

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

Las pruebas de proveedores utilizan límites de SDK simulados y no realizan llamadas de red. La calificación en vivo es una puerta de despliegue separada y debe usar AgentConfig y secretos proporcionados por el operador.

Documentación

• Instalación

• Configuración y privacidad

• Despliegue

• Uso

• Resumen de arquitectura

El contenedor slim :mcp streamable-http (docker/mcp.compose.yml) publica :8000 con una comprobación /health; consulte Despliegue para la definición completa del servicio compose.

Licencia

Consulte LICENSE.

Desplegar con agent-utilities-deployment

Aprovisione este paquete con el flujo de trabajo consolidado agent-utilities-deployment. Selecciona una ruta de paquete instalado, fuente editable o contenedor inmutable; registra solo referencias de secretos en tiempo de ejecución y de perfil TLS en AgentConfig; y ejecuta compuertas de doctor, registro, política, observabilidad y reversión. Pida a su agente que "despliegue vector-mcp con agent-utilities-deployment".

El repositorio no incrusta ningún perfil de despliegue, valor de credencial, ruta de certificado o endpoint específico del entorno. Proporcione esos en tiempo de ejecución a través de AgentConfig y el proveedor de secretos configurado.

Instalación

Elija el extra que coincida con lo que desea ejecutar:

# 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]"

Imágenes de contenedor (:mcp vs :agent)

Un docker/Dockerfile de múltiples etapas construye dos imágenes de tamaño adecuado, seleccionadas por --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 ejecuta el servidor :mcp ligero; docker/agent.compose.yml ejecuta el agente (:latest) con un sidecar :mcp co-ubicado.

Base de datos de grafo de conocimiento (epistemic-graph)

El agente completo ([agent] / :latest) incorpora el motor epistemic-graph (incluido de forma transitiva a través de agent-utilities[agent]). Para producción — o para compartir un mismo grafo de conocimiento entre múltiples agentes — ejecute epistemic-graph como contenedor de base de datos propio y apunte el agente a él en lugar de incorporarlo. Las recetas de despliegue (nodo único + Raft HA), la configuración de conexión y la arquitectura completa de la base de datos (con diagramas) están documentadas en la guía de despliegue de epistemic-graph. El servidor [mcp] ligero no requiere la base de datos.

Propietarios del repositorio

Contribuir

¡Las contribuciones son bienvenidas! Por favor, asegure la calidad del código ejecutando comprobaciones locales antes de enviar pull requests:

• Formatee el código con ruff format .

• Ejecute el lint del código con ruff check .

• Valide la seguridad de tipos con mypy .

• Ejecute las suites de pruebas con pytest

Despliegue con agent-os-genesis

Este paquete puede ser aprovisionado para usted — guiado por habilidades — por la habilidad universal agent-os-genesis (su modo de despliegue de paquete único): elige su método de instalación, siembra secretos en OpenBao/Vault (o .env), confía en su CA empresarial, registra el servidor MCP y lo verifica — la misma maquinaria que levanta todo el Agent OS, reducida a este paquete. Pida a su agente que "despliegue vector-mcp con agent-os-genesis".

Los secretos se leen de los existentes y se siembran mediante vault_sync — solo se le solicita lo que falta.