Herramienta MCP (Protocolo de contexto de modelo) de Splunk

Una herramienta basada en FastMCP para interactuar con Splunk Enterprise/Cloud mediante lenguaje natural. Esta herramienta ofrece un conjunto de funciones para buscar datos de Splunk, gestionar almacenes KV y acceder a recursos de Splunk mediante una interfaz intuitiva.

Modos de funcionamiento

La herramienta funciona en tres modos:

1. Modo SSE (predeterminado)
   • Comunicación basada en eventos enviados por el servidor
   • Interacción bidireccional en tiempo real
   • Adecuado para clientes MCP basados en la web
   • Modo predeterminado cuando no se proporcionan argumentos
   • Acceso a través del punto final /sse
2. Modo API
   • Puntos finales de API RESTful
   • Acceso a través del prefijo de punto final /api/v1
   • Comience con python splunk_mcp.py api
3. Modo STDIO
   • Comunicación basada en entrada/salida estándar
   • Compatible con Claude Desktop y otros clientes MCP
   • Ideal para la integración directa con asistentes de IA
   • Comience con python splunk_mcp.py stdio

Características

• Búsqueda de Splunk : ejecute búsquedas de Splunk con consultas en lenguaje natural
• Gestión de índices : enumerar e inspeccionar índices de Splunk
• Administración de usuarios : ver y administrar usuarios de Splunk
• Operaciones de la tienda KV : crear, enumerar y administrar colecciones de la tienda KV
• Compatibilidad asincrónica : creada con patrones asíncronos/en espera para un mejor rendimiento
• Registro detallado : registro completo con indicadores emoji para una mejor visibilidad
• Configuración SSL : opciones de verificación SSL flexibles para diferentes requisitos de seguridad
• Depuración mejorada : conexión detallada y registro de errores para la resolución de problemas
• Pruebas integrales : pruebas unitarias que cubren todas las funcionalidades principales
• Manejo de errores : Manejo de errores robusto con códigos de estado apropiados
• Cumplimiento de SSE : Totalmente compatible con la especificación SSE de MCP

Herramientas MCP disponibles

Las siguientes herramientas están disponibles a través de la interfaz MCP:

Gestión de herramientas

• lista_de_herramientas
  • Enumera todas las herramientas MCP disponibles con sus descripciones y parámetros

Chequeo de salud

• chequeo de salud
  • Devuelve una lista de aplicaciones Splunk disponibles para verificar la conectividad
• silbido
  • Punto final de ping simple para verificar que el servidor MCP esté activo

Gestión de usuarios

• usuario_actual
  • Devuelve información sobre el usuario actualmente autenticado
• lista_usuarios
  • Devuelve una lista de todos los usuarios y sus roles.

Gestión de índices

• índices de lista
  • Devuelve una lista de todos los índices de Splunk accesibles
• obtener_información_del_índice
  • Devuelve información detallada sobre un índice específico
  • Parámetros: index_name (cadena)
• índices_y_tipos_de_fuente
  • Devuelve una lista completa de índices y sus tipos de origen.

Buscar

• búsqueda_splunk
  • Ejecuta una consulta de búsqueda de Splunk
  • Parámetros:
    • search_query (cadena): cadena de búsqueda de Splunk
    • earliest_time (cadena, opcional): hora de inicio de la ventana de búsqueda
    • latest_time (cadena, opcional): hora de finalización de la ventana de búsqueda
    • max_results (entero, opcional): número máximo de resultados a devolver
• lista_de_búsquedas_guardadas
  • Devuelve una lista de búsquedas guardadas en la instancia de Splunk

Tienda KV

• lista_colecciones_kvstore
  • Enumera todas las colecciones de la tienda KV
• crear_colección_kvstore
  • Crea una nueva colección de tienda KV
  • Parámetros: collection_name (cadena)
• eliminar_colección_kvstore
  • Elimina una colección de tienda KV existente
  • Parámetros: collection_name (cadena)

Puntos finales de SSE

Al ejecutarse en modo SSE, están disponibles los siguientes puntos finales:

• /sse : Devuelve información de conexión SSE en formato de texto/flujo de eventos
  • Proporciona metadatos sobre la conexión SSE
  • Incluye URL para el punto final de los mensajes
  • Proporciona información sobre protocolos y capacidades.
