guck MCP

古克

Guck是一个用于代理调试的小型MCP第一遥测存储。它提供 通过捕获JSONL遥测事件并公开 用于快速过滤查询的最小MCP工具集。

Guck的设计目的是：

• 语言不可知论：从任何运行时发出JSONL
• 先过滤：无默认尾随；MCP工具专注于目标查询
• 低摩擦：小可选SDK，简单 wrap 用于stdout/stderr的CLI

安装

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

注： guck 命令由提供 @guckdev/cli。如果您已经拥有 无关的npm guck 全局安装后，请先卸载。 如果您以前安装过 guck-cli，切换到 @guckdev/cli.

快速开始

1. 配置MCP（Codex/Claude/Copilot）：

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

1. 插入式日志捕获（JS）——使用auto-capture、emit（）或两者兼而有之：

import "@guckdev/sdk/auto";
import { emit } from "@guckdev/sdk";

emit({ message: "hello from app" });

1. 运行您的应用程序；MCP客户端将生成 guck mcp 日志可以通过以下方式查询

guck.stats / guck.search.

Vite插件（开发）

将Vite插件添加到代理 /guck/emit 在开发过程中：

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

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

然后将浏览器SDK指向 /guck/emit.

Monorepo布局

• packages/guck-cli --CLI（包装/发射/检查点/mcp）
• packages/guck-core --共享配置/类型/存储/编校
• packages/guck-js --JS-SDK
• packages/guck-mcp --MCP服务器
• packages/guck-py --Python SDK
• packages/guck-vite --Vite开发服务器插件
• specs --用于奇偶校验测试的共享合同夹具

Python SDK（预览版）

PyPI安装：

pip install guck-sdk

本地开发安装：

uv pip install -e packages/guck-py

用途：

from guck import emit

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

最佳实践（复制粘贴）

1. 添加共享配置（提交到仓库）：

.guck.json

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

可选：添加 .guck.local.json for per-dev重写（被git忽略）。 你可以跑 guck init 脚手架 .guck.json.

1. 在AGENTS.md中添加一行：

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

1. 运行：

guck wrap --service api --session session-001 -- 
guck mcp

会话与跟踪

Guck支持两者 session_id 和 trace_id，但它们有不同的用途：

• trace_id 是 请求范围 相关性（跨服务的单个事务）。
• session_id 是 运行范围 相关性（开发运行、测试运行或本地实验）。

session_id 即使您已经有了跟踪，它也很有用，因为许多事件 不依赖于跟踪（启动、后台作业、cron任务等）。它还提供 您可以使用一种简单的方法来过滤整个开发运行，而无需布线跟踪传播。

例子：

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

配置

Guck读到 .guck.json 从您的repo根目录。如果存在， .guck.local.json 是 合并到顶部以进行每开发覆盖。

古克是 默认启用 使用内置默认值。添加a .guck.json （以及 可选的 .guck.local.json)或设置 GUCK_CONFIG_PATH （或 GUCK_CONFIG)to 指向配置文件或repo目录。您还可以设置 "enabled": false 在配置中明确关闭它。

对于跨多个存储库的MCP使用，每个工具都接受一个可选 config_path 参数指向特定 .guck.json.

多服务或多仓库跟踪（共享存储）

要跨本地微服务（或多个存储库）进行跟踪，请指向每个服务 与此同时 绝对的 日志目录通过 GUCK_DIR。这将创建一个 共享日志存储 guck.search 可以查询。使用共享 GUCK_SESSION_ID 到 关联事件并区分 service 名称以分隔来源。

共享环境示例：

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

远程后端（CloudWatch/K8s）需要可选的SDK安装；仅当您使用它们时才安装。

JS SDK自动捕获（stdout/stderr）

JS SDK可以打补丁 process.stdout 和 process.stderr 发出Guck事件。 在应用程序启动的早期启用它：

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

配置切换：

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

如果你正在使用 guck wrap，CLI设置 GUCK_WRAPPED=1 以及SDK 自动捕获会故意跳过以避免重复记录。

浏览器SDK（控制台+错误）

使用接受以下条件的开发服务器端点 /guck/emit 并将事件写入 当地商店。在Vite @guckdev/vite 插件提供了这个端点。对于 其他堆栈，添加一个小型端点，将有效负载转发到服务器端 emit().

发送浏览器事件：

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

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

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

自动捕获控制台输出+未处理的错误：

const { stop } = client.installAutoCapture();

