Servidor MCP do Elasticsearch Octodet

Servidor MCP Elasticsearch Octodet

O Servidor MCP Elasticsearch Octodet é um poderoso servidor do Protocolo de Contexto de Modelo (MCP) projetado para interação sem costura com clusters Elasticsearch. Ele fornece uma maneira padronizada para aplicações alimentadas por LLM realizarem várias operações, como pesquisar, atualizar e gerenciar dados dentro do Elasticsearch.

Recursos

• Operações Completas do Elasticsearch: Execute operações completas de CRUD em documentos e índices sem esforço.
• Operações em Lote: Melhore o desempenho processando várias operações em uma única chamada de API.
• Atualizações/Exclusões Baseadas em Consulta: Modifique ou remova documentos com base em consultas específicas.
• Gerenciamento de Cluster: Monitore a saúde do seu cluster Elasticsearch, incluindo shards e templates.
• Pesquisa Avançada: Utilize todas as capacidades das consultas DSL do Elasticsearch com suporte embutido para destaque.

Como Instalar

Como um Pacote NPM

Para instalar o Servidor MCP Elasticsearch Octodet globalmente, execute:

npm install -g @octodet/elasticsearch-mcp

Alternativamente, você pode usá-lo diretamente com npx:

npx @octodet/elasticsearch-mcp

A Partir do Código Fonte

1. Clone o repositório.
2. Instale as dependências necessárias:

npm install

3. Construa o servidor:

npm run build

Integração com Clientes MCP

Integração com VS Code

Para integrar com a extensão MCP do VS Code, adicione a seguinte configuração ao seu settings.json:

"mcp.servers": {
  "elasticsearch": {
    "command": "npx",
    "args": [
      "-y", "@octodet/elasticsearch-mcp"
    ],
    "env": {
      "ES_URL": "http://localhost:9200",
      "ES_API_KEY": "sua_chave_api",
      "ES_VERSION": "8"
    }
  }
}

Integração com Claude Desktop

Para Claude Desktop, configure suas definições da seguinte forma:

{
  "mcpServers": {
    "elasticsearch": {
      "command": "npx",
      "args": ["-y", "@octodet/elasticsearch-mcp"],
      "env": {
        "ES_URL": "http://localhost:9200",
        "ES_API_KEY": "sua_chave_api",
        "ES_VERSION": "8"
      }
    }
  }
}

Para Desenvolvimento Local

Se você estiver desenvolvendo o servidor MCP localmente, configure seus clientes para usar sua construção local:

{
  "mcpServers": {
    "elasticsearch": {
      "command": "node",
      "args": ["caminho/para/build/index.js"],
      "env": {
        "ES_URL": "http://localhost:9200",
        "ES_API_KEY": "sua_chave_api",
        "ES_VERSION": "8"
      }
    }
  }
}

Configuração

O servidor pode ser configurado usando as seguintes variáveis de ambiente:

Variável	Descrição	Padrão
ES_URL	URL do servidor Elasticsearch	http://localhost:9200
ES_API_KEY	Chave API para autenticação
ES_USERNAME	Nome de usuário para autenticação
ES_PASSWORD	Senha para autenticação
ES_CA_CERT	Caminho para o certificado CA customizado
ES_VERSION	Versão do Elasticsearch (8 ou 9)	8
ES_SSL_SKIP_VERIFY	Ignorar verificação SSL	false
ES_PATH_PREFIX	Prefixo de caminho para Elasticsearch

Ferramentas

O servidor inclui 16 ferramentas MCP para várias operações do Elasticsearch, cada uma documentada com parâmetros obrigatórios e opcionais.

1. Listar Índices

Recupere uma lista de todos os índices disponíveis do Elasticsearch com informações detalhadas.

Parâmetros:

• indexPattern (opcional, string): Padrão para filtrar índices (por exemplo, "logs-", "meu-índice-")

Exemplo:

{
  "indexPattern": "logs-*"
}

2. Obter Mapeamentos

Busque os mapeamentos de campo para um índice específico do Elasticsearch.

Parâmetros:

• index (obrigatório, string): O nome do índice para o qual recuperar mapeamentos.

Exemplo:

{
  "index": "meu-índice"
}

3. Pesquisar

Realize uma pesquisa no Elasticsearch usando a consulta DSL fornecida e destaque.

Parâmetros:

• index (obrigatório, string): O índice ou índices a serem pesquisados (suporta valores separados por vírgula).
• queryBody (obrigatório, objeto): O corpo da consulta DSL do Elasticsearch.
• highlight (opcional, booleano): Ativar destaque para os resultados da pesquisa (padrão: true).

