Servidor MCP de Elasticsearch Octodet

Servidor MCP de Elasticsearch Octodet

El servidor MCP de Elasticsearch Octodet es un potente servidor del Protocolo de Contexto de Modelo (MCP) diseñado para una interacción fluida con clústeres de Elasticsearch. Proporciona una forma estandarizada para que las aplicaciones impulsadas por LLM realicen diversas operaciones como buscar, actualizar y gestionar datos dentro de Elasticsearch.

Características

• Operaciones completas de Elasticsearch: Ejecuta operaciones completas de CRUD en documentos e índices sin esfuerzo.
• Operaciones en bloque: Mejora el rendimiento procesando múltiples operaciones en una sola llamada a la API.
• Actualizaciones/Borrados basados en consultas: Modifica o elimina documentos en función de consultas específicas.
• Gestión de clústeres: Monitorea la salud de tu clúster de Elasticsearch, incluidos fragmentos y plantillas.
• Búsqueda avanzada: Utiliza todas las capacidades de las consultas DSL de Elasticsearch con soporte de resaltado incorporado.

Cómo instalar

Como paquete NPM

Para instalar el servidor MCP de Elasticsearch Octodet globalmente, ejecuta:

npm install -g @octodet/elasticsearch-mcp

Alternativamente, puedes usarlo directamente con npx:

npx @octodet/elasticsearch-mcp

Desde el código fuente

1. Clona el repositorio.
2. Instala las dependencias necesarias:

npm install

3. Construye el servidor:

npm run build

Integración con clientes MCP

Integración con VS Code

Para integrar con la extensión MCP de VS Code, agrega la siguiente configuración a tu settings.json:

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

Integración con Claude Desktop

Para Claude Desktop, configura tus ajustes de la siguiente manera:

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

Para desarrollo local

Si estás desarrollando el servidor MCP localmente, configura tus clientes para usar tu construcción local:

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

Configuración

El servidor se puede configurar utilizando las siguientes variables de entorno:

Variable	Descripción	Predeterminado
ES_URL	URL del servidor Elasticsearch	http://localhost:9200
ES_API_KEY	Clave API para autenticación
ES_USERNAME	Nombre de usuario para autenticación
ES_PASSWORD	Contraseña para autenticación
ES_CA_CERT	Ruta al certificado CA personalizado
ES_VERSION	Versión de Elasticsearch (8 o 9)	8
ES_SSL_SKIP_VERIFY	Omitir verificación SSL	false
ES_PATH_PREFIX	Prefijo de ruta para Elasticsearch

Herramientas

El servidor incluye 16 herramientas MCP para diversas operaciones de Elasticsearch, cada una documentada con parámetros requeridos y opcionales.

1. Listar Índices

Recupera una lista de todos los índices de Elasticsearch disponibles con información detallada.

Parámetros:

• indexPattern (opcional, cadena): Patrón para filtrar índices (por ejemplo, "logs-", "mi-índice-")

Ejemplo:

{
  "indexPattern": "logs-*"
}

2. Obtener Mapeos

Obtén los mapeos de campo para un índice específico de Elasticsearch.

Parámetros:

• index (requerido, cadena): El nombre del índice para recuperar mapeos.

Ejemplo:

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

3. Buscar

Realiza una búsqueda en Elasticsearch utilizando la consulta DSL proporcionada y resaltado.

Parámetros:

• index (requerido, cadena): El índice o índices en los que buscar (admite valores separados por comas).
• queryBody (requerido, objeto): El cuerpo de la consulta DSL de Elasticsearch.
• highlight (opcional, booleano): Habilitar resaltado para los resultados de búsqueda (predeterminado: true).

Ejemplo:

{
  "index": "mi-índice",
  "queryBody": {
    "query": {
      "match": {
        "content": "término de búsqueda"
      }
    },
    "size": 10,
    "from": 0,
    "sort": [{ "_score": { "order": "desc" } }]
  },
  "highlight": true
}

4. Obtener Salud del Clúster

Obtén información sobre la salud del clúster de Elasticsearch.

Parámetros:

• Ninguno requerido.

Ejemplo:

{}

5. Obtener Fragmentos

Recupera información sobre fragmentos para todos o índices específicos.

Parámetros:

• index (opcional, cadena): Índice específico para obtener información sobre fragmentos. Si se omite, devuelve fragmentos para todos los índices.

Ejemplo:

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

6. Agregar Documento

Inserta un nuevo documento en un índice específico de Elasticsearch.

Parámetros:

• index (requerido, cadena): El índice al que se añadirá el documento.
• document (requerido, objeto): El contenido del documento a añadir.
• id (opcional, cadena): ID del documento. Si se omite, Elasticsearch genera uno automáticamente.

Ejemplo:

{
  "index": "mi-índice",
  "id": "doc1",
  "document": {
    "title": "Mi Documento",
    "content": "Contenido del documento aquí",
    "timestamp": "2025-06-23T10:30:00Z",
    "tags": ["importante", "borrador"]
  }
}

7. Actualizar Documento

Modifica un documento existente en un índice específico de Elasticsearch.

Parámetros:

• index (requerido, cadena): El índice que contiene el documento.
• id (requerido, cadena): El ID del documento a actualizar.
• document (requerido, objeto): El documento parcial con campos a actualizar.

Ejemplo:

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

8. Eliminar Documento

Elimina un documento de un índice específico de Elasticsearch.

Parámetros:

• index (requerido, cadena): El índice que contiene el documento.
• id (requerido, cadena): El ID del documento a eliminar.

Ejemplo:

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

9. Actualizar por Consulta

Actualiza documentos en un índice de Elasticsearch basado en una consulta.

Parámetros:

• index (requerido, cadena): El índice para actualizar documentos.
• query (requerido, objeto): Consulta de Elasticsearch para coincidir documentos para actualizar.
• script (requerido, objeto): Script a ejecutar para actualizar documentos coincidentes.
• conflicts (opcional, cadena): Cómo manejar conflictos de versión ("abort" o "proceed", predeterminado: "abort").
• refresh (opcional, booleano): Si se debe refrescar el índice después de la operación (predeterminado: false).

Ejemplo:

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

10. Eliminar por Consulta

Elimina documentos en un índice de Elasticsearch basado en una consulta.

Parámetros:

• index (requerido, cadena): El índice para eliminar documentos.
• query (requerido, objeto): Consulta de Elasticsearch para coincidir documentos para eliminación.
• conflicts (opcional, cadena): Cómo manejar conflictos de versión ("abort" o "proceed", predeterminado: "abort").
• refresh (opcional, booleano): Si se debe refrescar el índice después de la operación (predeterminado: false).

Ejemplo:

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

11. Operaciones en Bloque

Ejecuta múltiples operaciones de documentos en una sola llamada a la API para mejorar el rendimiento.

Parámetros:

• operations (requerido, array): Array de objetos de operación, cada uno conteniendo:
  • action (requerido, cadena): El tipo de operación ("index", "create", "update" o "delete").
  • index (requerido, cadena): El índice para esta operación.
  • id (opcional, cadena): ID del documento (requerido para actualizar/eliminar, opcional para indexar/crear).
  • document (condicional, objeto): Contenido del documento (requerido para operaciones de indexar/crear/actualizar).

Ejemplo:

{
  "operations": [
    {
      "action": "index",
      "index": "mi-índice",
      "id": "doc1",
      "document": { "title": "Documento 1", "content": "Contenido aquí" }
    },
    {
      "action": "update",
      "index": "mi-índice",
      "id": "doc2",
      "document": { "title": "Título Actualizado" }
    },
    {
      "action": "delete",
      "index": "mi-índice",
      "id": "doc3"
    }
  ]
}

12. Crear Índice

Crea un nuevo índice de Elasticsearch con configuraciones y mapeos opcionales.

Parámetros:

• index (requerido, cadena): El nombre del índice a crear.
• settings (opcional, objeto): Configuraciones del índice como número de fragmentos, réplicas, etc.
• mappings (opcional, objeto): Mapeos de campo que definen cómo se deben indexar los documentos.

Ejemplo:

{
  "index": "nuevo-í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. Eliminar Índice

Elimina permanentemente un índice de Elasticsearch.

Parámetros:

• index (requerido, cadena): El nombre del índice a eliminar.

Ejemplo:

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

14. Contar Documentos

Cuenta documentos en un índice, opcionalmente filtrados por una consulta.

Parámetros:

• index (requerido, cadena): El índice para contar documentos.
• query (opcional, objeto): Consulta de Elasticsearch para filtrar documentos para contar.

Ejemplo:

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

15. Obtener Plantillas

Recupera plantillas de índice de Elasticsearch.

Parámetros:

• name (opcional, cadena): Nombre específico de la plantilla a recuperar. Si se omite, devuelve todas las plantillas.

Ejemplo:

{
  "name": "plantilla-logs"
}

16. Obtener Alias

Obtiene alias de índice de Elasticsearch.

Parámetros:

• name (opcional, cadena): Nombre específico del alias a recuperar. Si se omite, devuelve todos los alias.

Ejemplo:

{
  "name": "alias-logs"
}

Desarrollo

Ejecutar en Modo de Desarrollo

Para ejecutar el servidor en modo de vigilancia durante el desarrollo, usa:

npm run dev

Implementación del Protocolo

Este servidor implementa el Protocolo de Contexto de Modelo para facilitar la comunicación estandarizada entre clientes LLM y Elasticsearch. Proporciona un conjunto completo de herramientas que pueden ser invocadas por clientes MCP para realizar diversas operaciones de Elasticsearch.

Agregar Nuevas Herramientas

Para agregar una nueva herramienta al servidor:

1. Define la herramienta en src/index.ts utilizando el formato de registro de herramientas del servidor MCP.
2. Implementa la funcionalidad necesaria en src/utils/elasticsearchService.ts.
3. Actualiza este README para documentar la nueva herramienta.

Otros Clientes MCP

El servidor MCP de Elasticsearch Octodet se puede utilizar con cualquier cliente compatible con MCP, incluidos:

• ChatGPT de OpenAI a través de plugins MCP
• Claude Desktop de Anthropic
• Claude en VS Code
• Aplicaciones personalizadas utilizando el SDK de MCP

Uso Programático

También puedes usar el servidor de manera programática en tus aplicaciones Node.js:

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

// Configura la conexión a Elasticsearch
const config = {
  url: "http://localhost:9200",
  apiKey: "tu_api_key",
  version: "8",
};

// Crea y comienza el servidor
async function startServer() {
  const server = await createOctodetElasticsearchMcpServer(config);

  // Conéctate a tu transporte personalizado
  const transport = new CustomTransport();
  await server.connect(transport);

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

startServer().catch(console.error);

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.