MCP Server for Milvus

Servidor MCP para Milvus

El Protocolo de Contexto de Modelo (MCP) es un protocolo abierto que permite una integración fluida entre las aplicaciones LLM y las fuentes de datos y herramientas externas. Ya sea que esté creando un IDE basado en IA, mejorando una interfaz de chat o creando flujos de trabajo de IA personalizados, MCP proporciona una forma estandarizada de conectar las aplicaciones LLM con el contexto que necesitan.

Este repositorio contiene un servidor MCP que proporciona acceso a la funcionalidad de la base de datos de vectores de Milvus .

Prerrequisitos

Antes de utilizar este servidor MCP, asegúrese de tener:

• Python 3.10 o superior
• Una instancia de Milvus en ejecución (local o remota)
• uv instalado (recomendado para ejecutar el servidor)

Uso

La forma recomendada de usar este servidor MCP es ejecutarlo directamente con uv sin necesidad de instalación. Así es como Claude Desktop y Cursor están configurados para usarlo en los ejemplos a continuación.

Si desea clonar el repositorio:

Luego puedes ejecutar el servidor directamente:

Alternativamente, puede cambiar el archivo .env en el directorio src/mcp_server_milvus/ para configurar las variables de entorno y ejecutar el servidor con el siguiente comando:

Importante: el archivo .env tendrá mayor prioridad que los argumentos de la línea de comando.

Modos de ejecución

El servidor admite dos modos de ejecución: stdio (predeterminado) y SSE (eventos enviados por el servidor).

Modo Stdio (predeterminado)

• Descripción : Se comunica con el cliente mediante entrada/salida estándar. Este es el modo predeterminado si no se especifica ningún modo.
• Uso:
  uv run src/mcp_server_milvus/server.py --milvus-uri http://localhost:19530

Modo SSE

• Descripción : Utiliza eventos HTTP enviados por el servidor para la comunicación. Este modo permite la conexión entre varios clientes mediante HTTP y es adecuado para aplicaciones web.
• Uso:
  uv run src/mcp_server_milvus/server.py --sse --milvus-uri http://localhost:19530 --port 8000
  • --sse : habilita el modo SSE.
  • --port : especifica el puerto para el servidor SSE (predeterminado: 8000).
• Depuración en modo SSE:Si desea depurar en modo SSE, después de iniciar el servicio SSE, ingrese el siguiente comando:
  mcp dev src/mcp_server_milvus/server.py
  La salida será similar a:
  % mcp dev src/mcp_server_milvus/merged_server.py Starting MCP inspector... ⚙️ Proxy server listening on port 6277 🔍 MCP Inspector is up and running at http://127.0.0.1:6274 🚀
  Luego puede acceder al Inspector MCP en http://127.0.0.1:6274 para realizar pruebas.

Aplicaciones compatibles

Este servidor MCP se puede utilizar con varias aplicaciones LLM que admiten el Protocolo de contexto de modelo:

• Claude Desktop : la aplicación de escritorio de Anthropic para Claude
• Cursor : editor de código impulsado por IA con soporte MCP
• Clientes MCP personalizados : cualquier aplicación que implemente la especificación del cliente MCP

Uso con Claude Desktop

Configuración para diferentes modos

Configuración del modo SSE

Siga estos pasos para configurar Claude Desktop para el modo SSE:

1. Instale Claude Desktop desde https://claude.ai/download .
2. Abra el archivo de configuración de Claude Desktop:
   • macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
3. Agregue la siguiente configuración para el modo SSE:

4. Reinicie Claude Desktop para aplicar los cambios.

Configuración del modo Stdio

Para el modo stdio, siga estos pasos:

1. Instale Claude Desktop desde https://claude.ai/download .
2. Abra el archivo de configuración de Claude Desktop:
   • macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
3. Agregue la siguiente configuración para el modo stdio:

4. Reinicie Claude Desktop para aplicar los cambios.

Uso con cursor

Cursor también es compatible con herramientas MCP . Puede integrar su servidor Milvus MCP con Cursor siguiendo estos pasos:

Pasos de integración

1. Abra Cursor Settings > MCP
2. Haga clic en Add new global MCP server
3. Después de hacer clic, se le redirigirá automáticamente al archivo mcp.json , que se creará si no existe.

Configuración del archivo mcp.json

Para el modo Stdio:

Sobrescriba el archivo mcp.json con el siguiente contenido:

Para el modo SSE:

1. Inicie el servicio ejecutando el siguiente comando:
   uv run src/mcp_server_milvus/server.py --sse --milvus-uri http://your_sse_host --port port

   Nota : reemplace http://your_sse_host con su dirección de host SSE real y port con el número de puerto específico que está utilizando.

2. Una vez que el servicio esté en funcionamiento, sobrescriba el archivo mcp.json con el siguiente contenido:
   { "mcpServers": { "milvus-sse": { "url": "http://your_sse_host:port/sse", "disabled": false, "autoApprove": [] } } }

Completando la integración

Después de completar los pasos anteriores, reinicie Cursor o recargue la ventana para asegurarse de que la configuración surta efecto.

Verificando la integración

Para verificar que Cursor se haya integrado correctamente con su servidor Milvus MCP:

1. Abra Cursor Settings > MCP
2. Comprueba si "milvus" o "milvus-sse" aparecen en la lista (según el modo que hayas elegido).
3. Confirme que se enumeran las herramientas relevantes (por ejemplo, milvus_list_collections, milvus_vector_search, etc.)
4. Si el servidor está habilitado pero muestra un error, consulte la sección Solución de problemas a continuación

