Servidor MCP de Milvus

Este programa es un servicio de acceso a la base de datos vectorial Milvus diseñado para modelos de lenguaje grandes (LLM) que sigue el protocolo Model Context Protocol (MCP). Puede utilizarse como una herramienta externa de interacción con bases de datos vectoriales para LLMs (como Antigravity).

Es compatible con la base de datos vectorial Milvus 2.6 e incluye un servicio de Embedding compatible con OpenAI (como Tongyi Qianwen text-embedding-v4), lo que permite a los modelos realizar búsquedas semánticas directamente mediante lenguaje natural.

💡 Aspectos destacados

1. Búsqueda vectorial: Admite búsqueda semántica mediante entrada de texto (con embedding automático) y búsqueda vectorial pura.

2. Embedding integrado: Punto de conexión compatible con OpenAI integrado; el modelo recibe texto y lo convierte automáticamente en vectores, sin necesidad de servicios externos.

3. Gestión del ciclo de vida de colecciones: Crear, ver y eliminar colecciones; al crear, se indexan y cargan automáticamente.

4. Lectura y escritura de datos: Admite la inserción de datos vectoriales y la eliminación basada en condiciones.

5. Gestión de conexiones múltiples: Define múltiples conexiones con nombre a través de un archivo de configuración JSON; una sola instancia del servidor MCP puede servir a múltiples instancias de Milvus.

6. Diseño de seguridad: drop_collection y delete_entities funcionan como herramientas independientes que pueden activarse o desactivarse por separado en el cliente MCP; drop_collection requiere adicionalmente el parámetro confirmDrop=true como medida de seguridad doble.

7. Búsqueda híbrida: Admite consultas combinadas de búsqueda de similitud vectorial + filtrado escalar.

Related MCP server: MCP Server MySQL

⚙️ Requisitos del entorno

1. Entorno Node.js: Se requiere Node.js versión v18 o superior.

2. Instancia de Milvus: Se requiere una instancia de servicio de Milvus 2.6 accesible.

3. API de Embedding: Se requiere un punto de conexión de Embedding compatible con OpenAI (como la plataforma Bailian de Tongyi Qianwen).

4. Paquetes de dependencias: Es necesario ejecutar npm install --omit=dev en la máquina donde se ejecute.

🛠 Instalación y construcción

1. Construcción desde el código fuente

npm install
npm run build

Los artefactos compilados se guardarán en el directorio ./dist.

2. Instalación global local

npm link

Una vez ejecutado, puede utilizar el comando global milvus-mcp-server en cualquier parte del sistema para invocar rápidamente el servicio.

📝 Archivo de configuración

Utilice un archivo JSON para configurar las conexiones de Milvus y el servicio de Embedding.

Ejemplo de archivo de configuración

{
  "connections": [
    {
      "name": "my-milvus",
      "address": "localhost:19530",
      "username": "root",
      "password": "Milvus",
      "database": "default",
      "description": "本地开发 Milvus 实例，存储文档和图片的向量索引"
    }
  ],
  "embedding": {
    "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
    "apiKey": "sk-your-api-key",
    "model": "text-embedding-v4",
    "dimensions": 1024
  }
}

Descripción de los campos de conexión

Descripción de los campos de Embedding

🚀 Inicio y uso

milvus-mcp-server --config <path-to-config.json>

Lista de parámetros:

• -c, --config <path>: Ruta del archivo de configuración (obligatorio).

🧠 Ejemplo de configuración del cliente MCP

Tomando como ejemplo la configuración de un cliente MCP convencional (como Antigravity):

{
  "mcpServers": {
    "MilvusMCP": {
      "command": "node",
      "args": [
        "绝对路径/milvus_mcp_server/dist/index.js",
        "--config", "绝对路径/milvus-config.json"
      ]
    }
  }
}

🧰 Herramientas que el modelo puede invocar (Tools)

1. list_milvus_connections

• Descripción: Lista toda la información de las conexiones de Milvus configuradas (anonimizada, sin contraseñas).

• Parámetros: Ninguno.

2. list_collections

