splunk-mcp

Инструмент Splunk MCP (протокол контекста модели)

Инструмент на основе FastMCP для взаимодействия с Splunk Enterprise/Cloud посредством естественного языка. Этот инструмент предоставляет набор возможностей для поиска данных Splunk, управления хранилищами KV и доступа к ресурсам Splunk через интуитивно понятный интерфейс.

Режимы работы

Инструмент работает в трех режимах:

1. Режим SSE (по умолчанию)
   • Связь на основе событий, отправленных сервером
   • Двунаправленное взаимодействие в реальном времени
   • Подходит для веб-клиентов MCP
   • Режим по умолчанию, когда аргументы не указаны
   • Доступ через конечную точку /sse
2. Режим API
   • Конечные точки RESTful API
   • Доступ через префикс конечной точки /api/v1
   • Начните с python splunk_mcp.py api
3. Режим STDIO
   • Стандартная коммуникация на основе ввода/вывода
   • Совместимость с Claude Desktop и другими клиентами MCP
   • Идеально подходит для прямой интеграции с помощниками на основе искусственного интеллекта
   • Начните с python splunk_mcp.py stdio

Функции

• Поиск Splunk : выполнение поиска Splunk с использованием запросов на естественном языке.
• Управление индексами : список и проверка индексов Splunk
• Управление пользователями : просмотр и управление пользователями Splunk.
• Операции магазина KV : создание, перечисление и управление коллекциями магазина KV
• Поддержка асинхронности : построено на основе шаблонов async/await для лучшей производительности
• Подробное ведение журнала : комплексное ведение журнала с индикаторами эмодзи для лучшей видимости
• Конфигурация SSL : гибкие возможности проверки SSL для различных требований безопасности.
• Расширенная отладка : подробное протоколирование подключений и ошибок для устранения неполадок
• Комплексное тестирование : модульные тесты, охватывающие все основные функции
• Обработка ошибок : надежная обработка ошибок с соответствующими кодами состояния.
• Соответствие SSE : Полностью соответствует спецификации MCP SSE

Доступные инструменты MCP

Через интерфейс MCP доступны следующие инструменты:

Управление инструментами

• список_инструментов
  • Перечисляет все доступные инструменты MCP с их описаниями и параметрами.

Проверка здоровья

• проверка_здоровья
  • Возвращает список доступных приложений Splunk для проверки подключения
• пинг
  • Простой пинг конечной точки для проверки работоспособности сервера MCP

Управление пользователями

• текущий_пользователь
  • Возвращает информацию о текущем аутентифицированном пользователе
• список_пользователей
  • Возвращает список всех пользователей и их ролей

Управление индексом

• список_индексов
  • Возвращает список всех доступных индексов Splunk.
• получить_индексную_информацию
  • Возвращает подробную информацию о конкретном индексе
  • Параметры: index_name (строка)
• индексы_и_типы_источников
  • Возвращает полный список индексов и их исходных типов.

Поиск

• поиск_splunk
  • Выполняет поисковый запрос Splunk
  • Параметры:
    • search_query (string): Строка поиска Splunk
    • early_time (строка, необязательно): Время начала окна поиска
    • latest_time (строка, необязательно): Время окончания окна поиска
    • max_results (целое число, необязательно): максимальное количество возвращаемых результатов
• список_сохраненных_поисков
  • Возвращает список сохраненных поисков в экземпляре Splunk.

Магазин КВ

• список_kvstore_коллекции
  • Список всех коллекций магазина KV
• создать_kvstore_collection
  • Создает новую коллекцию магазина KV
  • Параметры: collection_name (строка)
• удалить_kvstore_collection
  • Удаляет существующую коллекцию магазина KV
  • Параметры: collection_name (строка)

Конечные точки SSE

При работе в режиме SSE доступны следующие конечные точки:

• /sse : Возвращает информацию о соединении SSE в формате текста/потока событий.
  • Предоставляет метаданные о соединении SSE
  • Включает URL для конечной точки сообщений
  • Предоставляет информацию о протоколе и возможностях
• /sse/messages : Основная конечная точка потока SSE
  • Транслирует системные события, такие как сердцебиение
  • Поддерживает постоянное соединение
  • Отправляет правильно отформатированные события SSE
