用途
mcp-zuul 是一个面向 Zuul CI 的 MCP（Model Context Protocol）服务器，用于通过自然语言提问来调试构建失败、搜索日志、管理流水线与监控任务，替代在 Web UI 中反复点击排查的方式。它可配合 Claude Code、Claude Desktop、Cursor、Codex、Windsurf 以及任何兼容 MCP 的客户端使用。
主要能力
- 覆盖构建、日志、流水线、任务、基础设施与实时状态，提供 48 个工具、5 个提示（prompts）和 3 个资源（resources）。
- 结构化失败分析：get_build_failures 解析 Zuul 的 job-output.json，返回失败的具体 Ansible 任务、所在主机、错误消息、返回码与 stderr。
- 读取任意日志文件：get_build_log 不限于 job-output.txt，可通过 log_name 读取构建日志目录中的任意文件（如 ci_script 日志、ansible.log、部署日志），支持完整 grep、tail 与行范围。
- 精确日志导航：通过 start_line / end_line 跳转到指定行范围。
- 智能 grep：支持正则搜索与上下文行，自动将常见 shell grep 的 | 语法转换为 Python 正则的 |。
- 实时流水线感知：get_change_status 返回实时任务进度、已耗时、预计完成时间与预失败检测（pre_fail 字段）；变更不在流水线中时自动获取最近一次已完成的 buildset。
- 工具过滤：通过 ZUUL_ENABLED_TOOLS 或 ZUUL_DISABLED_TOOLS 减少 LLM 选择工具的噪声，只暴露工作流需要的工具。
- 支持直接粘贴 Zuul 构建 URL，自动解析租户与 UUID。
- 不稳定任务检测：find_flaky_jobs 分析近期构建历史并计算通过/失败统计。
- 任务依赖图：get_freeze_jobs 返回经继承解析后的完整任务图及其依赖。
- Kerberos/SPNEGO 认证：支持位于 OIDC + Kerberos 之后的 Zuul 实例，自动走完整 SPNEGO 重定向链，会话 cookie 持久化并在过期时透明重新认证。
- Streamable HTTP 传输：通过 MCP_TRANSPORT=streamable-http 作为持久 HTTP 服务器运行，用于远程/共享部署；支持 stdio（默认）、SSE 和 streamable-http。
- 写操作：可入队/出队/提升变更以及重新入队 buildset。影响流水线的工具默认禁用（ZUUL_READ_ONLY=true），并完全从服务器移除；autohold 管理（创建/删除）因不影响运行中的流水线而始终可用。
- LogJuicer 集成：get_build_anomalies 使用基于机器学习的日志分析，通过对比失败日志与成功基线来发现异常行；该功能可选，需要配置 LOGJUICER_URL。
- Token 高效输出：所有响应去除 None 值并使用紧凑格式化；tail_build_log 只返回最后 N 行。
- 错误处理：所有工具返回 JSON（包括错误），网络失败、认证问题和无效参数返回 {"error": "descriptive message"}，不会抛出未处理异常。
使用方式
- 无需安装，一条命令即可运行（推荐 uvx）：uvx mcp-zuul（完整命令见官方仓库与 Setup 文档）。
- 也可安装：pip install mcp-zuul。
- MCP 客户端配置使用统一 JSON 结构，添加到客户端的 MCP 配置文件中；Claude Code 位于 ~/.claude.json 的 mcpServers 下，Claude Desktop（claude_desktop_config.json）、Cursor（.cursor/mcp.json）等格式相同。GUI 客户端不继承 shell PATH，需使用 uvx 的完整路径（通过 which uvx 获取）。
- 环境变量配置：支持通过 ZUUL_AUTH_TOKEN 传入令牌认证；Kerberos/SPNEGO 需有效的 Kerberos 票据（kinit）与 gssapi 包，Linux 需先安装系统包再以 mcp-zuul[kerberos] 安装；支持多实例配置。
- Docker 镜像：ghcr.io/imatza-rh/mcp-zuul；Docker 环境可用无值转发方式继承宿主环境变量，Kerberos 场景可挂载票据缓存。
- 提供的提示模板可预加载上下文并引导分析；可浏览资源供客户端在不调用工具的情况下附加到对话。
适用场景
- 调试构建失败：list_builds → get_build_failures 获取根因（任务名、错误、返回码）。
- 深入日志：browse_build_logs 找到日志文件后用 get_build_log 配合 grep 与上下文定位错误。
- 按行号精确读取日志片段。
- 查看实时流水线状态或最近完成的 buildset。
- 对比同一流水线中多个构建结果（list_builds → get_buildset）。
- 直接粘贴 Zuul URL 自动解析租户与 UUID。
- 排查任务未运行原因（get_config_errors）。
- 检查节点可用性（list_nodes、list_labels）。
- 检测不稳定任务（find_flaky_jobs）。
- 查看项目运行的任务（get_freeze_jobs）与继承后的节点集（get_freeze_job）。
- 用 tail_build_log 以最少 token 快速查看构建失败原因。
限制
- Kerberos 支持的 gssapi 在 Linux 上无预编译 wheel，需从源码编译并先安装系统依赖（如 krb5-config、Python.h）；macOS 和 Windows 有预编译 wheel，无需额外包。
- 写操作中的影响流水线工具默认禁用（ZUUL_READ_ONLY=true），需显式设置 ZUUL_READ_ONLY=false 并需要认证令牌或 Kerberos。
- LogJuicer 集成为可选功能，必须配置 LOGJUICER_URL。
- 令牌不应硬编码在配置文件中（会出现在 ps 输出中），应通过宿主环境变量传入。
- 暂未提供关于收费、价格、平台支持范围与效果指标的更多信息。
