Guck MCP

Guck é um pequeno armazenamento de telemetria focado em MCP para depuração de agentes.

GitHub
2
Experimente este MCPPatrocinado

Documentação

Guck

Guck é um armazenamento de telemetria minúsculo, MCP-first, para depuração agêntica. Ele fornece análise de logs eficiente em tokens ao capturar eventos de telemetria JSONL e expor um conjunto mínimo de ferramentas MCP para consultas rápidas e filtradas.

Guck foi projetado para ser:

  • Agnóstico de linguagem: emita JSONL de qualquer runtime
  • Filtro primeiro: sem tail padrão; as ferramentas MCP focam em consultas direcionadas
  • Baixo atrito: SDK opcional pequeno, CLI wrap simples para stdout/stderr

Instalação

pnpm add -g @guckdev/cli
# or
npm install -g @guckdev/cli
# or
npx @guckdev/cli

Nota: o comando guck é fornecido pelo @guckdev/cli. Se você já tiver o guck npm não relacionado instalado globalmente, desinstale-o primeiro. Se você instalou o guck-cli anteriormente, mude para o @guckdev/cli.

Início rápido

  1. Configure o MCP (Codex/Claude/Copilot):
{
  "mcpServers": {
    "guck": {
      "command": "guck",
      "args": ["mcp"],
      "env": {
        "GUCK_CONFIG_PATH": "/path/to/.guck.json"
      }
    }
  }
}
  1. Captura de logs drop-in (JS) — use auto-capture, emit(), ou ambos:
import "@guckdev/sdk/auto";
import { emit } from "@guckdev/sdk";

emit({ message: "hello from app" });
  1. Execute seu aplicativo; o cliente MCP iniciará o guck mcp e os logs poderão ser consultados via guck.stats / guck.search.

Vite drop-in (dev)

Adicione o plugin Vite para fazer proxy do /guck/emit durante o desenvolvimento:

import { defineConfig } from "vite";
import { guckVitePlugin } from "@guckdev/vite";

export default defineConfig({
  plugins: [guckVitePlugin()],
});

Em seguida, aponte o SDK do navegador para /guck/emit.

Estrutura do monorepo

  • packages/guck-cli — CLI (wrap/emit/checkpoint/mcp)
  • packages/guck-core — configuração/tipos/armazenamento/redação compartilhados
  • packages/guck-js — SDK JS
  • packages/guck-mcp — servidor MCP
  • packages/guck-py — SDK Python
  • packages/guck-vite — plugin do servidor de desenvolvimento Vite
  • specs — fixtures de contrato compartilhadas para testes de paridade

SDK Python (prévia)

Instalação via PyPI:

pip install guck-sdk

Instalação local de desenvolvimento:

uv pip install -e packages/guck-py

Uso:

from guck import emit

emit({"message": "hello from python"})

Melhores práticas (copiar e colar)

  1. Adicione a configuração compartilhada (commit no repositório):

.guck.json

{
  "version": 1,
  "enabled": true,
  "default_service": "api"
}

Opcional: adicione .guck.local.json para substituições por desenvolvedor (ignorado pelo git). Você pode executar guck init para gerar o .guck.json.

  1. Adicione uma linha ao AGENTS.md:
When debugging, use Guck telemetry first (guck.stats → guck.search; tail only if asked).
  1. Execute:
guck wrap --service api --session session-001 -- <your command>
guck mcp

Sessão vs trace

Guck suporta tanto session_id quanto trace_id, mas eles servem a propósitos diferentes:

  • trace_id é correlação de escopo de requisição (uma única transação entre serviços).
  • session_id é correlação de escopo de execução (uma execução de desenvolvimento, execução de teste ou experimento local).

session_id é útil mesmo quando você já tem traces, porque muitos eventos não estão vinculados a um trace (inicialização, jobs em segundo plano, tarefas cron, etc.). Ele também oferece uma maneira simples de filtrar uma execução de desenvolvimento inteira sem configurar a propagação de traces.

Exemplo:

export GUCK_SESSION_ID=session-001
guck wrap --service api --session session-001 -- pnpm run dev

Configuração

Guck lê .guck.json da raiz do seu repositório. Se presente, .guck.local.json é mesclado por cima para substituições por desenvolvedor.

Guck está habilitado por padrão usando padrões integrados. Adicione um .guck.json (e opcionalmente .guck.local.json) ou defina GUCK_CONFIG_PATH (ou GUCK_CONFIG) para apontar para um arquivo de configuração ou diretório do repositório. Você também pode definir "enabled": false dentro da configuração para desativá-lo explicitamente.