Herramientas disponibles

El servidor proporciona las siguientes herramientas:

Operaciones de búsqueda y consulta

• milvus_text_search : Busque documentos mediante la búsqueda de texto completo
  • Parámetros:
    • collection_name : Nombre de la colección a buscar
    • query_text : Texto a buscar
    • limit : el número máximo de resultados a devolver (predeterminado: 5)
    • output_fields : Campos a incluir en los resultados
    • drop_ratio : Proporción de términos de baja frecuencia que se deben ignorar (0,0-1,0)
• milvus_vector_search : Realizar una búsqueda de similitud vectorial en una colección
  • Parámetros:
    • collection_name : Nombre de la colección a buscar
    • vector : vector de consulta
    • vector_field : Nombre del campo para la búsqueda de vectores (predeterminado: "vector")
    • limit : el número máximo de resultados a devolver (predeterminado: 5)
    • output_fields : Campos a incluir en los resultados
    • filter_expr : Expresión de filtro
    • metric_type : Métrica de distancia (COSINO, L2, IP) (predeterminado: "COSINO")
• milvus_hybrid_search : Realizar una búsqueda híbrida en una colección
  • Parámetros:
    • collection_name : Nombre de la colección a buscar
    • query_text : Consulta de texto para búsqueda
    • text_field : Nombre del campo para la búsqueda de texto
    • vector : Vector de la consulta de texto
    • vector_field : Nombre del campo para la búsqueda de vectores
    • limit : el número máximo de resultados a devolver
    • output_fields : Campos a incluir en los resultados
    • filter_expr : Expresión de filtro
• milvus_query : Colección de consultas mediante expresiones de filtro
  • Parámetros:
    • collection_name : Nombre de la colección a consultar
    • filter_expr : expresión de filtro (por ejemplo, 'edad > 20')
    • output_fields : Campos a incluir en los resultados
    • limit : el número máximo de resultados a devolver (predeterminado: 10)

Gestión de cobros

• milvus_list_collections : Lista todas las colecciones en la base de datos
• milvus_create_collection : Crea una nueva colección con el esquema especificado
  • Parámetros:
    • collection_name : Nombre para la nueva colección
    • collection_schema : Definición del esquema de colección
    • index_params : Parámetros de índice opcionales
• milvus_load_collection : Carga una colección en la memoria para realizar búsquedas y consultas.
  • Parámetros:
    • collection_name : Nombre de la colección a cargar
    • replica_number : Número de réplicas (predeterminado: 1)
• milvus_release_collection : Liberar una colección de la memoria
  • Parámetros:
    • collection_name : Nombre de la colección a liberar
• milvus_get_collection_info : enumera información detallada como el esquema, las propiedades, el ID de la colección y otros metadatos de una colección específica.
  • Parámetros:
    • collection_name : Nombre de la colección sobre la que se obtendrá información detallada

Operaciones de datos

• milvus_insert_data : insertar datos en una colección
  • Parámetros:
    • collection_name : Nombre de la colección
    • data : Diccionario que asigna nombres de campos a listas de valores
• milvus_delete_entities : eliminar entidades de una colección según una expresión de filtro
  • Parámetros:
    • collection_name : Nombre de la colección
    • filter_expr : Expresión de filtro para seleccionar entidades a eliminar

Variables de entorno

• MILVUS_URI : URI del servidor Milvus (se puede configurar en lugar de --milvus-uri)
• MILVUS_TOKEN : Token de autenticación opcional
• MILVUS_DB : Nombre de la base de datos (predeterminado: "predeterminado")

Desarrollo

Para ejecutar el servidor directamente:

Ejemplos

Uso de Claude Desktop

Ejemplo 1: Listado de colecciones

Luego, Claude utilizará MCP para verificar esta información en su base de datos Milvus.

Ejemplo 2: Búsqueda de documentos

Claude utilizará las capacidades de búsqueda de texto completo de Milvus para encontrar documentos relevantes:

Usando el cursor

Ejemplo: Creación de una colección

En Cursor, puedes preguntar:

El cursor utilizará el servidor MCP para ejecutar esta operación:

Solución de problemas

Problemas comunes

Errores de conexión

Si ve errores como "Error al conectarse al servidor Milvus":

1. Verifique que su instancia de Milvus se esté ejecutando: docker ps (si usa Docker)
2. Comprueba que la URI sea correcta en tu configuración
3. Asegúrese de que no haya reglas de firewall que bloqueen la conexión
4. Intente usar 127.0.0.1 en lugar de localhost en la URI

Problemas de autenticación

Si ve errores de autenticación:

1. Verifique que su MILVUS_TOKEN sea correcto
2. Comprueba si tu instancia de Milvus requiere autenticación
3. Asegúrese de tener los permisos correctos para las operaciones que intenta realizar

Herramienta no encontrada

Si las herramientas MCP no aparecen en Claude Desktop o Cursor:

1. Reiniciar la aplicación
2. Verifique los registros del servidor para detectar cualquier error
3. Verifique que el servidor MCP esté funcionando correctamente
4. Presione el botón de actualización en la configuración de MCP (para el cursor)

Obtener ayuda

Si continúa experimentando problemas:

1. Consulte los problemas de GitHub para ver problemas similares
2. Únete al Discord de la comunidad Zilliz para obtener ayuda.
3. Presentar un nuevo problema con información detallada sobre el mismo