• /sse/health : Конечная точка проверки работоспособности для режима SSE
  • Возвращает информацию о статусе и версии в формате SSE

Обработка ошибок

Реализация MCP включает последовательную обработку ошибок:

• Неверные команды поиска или неправильно сформированные запросы
• Недостаточно прав
• Ресурс не найден
• Неверная проверка ввода
• Неожиданные ошибки сервера
• Проблемы с подключением к серверу Splunk

Все ответы об ошибках содержат подробное сообщение с объяснением ошибки.

Предпосылки

• Python 3.10 или выше
• Поэзия для управления зависимостью
• Экземпляр Splunk Enterprise/Cloud
• Соответствующие учетные данные Splunk с необходимыми разрешениями

Установка

Вариант 1: Локальная установка

1. Клонируйте репозиторий:

2. Установка зависимостей с помощью Poetry:

3. Скопируйте пример файла среды и настройте параметры:

4. Обновите файл .env , указав свои учетные данные Splunk:

Вариант 2: Установка Docker

1. Извлеките последнее изображение:

2. Создайте файл .env , как указано выше, или используйте переменные среды напрямую.
3. Запустить с помощью Docker Compose:

Или напрямую с помощью Docker:

Использование

Местное использование

Инструмент может работать в трех режимах:

1. Режим SSE (по умолчанию для клиентов MCP):

3. Режим STDIO:

Использование Докера

Проект поддерживает как новые команды docker compose (V2), так и устаревшие команды docker-compose (V1). В примерах ниже используется синтаксис V2, но поддерживаются обе.

1. Режим SSE (по умолчанию):

2. Режим API:

3. Режим STDIO:

Тестирование с помощью Docker

Проект включает в себя специальную тестовую среду в Docker:

1. Запустите все тесты:

2. Запустите определенные компоненты теста:

Результаты теста будут доступны в каталоге ./test-results .

Советы по разработке Docker

1. Изображения зданий :

2. Просмотр журналов :

3. Отладка :

Примечание: Если вы используете Docker Compose V1, замените docker compose на docker-compose в приведенных выше командах.

Заметки о безопасности

1. Переменные среды :

• Никогда не фиксируйте файлы .env
• Использовать .env.example как шаблон
• Рассмотрите возможность использования Docker-секретов для производства

2. Проверка SSL :

• VERIFY_SSL=true рекомендуется для производства
• Можно отключить для разработки/тестирования
• Настройка через переменные среды

3. Портовая экспозиция :

• Открывайте только необходимые порты
• По возможности используйте внутреннюю сеть Docker
• Рассмотрите возможность обеспечения сетевой безопасности в производстве

Переменные среды

Настройте следующие переменные среды:

• SPLUNK_HOST : адрес вашего хоста Splunk
• SPLUNK_PORT : порт управления Splunk (по умолчанию: 8089)
• SPLUNK_USERNAME : Ваше имя пользователя Splunk
• SPLUNK_PASSWORD : Ваш пароль Splunk
• SPLUNK_SCHEME : Схема подключения (по умолчанию: https)
• VERIFY_SSL : включить/отключить проверку SSL (по умолчанию: true)
• FASTMCP_LOG_LEVEL : Уровень ведения журнала (по умолчанию: ИНФОРМАЦИЯ)
• SERVER_MODE : режим сервера (sse, api, stdio) при использовании uvicorn

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

Инструмент предоставляет гибкие возможности проверки SSL:

1. Режим по умолчанию (безопасный) :

• Полная проверка SSL-сертификата
• Включена проверка имени хоста
• Рекомендуется для производственных сред

2. Расслабленный режим :

• Проверка SSL-сертификата отключена
• Проверка имени хоста отключена
• Полезно для тестирования или самоподписанных сертификатов.

Тестирование

Проект включает в себя комплексное тестирование с использованием pytest и сквозное тестирование с использованием специального клиента MCP:

Проведение тестов

Выполнение базового теста:

С отчетностью по охвату:

С подробным выводом:

Сквозное тестирование SSE

Проект включает в себя специальный тестовый скрипт клиента MCP, который подключается к действующей конечной точке SSE и тестирует все инструменты:

Этот скрипт действует как клиент MCP:

1. Подключение к конечной точке /sse для получения URL-адреса сообщений
2. Отправка вызовов инструментов в конечную точку сообщений
3. Обработка событий SSE для извлечения результатов инструмента
4. Проверка результатов на соответствие ожидаемым форматам

Это обеспечивает реальное тестирование интерфейса SSE, как если бы он использовался реальным клиентом MCP.

Структура теста

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

1. Интеграционные тесты MCP ( tests/test_api.py ) :
   • Тестирует интерфейс инструментов MCP через mcp.call_tool()
   • Проверяет правильную регистрацию инструмента с помощью FastMCP
   • Обеспечивает правильный формат ответа и структуру данных
   • Проверяет обработку ошибок на уровне интерфейса MCP
   • Примечание: в идеале этот файл следует переименовать в test_mcp.py , чтобы лучше отразить его назначение.
2. Тесты прямой функции ( tests/test_endpoints_pytest.py ) :
   • Тестирует функции Splunk напрямую (минуя уровень MCP)
   • Обеспечивает более полное освещение деталей реализации функций.
   • Тестирует пограничные случаи, вариации параметров и обработку ошибок
   • Включает тесты конфигурации SSL, параметров соединения и тайм-аутов.
   • Использует параметризованное тестирование для эффективного тестового покрытия
3. Сквозные тесты клиента MCP ( test_endpoints.py ) :
   • Ведет себя как настоящий клиент MCP, подключающийся к конечной точке SSE
   • Тестирует весь поток от подключения до вызова инструмента и анализа ответа.
   • Проверяет фактическую реализацию протокола SSE
   • Тестирует инструменты с реальными параметрами на реальном сервере
4. Тесты конфигурации ( tests/test_config.py ) :
   • Тесты для анализа переменных окружения
   • Настройки проверки SSL
   • Проверка параметров соединения

Инструменты тестирования

Тесты подтверждают:

• Асинхронное тестирование с помощью pytest-asyncio
• Отчет о покрытии с помощью pytest-cov
• Мошенничество с pytest-mock
• Параметризованное тестирование
• Тестирование тайм-аута соединения

Поиск неисправностей

Проблемы с подключением

1. Базовые возможности подключения :

• Теперь инструмент выполняет базовую проверку TCP-подключения.
• Проверьте, доступен ли порт 8089.
• Проверьте сетевую маршрутизацию и брандмауэры

2. Проблемы с SSL :

• Если вы видите ошибки SSL, попробуйте установить VERIFY_SSL=false
• Проверьте действительность сертификата и цепочку доверия
• Проверьте соответствие имени хоста сертификату

3. Проблемы аутентификации :

• Проверьте учетные данные Splunk
• Проверьте права пользователя
• Убедитесь, что аккаунт не заблокирован

4. Отладка :

• Установите FASTMCP_LOG_LEVEL=DEBUG для получения подробных журналов
• Проверьте журналы подключений на наличие конкретных сообщений об ошибках.
• Просмотр сообщений конфигурации SSL

5. Проблемы с подключением SSE :

• Убедитесь, что конечная точка SSE доступна через /sse
• Проверьте правильность заголовков типа контента
• Используйте инструменты разработчика браузера для проверки соединений SSE

Клод Интеграция

Конфигурация рабочего стола Клода

Вы можете интегрировать Splunk MCP с Claude Desktop, настроив его на использование режима SSE или STDIO. Добавьте следующую конфигурацию в ваш claude_desktop_config.json :

Режим STDIO (рекомендуется для настольных компьютеров)

Режим SSE

Использование с Клодом

После настройки вы сможете использовать естественный язык для взаимодействия со Splunk через Claude. Примеры:

1. Список доступных индексов:

2. Поиск данных Splunk:

3. Получите информацию о состоянии системы:

4. Управление магазинами KV:

Инструменты MCP будут автоматически доступны Клоду, что позволит ему выполнять эти операции с помощью команд на естественном языке.

Лицензия

[Ваша лицензия здесь]

Благодарности

• Фреймворк FastMCP
• Splunk SDK для Python
• Python-decouple для управления конфигурацией
• SSE Starlette для внедрения SSE