Exemplo:

{
  "index": "meu-índice",
  "queryBody": {
    "query": {
      "match": {
        "content": "termo de pesquisa"
      }
    },
    "size": 10,
    "from": 0,
    "sort": [{ "_score": { "order": "desc" } }]
  },
  "highlight": true
}

4. Obter Saúde do Cluster

Obtenha informações de saúde sobre o cluster Elasticsearch.

Parâmetros:

• Nenhum obrigatório.

Exemplo:

{}

5. Obter Shards

Recupere informações sobre shards para todos ou índices específicos.

Parâmetros:

• index (opcional, string): Índice específico para obter informações sobre shards. Se omitido, retorna shards para todos os índices.

Exemplo:

{
  "index": "meu-índice"
}

6. Adicionar Documento

Insira um novo documento em um índice específico do Elasticsearch.

Parâmetros:

• index (obrigatório, string): O índice ao qual o documento será adicionado.
• document (obrigatório, objeto): O conteúdo do documento a ser adicionado.
• id (opcional, string): ID do documento. Se omitido, o Elasticsearch gera um automaticamente.

Exemplo:

{
  "index": "meu-índice",
  "id": "doc1",
  "document": {
    "title": "Meu Documento",
    "content": "Conteúdo do documento aqui",
    "timestamp": "2025-06-23T10:30:00Z",
    "tags": ["importante", "rascunho"]
  }
}

7. Atualizar Documento

Modifique um documento existente em um índice específico do Elasticsearch.

Parâmetros:

• index (obrigatório, string): O índice que contém o documento.
• id (obrigatório, string): O ID do documento a ser atualizado.
• document (obrigatório, objeto): O documento parcial com campos a serem atualizados.

Exemplo:

{
  "index": "meu-índice",
  "id": "doc1",
  "document": {
    "title": "Título do Documento Atualizado",
    "last_modified": "2025-06-23T10:30:00Z"
  }
}

8. Deletar Documento

Remova um documento de um índice específico do Elasticsearch.

Parâmetros:

• index (obrigatório, string): O índice que contém o documento.
• id (obrigatório, string): O ID do documento a ser deletado.

Exemplo:

{
  "index": "meu-índice",
  "id": "doc1"
}

9. Atualizar por Consulta

Atualize documentos em um índice do Elasticsearch com base em uma consulta.

Parâmetros:

• index (obrigatório, string): O índice para atualizar documentos.
• query (obrigatório, objeto): Consulta do Elasticsearch para corresponder documentos para atualização.
• script (obrigatório, objeto): Script a ser executado para atualizar documentos correspondentes.
• conflicts (opcional, string): Como lidar com conflitos de versão ("abort" ou "proceed", padrão: "abort").
• refresh (opcional, booleano): Se deve atualizar o índice após a operação (padrão: false).

Exemplo:

{
  "index": "meu-índice",
  "query": {
    "term": {
      "status": "ativo"
    }
  },
  "script": {
    "source": "ctx._source.status = params.newStatus; ctx._source.updated_at = params.timestamp",
    "params": {
      "newStatus": "inativo",
      "timestamp": "2025-06-23T10:30:00Z"
    }
  },
  "conflicts": "proceed",
  "refresh": true
}

10. Deletar por Consulta

Deletar documentos em um índice do Elasticsearch com base em uma consulta.

Parâmetros:

• index (obrigatório, string): O índice para deletar documentos.
• query (obrigatório, objeto): Consulta do Elasticsearch para corresponder documentos para exclusão.
• conflicts (opcional, string): Como lidar com conflitos de versão ("abort" ou "proceed", padrão: "abort").
• refresh (opcional, booleano): Se deve atualizar o índice após a operação (padrão: false).

Exemplo:

{
  "index": "meu-índice",
  "query": {
    "range": {
      "created_date": {
        "lt": "2025-01-01"
      }
    }
  },
  "conflicts": "proceed",
  "refresh": true
}

11. Operações em Lote

Execute várias operações de documentos em uma única chamada de API para melhorar o desempenho.

Parâmetros:

• operations (obrigatório, array): Array de objetos de operação, cada um contendo:
  • action (obrigatório, string): O tipo de operação ("index", "create", "update" ou "delete").
  • index (obrigatório, string): O índice para esta operação.
  • id (opcional, string): ID do documento (obrigatório para update/delete, opcional para index/create).
  • document (condicional, objeto): Conteúdo do documento (obrigatório para operações de index/create/update).

