Graylog Agent Toolkit

一个不绑定模型厂商的 Graylog MCP 服务，以及可移植的代码运行时诊断 Skill。目标是让 Codex、Gemini CLI、支持 MCP 的 IDE、自建 Agent 使用同一套查询能力和诊断流程。

设计

项目把能力拆成三个稳定层次：

1. MCP 服务负责 Graylog 认证、查询、脱敏、排序和关联 ID 扩展。
2. 通用 Skill指导 Agent 从代码中的日志语句提取稳定文本，查询运行时证据，并把日志 映射回代码分支。
3. 业务 Profile只描述业务入口、阶段、日志文本和额外关联字段。增加几十上百个业务时， 新增 YAML 文件，不复制 MCP 或 Skill。

MCP 暴露标准 Tools、Resources 和 Prompt，并支持 stdio 与 Streamable HTTP。服务端不调用 Codex、Gemini 或任何其他模型 API。

工具

• graylog_get_system_info：验证认证、API 路径和集群版本。
• graylog_search_messages：执行受时间范围和结果数限制的原始 Lucene 查询。
• graylog_diagnose_code_logs：按代码日志常量和业务 ID 查询，并自动扩展结果中的关联 ID。
• graylog_list_profiles / graylog_get_profile：发现和读取业务 Profile。
• diagnose_code_runtime MCP Prompt：为不支持本地 Skill 的 MCP 客户端提供同一诊断流程。

安装

需要 Python 3.11+ 和 uv。

cd /home/ijx/anpengyu/graylog-agent-toolkit
uv sync --extra dev
cp .env.example .env

编辑 .env 后，本地验证：

GRAYLOG_ENV_FILE=.env uv run graylog-agent-toolkit

stdio 模式启动后等待 MCP 客户端握手，终端无普通输出是正常行为。日志只能写入 stderr， 不能污染 MCP 的 stdout 协议流。

Graylog 认证

支持三种模式：

• session：GRAYLOG_SESSION_ID=<浏览器 authentication 对应的 UUID>。Basic Auth 密码固定为 session。浏览器会话可能过期。
• token：GRAYLOG_TOKEN=<access token>。Basic Auth 密码固定为 token。
• basic：GRAYLOG_USERNAME 和 GRAYLOG_PASSWORD。

使用 Graylog 用户名密码时，.env 配置如下：

GRAYLOG_API_BASE=https://graylog.example.com/api
GRAYLOG_AUTH_MODE=basic
GRAYLOG_USERNAME=your-graylog-username
GRAYLOG_PASSWORD=your-graylog-password

MCP 通过标准 HTTP Basic Auth 连接 Graylog。用户名密码只保存在 MCP 服务端环境中，不应放进 Agent 提示词、业务 Profile 或源码。

不要提交 .env。工具默认对 Authorization、Cookie、密码、Session 和常见签名 URL 参数 脱敏，但脱敏不能代替最小权限和 Graylog 审计。

此实现调用 Graylog 5.1 的 JSON Scripting Search API： POST /api/search/messages。该 API 需要实例启用 scripting_api_preview；当前实例已用真实 JSON 响应验证。如果其他集群未启用，需先开启该特性或新增兼容适配器。

Codex 接入

用本机 CLI 注册 stdio 服务：

codex mcp add graylog \
  --env GRAYLOG_API_BASE="$GRAYLOG_API_BASE" \
  --env GRAYLOG_AUTH_MODE="$GRAYLOG_AUTH_MODE" \
  --env GRAYLOG_SESSION_ID="$GRAYLOG_SESSION_ID" \
  --env GRAYLOG_PROFILE_DIR="/home/ijx/anpengyu/graylog-agent-toolkit/profiles" \
  -- uv --directory /home/ijx/anpengyu/graylog-agent-toolkit run graylog-agent-toolkit

也可以参考 examples/codex/config.toml.example。把 skills/code-runtime-diagnose 复制或链接到 Codex 的个人 Skill 目录后，新会话可按描述自动启用。 MCP 配置和 Skill 安装后都需要新开或重载 Agent 会话。

Gemini CLI 接入

项目本身是一个 Gemini CLI 扩展，包含标准 MCP 与标准 skills/ 目录：

cd /home/ijx/anpengyu/graylog-agent-toolkit
gemini extensions link .

Gemini CLI 会提示扩展设置，并把敏感值保存到系统密钥链。也可使用 examples/gemini/settings.json.example 手工配置。进入 Gemini CLI 后用 /mcp 检查连接；MCP Prompt 可作为 /diagnose-code-runtime 调用。

自建 Agent 接入

任何实现 MCP 客户端初始化、tools/list 和 tools/call 的 Agent 都可以调用本服务。最小 Python 示例位于 examples/custom-agent/client.py。如果宿主不实现 Agent Skills，可：

1. 读取 MCP Server Instructions；
2. 调用 MCP Prompt diagnose_code_runtime；或
3. 将 skills/code-runtime-diagnose/SKILL.md 作为系统/任务指令载入。

“任何 Agent 可用”的边界是宿主至少支持 MCP，或允许加载文本指令。完全不支持 MCP、Tool Call、 Prompt 或外部指令的宿主无法自动使用外部能力。

Streamable HTTP

共享服务可这样启动：

MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8765 \
  GRAYLOG_ENV_FILE=.env uv run graylog-agent-toolkit

客户端连接 http://127.0.0.1:8765/mcp。需要跨机器访问时，在服务前部署 TLS、身份认证、访问 控制和审计反向代理；不要直接把无认证端口暴露到网络。

新增业务

复制 profiles/weekly-training.yaml，修改名称、入口、稳定日志文本和业务关联字段即可。Profile 结构见 skills/code-runtime-diagnose/references/profile-schema.md。

profiles/
├── weekly-training.yaml
├── personal-homework.yaml
└── public-homework.yaml

每次改 Profile 后运行测试，并通过 graylog_get_profile 验证实际加载结果。

验证

uv run ruff check .
uv run pytest -q
python3 /home/ijx/.codex/skills/.system/skill-creator/scripts/quick_validate.py \
  skills/code-runtime-diagnose