Serveur MCP Elasticsearch Octodet

Le serveur MCP Elasticsearch Octodet est un puissant serveur de Protocole de Contexte de Modèle (MCP) conçu pour une interaction fluide avec les clusters Elasticsearch. Il fournit un moyen standardisé pour les applications alimentées par LLM d'effectuer diverses opérations telles que la recherche, la mise à jour et la gestion des données au sein d'Elasticsearch.

Fonctionnalités

Opérations Elasticsearch Complètes : Exécutez facilement des opérations CRUD complètes sur des documents et des indices.
Opérations en Masse : Améliorez les performances en traitant plusieurs opérations dans un seul appel API.
Mises à Jour/Suppressions Basées sur des Requêtes : Modifiez ou supprimez des documents en fonction de requêtes spécifiques.
Gestion de Cluster : Surveillez la santé de votre cluster Elasticsearch, y compris les shards et les modèles.
Recherche Avancée : Utilisez toutes les capacités des requêtes DSL d'Elasticsearch avec un support de mise en surbrillance intégré.

Comment Installer

En tant que Paquet NPM

Pour installer le serveur MCP Elasticsearch Octodet globalement, exécutez :

npm install -g @octodet/elasticsearch-mcp

Alternativement, vous pouvez l'utiliser directement avec npx :

npx @octodet/elasticsearch-mcp

À partir de la Source

Clonez le dépôt.
Installez les dépendances nécessaires :

npm install

Construisez le serveur :

npm run build

Intégration avec les Clients MCP

Intégration VS Code

Pour intégrer avec l'extension MCP de VS Code, ajoutez la configuration suivante à votre settings.json :

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

Intégration Claude Desktop

Pour Claude Desktop, configurez vos paramètres comme suit :

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

Pour le Développement Local

Si vous développez le serveur MCP localement, configurez vos clients pour utiliser votre build local :

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

Configuration

Le serveur peut être configuré à l'aide des variables d'environnement suivantes :

Outils

Le serveur comprend 16 outils MCP pour diverses opérations Elasticsearch, chacun documenté avec des paramètres requis et optionnels.

1. Lister les Indices

Récupérez une liste de tous les indices Elasticsearch disponibles avec des informations détaillées.

Paramètres :

indexPattern (optionnel, chaîne) : Modèle pour filtrer les indices (par exemple, "logs-", "my-index-")

Exemple :

{
  "indexPattern": "logs-*"
}

2. Obtenir les Mappages

Récupérez les mappages de champs pour un indice Elasticsearch spécifique.

Paramètres :

index (requis, chaîne) : Le nom de l'indice pour lequel récupérer les mappages.

Exemple :

{
  "index": "my-index"
}

3. Rechercher

Effectuez une recherche Elasticsearch en utilisant la requête DSL fournie et la mise en surbrillance.

Paramètres :

index (requis, chaîne) : L'indice ou les indices à rechercher (prend en charge les valeurs séparées par des virgules).
queryBody (requis, objet) : Le corps de la requête DSL d'Elasticsearch.
highlight (optionnel, booléen) : Activer la mise en surbrillance pour les résultats de recherche (par défaut : vrai).

Exemple :

{
  "index": "my-index",
  "queryBody": {
    "query": {
      "match": {
        "content": "terme de recherche"
      }
    },
    "size": 10,
    "from": 0,
    "sort": [{ "_score": { "order": "desc" } }]
  },
  "highlight": true
}

4. Obtenir la Santé du Cluster

Obtenez des informations sur la santé du cluster Elasticsearch.

Paramètres :

Aucun requis.

Exemple :

{}

5. Obtenir les Shards

Récupérez des informations sur les shards pour tous les indices ou des indices spécifiques.

Paramètres :

index (optionnel, chaîne) : Indice spécifique pour obtenir des informations sur les shards. Si omis, renvoie les shards pour tous les indices.

Exemple :

{
  "index": "my-index"
}

6. Ajouter un Document

Insérez un nouveau document dans un indice Elasticsearch spécifique.

Paramètres :

index (requis, chaîne) : L'indice auquel le document sera ajouté.
document (requis, objet) : Le contenu du document à ajouter.
id (optionnel, chaîne) : ID du document. Si omis, Elasticsearch en génère un automatiquement.

Exemple :

{
  "index": "my-index",
  "id": "doc1",
  "document": {
    "title": "Mon Document",
    "content": "Contenu du document ici",
    "timestamp": "2025-06-23T10:30:00Z",
    "tags": ["important", "brouillon"]
  }
}

7. Mettre à Jour un Document

Modifiez un document existant dans un indice Elasticsearch spécifique.

Paramètres :

index (requis, chaîne) : L'indice contenant le document.
id (requis, chaîne) : L'ID du document à mettre à jour.
document (requis, objet) : Le document partiel avec les champs à mettre à jour.

Exemple :

{
  "index": "my-index",
  "id": "doc1",
  "document": {
    "title": "Titre du Document Mis à Jour",
    "last_modified": "2025-06-23T10:30:00Z"
  }
}

8. Supprimer un Document

Supprimez un document d'un indice Elasticsearch spécifique.

Paramètres :

index (requis, chaîne) : L'indice contenant le document.
id (requis, chaîne) : L'ID du document à supprimer.

Exemple :

{
  "index": "my-index",
  "id": "doc1"
}

9. Mettre à Jour par Requête

Mettez à jour des documents dans un indice Elasticsearch en fonction d'une requête.

Paramètres :