• Descripción: Lista todas las colecciones bajo una conexión específica.

• Parámetros:

  • connectionName (String): Nombre de la conexión objetivo.

3. describe_collection

• Descripción: Obtiene información detallada del esquema de la colección, incluyendo definiciones de campos, índices y estadísticas de filas.

• Parámetros:

  • connectionName (String): Nombre de la conexión objetivo.

  • collectionName (String): Nombre de la colección.

4. create_collection

• Descripción: Crea una nueva colección. Crea automáticamente un índice AUTOINDEX para el campo vectorial y carga la colección para que sea inmediatamente buscable.

• Parámetros:

  • connectionName (String): Nombre de la conexión objetivo.

  • collectionName (String): Nombre de la nueva colección.

  • description (String, opcional): Descripción de la colección.

  • fields (Array): Matriz de definiciones de campos, cada elemento incluye name, dataType, isPrimaryKey?, autoId?, dimension?, maxLength?, description?.

5. drop_collection

• Descripción: Elimina permanentemente una colección y todos sus datos. Operación irreversible.

• Parámetros:

  • connectionName (String): Nombre de la conexión objetivo.

  • collectionName (String): Nombre de la colección a eliminar.

  • confirmDrop (Boolean): Debe establecerse en true para ejecutar la eliminación. Mecanismo de doble confirmación de seguridad.

• Control de interruptor: Esta herramienta puede habilitarse o deshabilitarse por separado en el cliente MCP.

6. insert_vectors

• Descripción: Inserta datos en una colección. Cada dato es un objeto JSON que contiene los valores de cada campo (incluyendo el campo vectorial).

• Parámetros:

  • connectionName (String): Nombre de la conexión objetivo.

  • collectionName (String): Nombre de la colección objetivo.

  • data (Array): Matriz de datos.

7. delete_entities

• Descripción: Elimina entidades según una expresión de filtro.

• Parámetros:

  • connectionName (String): Nombre de la conexión objetivo.

  • collectionName (String): Nombre de la colección objetivo.

  • filter (String): Expresión de filtro de Milvus, ej. 'id in [1, 2, 3]'.

• Control de interruptor: Esta herramienta puede habilitarse o deshabilitarse por separado en el cliente MCP.

8. vector_search

• Descripción: Búsqueda de similitud vectorial. Admite la entrada de texto (llama automáticamente al servicio de Embedding para convertirlo en vector) o vectores originales.

• Parámetros:

  • connectionName (String): Nombre de la conexión objetivo.

  • collectionName (String): Nombre de la colección objetivo.

  • text (String, opcional): Texto de búsqueda, alternativo a vector.

  • vector (Number[], opcional): Vector de búsqueda original, alternativo a text.

  • topK (Number, opcional): Número de resultados a devolver, por defecto 10.

  • filter (String, opcional): Expresión de filtro escalar.

  • outputFields (String[], opcional): Lista de campos a devolver.

9. query_entities

• Descripción: Consulta entidades según condiciones escalares, sin involucrar búsqueda vectorial.

• Parámetros:

  • connectionName (String): Nombre de la conexión objetivo.

  • collectionName (String): Nombre de la colección objetivo.

  • filter (String): Expresión de filtro de Milvus.

  • outputFields (String[], opcional): Lista de campos a devolver.

  • limit (Number, opcional): Número máximo de resultados a devolver, por defecto 100.

10. hybrid_search

• Descripción: Consulta combinada de búsqueda vectorial + filtrado escalar. La diferencia con vector_search es que filter es un parámetro obligatorio.

• Parámetros:

  • connectionName (String): Nombre de la conexión objetivo.

  • collectionName (String): Nombre de la colección objetivo.

  • text (String, opcional): Texto de búsqueda, alternativo a vector.

  • vector (Number[], opcional): Vector de búsqueda original, alternativo a text.

  • filter (String): Obligatorio, expresión de filtro escalar.

  • topK (Number, opcional): Número de resultados a devolver, por defecto 10.

  • outputFields (String[], opcional): Lista de campos a devolver.