Para uso do MCP em vários repositórios, cada ferramenta aceita um parâmetro opcional config_path para apontar para um .guck.json específico.

Rastreamento multi-serviço ou multi-repo (armazenamento compartilhado)

Para rastrear entre microsserviços locais (ou vários repositórios), aponte cada serviço para o mesmo diretório de logs absoluto via GUCK_DIR. Isso cria um armazenamento de logs compartilhado único que guck.search pode consultar. Use um GUCK_SESSION_ID compartilhado para correlacionar eventos e nomes de service distintos para separar fontes.

Exemplo de ambiente compartilhado:

export GUCK_DIR=/path/to/guck/logs
export GUCK_SESSION_ID=session-001
# optional: share a single config across repos
export GUCK_CONFIG_PATH=/path/to/shared/.guck.json

Exemplo de configuração compartilhada:

{
  "version": 1,
  "enabled": true,
  "default_service": "api",
  "redaction": {
    "enabled": true,
    "keys": ["authorization","api_key","token","secret","password"],
    "patterns": ["sk-[A-Za-z0-9]{20,}","Bearer\\s+[A-Za-z0-9._-]+"]
  },
  "mcp": { "max_results": 200, "max_output_chars": 20000, "default_lookback_ms": 300000 }
}

Backends remotos (CloudWatch/K8s) exigem instalações opcionais do SDK; instale apenas se você os usar.

Auto-captura do SDK JS (stdout/stderr)

O SDK JS pode corrigir process.stdout e process.stderr para emitir eventos Guck. Habilite-o no início da inicialização do seu aplicativo:

import "@guckdev/sdk/auto";
// or
import { installAutoCapture } from "@guckdev/sdk";
installAutoCapture();

Alternâncias de configuração:

{ "sdk": { "enabled": true, "capture_stdout": true, "capture_stderr": true } }

Se você estiver usando guck wrap, a CLI define GUCK_WRAPPED=1 e a auto-captura do SDK intencionalmente pula para evitar registro duplicado.

SDK do navegador (console + erros)

Use um endpoint do servidor de desenvolvimento que aceite /guck/emit e grave eventos no armazenamento local. No Vite, o plugin @guckdev/vite fornece esse endpoint. Para outras stacks, adicione um endpoint pequeno que encaminhe payloads para o emit() do lado do servidor.

Emita eventos do navegador:

import { createBrowserClient } from "@guckdev/browser";

const client = createBrowserClient({
  endpoint: "/guck/emit",
  service: "web",
  sessionId: "session-001",
});

await client.emit({ message: "hello from the browser" });

Auto-capture da saída do console + erros não tratados:

const { stop } = client.installAutoCapture();

console.error("boom");

// call stop() to restore console and listeners (useful in component unmounts/tests)
stop();

Notas:

  • installAutoCapture() geralmente deve ser chamado uma vez na inicialização do aplicativo; chamadas repetidas envolverão o console várias vezes.
  • Se você instalá-lo dentro de um componente ou teste, chame stop() na limpeza para evitar registro duplicado.
  • Para SPAs, tudo bem chamar installAutoCapture() uma vez na entrada do seu aplicativo (ex.: index.ts) e nunca chamar stop().
  • Ainda não há bundle UMD/IIFE pré-construído; para JS vanilla, você deve usar um bundler ou importação ESM nativa.

Substituições de ambiente

  • GUCK_CONFIG_PATH — caminho de configuração explícito (arquivo ou diretório do repositório)
  • GUCK_CONFIG — alias de GUCK_CONFIG_PATH
  • GUCK_DIR — substituição do diretório de armazenamento (padrão: ~/.guck/logs)
  • GUCK_ENABLED — true/false
  • GUCK_SERVICE — nome do serviço
  • GUCK_SESSION_ID — substituição de sessão
  • GUCK_RUN_ID — substituição do ID de execução

Checkpoint

guck checkpoint grava um arquivo .guck-checkpoint na raiz do seu diretório de armazenamento (GUCK_DIR ou ~/.guck/logs) contendo um timestamp em milissegundos epoch. Quando as ferramentas MCP são chamadas sem since, Guck usa o timestamp do checkpoint como janela de tempo padrão. Você também pode passar since: "checkpoint" para ancorar explicitamente uma consulta ao checkpoint.

Esquema de eventos (JSONL)

Cada linha no log é um único evento JSON:

{
  "id": "uuid",
  "ts": "2026-02-08T18:40:00.123Z",
  "level": "info",
  "type": "log",
  "service": "worker",
  "run_id": "uuid",
  "session_id": "session-123",
  "message": "speaker started",
  "data": { "turnId": 3 },
  "tags": { "env": "local" },
  "trace_id": "...",
  "span_id": "...",
  "source": { "kind": "sdk" }
}

