Guck MCP

Guck is a tiny, MCP-first telemetry store for agentic debugging. It provides token-efficient log analytics by capturing JSONL telemetry events and exposing a minimal MCP toolset for fast, filtered queries.

- Language-agnostic: emit JSONL from any runtime
- Filter-first: no default tailing; MCP tools focus on targeted queries
- Low-friction: small optional SDK, simplewrapCLI for stdout/stderr

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

Note: theguckcommand is provided by@guckdev/cli. If you already have the unrelated npmguckinstalled globally, uninstall it first. If you previously installedguck-cli, switch to@guckdev/cli.

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

- Drop‑in log capture (JS) — use auto‑capture, emit(), or both:

import "@guckdev/sdk/auto"; import { emit } from "@guckdev/sdk"; emit({ message: "hello from app" });

- Run your app; the MCP client will spawnguck mcpand logs are queryable viaguck.stats/guck.search.

Add the Vite plugin to proxy/guck/emitduring development:

import { defineConfig } from "vite"; import { guckVitePlugin } from "@guckdev/vite"; export default defineConfig({ plugins: [guckVitePlugin()], });

Then point the browser SDK at/guck/emit.

- packages/guck-cli— CLI (wrap/emit/checkpoint/mcp)
- packages/guck-core— shared config/types/store/redaction
- packages/guck-js— JS SDK
- packages/guck-mcp— MCP server
- packages/guck-py— Python SDK
- packages/guck-vite— Vite dev server plugin
- specs— shared contract fixtures for parity tests

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

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

Optional: add.guck.local.jsonfor per-dev overrides (ignored by git). You can runguck initto scaffold.guck.json.

When debugging, use Guck telemetry first (guck.stats → guck.search; tail only if asked).

guck wrap --service api --session session-001 -- <your command> guck mcp

Guck supports bothsession_idandtrace_id, but they serve different purposes:

- trace_idisrequest-scopecorrelation (a single transaction across services).
- session_idisrun-scopecorrelation (a dev run, test run, or local experiment).

session_idis useful even when you already have traces because many events are not tied to a trace (startup, background jobs, cron tasks, etc.). It also gives you a simple way to filter a whole dev run without wiring trace propagation.

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

Guck reads.guck.jsonfrom your repo root. If present,.guck.local.jsonis merged on top for per-dev overrides.

Guck isenabled by defaultusing built-in defaults. Add a.guck.json(and optional.guck.local.json) or setGUCK_CONFIG_PATH(orGUCK_CONFIG) to point at a config file or repo directory. You can also set"enabled": falseinside the config to turn it off explicitly.

For MCP usage across multiple repos, each tool accepts an optionalconfig_pathparameter to point at a specific.guck.json.

Multi-service or multi-repo tracing (shared store)

To trace across local microservices (or multiple repos), point every service at the sameabsolutelog directory viaGUCK_DIR. This creates a single shared log store thatguck.searchcan query across. Use a sharedGUCK_SESSION_IDto correlate events and distinctservicenames to separate sources.

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

{ "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 } }

Remote backends (CloudWatch/K8s) require optional SDK installs; install only if you use them.

The JS SDK can patchprocess.stdoutandprocess.stderrto emit Guck events. Enable it early in your app startup:

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

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

If you're usingguck wrap, the CLI setsGUCK_WRAPPED=1and the SDK auto-capture intentionally skips to avoid double logging.

Use a dev server endpoint that accepts/guck/emitand writes events to the local store. In Vite, the@guckdev/viteplugin provides this endpoint. For other stacks, add a small endpoint that forwards payloads to your server-sideemit().

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 console output + unhandled errors:

const { stop } = client.installAutoCapture(); console.error("boom"); // call stop() to restore console and listeners (useful in component unmounts/tests) stop();

- installAutoCapture()should usually be called once at app startup; repeated calls will wrap console multiple times.
- If you install it inside a component or test, callstop()on cleanup to avoid duplicate logging.
- For SPAs, it's fine to callinstallAutoCapture()once in your app entry (e.g.index.ts) and never callstop().
- There is no prebuilt UMD/IIFE bundle yet; for vanilla JS you should use a bundler or a native ESM import.

- GUCK_CONFIG_PATH— explicit config path (file or repo dir)
- GUCK_CONFIG— alias ofGUCK_CONFIG_PATH
- GUCK_DIR— store dir override (default:~/.guck/logs)
- GUCK_ENABLED— true/false
- GUCK_SERVICE— service name
- GUCK_SESSION_ID— session override
- GUCK_RUN_ID— run id override

guck checkpointwrites a.guck-checkpointfile in the root of your store dir (GUCK_DIRor~/.guck/logs) containing an epoch millisecond timestamp. When MCP tools are called withoutsince, Guck uses the checkpoint timestamp as the default time window. You can also passsince: "checkpoint"to explicitly anchor a query to the checkpoint.

Each line in the log is a single JSON event:

{ "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" } }