• /sse/messages : El punto final principal del flujo SSE
  • Transmite eventos del sistema como latidos
  • Mantiene una conexión persistente
  • Envía eventos SSE con el formato correcto
• /sse/health : Punto final de verificación de estado para el modo SSE
  • Devuelve información de estado y versión en formato SSE

Manejo de errores

La implementación de MCP incluye un manejo de errores consistente:

• Comandos de búsqueda no válidos o solicitudes mal formadas
• Permisos insuficientes
• Recurso no encontrado
• Validación de entrada no válida
• Errores inesperados del servidor
• Problemas de conexión con el servidor Splunk

Todas las respuestas de error incluyen un mensaje detallado que explica el error.

Prerrequisitos

• Python 3.10 o superior
• Poesía para la gestión de la dependencia
• Instancia de Splunk Enterprise/Cloud
• Credenciales de Splunk adecuadas con los permisos necesarios

Instalación

Opción 1: Instalación local

1. Clonar el repositorio:

2. Instalar dependencias usando Poetry:

3. Copie el archivo de entorno de ejemplo y configure sus ajustes:

4. Actualice el archivo .env con sus credenciales de Splunk:

Opción 2: Instalación de Docker

1. Extrae la última imagen:

2. Cree su archivo .env como se indica arriba o utilice variables de entorno directamente.
3. Ejecutar usando Docker Compose:

O usando Docker directamente:

Uso

Uso local

La herramienta puede funcionar en tres modos:

1. Modo SSE (predeterminado para clientes MCP):

3. Modo STDIO:

Uso de Docker

El proyecto admite tanto el nuevo comando docker compose (V2) como el antiguo docker-compose (V1). Los ejemplos a continuación utilizan la sintaxis V2, pero ambos son compatibles.

1. Modo SSE (predeterminado):

2. Modo API:

3. Modo STDIO:

Pruebas con Docker

El proyecto incluye un entorno de prueba dedicado en Docker:

1. Ejecutar todas las pruebas:

2. Ejecutar componentes de prueba específicos:

Los resultados de la prueba estarán disponibles en el directorio ./test-results .

Consejos de desarrollo de Docker

1. Imágenes del edificio :

2. Visualización de registros :

3. Depuración :

Nota: Si está utilizando Docker Compose V1, reemplace docker compose con docker-compose en los comandos anteriores.

Notas de seguridad

1. Variables de entorno :

• Nunca confirmes archivos .env
• Utilice .env.example como plantilla
• Considere usar secretos de Docker para producción

2. Verificación SSL :

• VERIFY_SSL=true recomendado para producción
• Se puede deshabilitar para desarrollo/pruebas
• Configurar a través de variables de entorno

3. Exposición del puerto :

• Exponer únicamente los puertos necesarios
• Utilice la red interna de Docker cuando sea posible
• Considere la seguridad de la red en la producción

Variables de entorno

Configure las siguientes variables de entorno:

• SPLUNK_HOST : Su dirección de host de Splunk
• SPLUNK_PORT : puerto de administración de Splunk (predeterminado: 8089)
• SPLUNK_USERNAME : Su nombre de usuario de Splunk
• SPLUNK_PASSWORD : Su contraseña de Splunk
• SPLUNK_SCHEME : Esquema de conexión (predeterminado: https)
• VERIFY_SSL : Habilitar o deshabilitar la verificación SSL (valor predeterminado: verdadero)
• FASTMCP_LOG_LEVEL : Nivel de registro (predeterminado: INFO)
• SERVER_MODE : Modo servidor (sse, api, stdio) al usar uvicorn

Configuración SSL

La herramienta proporciona opciones flexibles de verificación SSL:

1. Modo predeterminado (seguro) :

• Verificación completa del certificado SSL
• Verificación del nombre de host habilitada
• Recomendado para entornos de producción

2. Modo relajado :

• Verificación del certificado SSL deshabilitada
• Verificación del nombre de host deshabilitada
• Útil para probar certificados autofirmados.

Pruebas

El proyecto incluye una cobertura de pruebas integral utilizando pytest y pruebas de extremo a extremo con un cliente MCP personalizado:

Ejecución de pruebas

Ejecución de prueba básica:

Con informes de cobertura:

Con salida detallada:

Pruebas SSE de extremo a extremo

El proyecto incluye un script de prueba de cliente MCP personalizado que se conecta al punto final SSE en vivo y prueba todas las herramientas:

