Criando um servidor MCP do Elasticsearch com TypeScript

Ao trabalhar com grandes bases de conhecimento no Elasticsearch, encontrar informações é apenas metade da batalha. Engenheiros precisam sintetizar resultados de múltiplos documentos, gerar resumos e rastrear respostas até as fontes. Para isso, o Protocolo de Contexto do Modelo (MCP) oferece uma maneira padronizada de conectar o Elasticsearch a aplicativos baseados em grandes modelos de linguagem (LLM). Embora a Elastic ofereça soluções oficiais, como o Elastic Agent Builder (que inclui um endpoint MCP entre os recursos), a criação de um servidor MCP personalizado oferece controle total sobre a lógica de busca, a formatação dos resultados e como o conteúdo recuperado é passado para um LLM para síntese, resumos e citações.

Neste artigo, exploraremos os benefícios de criar um servidor MCP do Elasticsearch personalizado e mostraremos como criar um servidor em TypeScript que conecte o Elasticsearch a aplicativos com LLM.

Por que criar um servidor MCP do Elasticsearch personalizado?

A Elastic oferece algumas alternativas para servidores MCP:

• Servidor MCP do Elastic Agent Builder para Elasticsearch 9.2+
• Servidor MCP do Elasticsearch para versões mais antigas (Python)

Se você precisar de mais controle sobre como o servidor MCP interage com o Elasticsearch, a criação do seu próprio servidor personalizado oferece a flexibilidade de adaptá-lo exatamente às suas necessidades. Por exemplo, o endpoint MCP do Agent Builder é limitado a consultas em Elasticsearch Query Language (ES|QL), enquanto um servidor personalizado permite usar o Query DSL completo. Você também tem controle sobre como os resultados são formatados antes de serem passados para o LLM e pode integrar etapas adicionais de processamento, como o resumo com tecnologia OpenAI que implementaremos neste tutorial.

Ao final deste artigo, você terá um servidor MCP no TypeScript que busca informações armazenadas em um índice do Elasticsearch, resume essas informações e fornece citações. Usaremos o Elasticsearch para recuperação, o modelo gpt-4o-mini da OpenAI para resumir e gerar citações, e o Claude Desktop como cliente MCP e UI para receber consultas dos usuários e dar respostas. O resultado é um assistente de conhecimento interno que ajuda os engenheiros a entender e sintetizar as práticas recomendadas nos documentos técnicos de sua organização.

Pré-requisitos:

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

O que é MCP?

O MCP é um padrão aberto, criado pela Anthropic, que oferece conexões seguras e bidirecionais entre LLMs e sistemas externos, como o Elasticsearch. Você pode ler mais sobre a situação atual do MCP neste artigo.

O cenário de MCP está em constante evolução, com servidores disponíveis para uma ampla gama de casos de uso. Além disso, é fácil criar seu próprio servidor MCP personalizado, como mostraremos neste artigo.

Clientes do MCP

Há uma longa lista de clientes MCP disponíveis, cada um com as próprias características e limitações. Por simplicidade e popularidade, usaremos o Claude Desktop como nosso cliente MCP. Ele servirá como interface de chat na qual os usuários poderão fazer perguntas em linguagem natural e que invocará automaticamente as ferramentas expostas pelo nosso servidor MCP para buscar documentos e gerar resumos.

Criando um servidor MCP do Elasticsearch

Usando o TypeScript SDK, podemos criar um servidor que entende como consultar nossos dados do Elasticsearch com base em uma entrada de consulta do usuário.

Aqui estão os passos deste artigo para integrar o servidor MCP do Elasticsearch com o cliente Claude Desktop:

1. Configure o servidor MCP para o Elasticsearch.
2. Carregue o servidor MCP no Claude Desktop.
3. Faça o teste.

Configure o servidor MCP para o Elasticsearch

Para começar, vamos iniciar uma aplicação de nó:

Isso criará um arquivo package.json e, com ele, poderemos começar a instalar as dependências necessárias para essa aplicação.

• @elastic/elasticsearch nos dará acesso à biblioteca Elasticsearch Node.js.
• @modelcontextprotocol/sdk fornece as ferramentas de núcleo para criar e gerenciar um servidor MCP, registrar ferramentas e lidar com a comunicação com clientes MCP.
• openai permite a interação com modelos OpenAI para gerar resumos ou respostas em linguagem natural.
• zod ajuda a definir e validar esquemas estruturados para dados de entrada e saída em cada ferramenta.

ts-node, @types/node, e typescript serão usados durante o desenvolvimento para digitar o código e compilar os scripts.

Configurar o conjunto de dados

Para fornecer os dados que o Claude Desktop pode consultar usando nosso servidor MCP, usaremos um conjunto de dados fictício de base de conhecimento interna. Veja como será um documento desse conjunto de dados:

Para ingerir os dados, preparamos um script que cria um índice no Elasticsearch e carrega o conjunto de dados nele. Você pode encontrá-lo aqui.

Servidor MCP

Crie um arquivo chamado index.ts e adicione o seguinte código para importar as dependências e lidar com as variáveis de ambiente:

Além disso, vamos inicializar os clientes para lidar com as chamadas do Elasticsearch e do OpenAI:

Para tornar nossa implementação mais robusta e garantir entrada e saída estruturadas, definiremos esquemas usando zod. Isso nos permite validar dados em tempo de execução, detectar erros com antecedência e facilitar o processamento de forma programática das respostas da ferramenta:

Saiba mais sobre saídas estruturadas aqui.

Agora vamos inicializar o servidor MCP:

Definição das ferramentas MCP

Com tudo configurado, podemos começar a escrever as ferramentas que serão expostas pelo nosso servidor MCP. Esse servidor expõe duas ferramentas:

• search_docs: Busca por documentos no Elasticsearch usando busca de texto completo.
• summarize_and_cite: Resume e sintetiza informações de documentos previamente recuperados para responder a uma pergunta do usuário. Essa ferramenta também adiciona citações que referenciam os documentos fonte.

Juntas, essas ferramentas formam um fluxo de trabalho simples de "recuperar e resumir", em que uma ferramenta busca documentos relevantes e a outra usa esses documentos para gerar uma resposta resumida e citada.

Formato de resposta da ferramenta

Cada ferramenta pode aceitar parâmetros de entrada arbitrários, mas deve responder com a seguinte estrutura:

• Conteúdo: esta é a resposta da ferramenta em um formato não estruturado. Este campo geralmente é usado para retornar texto, imagens, áudio, links ou embeddings. Para esta aplicação, ele será usado para retornar texto formatado com as informações geradas pelas ferramentas.
• structuredContent: Esse é um retorno opcional usado para fornecer os resultados de cada ferramenta em um formato estruturado. É útil para fins programáticos. Embora não seja usado neste servidor MCP, pode ser útil caso você queira desenvolver outras ferramentas ou processar os resultados programaticamente.

Com essa estrutura em mente, vamos nos aprofundar em cada ferramenta em detalhes.

Ferramenta de Busca de Documentos

Esta ferramenta realiza uma busca de texto completo no índice do Elasticsearch para recuperar os documentos mais relevantes com base na consulta do usuário. Ele destaca correspondências-chave e oferece uma visão geral rápida com pontuações de relevância.

Configuramos fuzziness: “AUTO” para ter uma tolerância variável de erros de digitação com base no comprimento do token que está sendo analisado. Também definimos title^2 para aumentar a pontuação dos documentos onde a correspondência ocorre no campo de título.

Ferramenta summarize_and_cite

Esta ferramenta gera um resumo baseado em documentos recuperados na busca anterior. Usa o modelo gpt-4o-mini da OpenAI para sintetizar as informações mais relevantes e responder à pergunta do usuário, fornecendo respostas derivadas diretamente dos resultados da busca. Além do resumo, também retorna metadados de citação para os documentos de origem usados.

Por fim, precisamos iniciar o servidor usando stdio. Isso significa que o cliente MCP se comunicará com nosso servidor lendo e escrevendo nos fluxos padrão de entrada e saída. Stdio é a opção de transporte mais simples e funciona bem para servidores MCP locais lançados como subprocessos pelo cliente. Adicione o seguinte código ao final do arquivo:

Agora compile o projeto usando o seguinte comando:

Isso criará uma pasta dist e, dentro dela, um arquivo index.js.

Carregue o servidor MCP no Claude Desktop

Siga este guia para configurar o servidor MCP com o Claude Desktop. No arquivo de configuração Claude, precisamos definir os seguintes valores:

O valor args deve apontar para o arquivo compilado na pasta dist. Você também precisa definir as variáveis de ambiente no arquivo de configuração com exatamente os mesmos nomes definidos no código.

Faça o teste

Antes de executar cada ferramenta, clique em Busca e Ferramentas para garantir que as ferramentas estejam ativadas. Aqui você também pode ativar ou desativar cada uma delas:

Por fim, vamos testar o servidor MCP no chat do Claude Desktop e começar a fazer perguntas:

Para a pergunta “Buscar documentos sobre métodos de autenticação e controle de acesso por função”, a ferramenta search_docs é executada e retorna os seguintes resultados:

A resposta é: "Ótimo! Encontrei 5 documentos relevantes sobre métodos de autenticação e controle de acesso por função. Eis o que foi encontrado:"

A chamada de ferramenta retorna os documentos fonte como parte da carga útil de resposta, que são posteriormente usados para gerar citações.

Também é possível encadear várias ferramentas em uma única interação. Neste caso, o Claude Desktop analisa a pergunta do usuário e determina que precisa primeiro chamar search_docs para recuperar documentos relevantes e depois passar esses resultados para summarize_and_cite para gerar a resposta final, tudo isso sem exigir prompts separados do usuário:

Neste caso, para a consulta “Quais são as principais recomendações para melhorar a autenticação e o controle de acesso em nossos sistemas? Inclua referências.”, obtivemos os seguintes resultados:

Como na etapa anterior, podemos ver a resposta de cada ferramenta para esta pergunta:

Nota: Se aparecer um submenu perguntando se você aprova o uso de cada ferramenta, selecione Permitir sempre ou Permitir uma vez.

Conclusão

Os servidores MCP representam um passo significativo rumo à padronização das ferramentas LLM para aplicações locais e remotas. Embora a compatibilidade total ainda esteja em andamento, estamos avançando nessa direção.

Neste artigo, aprendemos como criar um servidor MCP personalizado em TypeScript que conecta o Elasticsearch a aplicações baseadas em LLM. Nosso servidor expõe duas ferramentas: search_docs para recuperar documentos relevantes usando Query DSL; e summarize_and_cite para gerar resumos com citações via modelos OpenAI e Claude Desktop como UI.

O futuro da compatibilidade entre diferentes provedores de clientes e servidores parece promissor. As próximas etapas incluem adicionar mais funcionalidades e flexibilidade ao seu agente. Existe um artigo prático sobre como parametrizar suas consultas usando modelos de pesquisa para ter precisão e flexibilidade.