By default, Guck writes per-run JSONL files under~/.guck/logs:

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

Guck’s CLI is intentionally minimal. It exists tocaptureandservetelemetry; filtering is MCP-first.

- guck init— create.guck.json
- guck checkpoint— write.guck-checkpointepoch timestamp
- guck wrap --service <name> --session <id> -- <cmd...>— capture stdout/stderr
- guck emit --service <name> --session <id>— append JSON events from stdin
- guck mcp— start MCP server
- guck upgrade [--manager <npm|pnpm|yarn|bun>]— update the CLI install

Guck exposes these MCP tools (filter-first):

- guck.search
- guck.search_batch
- guck.stats
- guck.sessions
- guck.tail(available, but not default in docs)

guck.searchandguck.tailsupport additional output and query controls:

- query— boolean search overmessage only(case-insensitive). SupportsAND,OR,NOT, parentheses, and quoted phrases.
- contains— substring search across message/type/session_id/data (unchanged).
- format—json(default) ortext.
- fields— whenformat: "json", project events to these fields. Dotted paths likedata.rawPeakare supported.
- flatten— whenformat: "json", emit dotted field paths as top-level keys (e.g."data.rawPeak": 43).
- template— whenformat: "text", format each line using tokens like{ts}|{service}|{message}. Dotted tokens like{data.rawPeak}are supported. Missing tokens become empty strings.
- force— bypass output-size guard and return the full payload.
- max_message_chars— per-message cap; trims themessagefield only.

Output is capped bymcp.max_output_chars. If a response would exceed the cap, the tool returns a warning instead of events/lines unlessforce=true. Warnings includeavg_message_charsandmax_message_charscomputed from full, untrimmed messages.

{ "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 }

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

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

Start withstats, thensearch, and onlytailif needed:
- guck.statswith a narrow time window
- guck.searchfor relevant types/levels/messages
- guck.tailonly when live-streaming is required

This keeps prompts short and avoids flooding the model with irrelevant logs.

Use Guck as a tight loop to avoid log spam and wasted tokens:
- Scopewithguck.stats(short time window, service/session).
- Inspectwithguck.searchfor errors/warns or a specific boundary.
- Hypothesizethe failing stage or component.
- Instrumentonly the boundary (entry/exit, inputs/outputs).
- Re-runand re-query the same narrow window.

This keeps investigations focused while still enabling deep, iterative debugging.

Guck applies redaction onwriteand onreadusing configured key names and regex patterns.

Any language can emit Guck events by writing JSONL lines to the store. The optional SDK simply adds conveniences likerun_idand redaction.

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

Paid remote MCP for AI agent run monitoring, failure detection, tool-call incident replay, SLA receipts, and client status exports.

Behavioral trust scoring for 14,820+ MCP servers. Check reliability, latency, and success rates before tool calls.

Multi-Agent Monitoring LangFuse MCP Server

A Model Context Protocol (MCP) server for comprehensive monitoring and observability of multi-agent systems using Langfuse.

Expose data observability, lineage, test results & incidents to AI agents via MCP

Seamlessly bring real-time production context—logs, metrics, and traces—into your local environment to auto-fix code faster.

Scout's official MCP pipes error, trace and metric data from production to your AI agent

Interact with Bigeye's data quality monitoring platform via its Datawatch API. Supports dynamic API key authentication.

Stateful health monitoring, diagnostics, and web attestation for AI agents. 11 MCP tools. Free Founder's Beta

Access Grafana resources like dashboards, datasources, Prometheus, Loki, and alerts.

Access and manage Grafana resources, including dashboards, datasources, Prometheus, Loki, and alerting.