console.error("boom");

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

笔记：

• installAutoCapture() 通常应在应用程序启动时调用一次；重复调用将多次包装控制台。
• 如果将其安装在组件或测试中，请调用 stop() 清理以避免重复记录。
• 对于SPA，可以打电话 installAutoCapture() 一旦进入您的应用程序条目（例如。 index.ts)永远不要打电话 stop().
• 还没有预构建的UMD/IIFE捆绑包；对于vanilla JS，您应该使用bundler或本地ESM导入。

环境覆盖

• GUCK_CONFIG_PATH --显式配置路径（文件或仓库目录）
• GUCK_CONFIG --别名 GUCK_CONFIG_PATH
• GUCK_DIR --存储目录覆盖（默认： ~/.guck/logs)
• GUCK_ENABLED --真/假
• GUCK_SERVICE --服务名称
• GUCK_SESSION_ID --会话覆盖
• GUCK_RUN_ID --运行id覆盖

检查点

guck checkpoint 写a .guck-checkpoint 根目录下的文件 商店目录(GUCK_DIR 或 ~/.guck/logs)包含纪元毫秒时间戳。当 MCP工具在没有 since，Guck使用检查点时间戳作为 默认时间窗口。你 也可以通过 since: "checkpoint" 将查询明确地锚定到 检查站。

事件模式（JSONL）

日志中的每一行都是一个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" }
}

店内布局

默认情况下，Guck每次运行都会在以下目录下写入JSONL文件 ~/.guck/logs:

~/.guck/logs///.jsonl

集 GUCK_DIR 以覆盖根。

最小CLI

Guck的CLI故意最小化。它的存在是为了 捕捉 和 服务 遥测；滤波首先是MCP。

• guck init --创建 .guck.json
• guck checkpoint --写 .guck-checkpoint 纪元时间戳
• guck wrap --service --session -- --捕获stdout/stderr
• guck emit --service --session --从stdin附加JSON事件
• guck mcp --启动MCP服务器
• guck upgrade [--manager ] --更新CLI安装

MCP工具

Guck公开了这些MCP工具（先过滤）：

• guck.search
• guck.search_batch
• guck.stats
• guck.sessions
• guck.tail （可用，但不是文档中的默认值）

搜索和尾部参数

guck.search 和 guck.tail 支持其他输出和查询控件：

• query --布尔搜索 仅消息 不区分大小写支持 AND, OR, NOT、括号和引号短语。
• contains --在message/type/session_id/data中搜索子字符串（未更改）。
• format — json （默认）或 text.
• fields --何时 format: "json"，将事件投影到这些字段。点状路径，如 data.rawPeak 支持。
• flatten --何时 format: "json"，将虚线字段路径作为顶级键发出（例如。 "data.rawPeak": 43).
• template --何时 format: "text"，使用标记格式化每一行，如下所示 {ts}|{service}|{message}.点状标记，如 {data.rawPeak} 支持。缺少的令牌将变为空字符串。
• force --绕过输出大小保护并返回全部有效载荷。
• max_message_chars --每条消息的上限；修剪 message 仅限现场。

输出上限为 mcp.max_output_chars如果响应将超过上限， 该工具返回警告而不是事件/行，除非 force=true. 警告包括 avg_message_chars 和 max_message_chars 根据完整、未修剪的消息计算。

示例：

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

AI使用指南

从...开始 统计那么 搜索，并且仅 尾巴 如果需要：

1. guck.stats 时间窗口很窄
2. guck.search 相关类型/级别/消息
3. guck.tail 仅当需要直播时

这使提示保持简短，并避免用不相关的日志淹没模型。

调试策略（推荐）

使用Guck作为紧密循环，以避免日志垃圾邮件和浪费令牌：

1. 范围 随着 guck.stats （短时间窗口、服务/会话）。
2. 检查 随着 guck.search 用于错误/警告或特定边界。
3. 假设 故障阶段或组件。
4. 仪器 只有边界（入口/出口、输入/输出）。
5. 重新运行 并重新查询同一窄窗口。

这使调查保持专注，同时仍然能够进行深入的迭代调试。

补救措施

Guck对以下内容进行了编辑 写 继续 读 使用配置的密钥名称 以及正则表达式模式。

兼容性

任何语言都可以通过将JSONL行写入存储来发出Guck事件。 可选的SDK只是增加了便利，如 run_id 以及编辑。

MCP服务器配置示例

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

许可证

麻省理工学院

看