mcp-parseable-server

Servidor MCP para a plataforma de observabilidade Parseable

GitHub
4
Experimente este MCPPatrocinado

Documentação

mcp-parseable-server - Um servidor MCP Parseable

Este projeto está atualmente em desenvolvimento inicial com foco em dados de log. Feedback e contribuições são bem-vindos.

Os testes foram feitos usando:

  • vscode com Github Copilot como agente.
  • ferramenta CLI opencode agent

[TOC]

Visão Geral

Este projeto fornece um servidor MCP (Message Context Protocol) para Parseable, permitindo que agentes e ferramentas de IA interajam com streams de dados do Parseable (logs, métricas, traces) usando linguagem natural e chamadas de ferramentas estruturadas.

Recursos

  • Listar streams de dados disponíveis no Parseable
  • Consultar streams de dados usando SQL
  • Obter schema, estatísticas e informações para qualquer stream de dados
  • Registro modular de ferramentas MCP para fácil extensão
  • Suporta modos MCP HTTP e stdio
  • Configuração baseada em variáveis de ambiente e flags
  • O servidor MCP retorna respostas em JSON, onde o payload está tanto em formato texto quanto estruturado.

No Parseable, os nomes de dataset e data stream são usados de forma intercambiável, pois os datasets do Parseable são essencialmente streams de dados nomeados. Em todas as descrições de ferramentas, tentamos usar o termo data stream para evitar confusão com o termo dataset, que pode ter significados diferentes em outros contextos.

Limitações

Autenticação

O servidor MCP não implementa nenhum mecanismo de autenticação. Se isso for necessário, use um proxy reverso como nginx ou envoy na frente do servidor MCP para adicionar autenticação e autorização.

Gerenciamento de sessão MCP

O servidor MCP não implementa nenhum gerenciamento de sessão, pois todas as chamadas de ferramentas são stateless. Isso pode mudar no futuro.

Compilação

Certifique-se de ter o 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

Execução

Modo HTTP (padrão)

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

O servidor MCP escutará em http://localhost:9034/mcp para solicitações de agentes/ferramentas.

Modo Stdio

./mcp-parseable-server --mode stdio

Este modo é usado para fluxos de trabalho CLI ou agente-a-agente.

Configuração

Você pode configurar a conexão com o Parseable usando variáveis de ambiente ou flags:

  • PARSEABLE_URL ou --parseable-url- URL da instância Parseable (padrão: http://localhost:8000)
  • PARSEABLE_USERNAME ou --parseable-user (padrão: admin)
  • PARSEABLE_PASSWORD ou --parseable-pass (padrão: admin)
  • LISTEN_ADDR ou --listen - o endereço ao executar o servidor MCP em modo HTTP (padrão: :9034)
  • INSECURE - defina como true para pular a verificação TLS (padrão: false)`
  • LOG_LEVEL - defina o nível de log. Níveis suportados: debug, info, warn e error (padrão: info)

Exemplo:

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

Implantação em produção

Para implantação em produção, use um proxy reverso como nginx ou envoy na frente do servidor MCP que gerencie autenticação, autorização e terminação TLS.

Testes

Consulte TESTING.md para um guia completo de testes.

Referência de Ferramentas MCP

1. query_data_stream

Execute uma consulta SQL em um data stream.

  • Entradas:
    • query: string de consulta SQL
    • streamName: Nome do data stream
    • startTime: horário de início ISO 8601 (ex.: 2026-01-01T00:00:00+00:00)
    • endTime: horário de término ISO 8601
  • Retorna: Resultado da consulta e a contagem de linhas retornadas

2. get_data_streams

Lista todos os data streams disponíveis no Parseable.

  • Retorna: Array de objetos de stream com contagem

3. get_data_stream_schema

Obtém o schema de campos para um data stream específico.

  • Entradas:
    • stream: Nome do data stream
  • Retorna: Campos e tipos do schema

4. get_data_stream_stats

Obtém estatísticas para um data stream.

  • Entradas:
    • streamName: Nome do data stream
  • Retorna: Objeto de estatísticas (veja a descrição da ferramenta para detalhes)

5. get_data_stream_info

Obtém informações para um data stream.

  • Entradas:
    • streamName: Nome do data stream
  • Retorna: Objeto de informações (veja a descrição da ferramenta para detalhes)

6. get_about

Obtém informações sobre o Parseable.

  • Retorna: Objeto About (veja a descrição da ferramenta para detalhes)

7. get_roles

Obtém as funções do Parseable.

  • Retorna: Objeto de funções (veja a descrição da ferramenta para detalhes)

8. get_users

Obtém todos os usuários configurados.

  • Retorna: Array de usuários com contagem

Referência de Prompts MCP

O servidor fornece 5 prompts pré-construídos para fluxos de trabalho comuns:

  1. analyze-errors - Encontrar e analisar logs de erro
  2. stream-health-check - Realizar avaliação abrangente de saúde
  3. investigate-field - Aprofundar-se em valores e distribuições de campos
  4. compare-streams - Comparar métricas entre vários streams
  5. find-anomalies - Detectar padrões e anomalias incomuns

Para documentação detalhada e exemplos, consulte PROMPTS_GUIDE.md.

Descoberta de Ferramentas

Os agentes podem descobrir todas as ferramentas disponíveis e seus schemas de entrada/saída por meio do protocolo MCP. Cada descrição de ferramenta inclui detalhes sobre os campos retornados e seus significados.

Extensão

Para adicionar novas ferramentas, crie um novo arquivo em tools/, implemente a função de registro e adicione-a a RegisterParseableTools em tools/register.go.

Solução de Problemas

Problemas de conexão com PARSEABLE_URL

Verifique a conexão com o Parseable:

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

O agente expira em consultas

  • Reduza o intervalo de tempo da consulta
  • Adicione cláusulas LIMIT às consultas SQL
  • Verifique se o Parseable está responsivo

O agente não encontra streams

  • Verifique se os streams existem: peça ao agente para "listar todos os streams"
  • Verifique se os nomes dos streams correspondem exatamente (sensível a maiúsculas/minúsculas)
  • Verifique se o Parseable tem dados nos streams

Respostas vazias de prompt

Verifique se:

  • O nome do stream existe e tem dados
  • O intervalo de tempo inclui eventos reais
  • PARSEABLE_URL, USER, PASS estão corretos

O agente retorna dados incompletos

  • Verifique se o intervalo de tempo contém dados
  • Verifique se PARSEABLE_USER tem permissões para os streams
  • Use os recursos de solução de problemas do agente para depurar

O servidor MCP não inicia

Verifique:

  • A porta 9034 está disponível (para o modo HTTP)
  • As variáveis de ambiente estão definidas
  • A versão do Go é 1.20+ (go version)

Licença

Este trabalho é licenciado sob a GNU GENERAL PUBLIC LICENSE Versão 3.

Tarefas

  • Nenhum recurso está atualmente incluído para uso do agente (os prompts estão implementados).
  • Não há ferramentas para entender as configurações do Parseable. É possível, usando a ferramenta about, entender se é cluster ou standalone, mas nada sobre a configuração.