loggly-mcp

Read-only Model Context Protocol (MCP) server for Loggly `/apiv2/*` APIs, plus IP intelligence (RDAP, GreyNoise, AbuseIPDB). Exposes Loggly search/analytics/field tools, aggregation-first traffic tools, and IP-context tools

GitHubExperimente este MCPPatrocinado

Documentação

Loggly MCP

loggly-mcp MCP server – quality and maintenance score on Glama

Servidor Model Context Protocol (MCP) somente leitura para as APIs /apiv2/* do Loggly, além de inteligência de IP (RDAP, GreyNoise, AbuseIPDB). Expõe ferramentas de busca/análise/campos do Loggly, ferramentas de tráfego com agregação em primeiro lugar e ferramentas de contexto de IP, bloqueando endpoints de escrita.

Uso de Habilidades

Para recuperação eficiente de logs (menos uso de tokens) e sumarização, combine este servidor com uma habilidade.

Início Rápido

Instalar via npm

LOGGLY_SUBDOMAIN=your-subdomain LOGGLY_TOKEN=your-token npx -y @andrewbabu/loggly-mcp

Configuração do cliente MCP:

{
  "mcpServers": {
    "loggly": {
      "command": "npx",
      "args": ["-y", "@andrewbabu/loggly-mcp"],
      "env": {
        "LOGGLY_SUBDOMAIN": "your-subdomain",
        "LOGGLY_TOKEN": "your-token"
      }
    }
  }
}

Executar a partir do código-fonte

git clone https://github.com/andrewbabu/loggly-mcp.git
cd loggly-mcp
npm install
cp .env.example .env

Edite .env com suas credenciais do Loggly e execute:

npm start

Depois que o repositório for confiável no Codex, o servidor MCP também pode ser iniciado automaticamente via .codex/config.toml.

Configuração

O servidor carrega .env do seu diretório de trabalho na inicialização.

Obrigatório

  • LOGGLY_SUBDOMAIN
    Subdomínio da conta Loggly ou URL completa do Loggly (ex.: your-subdomain ou https://your-subdomain.loggly.com)
  • LOGGLY_TOKEN
    Token da API Loggly

Opcional

  • LOGGLY_AUTH_MODE
    bearer (padrão) ou basic
  • LOGGLY_MAX_RETRIES
    Padrão: 2
  • LOGGLY_REQUEST_TIMEOUT_MS
    Padrão: 15000
  • LOGGLY_LOG_LEVEL
    error, warn, info (padrão) ou debug

Servidor Remoto (HTTP)

Para um servidor stdio que qualquer pessoa da equipe possa acessar pelo Claude Code sem um checkout local, execute a variante HTTP e hospede-a em um servidor/VM interno.

cp .env.example .env

Edite .env com suas credenciais do Loggly e também MCP_BEARER_TOKEN (gere um com node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"), depois:

npm run start:http

Isso inicia um servidor MCP HTTP Streamable sem estado em MCP_HTTP_PORT (padrão 8787):

  • GET /healthz — verificação de atividade sem autenticação.
  • POST /mcp — o endpoint MCP. Requer Authorization: Bearer <MCP_BEARER_TOKEN>; qualquer outra solicitação para /mcp recebe 401.

As credenciais do Loggly permanecem no lado do servidor — todos que se conectam compartilham o mesmo acesso à conta Loggly. MCP_BEARER_TOKEN apenas controla o acesso ao próprio servidor MCP, então trate-o como um segredo e rotacione-o se vazar (ex.: gere novamente e redistribua).

Execute isso apenas atrás da sua rede/VPN interna, não exponha diretamente à internet pública — há um único token compartilhado, não autenticação por usuário.

Conectando pelo Claude Code

Cada membro da organização adiciona o servidor remoto uma vez:

claude mcp add --transport http loggly https://your-internal-host:8787/mcp \
  --header "Authorization: Bearer <MCP_BEARER_TOKEN>"

Substitua pelo hostname/porta interno que você implantou e o token que recebeu.

Executando com Docker

docker build -t loggly-mcp .
docker run -d --name loggly-mcp -p 8787:8787 --env-file .env loggly-mcp

Múltiplas Contas / Domínios

O servidor pode armazenar credenciais para várias contas Loggly (subdomínios diferentes, tokens diferentes) ao mesmo tempo e direcioná-las por chamada de ferramenta.

Defina LOGGLY_ACCOUNTS como um objeto JSON que mapeia um nome de conta para suas credenciais:

LOGGLY_ACCOUNTS={"acme":{"subdomain":"acme","token":"acme_token","authMode":"bearer"},"beta":{"subdomain":"beta","token":"beta_token"}}

Quando LOGGLY_ACCOUNTS está definido, ele substitui LOGGLY_SUBDOMAIN/LOGGLY_TOKEN/LOGGLY_AUTH_MODE. Cada ferramenta então aceita um argumento opcional account (ex.: account: "acme") para escolher quais credenciais de conta usar para essa chamada.

  • Se account for omitido, o servidor usa LOGGLY_DEFAULT_ACCOUNT se definido, caso contrário "default", caso contrário a única conta configurada se houver apenas uma.
  • Um valor desconhecido de account retorna um erro listando os nomes das contas configuradas.
  • iterate_events_next também pode inferir a conta a partir do host next_url quando account é omitido, desde que exatamente uma conta configurada corresponda a esse host.

Configurações existentes de conta única (apenas LOGGLY_SUBDOMAIN/LOGGLY_TOKEN) continuam funcionando sem alterações — elas são tratadas como uma conta chamada "default".

Ferramentas de Tráfego com Agregação em Primeiro Lugar

Despejos de eventos brutos são lentos e caros para raciocinar. Essas ferramentas retornam um resumo — totais, detalhamentos top-N, uma linha do tempo em intervalos e uma pequena amostra representativa — em vez disso:

  • search_logs — a versão de uso geral: consulta + intervalo de tempo na entrada, resumo agregado na saída.
  • traffic_by_ip / traffic_by_host / traffic_by_path — mesma agregação, pré-escopada para um IP/hostname/caminho.
  • group_by_ip / group_by_path / group_by_user_agent — apenas contagens de facetas (wrappers finos sobre field_facets), para quando você só precisa de um detalhamento, não do agregado completo.
  • timeline — contagens em intervalos ao longo de um período, calculadas no lado do cliente via chamadas repetidas de /apiv2/events/count (o endpoint volume-metrics do Loggly não aceita uma consulta de texto livre, então esta é a única maneira de obter uma linha do tempo para uma busca arbitrária).
  • sample_events — um punhado de eventos brutos representativos, quando você precisa de exemplos em vez do conjunto completo de resultados.

A nomeação de campos depende de como cada fonte do Loggly analisa seus logs e pode diferir entre contas e até mesmo entre tags dentro de uma conta — então essas ferramentas resolvem nomes de campos primeiro pela descoberta: para qualquer papel não explicitamente sobrescrito (argumentos host_field/path_field/status_field/user_agent_field/ip_field, ou as variáveis de ambiente LOGGLY_FIELD_HOST/_PATH/_STATUS/_USER_AGENT/_IP), elas verificam /apiv2/fields/ para a consulta real e correspondem candidatos contra padrões de papel conhecidos:

  • Exatamente uma correspondência → usada automaticamente, relatada sob discovered_fields no resultado.
  • Múltiplas correspondências plausíveis (ex.: uma fonte com ambos ClientIp e CustIP) → nunca adivinhado entre elas — relatado sob ambiguous_fields em vez disso, recorrendo ao padrão configurado. Passe a correta explicitamente via o argumento *_field correspondente.
  • Nenhuma correspondência → recorre ao padrão configurado (host, path, status, user_agent, ip).

Execute list_fields você mesmo se quiser ver todos os candidatos antes de decidir sobre uma sobrescrita.

Inteligência de IP

  • rdap_lookup — propriedade de IP/registro de rede (RIR, netblock, org, país) via RDAP público (rdap.org). Nenhuma chave de API necessária.
  • ip_reputation — GreyNoise (ruído de varredura em toda a internet) + AbuseIPDB (relatórios de abuso da comunidade) para um IP. Requer GREYNOISE_API_KEY / ABUSEIPDB_API_KEY; se um deles estiver ausente, apenas retorna como available: false para essa fonte, não um erro.
  • get_ip_context — combina tudo acima com tráfego do Loggly (contagens 1h/24h/30d, primeira/última vez visto, hosts, principais caminhos) verificado em cada conta Loggly configurada, a menos que account seja fornecido, e sinaliza cross_domain_correlation quando o IP mostra atividade em mais de uma conta. De acordo com o playbook bot-traffic-triage, esse padrão entre domínios é o sinal mais forte para distinguir reconhecimento direcionado de ruído de fundo.

Trate toda a saída de inteligência de IP como uma entrada entre várias — dados de identidade/reputação (quem possui um IP, relatórios de scanners de terceiros) devem ter menos peso do que evidências comportamentais dos seus próprios logs. Veja a habilidade bot-traffic-triage para a metodologia completa de investigação.

Registro de Logs

Os logs são gravados em stderr para evitar interferência com o tráfego stdio do MCP.
Use LOGGLY_LOG_LEVEL para controlar a verbosidade. O padrão é info.

Timeouts, Repetições e Concorrência

As solicitações impõem um timeout por chamada de LOGGLY_REQUEST_TIMEOUT_MS (padrão 15000).
Falhas transitórias (429, 500 com corpo semelhante a timeout, 503, 504 ou timeouts de rede) são repetidas até LOGGLY_MAX_RETRIES vezes, respeitando um cabeçalho Retry-After em 429 quando o Loggly envia um, recorrendo a backoff exponencial caso contrário.

As ferramentas de agregação (search_logs, traffic_by_*, get_ip_context, etc.) distribuem várias solicitações por chamada via Promise.all (facetas + intervalos de linha do tempo + uma amostra). LOGGLY_MAX_CONCURRENT_REQUESTS (padrão 4) limita quantas dessas são executadas ao mesmo tempo por conta, para que a distribuição não dispare o limite de taxa do próprio Loggly por si só. Se você ainda vir 429s de uma única chamada de agregação, diminua isso; se o limite do Loggly for mais generoso, aumente.

Manifesto de Ferramentas

Os metadados das ferramentas são armazenados em tool-manifest.json e verificados contra src/server.js.

npm run verify:manifest

Teste de Fumaça

O teste de fumaça é executado sem credenciais do Loggly definindo LOGGLY_SMOKE_TEST=1.

npm run smoke

Ferramentas MCP Implementadas

Wrappers de API Loggly de baixo nível:

  • connection_test
  • create_search
  • get_events
  • search_and_get_events
  • iterate_events_page
  • iterate_events_next
  • count_events
  • volume_metrics
  • stats_query
  • list_fields
  • field_facets
  • raw_api_call

Ferramentas de tráfego com agregação em primeiro lugar:

  • search_logs
  • traffic_by_ip
  • traffic_by_host
  • traffic_by_path
  • group_by_ip
  • group_by_path
  • group_by_user_agent
  • timeline
  • sample_events

Inteligência de IP:

  • rdap_lookup
  • ip_reputation
  • get_ip_context

Exemplos

Exemplos de payloads de argumentos de ferramentas estão em examples/.

Desenvolvimento

npm test

npm test executa a verificação do manifesto e o teste de fumaça. O CI executa as mesmas verificações em .github/workflows/ci.yml.

Versionamento

  • VERSION contém a versão atual da release.
  • CHANGELOG.md rastreia mudanças por release.

Notas de Segurança

  • Arquivos .env nunca devem ser commitados.
  • Tokens e chaves de API (LOGGLY_TOKEN, LOGGLY_ACCOUNTS, GREYNOISE_API_KEY, ABUSEIPDB_API_KEY, MCP_BEARER_TOKEN) são tratados como segredos.
  • Este servidor impõe acesso somente leitura aos endpoints /apiv2/* do Loggly. Chamadas de inteligência de IP (RDAP/GreyNoise/AbuseIPDB) são solicitações GET somente leitura para esses serviços de terceiros; nenhuma credencial do Loggly é enviada a eles, e nenhuma chave de inteligência de IP é enviada ao Loggly.