Cómo crear un servidor MCP de Elasticsearch con TypeScript

Cuando se trabaja con grandes bases de conocimiento en Elasticsearch, encontrar información es solo la mitad de la batalla. Los ingenieros suelen necesitar sintetizar resultados de varios documentos, generar resúmenes y rastrear las respuestas hasta sus fuentes. El protocolo de contexto de modelo (MCP) proporciona una manera estandarizada de conectar Elasticsearch con aplicaciones basadas en modelos de lenguaje grande (LLM) para lograr esto. Mientras que Elastic ofrece soluciones oficiales, como Elastic Agent Builder (que incluye un endpoint MCP entre sus características), construir un servidor MCP personalizado te brinda control total sobre la lógica de búsqueda, el formato de resultados y cómo se pasa el contenido recuperado a un LLM para síntesis, resúmenes y citas.

En este artículo, exploraremos las ventajas de construir un servidor MCP personalizado de Elasticsearch y mostraremos cómo crear uno en TypeScript que conecte Elasticsearch con aplicaciones impulsadas por LLM.

¿Por qué construir un servidor MCP personalizado de Elasticsearch?

Elastic ofrece algunas alternativas para los servidores MCP:

• Servidor MCP de Elastic Agent Builder para Elasticsearch 9.2+
• Servidor MCP de Elasticsearch para versiones anteriores (Python)

Si necesitas más control sobre cómo tu servidor MCP interactúa con Elasticsearch, construir tu propio servidor personalizado te da la flexibilidad de adaptarlo exactamente a tus necesidades. Por ejemplo, el endpoint MCP de Agent Builder está limitado a las consultas de lenguaje de búsqueda (ES|QL) de Elasticsearch, mientras que un servidor personalizado te permite usar el DSL de consulta completo. También obtienes control sobre cómo se formatean los resultados antes de pasarlos al LLM y puedes integrar pasos de procesamiento adicionales, como el resumen impulsado por OpenAI que implementaremos en este tutorial.

Al final de este artículo, tendrás un servidor MCP en TypeScript que busca información almacenada en un índice de Elasticsearch, la resume y proporciona citas. Usaremos Elasticsearch para la recuperación, el modelo gpt-4o-mini de OpenAI para resumir y generar citas, y Claude Desktop como cliente MCP y UI para recibir las búsquedas de los usuarios y dar respuestas. El resultado final es un asistente de conocimiento interno que ayuda a los ingenieros a descubrir y sintetizar las mejores prácticas en los documentos técnicos de su organización.

Requisitos previos:

• Node.js 20 +
• Elasticsearch
• Clave de API de OpenAI
• Claude Desktop

¿Qué es MCP?

MCP es un estándar abierto, creado por Anthropic, que ofrece conexiones seguras y bidireccionales entre los modelos de lenguaje grande (LLM) y sistemas externos, como Elasticsearch. Puedes leer más sobre el estado actual del MCP en este artículo.

El panorama de MCP evoluciona cada día, con servidores disponibles para una amplia gama de casos de uso. Además de eso, desarrollar tu propio servidor MCP personalizado es fácil, como te mostraremos en este artículo.

Clientes del MCP

Hay una larga lista de clientes del MCP disponibles, cada uno con sus propias características y limitaciones. Por su sencillez y popularidad, usaremos Claude Desktop como nuestro cliente MCP. Servirá como interfaz de chat en la que los usuarios podrán hacer preguntas en lenguaje natural e invocar automáticamente las herramientas expuestas por nuestro servidor MCP para buscar documentos y generar resúmenes.

Cómo crear un servidor MCP de Elasticsearch

Con el SDK de TypeScript, podemos crear fácilmente un servidor que entiende cómo hacer búsquedas en nuestros datos de Elasticsearch con base en la entrada de búsqueda del usuario.

Estos son los pasos en este artículo para integrar el servidor MCP de Elasticsearch con el cliente Claude Desktop:

1. Configurar el servidor MCP para Elasticsearch.
2. Carga el servidor MCP en Claude Desktop.
3. Pruébalo.

Configurar el servidor MCP para Elasticsearch

Para comenzar, inicialicemos una aplicación de nodo:

Esto creará un archivo package.json y, con él, podremos empezar a instalar las dependencias necesarias para esta aplicación.

• @elastic/elasticsearch nos dará acceso a la biblioteca de Elasticsearch para Node.js.
• @modelcontextprotocol/sdk proporciona las herramientas básicas para crear y administrar un servidor MCP, registrar herramientas y manejar la comunicación con los clientes de MCP.
• openAI permite la interacción con modelos OpenAI para generar resúmenes o respuestas en lenguaje natural.
• zod ayuda a definir y validar esquemas estructurados para los datos de entrada y salida en cada herramienta.

ts-node, @types/node y typescript se usarán durante el desarrollo para escribir el código y compilar los scripts.

Configura los sets de datos

Para proporcionar los datos que Claude Desktop puede consultar con nuestro servidor de MCP, utilizaremos un conjunto de datos de base de conocimiento interna simulado. Así es como se verá un documento de este sets de datos:

Para cargar los datos, preparamos un script que cree un índice en Elasticsearch y cargue el set de datos en él. Puedes encontrarlo aquí.

Servidor MCP

Crea un archivo llamado index.ts y agrega el siguiente código para importar las dependencias y gestionar las variables de entorno:

Además, preparemos a los clientes para que gestionen las llamadas a Elasticsearch y OpenAI:

Para hacer nuestra implementación más robusta y asegurar entradas y salidas estructuradas, definiremos esquemas usando zod. Esto nos permite validar los datos en tiempo de ejecución, detectar errores a tiempo y facilitar el procesamiento de las respuestas de la herramienta mediante código:

Descubre más sobre las salidas estructuradas aquí.