Estrutura de armazenamento

Por padrão, Guck grava arquivos JSONL por execução em ~/.guck/logs:

~/.guck/logs/<service>/<YYYY-MM-DD>/<run_id>.jsonl

Defina GUCK_DIR para substituir a raiz.

CLI mínima

A CLI do Guck é intencionalmente mínima. Ela existe para capturar e servir telemetria; a filtragem é MCP-first.

  • guck init — criar .guck.json
  • guck checkpoint — gravar timestamp epoch .guck-checkpoint
  • guck wrap --service <name> --session <id> -- <cmd...> — capturar stdout/stderr
  • guck emit --service <name> --session <id> — anexar eventos JSON do stdin
  • guck mcp — iniciar servidor MCP
  • guck upgrade [--manager <npm|pnpm|yarn|bun>] — atualizar a instalação da CLI

Ferramentas MCP

Guck expõe estas ferramentas MCP (filtro primeiro):

  • guck.search
  • guck.search_batch
  • guck.stats
  • guck.sessions
  • guck.tail (disponível, mas não padrão na documentação)

Parâmetros de busca e tail

guck.search e guck.tail suportam controles adicionais de saída e consulta:

  • query — busca booleana apenas sobre message (sem diferenciar maiúsculas/minúsculas). Suporta AND, OR, NOT, parênteses e frases entre aspas.
  • contains — busca por substring em message/type/session_id/data (inalterado).
  • format — json (padrão) ou text.
  • fields — quando format: "json", projete eventos para estes campos. Caminhos com pontos como data.rawPeak são suportados.
  • flatten — quando format: "json", emita caminhos de campos com pontos como chaves de nível superior (ex.: "data.rawPeak": 43).
  • template — quando format: "text", formate cada linha usando tokens como {ts}|{service}|{message}. Tokens com pontos como {data.rawPeak} são suportados. Tokens ausentes se tornam strings vazias.
  • force — ignorar a proteção de tamanho de saída e retornar o payload completo.
  • max_message_chars — limite por mensagem; trunca apenas o campo message.

A saída é limitada por mcp.max_output_chars. Se uma resposta exceder o limite, a ferramenta retorna um aviso em vez de eventos/linhas, a menos que force=true. Os avisos incluem avg_message_chars e max_message_chars calculados a partir de mensagens completas, sem truncamento.

Exemplos:

{ "query": "error AND (db OR timeout)" }
{ "format": "text", "template": "{ts}|{service}|{message}" }
{ "format": "json", "fields": ["ts", "level", "message"] }
{ "format": "json", "fields": ["ts", "data.rawPeak"], "flatten": true }

Busca em lote:

{
  "searches": [
    { "id": "errors", "query": "error", "limit": 50 },
    { "id": "warnings", "levels": ["warn"], "limit": 50, "max_message_chars": 200 }
  ]
}

Saída mínima recomendada para agentes:

{ "format": "text", "template": "{ts}|{service}|{message}" }

Orientação de uso para IA

Comece com stats, depois search, e use tail apenas se necessário:

  1. guck.stats com uma janela de tempo estreita
  2. guck.search para tipos/níveis/mensagens relevantes
  3. guck.tail apenas quando streaming ao vivo for necessário

Isso mantém os prompts curtos e evita inundar o modelo com logs irrelevantes.

Estratégia de depuração (recomendada)

Use Guck como um loop fechado para evitar spam de logs e desperdício de tokens:

  1. Escopo com guck.stats (janela de tempo curta, serviço/sessão).
  2. Inspecione com guck.search para erros/avisos ou um limite específico.
  3. Formule hipóteses sobre o estágio ou componente com falha.
  4. Instrumente apenas o limite (entrada/saída, entradas/saídas).
  5. Execute novamente e consulte novamente a mesma janela estreita.

Isso mantém as investigações focadas enquanto ainda permite depuração profunda e iterativa.

Redação

Guck aplica redação na gravação e na leitura usando nomes de chave e padrões regex configurados.

Compatibilidade

Qualquer linguagem pode emitir eventos Guck gravando linhas JSONL no armazenamento. O SDK opcional simplesmente adiciona conveniências como run_id e redação.

Exemplo de configuração do servidor MCP

{
  "mcpServers": {
    "guck": {
      "command": "guck",
      "args": ["mcp"],
      "env": {
        "GUCK_CONFIG_PATH": "/path/to/.guck.json"
      }
    }
  }
}

Licença

MIT

guck