Exemplo:

{
  "operations": [
    {
      "action": "index",
      "index": "meu-índice",
      "id": "doc1",
      "document": { "title": "Documento 1", "content": "Conteúdo aqui" }
    },
    {
      "action": "update",
      "index": "meu-índice",
      "id": "doc2",
      "document": { "title": "Título Atualizado" }
    },
    {
      "action": "delete",
      "index": "meu-índice",
      "id": "doc3"
    }
  ]
}

12. Criar Índice

Crie um novo índice Elasticsearch com configurações e mapeamentos opcionais.

Parâmetros:

• index (obrigatório, string): O nome do índice a ser criado.
• settings (opcional, objeto): Configurações do índice, como número de shards, réplicas, etc.
• mappings (opcional, objeto): Mapeamentos de campo definindo como os documentos devem ser indexados.

Exemplo:

{
  "index": "novo-índice",
  "settings": {
    "number_of_shards": 3,
    "number_of_replicas": 1,
    "analysis": {
      "analyzer": {
        "custom_analyzer": {
          "type": "standard",
          "stopwords": "_english_"
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "title": {
        "type": "text",
        "analyzer": "custom_analyzer"
      },
      "created": {
        "type": "date",
        "format": "yyyy-MM-dd'T'HH:mm:ss'Z'"
      },
      "tags": {
        "type": "keyword"
      }
    }
  }
}

13. Deletar Índice

Delete permanentemente um índice Elasticsearch.

Parâmetros:

• index (obrigatório, string): O nome do índice a ser deletado.

Exemplo:

{
  "index": "meu-índice"
}

14. Contar Documentos

Conte documentos em um índice, opcionalmente filtrados por uma consulta.

Parâmetros:

• index (obrigatório, string): O índice para contar documentos.
• query (opcional, objeto): Consulta do Elasticsearch para filtrar documentos para contagem.

Exemplo:

{
  "index": "meu-índice",
  "query": {
    "bool": {
      "must": [
        { "term": { "status": "ativo" } },
        { "range": { "created_date": { "gte": "2025-01-01" } } }
      ]
    }
  }
}

15. Obter Templates

Recupere templates de índice do Elasticsearch.

Parâmetros:

• name (opcional, string): Nome específico do template a ser recuperado. Se omitido, retorna todos os templates.

Exemplo:

{
  "name": "template-logs"
}

16. Obter Aliases

Busque aliases de índice do Elasticsearch.

Parâmetros:

• name (opcional, string): Nome específico do alias a ser recuperado. Se omitido, retorna todos os aliases.

Exemplo:

{
  "name": "alias-logs"
}

Desenvolvimento

Executando em Modo de Desenvolvimento

Para executar o servidor em modo de observação durante o desenvolvimento, use:

npm run dev

Implementação do Protocolo

Este servidor implementa o Protocolo de Contexto de Modelo para facilitar a comunicação padronizada entre clientes LLM e Elasticsearch. Ele fornece um conjunto abrangente de ferramentas que podem ser invocadas por clientes MCP para realizar várias operações do Elasticsearch.

Adicionando Novas Ferramentas

Para adicionar uma nova ferramenta ao servidor:

1. Defina a ferramenta em src/index.ts usando o formato de registro de ferramentas do servidor MCP.
2. Implemente a funcionalidade necessária em src/utils/elasticsearchService.ts.
3. Atualize este README para documentar a nova ferramenta.

Outros Clientes MCP

O Servidor MCP Elasticsearch Octodet pode ser utilizado com qualquer cliente compatível com MCP, incluindo:

• ChatGPT da OpenAI via plugins MCP
• Claude Desktop da Anthropic
• Claude no VS Code
• Aplicações personalizadas usando o SDK MCP

Uso Programático

Você também pode usar o servidor programaticamente em suas aplicações Node.js:

import { createOctodetElasticsearchMcpServer } from "@octodet/elasticsearch-mcp";
import { CustomTransport } from "@modelcontextprotocol/sdk/server";

// Configure a conexão com o Elasticsearch
const config = {
  url: "http://localhost:9200",
  apiKey: "sua_chave_api",
  version: "8",
};

// Crie e inicie o servidor
async function startServer() {
  const server = await createOctodetElasticsearchMcpServer(config);

  // Conecte-se ao seu transporte personalizado
  const transport = new CustomTransport();
  await server.connect(transport);

  console.log("Servidor MCP Elasticsearch iniciado");
}

startServer().catch(console.error);

Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.