mcp-meilisearch

Servidor API de MCP Meilisearch

Una implementación de servidor de Protocolo de Contexto de Modelo (MCP) que proporciona un puente entre los modelos de IA y el motor de búsqueda Meilisearch.

Descripción general

• Servidor MCP : expone las API de Meilisearch como herramientas utilizando el Protocolo de contexto de modelo.
• Demostración de cliente web : una interfaz de demostración que muestra las funcionalidades de búsqueda.
• Inferencia de IA : selección inteligente de herramientas basada en consultas del usuario.

Características principales

• Múltiples opciones de transporte : admite transportes STDIO y StreamableHTTP.
• Soporte de API de Meilisearch : acceso completo a las funcionalidades de Meilisearch.
• Demostración del cliente web : Interfaz actualizada que muestra capacidades y funciones de búsqueda.
• Inferencia de IA : aprovecha los LLM de proveedores como OpenAIo HuggingFace para determinar y utilizar de forma inteligente la herramienta más adecuada para las consultas de los usuarios.

Empezando

Prerrequisitos

• Node.js v20 o superior.
• Una instancia de Meilisearch en ejecución (local o remota).
• Clave API para Meilisearch (si es necesario).
• Clave API del proveedor de IA (si se utiliza inferencia de IA).

Instalación

Instalar el paquete:

Opciones

Opciones de conexión de Meilisearch

• meilisearchHost : URL de la instancia de Meilisearch (predeterminado: " http://localhost:7700 ")
• meilisearchApiKey : clave API para autenticarse con Meilisearch (predeterminado: "")

Opciones del servidor MCP

• transport : Tipo de transporte para el servidor MCP ("http" | "stdio") (predeterminado: "http")
• httpPort : puerto HTTP para el servidor MCP (predeterminado: 4995)
• mcpEndpoint : ruta del punto final de MCP (predeterminado: "/mcp")

Opciones de sesión

• sessionTimeout : Tiempo de espera de la sesión en milisegundos (predeterminado: 3600000)
• sessionCleanupInterval : intervalo de limpieza de sesión en milisegundos (predeterminado: 60000)

Opciones de inferencia de IA

• aiProviderName : Nombre del proveedor de IA ("openai" | "huggingface" | "openrouter" | "ollama") (Predeterminado: "openai")
• aiProviderApiKey : clave API del proveedor de IA para la inferencia de IA
• llmModel : Modelo de IA a utilizar (predeterminado: "gpt-3.5-turbo")

Tenga en cuenta que no todos los modelos admiten la llamada a funciones, necesaria para una inferencia de IA adecuada en este paquete. Asegúrese de seleccionar un modelo que admita el parámetro de herramientas.

Ejemplo de configuración del servidor

Uso de MCPClient

El paquete exporta la clase MCPClient para la integración del lado del cliente:

Métodos de cliente de inferencia de IA

callToolWithAI(query, options)

Procesa una consulta del usuario a través de IA para determinar y ejecutar la herramienta más adecuada.

Parámetros:

• query : Cadena: la consulta o solicitud del usuario que se procesará
• options : Objeto (Opcional) - Opciones de configuración
  • specificTools : String[] (opcional) - Restringe la selección de herramientas a esta lista de nombres de herramientas
  • justReasoning : Boolean (opcional): cuando se establece en true , devuelve solo el razonamiento de la IA sin ejecutar la herramienta seleccionada

Iniciando el servidor

Puede iniciar el servidor mediante programación:

Herramientas

El servidor MCP expone diversas herramientas que permiten interactuar con las funcionalidades de Meilisearch. Cada herramienta corresponde a un punto final específico de la API de Meilisearch, lo que permite realizar operaciones como búsquedas, indexación y gestión de documentos.

Categorías de herramientas

1. Herramientas del sistema : comprobaciones de estado, información de versión, estadísticas del servidor.
2. Herramientas de índice : Administrar índices (crear, actualizar, eliminar, listar).
3. Herramientas de documentos : agregue, actualice, elimine y recupere documentos.
4. Herramientas de búsqueda : Búsqueda avanzada, incluida búsqueda vectorial.
5. Herramientas de configuración : configure los ajustes del índice.
6. Herramientas de tareas : Administrar tareas asincrónicas.
7. Herramientas vectoriales : capacidades de búsqueda vectorial experimental.

Herramientas del sistema

salud

