mcp-parseable-server

Servidor MCP para la plataforma de observabilidad Parseable

GitHub
4
Prueba este MCPPatrocinado

Documentación

mcp-parseable-server - Un servidor MCP de Parseable

Este proyecto se encuentra actualmente en desarrollo temprano con enfoque en datos de logs. Se agradecen comentarios y contribuciones.

Las pruebas se han realizado usando:

  • vscode con Github Copilot como agente.
  • herramienta CLI de agente opencode

[TOC]

Descripción general

Este proyecto proporciona un servidor MCP (Protocolo de Contexto de Mensajes) para Parseable, permitiendo que agentes y herramientas de IA interactúen con flujos de datos de Parseable (logs, métricas, trazas) usando lenguaje natural y llamadas estructuradas a herramientas.

Características

  • Listar flujos de datos disponibles en Parseable
  • Consultar flujos de datos usando SQL
  • Obtener esquema, estadísticas e información de cualquier flujo de datos
  • Registro modular de herramientas MCP para fácil extensión
  • Soporta modos MCP HTTP y stdio
  • Configuración basada en variables de entorno y banderas
  • El servidor MCP devuelve respuestas en json donde la carga útil está tanto en formato de texto como estructurado.

En Parseable, los nombres de conjuntos de datos y flujos de datos se usan indistintamente, ya que los conjuntos de datos de Parseable son esencialmente flujos de datos con nombre. En todas las descripciones de herramientas intentamos usar el término flujo de datos para evitar confusión con el término conjunto de datos, que puede tener diferentes significados en otros contextos.

Limitaciones

Autenticación

El servidor MCP no implementa ningún mecanismo de autenticación. Si esto es necesario, use un proxy inverso como nginx o envoy frente al servidor MCP para agregar autenticación y autorización.

Gestión de sesiones MCP

El servidor MCP no implementa ninguna gestión de sesiones, ya que todas las llamadas a herramientas no tienen estado. Esto puede cambiar en el futuro.

Compilación

Asegúrese de tener Go 1.20+ instalado.

git clone https://github.com/thenodon/mcp-parseable-server
cd mcp-parseable-server
# Build the MCP server binary
go build -o mcp-parseable-server ./cmd/mcp_parseable_server

Ejecución

Modo HTTP (predeterminado)

./mcp-parseable-server --listen :9034

El servidor MCP escuchará en http://localhost:9034/mcp para solicitudes de agentes/herramientas.

Modo Stdio

./mcp-parseable-server --mode stdio

Este modo se usa para flujos de trabajo CLI o entre agentes.

Configuración

