Octodet Elasticsearch MCP Сервер

Octodet Elasticsearch MCP Server

Сервер Octodet Elasticsearch MCP — это мощный сервер Протокола Контекста Модели (MCP), предназначенный для бесшовного взаимодействия с кластерами Elasticsearch. Он предоставляет стандартизированный способ для приложений на базе LLM выполнять различные операции, такие как поиск, обновление и управление данными в Elasticsearch.

Особенности

• Полные операции Elasticsearch: Выполняйте полные операции CRUD с документами и индексами без усилий.
• Пакетные операции: Повышайте производительность, обрабатывая несколько операций в одном API-вызове.
• Обновления/Удаления на основе запросов: Изменяйте или удаляйте документы на основе конкретных запросов.
• Управление кластером: Мониторьте состояние вашего кластера Elasticsearch, включая шардирование и шаблоны.
• Расширенный поиск: Используйте все возможности запросов DSL Elasticsearch с поддержкой встроенного выделения.

Как установить

Как пакет NPM

Чтобы установить сервер Octodet Elasticsearch MCP глобально, выполните:

npm install -g @octodet/elasticsearch-mcp

В качестве альтернативы, вы можете использовать его напрямую с npx:

npx @octodet/elasticsearch-mcp

Из исходников

1. Клонируйте репозиторий.
2. Установите необходимые зависимости:

npm install

3. Соберите сервер:

npm run build

Интеграция с клиентами MCP

Интеграция с VS Code

Чтобы интегрировать с расширением MCP для VS Code, добавьте следующую конфигурацию в ваш 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"
    }
  }
}

Интеграция с Claude Desktop

Для Claude Desktop настройте ваши параметры следующим образом:

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

Для локальной разработки

Если вы разрабатываете сервер MCP локально, настройте ваши клиенты на использование вашей локальной сборки:

{
  "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"
      }
    }
  }
}

Конфигурация

Сервер можно настроить с помощью следующих переменных окружения:

| Переменная | Описание | Значение по умолчанию | | | | | | ES_URL | URL сервера Elasticsearch | http://localhost:9200 | | ES_API_KEY | API-ключ для аутентификации | | | ES_USERNAME | Имя пользователя для аутентификации | | | ES_PASSWORD | Пароль для аутентификации | | | ES_CA_CERT | Путь к пользовательскому CA-сертификату | | | ES_VERSION | Версия Elasticsearch (8 или 9) | 8 | | ES_SSL_SKIP_VERIFY | Пропустить проверку SSL | false | | ES_PATH_PREFIX | Префикс пути для Elasticsearch | |

Инструменты

Сервер включает 16 инструментов MCP для различных операций Elasticsearch, каждый из которых документирован с обязательными и необязательными параметрами.

1. Список индексов

Получите список всех доступных индексов Elasticsearch с подробной информацией.

Параметры:

• indexPattern (необязательный, строка): Шаблон для фильтрации индексов (например, "logs-", "my-index-")

Пример:

{
  "indexPattern": "logs-*"
}

2. Получить отображения

Получите отображения полей для конкретного индекса Elasticsearch.

Параметры:

• index (обязательный, строка): Имя индекса, для которого нужно получить отображения.

Пример:

{
  "index": "my-index"
}

3. Поиск

Проведите поиск в Elasticsearch, используя предоставленный запрос DSL и выделение.

Параметры:

• index (обязательный, строка): Индекс или индексы для поиска (поддерживает значения, разделенные запятыми).
• queryBody (обязательный, объект): Тело запроса DSL Elasticsearch.
• highlight (необязательный, булев): Включить выделение для результатов поиска (по умолчанию: true).

Пример:

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

4. Получить состояние кластера

Получите информацию о состоянии кластера Elasticsearch.

Параметры:

• Не требуется.

Пример:

{}

5. Получить шардирование

Получите информацию о шардировании для всех или конкретных индексов.

Параметры:

• index (необязательный, строка): Конкретный индекс для получения информации о шардировании. Если опущен, возвращает шардирование для всех индексов.

Пример:

{
  "index": "my-index"
}

6. Добавить документ

Вставьте новый документ в конкретный индекс Elasticsearch.

Параметры:

• index (обязательный, строка): Индекс, в который будет добавлен документ.
• document (обязательный, объект): Содержимое документа для добавления.
• id (необязательный, строка): ID документа. Если опущен, Elasticsearch автоматически сгенерирует его.

Пример:

{
  "index": "my-index",
  "id": "doc1",
  "document": {
    "title": "My Document",
    "content": "Document content here",
    "timestamp": "2025-06-23T10:30:00Z",
    "tags": ["important", "draft"]
  }
}

7. Обновить документ

Измените существующий документ в конкретном индексе Elasticsearch.

Параметры:

• index (обязательный, строка): Индекс, содержащий документ.
• id (обязательный, строка): ID документа для обновления.
• document (обязательный, объект): Частичный документ с полями для обновления.

Пример:

{
  "index": "my-index",
  "id": "doc1",
  "document": {
    "title": "Updated Document Title",
    "last_modified": "2025-06-23T10:30:00Z"
  }
}

8. Удалить документ

Удалите документ из конкретного индекса Elasticsearch.

Параметры:

• index (обязательный, строка): Индекс, содержащий документ.
• id (обязательный, строка): ID документа для удаления.

Пример:

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

9. Обновить по запросу

Обновите документы в индексе Elasticsearch на основе запроса.

Параметры:

• index (обязательный, строка): Индекс для обновления документов.
• query (обязательный, объект): Запрос Elasticsearch для сопоставления документов для обновления.
• script (обязательный, объект): Скрипт для выполнения обновления сопоставленных документов.
• conflicts (необязательный, строка): Как обрабатывать конфликты версий ("abort" или "proceed", по умолчанию: "abort").
• refresh (необязательный, булев): Нужно ли обновлять индекс после операции (по умолчанию: false).

Пример:

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

10. Удалить по запросу

Удалите документы в индексе Elasticsearch на основе запроса.

Параметры:

• index (обязательный, строка): Индекс для удаления документов.
• query (обязательный, объект): Запрос Elasticsearch для сопоставления документов для удаления.
• conflicts (необязательный, строка): Как обрабатывать конфликты версий ("abort" или "proceed", по умолчанию: "abort").
• refresh (необязательный, булев): Нужно ли обновлять индекс после операции (по умолчанию: false).

Пример:

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

11. Пакетные операции

Выполните несколько операций с документами в одном API-вызове для повышения производительности.

Параметры:

• operations (обязательный, массив): Массив объектов операций, каждый из которых содержит:
  • action (обязательный, строка): Тип операции ("index", "create", "update" или "delete").
  • index (обязательный, строка): Индекс для этой операции.
  • id (необязательный, строка): ID документа (обязателен для обновления/удаления, необязателен для индексации/создания).
  • document (условный, объект): Содержимое документа (обязательно для индексации/создания/обновления).

Пример:

{
  "operations": [
    {
      "action": "index",
      "index": "my-index",
      "id": "doc1",
      "document": { "title": "Document 1", "content": "Content here" }
    },
    {
      "action": "update",
      "index": "my-index",
      "id": "doc2",
      "document": { "title": "Updated Title" }
    },
    {
      "action": "delete",
      "index": "my-index",
      "id": "doc3"
    }
  ]
}

12. Создать индекс

Создайте новый индекс Elasticsearch с необязательными настройками и отображениями.

Параметры:

• index (обязательный, строка): Имя индекса для создания.
• settings (необязательный, объект): Настройки индекса, такие как количество шардов, реплик и т. д.
• mappings (необязательный, объект): Отображения полей, определяющие, как документы должны индексироваться.

Пример:

{
  "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. Удалить индекс

Постоянно удалите индекс Elasticsearch.

Параметры:

• index (обязательный, строка): Имя индекса для удаления.

Пример:

{
  "index": "my-index"
}

14. Подсчитать документы

Подсчитайте документы в индексе, при необходимости отфильтровав по запросу.

Параметры:

• index (обязательный, строка): Индекс для подсчета документов.
• query (необязательный, объект): Запрос Elasticsearch для фильтрации документов для подсчета.

Пример:

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

15. Получить шаблоны

Получите шаблоны индексов из Elasticsearch.

Параметры:

• name (необязательный, строка): Конкретное имя шаблона для получения. Если опущено, возвращает все шаблоны.

Пример:

{
  "name": "logs-template"
}

16. Получить псевдонимы

Получите псевдонимы индексов из Elasticsearch.

Параметры:

• name (необязательный, строка): Конкретное имя псевдонима для получения. Если опущено, возвращает все псевдонимы.

Пример:

{
  "name": "logs-alias"
}

Разработка

Запуск в режиме разработки

Чтобы запустить сервер в режиме наблюдения во время разработки, используйте:

npm run dev

Реализация протокола

Этот сервер реализует Протокол Контекста Модели для облегчения стандартизированного общения между клиентами LLM и Elasticsearch. Он предоставляет комплексный набор инструментов, которые могут быть вызваны клиентами MCP для выполнения различных операций Elasticsearch.

Добавление новых инструментов

Чтобы добавить новый инструмент на сервер:

1. Определите инструмент в src/index.ts, используя формат регистрации инструментов сервера MCP.
2. Реализуйте необходимую функциональность в src/utils/elasticsearchService.ts.
3. Обновите этот README для документирования нового инструмента.

Другие клиенты MCP

Сервер Octodet Elasticsearch MCP может быть использован с любым совместимым клиентом MCP, включая:

• ChatGPT от OpenAI через плагины MCP
• Claude Desktop от Anthropic
• Claude в VS Code
• Пользовательские приложения с использованием MCP SDK

Программное использование

Вы также можете использовать сервер программно в ваших приложениях Node.js:

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

// Настройте соединение с Elasticsearch
const config = {
  url: "http://localhost:9200",
  apiKey: "your_api_key",
  version: "8",
};

// Создайте и запустите сервер
async function startServer() {
  const server = await createOctodetElasticsearchMcpServer(config);

  // Подключите ваш пользовательский транспорт
  const transport = new CustomTransport();
  await server.connect(transport);

  console.log("Сервер Elasticsearch MCP запущен");
}

startServer().catch(console.error);

Лицензия

Этот проект лицензирован под лицензией MIT - смотрите файл LICENSE для подробностей.