• Descripción : Comprueba si el servidor Meilisearch está en buen estado.

versión

• Descripción : Obtenga la información de la versión del servidor Meilisearch.

información

• Descripción : Obtenga la información del sistema del servidor Meilisearch.

estadísticas

• Descripción : Obtenga estadísticas sobre todos los índices o un índice específico.
• Parámetros :
  • indexUid (cadena, opcional): identificador único del índice.

obtener tareas

• Descripción : Obtenga información sobre las tareas con filtrado opcional.
• Parámetros :
  • limit (número, opcional): número máximo de tareas a devolver.
  • from (número, opcional): uid de la tarea desde el cual comenzar la búsqueda.
  • status (cadena, opcional): Estado de las tareas a devolver.
  • type (cadena, opcional): tipo de tareas a devolver.
  • indexUids (string[], opcional): UID de los índices en los que se realizaron tareas.

eliminar tareas

• Descripción : Eliminar tareas según los filtros proporcionados.
• Parámetros :
  • statuses (cadena[], opcional): estados de las tareas a eliminar.
  • types (cadena[], opcional): tipos de tareas a eliminar.
  • indexUids (string[], opcional): UID de los índices en los que se realizaron las tareas a eliminar.
  • uids (número[], opcional): UID de las tareas a eliminar.
  • canceledBy (number[], opcional): UID de las tareas que cancelaron las tareas a eliminar.
  • beforeUid (número, opcional): elimina las tareas cuyo uid sea anterior a este valor.
  • beforeStartedAt (cadena, opcional): elimina las tareas que comenzaron a procesarse antes de esta fecha (formato ISO 8601).
  • beforeFinishedAt (cadena, opcional): elimina las tareas que finalizaron su procesamiento antes de esta fecha (formato ISO 8601).

Herramientas de índice

índices de lista

• Descripción : enumera todos los índices en la instancia de Meilisearch.
• Parámetros :
  • limit (número, opcional): número máximo de índices a devolver.
  • offset (número, opcional): Número de índices a omitir.

obtener índice

• Descripción : Obtenga información sobre un índice específico de Meilisearch.
• Parámetros :
  • indexUid (cadena, obligatoria): identificador único del índice.

crear-índice

• Descripción : Crea un nuevo índice de Meilisearch.
• Parámetros :
  • indexUid (cadena, obligatoria): identificador único para el nuevo índice.
  • primaryKey (cadena, opcional): clave principal para el índice.

índice de actualización

• Descripción : Actualiza un índice de Meilisearch (actualmente solo admite la actualización de la clave principal).
• Parámetros :
  • indexUid (cadena, obligatoria): identificador único del índice.
  • primaryKey (cadena, obligatoria): nueva clave principal para el índice.

eliminar índice

• Descripción : Eliminar un índice de Meilisearch.
• Parámetros :
  • indexUid (cadena, obligatoria): identificador único del índice a eliminar.

índices de swap

• Descripción : Intercambia dos o más índices en Meilisearch.
• Parámetros :
  • indexes (cadena, obligatoria): matriz JSON de pares de índices para intercambiar, por ejemplo, [["movies", "movies_new"]].

Herramientas de documentos

obtener documentos

• Descripción : Obtenga documentos de un índice de Meilisearch.
• Parámetros :
  • indexUid (cadena, obligatoria): identificador único del índice.
  • limit (número, opcional): número máximo de documentos a devolver (predeterminado: 20).
  • offset (número, opcional): Número de documentos a omitir (predeterminado: 0).
  • fields (string[], opcional): Campos a devolver en los documentos.
  • filter (cadena, opcional): consulta de filtro a aplicar.

obtener documento

• Descripción : Obtenga un documento por su ID de un índice de Meilisearch.
• Parámetros :
  • indexUid (cadena, obligatoria): identificador único del índice.
  • documentId (cadena, obligatoria): ID del documento a recuperar.
  • fields (cadena[], opcional): Campos a devolver en el documento.

agregar documentos

• Descripción : Agrega documentos a un índice de Meilisearch.
• Parámetros :
  • indexUid (cadena, obligatoria): identificador único del índice.
  • documents (cadena, obligatoria): matriz JSON de documentos para agregar.
  • primaryKey (cadena, opcional): clave principal para los documentos.

actualizar documentos