Puede configurar la conexión a Parseable usando variables de entorno o banderas:

  • PARSEABLE_URL o --parseable-url - url a la instancia de parseable (predeterminado: http://localhost:8000)
  • PARSEABLE_USERNAME o --parseable-user (predeterminado: admin)
  • PARSEABLE_PASSWORD o --parseable-pass (predeterminado: admin)
  • LISTEN_ADDR o --listen - la dirección al ejecutar el servidor MCP en modo http (predeterminado: :9034)
  • INSECURE - configúrelo en true para omitir la verificación TLS (predeterminado: false)`
  • LOG_LEVEL - establece el nivel de registro. Los niveles admitidos son debug, info, warn y error (predeterminado: info)

Ejemplo:

PARSEABLE_URL="http://your-parseable-host:8000" PARSEABLE_USER="admin" PARSEABLE_PASS="admin" ./mcp-parseable-server

Despliegue en producción

Para el despliegue en producción, use un proxy inverso como nginx o envoy frente al servidor MCP que gestione autenticación, autorización y terminación TLS.

Pruebas

Consulte TESTING.md para una guía completa de pruebas.

Referencia de herramientas MCP

1. query_data_stream

Ejecuta una consulta SQL contra un flujo de datos.

  • Entradas:
    • query: cadena de consulta SQL
    • streamName: nombre del flujo de datos
    • startTime: hora de inicio ISO 8601 (p. ej., 2026-01-01T00:00:00+00:00)
    • endTime: hora de fin ISO 8601
  • Devuelve: resultado de la consulta y el número de filas devueltas

2. get_data_streams

Lista todos los flujos de datos disponibles en Parseable.

  • Devuelve: matriz de objetos de flujo con recuento

3. get_data_stream_schema

Obtiene el esquema de campos para un flujo de datos específico.

  • Entradas:
    • stream: nombre del flujo de datos
  • Devuelve: campos y tipos del esquema

4. get_data_stream_stats

Obtiene estadísticas para un flujo de datos.

  • Entradas:
    • streamName: nombre del flujo de datos
  • Devuelve: objeto de estadísticas (consulte la descripción de la herramienta para más detalles)

5. get_data_stream_info

Obtiene información para un flujo de datos.

  • Entradas:
    • streamName: nombre del flujo de datos
  • Devuelve: objeto de información (consulte la descripción de la herramienta para más detalles)

6. get_about

Obtiene información general de Parseable.

  • Devuelve: objeto de información general (consulte la descripción de la herramienta para más detalles)

7. get_roles

Obtiene roles de Parseable.

  • Devuelve: objeto de roles (consulte la descripción de la herramienta para más detalles)

8. get_users

Obtiene todos los usuarios configurados.

  • Devuelve: matriz de usuarios con recuento

Referencia de prompts MCP

El servidor proporciona 5 prompts preconstruidos para flujos de trabajo comunes:

  1. analyze-errors - Encontrar y analizar logs de errores
  2. stream-health-check - Realizar evaluación integral de salud
  3. investigate-field - Profundizar en valores y distribuciones de campos
  4. compare-streams - Comparar métricas entre múltiples flujos
  5. find-anomalies - Detectar patrones y anomalías inusuales

Para documentación detallada y ejemplos, consulte PROMPTS_GUIDE.md.

Descubrimiento de herramientas

Los agentes pueden descubrir todas las herramientas disponibles y sus esquemas de entrada/salida mediante el protocolo MCP. Cada descripción de herramienta incluye detalles sobre los campos devueltos y sus significados.

Extensión

Para agregar nuevas herramientas, cree un nuevo archivo en tools/, implemente la función de registro y agréguela a RegisterParseableTools en tools/register.go.

Solución de problemas

Problemas de conexión con PARSEABLE_URL

Verifique la conexión a Parseable:

curl -u admin:<password> http://localhost:8000/api/v1/about

El agente agota el tiempo de espera en consultas

  • Reduzca el rango de tiempo de la consulta
  • Agregue cláusulas LIMIT a las consultas SQL
  • Verifique que Parseable responda

El agente no puede encontrar flujos

  • Verifique que los flujos existan: pida al agente que "liste todos los flujos"
  • Verifique que los nombres de los flujos coincidan exactamente (distinguen mayúsculas y minúsculas)
  • Verifique que Parseable tenga datos en los flujos

Respuestas de prompt vacías

Verifique que:

  • El nombre del flujo exista y tenga datos
  • El rango de tiempo incluya eventos reales
  • PARSEABLE_URL, USER, PASS sean correctos

El agente devuelve datos incompletos

  • Verifique que el rango de tiempo contenga datos
  • Verifique que PARSEABLE_USER tenga permisos para los flujos
  • Use las capacidades de solución de problemas del agente para depurar

El servidor MCP no se inicia

Verifique:

  • Que el puerto 9034 esté disponible (para modo HTTP)
  • Que las variables de entorno estén configuradas
  • Que la versión de Go sea 1.20+ (go version)

Licencia

Este trabajo está licenciado bajo la LICENCIA PÚBLICA GENERAL DE GNU Versión 3.

Pendiente

  • Actualmente no se incluyen recursos para uso del agente (los prompts están implementados).
  • No hay herramientas para comprender las configuraciones de Parseable. Se puede usar la herramienta about para entender si es clúster o independiente, pero nada sobre la configuración.