Este script actúa como un cliente MCP mediante:

1. Conectarse al punto final /sse para obtener la URL de los mensajes
2. Envío de invocaciones de herramientas al punto final de mensajes
3. Procesamiento de los eventos SSE para extraer resultados de la herramienta
4. Validación de los resultados frente a los formatos esperados

Esto proporciona una prueba real de la interfaz SSE tal como la utilizaría un cliente MCP real.

Estructura de la prueba

El proyecto utiliza tres enfoques de prueba complementarios:

1. Pruebas de integración de MCP ( tests/test_api.py ) :
   • Prueba la interfaz de herramientas MCP a través de mcp.call_tool()
   • Verifica el registro correcto de la herramienta con FastMCP
   • Garantiza el formato de respuesta y la estructura de datos correctos.
   • Valida el manejo de errores en el nivel de interfaz MCP
   • Nota: Lo ideal sería cambiar el nombre de este archivo a test_mcp.py para reflejar mejor su propósito.
2. Pruebas de función directa ( tests/test_endpoints_pytest.py ) :
   • Prueba las funciones de Splunk directamente (omitiendo la capa MCP)
   • Proporciona una cobertura más completa de los detalles de implementación de funciones.
   • Prueba casos extremos, variaciones de parámetros y manejo de errores.
   • Incluye pruebas de configuración de SSL, parámetros de conexión y tiempos de espera.
   • Utiliza pruebas parametrizadas para una cobertura de pruebas eficiente
3. Pruebas de cliente MCP de extremo a extremo ( test_endpoints.py ) :
   • Se comporta como un cliente MCP real que se conecta al punto final SSE
   • Prueba el flujo completo desde la conexión hasta la invocación de la herramienta y el análisis de la respuesta.
   • Valida la implementación real del protocolo SSE
   • Prueba herramientas con parámetros reales contra el servidor en vivo
4. Pruebas de configuración ( tests/test_config.py ) :
   • Pruebas para el análisis de variables de entorno
   • Configuración de verificación SSL
   • Validación de parámetros de conexión

Herramientas de prueba

Las pruebas admiten:

• Pruebas asincrónicas con pytest-asyncio
• Informes de cobertura con pytest-cov
• Burlándose con pytest-mock
• Pruebas parametrizadas
• Prueba de tiempo de espera de conexión

Solución de problemas

Problemas de conexión

1. Conectividad básica :

• La herramienta ahora realiza una prueba básica de conectividad TCP
• Compruebe si el puerto 8089 es accesible
• Verificar el enrutamiento de la red y los firewalls

2. Problemas de SSL :

• Si ve errores de SSL, intente configurar VERIFY_SSL=false
• Comprobar la validez del certificado y la cadena de confianza
• Verificar que el nombre de host coincida con el certificado

3. Problemas de autenticación :

• Verificar las credenciales de Splunk
• Comprobar los permisos de usuario
• Asegúrese de que la cuenta no esté bloqueada

4. Depuración :

• Establezca FASTMCP_LOG_LEVEL=DEBUG para obtener registros detallados
• Consulte los registros de conexión para ver si hay mensajes de error específicos
• Revisar los mensajes de configuración de SSL

5. Problemas de conexión SSE :

• Verifique que el punto final de SSE sea accesible a través de /sse
• Verifique que los encabezados de tipo de contenido sean adecuados
• Utilice las herramientas para desarrolladores del navegador para inspeccionar las conexiones SSE

Integración de Claude

Configuración del escritorio de Claude

Puede integrar Splunk MCP con Claude Desktop configurándolo para usar el modo SSE o STDIO. Agregue la siguiente configuración a su claude_desktop_config.json :

Modo STDIO (recomendado para escritorio)

Modo SSE

Uso con Claude

Una vez configurado, puede usar lenguaje natural para interactuar con Splunk a través de Claude. Ejemplos:

1. Lista de índices disponibles:

2. Buscar datos de Splunk:

3. Obtener el estado del sistema:

4. Administrar tiendas KV:

Las herramientas MCP estarán disponibles automáticamente para Claude, lo que le permitirá ejecutar estas operaciones a través de comandos de lenguaje natural.

Licencia

[Su licencia aquí]

Expresiones de gratitud

• Marco FastMCP
• SDK de Splunk para Python
• Python-decouple para la gestión de la configuración
• SSE Starlette para la implementación de SSE