Ahora vamos a inicializar el servidor MCP:

Definición de las herramientas MCP

Ahora que ya tenemos todo configurado, podemos empezar a desarrollar las herramientas que ofrecerá nuestro servidor MCP. Este servidor ofrece dos herramientas:

• search_docs: Búsquedas de documentos en Elasticsearch mediante la búsqueda de texto.
• summarize_and_cite: Resume y sintetiza información de documentos previamente recuperados para responder a una pregunta del usuario. Esta herramienta también agrega citas que hacen referencia a los documentos originales.

Juntas, estas herramientas forman un flujo de trabajo simple de “recuperación y resumen”, donde una herramienta busca documentos relevantes y la otra usa esos documentos para generar una respuesta resumida y citada.

Formato de respuesta de herramienta

Cada herramienta puede aceptar parámetros de entrada arbitrarios, pero debe responder con la siguiente estructura:

• Contenido: esta es la respuesta de la herramienta en un formato no estructurado. Este campo se suele usar para mostrar texto, imágenes, audio, enlaces o contenido incrustado. Para esta aplicación, se utilizará para devolver texto formateado con la información generada por las herramientas.
• structuredContent: este es un retorno opcional que se usa para proporcionar los resultados de cada herramienta en un formato estructurado. Esto es útil para fines programáticos. Aunque no se usa en este servidor de MCP, puede ser útil si quieres desarrollar otras herramientas o procesar los resultados mediante programación.

Con esa estructura en mente, comencemos con cada herramienta en detalle.

Herramienta Search_docs

Esta herramienta realiza una búsqueda de texto completo en el índice de Elasticsearch para recuperar los documentos más relevantes según la consulta del usuario. Destaca los resultados clave y ofrece una visión general rápida con puntuaciones de relevancia.

Configuramos fuzziness: “AUTO” para que tenga una tolerancia tipográfica variable basada en la longitud del token que se está analizando. También establecemos title^2 para aumentar la puntuación de los documentos donde se produce la coincidencia en el campo de título.

herramienta de resumen y cita: summarize_and_cite

Esta herramienta genera un resumen basado en los documentos recuperados en la búsqueda anterior. Usa el modelo gpt-4o-mini de OpenAI para sintetizar la información más relevante y responder a la pregunta del usuario para obtener respuestas derivadas directamente de los resultados de búsqueda. Además del resumen, también devuelve metadatos de citas para los documentos fuente utilizados.

Finalmente, necesitamos iniciar el servidor a través de stdio. Esto significa que el cliente MCP se comunicará con nuestro servidor leyendo y escribiendo en sus flujos estándar de entrada y salida. stdio es la opción de transporte más sencilla y funciona bien para servidores MCP locales lanzados como subprocesos por el cliente. Agrega el siguiente código al final del archivo:

Ahora compila el proyecto usando el siguiente comando:

Esto creará una carpeta dist y, dentro de ella, un archivo index.js.

Carga el servidor MCP en Claude Desktop

Sigue esta guía para configurar el servidor MCP con Claude Desktop. En el archivo de configuración de Claude, tienes que establecer los siguientes valores:

El valor args debe apuntar al archivo compilado en la carpeta dist. También es necesario configurar las variables de entorno en el archivo de configuración con los mismos nombres exactos definidos en el código.

Pruébalo

Antes de ejecutar cada herramienta, haz clic en Búsqueda y herramientas para asegurarte de que las herramientas estén habilitadas. Aquí también puedes habilitar o deshabilitar cada una de ellas:

Finalmente, probemos el servidor MCP desde el chat de Claude Desktop y comencemos a hacer preguntas:

Para la consulta"Buscar documentos sobre métodos de autenticación y control de acceso basado en roles", se ejecuta la herramienta search_docs y arroja los siguientes resultados:

La respuesta es: “¡Genial! Encontré 5 documentos relevantes sobre métodos de autenticación y control de acceso basado en roles. Esto es lo que se encontró:”

La llamada a la herramienta devuelve los documentos de origen como parte de su carga útil de respuesta, que luego se utilizan para generar citas.

También es posible encadenar varias herramientas en una sola interacción. En este caso, Claude Desktop analiza la pregunta del usuario y determina que primero debe llamar a search_docs para recuperar documentos relevantes y luego pasar esos resultados a summarize_and_cite para generar la respuesta final, todo eso sin requerir indicaciones separadas del usuario:

En este caso, para la búsqueda: "¿Cuáles son las principales recomendaciones para mejorar la autenticación y el control de acceso en todos nuestros sistemas? Incluye referencias.", obtuvimos los siguientes resultados:

Al igual que en el paso anterior, podemos ver la respuesta de cada herramienta a esta pregunta:

Nota: si aparece un submenú que pregunta si apruebas el uso de cada herramienta, selecciona Permitir siempre o Permitir una vez.

Conclusión

Los servidores MCP representan un paso significativo hacia la estandarización de las herramientas LLM para aplicaciones tanto locales como remotas. Aunque la compatibilidad total todavía está en proceso, nos estamos moviendo rápido en esa dirección.

En este artículo, aprendimos cómo construir un servidor MCP personalizado en TypeScript que conecta Elasticsearch con aplicaciones impulsadas por modelos LLM. Nuestro servidor expone dos herramientas: search_docs para recuperar documentos relevantes con Query DSL y summarize_and_cite para generar resúmenes con citas a través de modelos de OpenAI y Claude Desktop como client UI.

El futuro de la compatibilidad entre los distintos proveedores de clientes y servidores parece prometedor. Los próximos pasos consisten en agregar más funcionalidades y flexibilidad a tu agente. Hay un artículo práctico sobre cómo puedes agregar parámetros a tus consultas a través de plantillas de búsqueda para ganar precisión y flexibilidad.