• Descripción : Actualizar documentos en un índice de Meilisearch.
• Parámetros :
  • indexUid (cadena, obligatoria): identificador único del índice.
  • documents (cadena, obligatoria): matriz JSON de documentos para actualizar.
  • primaryKey (cadena, opcional): clave principal para los documentos.

eliminar documento

• Descripción : Eliminar un documento por su ID de un índice de Meilisearch.
• Parámetros :
  • indexUid (cadena, obligatoria): identificador único del índice.
  • documentId (cadena, obligatoria): ID del documento a eliminar.

eliminar documentos

• Descripción : Elimina varios documentos por sus ID de un índice de Meilisearch.
• Parámetros :
  • indexUid (cadena, obligatoria): identificador único del índice.
  • documentIds (cadena, obligatoria): matriz JSON de ID de documentos que se eliminarán.

eliminar-todos-los-documentos

• Descripción : Eliminar todos los documentos en un índice de Meilisearch.
• Parámetros :
  • indexUid (cadena, obligatoria): identificador único del índice.

Herramientas de búsqueda

buscar

• Descripción : Busca documentos en un índice de Meilisearch.
• Parámetros :
  • indexUid (cadena, obligatoria): identificador único del índice.
  • q (cadena, obligatoria): consulta de búsqueda.
  • limit (número, opcional): número máximo de resultados a devolver (predeterminado: 20).
  • offset (número, opcional): Número de resultados a omitir (predeterminado: 0).
  • filter (cadena, opcional): consulta de filtro a aplicar.
  • sort (string[], opcional): atributos para ordenar, por ejemplo ["price"].
  • facets (cadena[], opcional): Facetas a devolver.
  • attributesToRetrieve (cadena[], opcional): atributos para incluir en los resultados.
  • attributesToCrop (cadena[], opcional): atributos a recortar.
  • cropLength (número, opcional): longitud a la que se recortarán los atributos recortados.
  • attributesToHighlight (string[], opcional): Atributos a resaltar.
  • highlightPreTag (cadena, opcional): etiqueta para insertar antes del texto resaltado.
  • highlightPostTag (cadena, opcional): etiqueta para insertar después del texto resaltado.
  • showMatchesPosition (booleano, opcional): si se deben incluir las posiciones de los partidos en los resultados.
  • matchingStrategy (cadena, opcional): Estrategia de coincidencia: 'todos' o 'último'.

búsqueda múltiple

• Descripción : Realizar múltiples búsquedas en una sola solicitud.
• Parámetros :
  • queries (cadena, obligatoria): matriz JSON de consultas de búsqueda, cada una de las cuales contiene los mismos parámetros que la herramienta search .

búsqueda global

• Descripción : Busque un término en todos los índices de Meilisearch disponibles y devuelva resultados combinados.
• Parámetros :
  • q (cadena, obligatoria): consulta de búsqueda.
  • limit (número, opcional): número máximo de resultados a devolver por índice (predeterminado: 20).
  • attributesToRetrieve (cadena[], opcional): atributos para incluir en los resultados.

búsqueda por facetas

• Descripción : Busque valores de facetas que coincidan con criterios específicos.
• Parámetros :
  • indexUid (cadena, obligatoria): identificador único del índice.
  • facetName (cadena, obligatoria): nombre de la faceta a buscar.
  • facetQuery (cadena, opcional): consulta para comparar con los valores de la faceta.
  • filter (cadena, opcional): filtro para aplicar a la búsqueda base.

Herramientas de configuración

obtener configuraciones

• Descripción : Obtenga todas las configuraciones para un índice de Meilisearch.
• Parámetros :
  • indexUid (cadena, obligatoria): identificador único del índice.

actualizar-configuración

• Descripción : Actualizar la configuración de un índice de Meilisearch.
• Parámetros :
  • indexUid (cadena, obligatoria): identificador único del índice.
  • settings (cadena, obligatoria): objeto JSON que contiene la configuración para actualizar.

restablecer configuración

• Descripción : Restablece todas las configuraciones de un índice de Meilisearch a sus valores predeterminados.
• Parámetros :
  • indexUid (cadena, obligatoria): identificador único del índice.

Obtener herramientas de configuración

Las siguientes herramientas recuperan configuraciones específicas para un índice de Meilisearch:

• obtener atributos mostrados
• obtener atributos de búsqueda
• obtener atributos filtrables
• obtener atributos ordenables
• reglas de clasificación
• palabras clave
• obtener sinónimos
• obtener tolerancia a errores tipográficos
• obtener paginación
• facetado
• obtener diccionario
• obtener precisión de proximidad
• obtener tokens separadores
• obtener tokens no separadores
• diccionario de palabras

Todas estas herramientas tienen el mismo parámetro:

• indexUid (cadena, obligatoria): identificador único del índice.

Herramientas de configuración de actualización

Las siguientes herramientas actualizan configuraciones específicas para un índice de Meilisearch:

• actualizar atributos mostrados
  • indexUid (cadena, obligatoria): identificador único del índice.
  • displayedAttributes (cadena, obligatoria): matriz JSON de atributos para mostrar, por ejemplo, ["título", "descripción"].
• actualizar atributos de búsqueda
  • indexUid (cadena, obligatoria): identificador único del índice.
  • searchableAttributes (cadena, obligatoria): matriz JSON de atributos que se pueden buscar, por ejemplo, ["título", "descripción"].
• actualizar atributos filtrables
  • indexUid (cadena, obligatoria): identificador único del índice.
  • filterableAttributes (cadena, obligatorio): matriz JSON de atributos que se pueden usar como filtros, por ejemplo, ["género", "director"].
• actualizar atributos ordenables
  • indexUid (cadena, obligatoria): identificador único del índice.
  • sortableAttributes (cadena, obligatoria): matriz JSON de atributos que se pueden usar para ordenar, por ejemplo, ["precio", "fecha"].
• actualizar-reglas-de-clasificación
  • indexUid (cadena, obligatoria): identificador único del índice.
  • rankingRules (cadena, obligatoria): matriz JSON de reglas de clasificación, por ejemplo, ["error tipográfico", "palabras", "proximidad", "atributo", "ordenación", "exactitud"].
• actualizar palabras vacías
  • indexUid (cadena, obligatoria): identificador único del índice.
  • stopWords (cadena, obligatoria): matriz JSON de palabras que se ignorarán en las consultas de búsqueda, por ejemplo, ["el", "un", "un"].
• actualizar-sinónimos
  • indexUid (cadena, obligatoria): identificador único del índice.
  • synonyms (cadena, obligatorio): objeto JSON que asigna palabras a sus sinónimos, por ejemplo {"movie": ["film"]}.
• actualización de tolerancia a errores tipográficos
  • indexUid (cadena, obligatoria): identificador único del índice.
  • typoTolerance (cadena, obligatoria): objeto JSON con configuración de tolerancia a errores tipográficos, por ejemplo, {"enabled": true, "minWordSizeForTypos": {"oneTypo": 5, "twoTypos": 9}}.
• actualización-paginación
  • indexUid (cadena, obligatoria): identificador único del índice.
  • pagination (cadena, obligatoria): objeto JSON con configuración de paginación, por ejemplo {"maxTotalHits": 1000}.
• actualización de facetas
  • indexUid (cadena, obligatoria): identificador único del índice.
  • faceting (cadena, obligatorio): objeto JSON con configuración de facetado, p. ej. {"maxValuesPerFacet": 100}.
• actualizar diccionario
  • indexUid (cadena, obligatoria): identificador único del índice.
  • dictionary (cadena, obligatorio): matriz JSON de palabras que se considerarán como una sola palabra, por ejemplo, ["San Francisco", "Nueva York"].
• actualizar-proximidad-precisión
  • indexUid (cadena, obligatoria): identificador único del índice.
  • proximityPrecision (cadena, obligatoria): cadena con valor de precisión de proximidad, puede ser 'byWord' o 'byAttribute'.
• tokens separadores de actualización
  • indexUid (cadena, obligatoria): identificador único del índice.
  • separatorTokens (cadena, obligatoria): matriz JSON de tokens que deben considerarse como separadores de palabras, por ejemplo, ["-", "_"].
• actualizar tokens no separadores
  • indexUid (cadena, obligatoria): identificador único del índice.
  • nonSeparatorTokens (cadena, obligatoria): matriz JSON de tokens que no deben considerarse como separadores de palabras, por ejemplo, ["@", "."].
• actualizar diccionario de palabras
  • indexUid (cadena, obligatoria): identificador único del índice.
  • wordDictionary (cadena, obligatoria): matriz JSON de palabras personalizadas para agregar al diccionario, por ejemplo, ["cbuilder", "meilisearch"].