index (requis, chaîne) : L'indice pour mettre à jour les documents.
query (requis, objet) : Requête Elasticsearch pour correspondre aux documents à mettre à jour.
script (requis, objet) : Script à exécuter pour mettre à jour les documents correspondants.
conflicts (optionnel, chaîne) : Comment gérer les conflits de version ("abort" ou "proceed", par défaut : "abort").
refresh (optionnel, booléen) : Si l'index doit être rafraîchi après l'opération (par défaut : faux).

Exemple :

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

10. Supprimer par Requête

Supprimez des documents dans un indice Elasticsearch en fonction d'une requête.

Paramètres :

index (requis, chaîne) : L'indice pour supprimer des documents.
query (requis, objet) : Requête Elasticsearch pour correspondre aux documents à supprimer.
conflicts (optionnel, chaîne) : Comment gérer les conflits de version ("abort" ou "proceed", par défaut : "abort").
refresh (optionnel, booléen) : Si l'index doit être rafraîchi après l'opération (par défaut : faux).

Exemple :

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

11. Opérations en Masse

Exécutez plusieurs opérations de documents dans un seul appel API pour améliorer les performances.

Paramètres :

operations (requis, tableau) : Tableau d'objets d'opération, chacun contenant :
- action (requis, chaîne) : Le type d'opération ("index", "create", "update" ou "delete").
- index (requis, chaîne) : L'indice pour cette opération.
- id (optionnel, chaîne) : ID du document (requis pour mise à jour/suppression, optionnel pour indexation/création).
- document (conditionnel, objet) : Contenu du document (requis pour les opérations d'indexation/création/mise à jour).

Exemple :

{
  "operations": [
    {
      "action": "index",
      "index": "my-index",
      "id": "doc1",
      "document": { "title": "Document 1", "content": "Contenu ici" }
    },
    {
      "action": "update",
      "index": "my-index",
      "id": "doc2",
      "document": { "title": "Titre Mis à Jour" }
    },
    {
      "action": "delete",
      "index": "my-index",
      "id": "doc3"
    }
  ]
}

12. Créer un Indice

Créez un nouvel indice Elasticsearch avec des paramètres et des mappages optionnels.

Paramètres :

index (requis, chaîne) : Le nom de l'indice à créer.
settings (optionnel, objet) : Paramètres de l'indice comme le nombre de shards, de répliques, etc.
mappings (optionnel, objet) : Mappages de champs définissant comment les documents doivent être indexés.

Exemple :

{
  "index": "new-index",
  "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. Supprimer un Indice

Supprimez définitivement un indice Elasticsearch.

Paramètres :

index (requis, chaîne) : Le nom de l'indice à supprimer.

Exemple :

{
  "index": "my-index"
}

14. Compter les Documents

Comptez les documents dans un indice, éventuellement filtrés par une requête.

Paramètres :

index (requis, chaîne) : L'indice pour compter les documents.
query (optionnel, objet) : Requête Elasticsearch pour filtrer les documents à compter.

Exemple :

{
  "index": "my-index",
  "query": {
    "bool": {
      "must": [
        { "term": { "status": "actif" } },
        { "range": { "created_date": { "gte": "2025-01-01" } } }
      ]
    }
  }
}

15. Obtenir des Modèles

Récupérez des modèles d'index d'Elasticsearch.

Paramètres :

name (optionnel, chaîne) : Nom spécifique du modèle à récupérer. Si omis, renvoie tous les modèles.

Exemple :

{
  "name": "logs-template"
}

16. Obtenir des Alias

Récupérez des alias d'index d'Elasticsearch.

Paramètres :

name (optionnel, chaîne) : Nom spécifique de l'alias à récupérer. Si omis, renvoie tous les alias.

Exemple :

{
  "name": "logs-alias"
}

Développement

Exécution en Mode Développement

Pour exécuter le serveur en mode veille pendant le développement, utilisez :

npm run dev

Mise en Œuvre du Protocole

Ce serveur met en œuvre le Protocole de Contexte de Modèle pour faciliter la communication standardisée entre les clients LLM et Elasticsearch. Il fournit un ensemble complet d'outils pouvant être invoqués par les clients MCP pour effectuer diverses opérations Elasticsearch.

Ajout de Nouveaux Outils

Pour ajouter un nouvel outil au serveur :

Définissez l'outil dans src/index.ts en utilisant le format d'enregistrement d'outil du serveur MCP.
Implémentez la fonctionnalité nécessaire dans src/utils/elasticsearchService.ts.
Mettez à jour ce README pour documenter le nouvel outil.

Autres Clients MCP

Le serveur MCP Elasticsearch Octodet peut être utilisé avec tout client compatible MCP, y compris :

ChatGPT d'OpenAI via des plugins MCP
Claude Desktop d'Anthropic
Claude dans VS Code
Applications personnalisées utilisant le SDK MCP

Utilisation Programmatique

Vous pouvez également utiliser le serveur de manière programmatique dans vos applications Node.js :

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

// Configurez la connexion Elasticsearch
const config = {
  url: "http://localhost:9200",
  apiKey: "your_api_key",
  version: "8",
};

// Créez et démarrez le serveur
async function startServer() {
  const server = await createOctodetElasticsearchMcpServer(config);

  // Connectez-vous à votre transport personnalisé
  const transport = new CustomTransport();
  await server.connect(transport);

  console.log("Serveur MCP Elasticsearch démarré");
}

startServer().catch(console.error);

Licence

Ce projet est sous licence MIT - voir le fichier LICENSE pour les détails.

Serveur MCP Elasticsearch Octodet

Aperçu