# 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`。

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

编辑 `.env` 后，本地验证：

```bash
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` 配置如下：

```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 服务：

```bash
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/` 目录：

```bash
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

共享服务可这样启动：

```bash
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`。

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

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

## 验证

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