Herramientas para restablecer configuraciones

Las siguientes herramientas restablecen configuraciones específicas para un índice de Meilisearch a sus valores predeterminados:

• restablecer atributos mostrados
• restablecer atributos de búsqueda
• restablecer atributos filtrables
• atributos ordenables restablecidos
• restablecer reglas de clasificación
• restablecer palabras vacías
• restablecer sinónimos
• restablecer la tolerancia a errores tipográficos
• restablecer paginación
• restablecimiento de facetas
• reiniciar diccionario
• restablecer proximidad-precisión
• tokens separadores de reinicio
• restablecer tokens no separadores
• restablecer diccionario de palabras

Todas estas herramientas de reinicio tienen el mismo parámetro:

• indexUid (cadena, obligatoria): identificador único del índice.

Herramientas de tareas

lista de tareas

• Descripción : Lista de tareas con filtrado opcional.
• Parámetros :
  • limit (número, opcional): número máximo de tareas a devolver.
  • from (número, opcional): uid de la tarea desde el cual comenzar la búsqueda.
  • statuses (cadena[], opcional): estados de las tareas a devolver.
  • types (cadena[], opcional): tipos de tareas a devolver.
  • indexUids (string[], opcional): UID de los índices en los que se realizaron tareas.
  • uids (número[], opcional): UID de tareas específicas para devolver.

obtener tarea

• Descripción : Obtener información sobre una tarea específica.
• Parámetros :
  • taskUid (número, obligatorio): Identificador único de la tarea.

cancelar tareas

• Descripción : Cancelar tareas según los filtros proporcionados.
• Parámetros :
  • statuses (cadena[], opcional): estados de las tareas a cancelar.
  • types (cadena[], opcional): Tipos de tareas a cancelar.
  • indexUids (string[], opcional): UID de los índices en los que se realizaron tareas a cancelar.
  • uids (número[], opcional): UID de las tareas a cancelar.

esperar la tarea

• Descripción : Esperar a que se complete una tarea específica.
• Parámetros :
  • taskUid (número, obligatorio): identificador único de la tarea a esperar.
  • timeoutMs (número, opcional): tiempo máximo de espera en milisegundos (predeterminado: 5000).
  • intervalMs (número, opcional): intervalo de sondeo en milisegundos (predeterminado: 500).

Herramientas vectoriales

habilitar la búsqueda vectorial

• Descripción : Habilite la función experimental de búsqueda vectorial en Meilisearch.

obtener características experimentales

• Descripción : Obtenga el estado de las funciones experimentales en Meilisearch.

actualización de incrustadores

• Descripción : Configurar incrustadores para la búsqueda vectorial.
• Parámetros :
  • indexUid (cadena, obligatoria): identificador único del índice.
  • embedders (cadena, obligatorio): objeto JSON que contiene configuraciones de embedder.

obtener incrustadores

• Descripción : Obtenga la configuración de incrustadores para un índice.
• Parámetros :
  • indexUid (cadena, obligatoria): identificador único del índice.

reiniciadores-incrustadores

• Descripción : Restablecer la configuración de incrustadores para un índice.
• Parámetros :
  • indexUid (cadena, obligatoria): identificador único del índice.

búsqueda vectorial

• Descripción : Realiza una búsqueda vectorial en un índice de Meilisearch.
• Parámetros :
  • indexUid (cadena, obligatoria): identificador único del índice.
  • vector (cadena, obligatoria): matriz JSON que representa el vector a buscar.
  • limit (número, opcional): número máximo de resultados a devolver (predeterminado: 20).
  • offset (número, opcional): Número de resultados a omitir (predeterminado: 0).
  • filter (cadena, opcional): filtro a aplicar (por ejemplo, 'género = terror Y año > 2020').
  • embedder (cadena, opcional): nombre del embedder a utilizar (si se omite, se debe proporcionar un 'vector').
  • attributes (cadena[], opcional): atributos a incluir en la búsqueda vectorial.
  • query (cadena, opcional): consulta de texto a buscar (si se usa 'embedder' en lugar de 'vector').
  • hybrid (booleano, opcional): si se debe realizar una búsqueda híbrida (combinando búsqueda vectorial y de texto).
  • hybridRatio (número, opcional): relación entre la búsqueda vectorial y la búsqueda de texto en la búsqueda híbrida (0-1, valor predeterminado: 0,5).