mcp-zuul

mcp-zuul

无需点击浏览器网页，只需提问即可调试构建失败。这是一款适用于 Zuul CI 的 MCP 服务。

如果 mcp-zuul 帮你省下了一次调试的时间，点个 ⭐ 星标 就能帮助其他人发现它。

一条命令，无需安装：

claude mcp add zuul -e ZUUL_URL=https://your-zuul.example.com -- uvx mcp-zuul

48 个工具、5 个提示词、3 个资源，涵盖构建、日志、流水线、作业、基础设施和实时状态。支持 Claude Code、Claude Desktop、Cursor、Codex、Windsurf，以及任何兼容 MCP 的客户端。

为什么选择 mcp-zuul？

	mcp-zuul	Zuul 原始 API	Zuul 网页界面
失败分析	结构化信息——任务、主机、错误、rc	原始 JSON，需要自行解析	逐页点击查看日志
日志搜索	正则表达式 + 上下文行 + 行范围	不支持	浏览器 Ctrl+F
不稳定测试检测	自动统计通过/失败情况	手动查询并计算	不支持
测试结果	解析 JUnit XML 并提供失败详情	不支持	外部链接
异常检测	通过 LogJuicer 实现，基于 ML	不支持	不支持
实时状态	作业进度、预计完成时间、失败前提醒	轮询 API	手动刷新
多实例	每个 Zuul 配置一条配置项	使用不同的基础 URL	使用不同的浏览器标签页

快速开始

uvx（无需安装，推荐）：

claude mcp add zuul \
               -e ZUUL_URL=https://softwarefactory-project.io/zuul \
               -e ZUUL_DEFAULT_TENANT=rdoproject.org \
               -- uvx mcp-zuul

pip：

pip install mcp-zuul

Docker：

docker build -t mcp-zuul .

LobeHub — 将以下内容发送给你的 AI Agent：

Read https://lobehub.com/mcp/imatza-rh-mcp-zuul/skill.md and follow the instructions to install the MCP server.

完整配置选项（包括 Kerberos 和多实例）请参阅设置。

功能

结构化失败分析 — 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 跳转到确切的行范围。在第 6148 行找到错误后，可以直接读取第 6130–6160 行，而不必在 200 行一组的日志块中滚动查找。

智能 grep — 支持带上下文行的正则搜索。会自动将常见的 shell grep \| 语法转换为 Python 正则表达式 |，因此 error\|failed\|timeout 这样的模式可以直接使用。

实时流水线状态 — get_change_status 会返回实时作业进度、已用时间、预计完成时间和失败预检结果（pre_fail 字段）。如果变更不在流水线中，则会自动获取最新的已完成构建集。

工具筛选 — 使用 ZUUL_ENABLED_TOOLS 或 ZUUL_DISABLED_TOOLS 减少大模型选择工具时的干扰。只公开工作流所需的工具，其余工具会从服务中彻底移除。

基于 URL 的输入 — 直接粘贴 Zuul 构建 URL。工具会自动从 https://zuul.example.com/t/tenant/build/abc123 这样的 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。

写入操作 — 将变更加入/移出队列、提升变更优先级，以及重新加入构建集。默认禁用会影响流水线的工具（ZUUL_READ_ONLY=true），并从服务中彻底移除，因此大模型甚至看不到这些工具。自保持管理（创建/删除）始终可用，因为它不会影响正在运行的流水线。

LogJuicer 集成 — get_build_anomalies 使用基于 ML 的日志分析，将失败日志与成功基线进行比较，以查找异常行。此功能可选，需要设置 LOGJUICER_URL。

节省令牌的输出 — 所有响应都会剔除 None 值，并使用紧凑格式化器。tail_build_log 仅返回最后 N 行，是检查构建失败原因的最快方式。

错误处理 — 所有工具均以 JSON 格式返回结果，包括错误。网络故障、身份验证问题和无效参数会生成 {"error": "descriptive message"}。工具绝不会抛出未处理的异常。

工具

构建与失败

工具	功能
list_builds	按项目、流水线、作业、变更、结果搜索构建。包含用于交叉引用的 buildset_uuid。
get_build	完整的构建详情 — 节点集、日志 URL、制品、错误详情。接受 url 或 uuid。
get_build_failures	排查失败时从这里开始。 从 job-output.json 获取结构化的任务级数据 — 失败的 play、任务、主机、msg、rc、stderr/stdout。接受 url 或 uuid。
diagnose_build	一次调用即可诊断失败。 将 job-output.json 中的结构化失败信息与针对性的日志上下文（来自 job-output.txt 的 fatal/FAILED 行及其周边内容）结合起来。建议使用此工具，而不是分别调用 get_build_failures 和 get_build_log。接受 url 或 uuid。
get_build_log	读取和搜索日志文件。模式：summary（末尾内容 + 错误行）、full（分页）、grep（正则表达式 + 上下文）、start_line/end_line（精确范围）。支持使用 log_name 指定任意文件。接受 url 或 uuid。
tail_build_log	最快的失败检查方式。 获取日志最后 N 行（默认 50 行，最多 500 行）。比 get_build_log 的摘要模式更节省令牌。接受 url 或 uuid。
browse_build_logs	列出日志目录内容或获取特定文件（清单、制品、must-gather）。每个文件最大 512KB。接受 url 或 uuid。
stream_build_console	获取正在运行的构建的实时控制台。 连接到 Zuul WebSocket，返回最后 N 行（末尾内容）。对于已完成的构建，请使用 tail_build_log。可选 — 需要 pip install mcp-zuul[console]。

构建集

工具	功能
list_buildsets	搜索构建集。使用 include_builds=true 可内嵌完整构建详情（减少往返调用）。
get_buildset	包含所有构建和事件的完整构建集信息。接受 url 或 uuid。

流水线与状态

工具	功能
get_status	实时流水线状态 — 查看排队和运行中的任务，以及作业进度和预计完成时间。可按流水线和项目筛选。
get_change_status	查看变更/PR/MR 的状态。在流水线中：显示正在运行的作业及已用时间。不在流水线中：自动获取最新的已完成构建集。接受 url 或 change。
list_pipelines	列出所有流水线及其触发类型。

作业与项目

工具	功能
list_tenants	列出所有租户及其项目数量。
list_jobs	列出作业，可选按名称筛选。
get_job	作业配置 — 父级、节点集、超时、变体、源项目。
get_project	查看为项目配置了哪些流水线和作业。
list_projects	列出租户中的所有项目，可选按名称筛选。
get_config_errors	作业未运行时请检查此项。 查看配置错误、缺失的引用和损坏的配置。可按项目筛选。
get_freeze_jobs	获取流水线/项目/分支的已解析作业依赖图。显示应用继承关系解析后将运行的确切作业。
get_freeze_job	继承关系解析后的作业配置。 查看特定作业最终合并后的节点集、playbook、变量和超时时间。回答“此作业实际会执行什么？”
find_flaky_jobs	分析近期构建历史中的间歇性失败。计算通过/失败率，并将作业标记为不稳定（失败率 >20% 且结果不一致）。
get_build_times	查看构建时长趋势及平均值/最小值/最大值统计。用于检测性能回归或容易超时的作业。
get_job_durations	一次调用即可批量获取多个作业的平均值/最小值/最大值时长。适用于监控整个流水线链，无需分别调用 N 次。
check_health	检查 API 连通性、身份验证状态和配置。如果 Kerberos 会话已过期，会自动触发重新验证。
get_tenant_info	查看租户功能 — 身份验证域、作业历史支持情况、websocket URL。

基础设施

工具	功能
list_nodes	列出 Nodepool 节点及其状态（就绪、使用中、构建中）、提供商和标签。包含状态摘要。
list_labels	列出可用的 Nodepool 标签，即作业可以请求的节点类型。
list_semaphores	列出资源锁及其当前持有者和最大容量。作业出现意外等待时可查看。
list_autoholds	列出活动的 autohold 请求，即失败后为调试而保留的节点。
get_autohold	获取特定 autohold 请求的完整详情，包括保留的节点、时间、项目和作业。
list_providers	列出 Nodepool 云提供商及其规格（VM 大小）、镜像和标签。
list_images	列出 Nodepool 磁盘镜像及其构建状态和提供商上传状态。
list_system_events	列出系统事件，包括配置更新、重新配置和流水线变更。可用于排查“为什么我的作业不再运行？”
get_badge	获取项目的 CI 状态徽章 URL（SVG），并提供可嵌入 README 的 Markdown 片段。
get_connections	列出已配置的源连接，包括 Gerrit、GitHub、GitLab 实例及其驱动和主机名。
get_components	列出系统组件，包括调度器、执行器、合并器、Web 服务器及其状态和版本。

写操作

会影响流水线的操作——默认禁用（ZUUL_READ_ONLY=true）。设置 ZUUL_READ_ONLY=false 以启用。需要身份验证令牌或 Kerberos。autohold 管理（创建/删除）始终可用，因为它不会影响正在运行的流水线。

工具	功能
enqueue	将变更或引用加入流水线。支持基于变更（check/gate）和基于引用（periodic）的入队。
promote	将变更提升至流水线队列的顶部。gate 队列较长时，可用于处理紧急修复。
reenqueue_buildset	重新将一个 buildset 入队——从之前的 buildset 中读取项目/流水线/引用，然后再次将其入队。
dequeue	从流水线中移除变更或引用。具有破坏性。
autohold_create	创建 autohold 请求——失败后保留节点以供调试。不受 ZUUL_READ_ONLY 限制。
autohold_delete	删除 autohold 请求。不受 ZUUL_READ_ONLY 限制。

测试结果与日志分析

工具	功能
get_build_test_results	解析 JUnit XML 测试结果。 通过 zuul-manifest.json 查找测试文件，并返回包含失败详情的结构化通过/失败/跳过计数。适用于 tempest、tobiko 以及任何 JUnit XML 输出。
get_build_anomalies	通过 LogJuicer 进行基于 ML 的日志异常检测。将失败日志与成功基线进行比较。需要 LOGJUICER_URL。

提示词

预先构建的提示词模板，可预加载上下文并引导分析：

提示词	功能
debug_build	获取构建详情和结构化失败信息，检查近期历史中是否有不稳定信号，然后引导进行根因分析。
compare_builds	并排加载两个构建及内联失败数据，以便进行差异分析——“为什么它从这里开始失败了？”
check_change	确定变更在当前流水线中的状态，或获取其最新结果，并给出相应的后续步骤。
tenant_health	评估租户整体健康状况，在一个视图中展示组件、配置错误和节点池状态。
diagnose_queue_delay	诊断作业排队或延迟的原因——检查节点、信号量和系统状态。

资源

客户端无需调用工具即可附加到对话中的可浏览上下文：

资源	URI 模式
构建详情	zuul://{tenant}/build/{uuid}
作业配置	zuul://{tenant}/job/{name}
项目配置	zuul://{tenant}/project/{org}/{repo}

设置

MCP 客户端配置

所有客户端都使用相同的 JSON 结构。将以下内容添加到客户端的 MCP 配置文件中：

Claude Code（~/.claude.json → mcpServers）：

{
  "mcpServers": {
    "zuul": {
      "command": "uvx",
      "args": ["mcp-zuul"],
      "env": {
        "ZUUL_URL": "https://softwarefactory-project.io/zuul",
        "ZUUL_DEFAULT_TENANT": "rdoproject.org"
      }
    }
  }
}

Claude Desktop（claude_desktop_config.json）、Cursor（.cursor/mcp.json）及其他 MCP 客户端使用相同格式。基于 GUI 的客户端不会继承 Shell 的 PATH，请使用 uvx 的完整路径（运行 which uvx 查找路径）。

也可以通过命令行配置：

claude mcp add zuul \
               -e ZUUL_URL=https://softwarefactory-project.io/zuul \
               -e ZUUL_DEFAULT_TENANT=rdoproject.org \
               -- uvx mcp-zuul

环境变量

变量	必需	默认值	说明
ZUUL_URL	是	—	Zuul 基础 URL（例如，https://softwarefactory-project.io/zuul）
ZUUL_DEFAULT_TENANT	否	—	默认租户（无需在每次调用时传入 tenant）
ZUUL_AUTH_TOKEN	否	—	用于需要身份验证的实例的 Bearer 令牌
ZUUL_USE_KERBEROS	否	false	启用 Kerberos/SPNEGO 身份验证
ZUUL_TIMEOUT	否	30	HTTP 超时时间（秒）
ZUUL_VERIFY_SSL	否	true	SSL 证书验证
MCP_TRANSPORT	否	stdio	传输方式：stdio、sse 或 streamable-http
MCP_HOST	否	127.0.0.1	HTTP 服务绑定地址（非 stdio 传输方式）
MCP_PORT	否	8000	HTTP 服务端口（非 stdio 传输方式）
ZUUL_ENABLED_TOOLS	否	—	要启用的工具列表，以逗号分隔（禁用所有其他工具）
ZUUL_DISABLED_TOOLS	否	—	要禁用的工具列表，以逗号分隔（不能与上面的变量同时使用）
ZUUL_READ_ONLY	否	true	设置为 false 以启用会影响流水线的写操作（enqueue、promote、dequeue、reenqueue_buildset）。Autohold 管理（创建/删除）始终可用。
LOGJUICER_URL	否	—	用于基于 ML 的日志异常检测的 LogJuicer 基础 URL

令牌身份验证

通过宿主环境传入 ZUUL_AUTH_TOKEN——切勿在配置文件中硬编码令牌（令牌会显示在 ps 输出中）：

export ZUUL_AUTH_TOKEN=<your-token>

对于 Docker，不指定值即可转发并继承宿主环境中的变量：

"args": ["run", "-i", "--rm", "-e", "ZUUL_AUTH_TOKEN", "mcp-zuul"]

Kerberos / SPNEGO

适用于位于 OIDC + Kerberos 后面的 Zuul。需要有效的 Kerberos 票证（kinit）和 gssapi 包。

Linux 先决条件——gssapi 没有预构建的 Linux wheel，必须从源代码编译：

# Fedora/RHEL/CentOS
sudo dnf install krb5-devel python3-devel gcc

# Debian/Ubuntu
sudo apt install libkrb5-dev python3-dev gcc

macOS 和 Windows 有预构建的 wheel，无需安装额外的包。

然后安装 Kerberos 支持：

pip install mcp-zuul[kerberos]    # or: uvx --with "mcp-zuul[kerberos]" mcp-zuul

通过命令行：

claude mcp add -s user zuul-internal \
               -e ZUUL_URL=https://internal-zuul.example.com/zuul \
               -e ZUUL_DEFAULT_TENANT=my-tenant \
               -e ZUUL_USE_KERBEROS=true \
               -e ZUUL_VERIFY_SSL=false \
               -- uvx --with "mcp-zuul[kerberos]" mcp-zuul

或通过 JSON 配置：

{
  "zuul-internal": {
    "command": "uvx",
    "args": ["--with", "mcp-zuul[kerberos]", "mcp-zuul"],
    "env": {
      "ZUUL_URL": "https://internal-zuul.example.com/zuul",
      "ZUUL_USE_KERBEROS": "true",
      "ZUUL_VERIFY_SSL": "false"
    }
  }
}

对于 Docker，请挂载 Kerberos 票证缓存：

docker run -i --rm \
  -v /etc/krb5.conf:/etc/krb5.conf:ro \
  -v /tmp/krb5cc_$(id -u):/tmp/krb5cc_$(id -u):ro \
  -e KRB5CCNAME=/tmp/krb5cc_$(id -u) \
  -e ZUUL_URL=https://internal-zuul.example.com/zuul \
  -e ZUUL_USE_KERBEROS=true \
  mcp-zuul

多个实例

为每个 Zuul 实例添加单独的条目：

{
  "mcpServers": {
    "zuul-rdo": {
      "command": "uvx", "args": ["mcp-zuul"],
      "env": { "ZUUL_URL": "https://softwarefactory-project.io/zuul", "ZUUL_DEFAULT_TENANT": "rdoproject.org" }
    },
    "zuul-internal": {
      "command": "mcp-zuul",
      "env": { "ZUUL_URL": "https://internal.example.com/zuul", "ZUUL_USE_KERBEROS": "true" }
    }
  }
}

故障排除

在 Linux 上安装 mcp-zuul[kerberos] 时出现 krb5-config: not found 或 Python.h: No such file：

gssapi 没有预构建的 Linux wheel，需要从源代码编译。请先安装系统包：

# Fedora/RHEL/CentOS
sudo dnf install krb5-devel python3-devel gcc

# Debian/Ubuntu
sudo apt install libkrb5-dev python3-dev gcc

在 Cursor 或 Claude Desktop 中出现 uvx: command not found：

基于 GUI 的 MCP 客户端不会继承 Shell 的 PATH。请使用 uvx 的完整路径：

which uvx    # find the path, e.g. /usr/bin/uvx or ~/.local/bin/uvx

然后在 MCP 配置中将该绝对路径用作 command：

"command": "/usr/bin/uvx"

~/.local/share/uv/ 出现 权限错误：

如果之前使用 sudo 运行过 uv，缓存目录可能归 root 所有：

sudo chown -R $(whoami) ~/.local/share/uv/

使用示例

调试构建失败

"Why did the latest build of my-project fail?"

→ list_builds(project="my-project", result="FAILURE", limit=1) → get_build_failures(uuid="...") → 获取根本原因，包括任务名称、错误和返回码。

深入查看日志

"The structured data says 'non-zero return code' but no error detail.
 Check the ci_script logs."

→ browse_build_logs(uuid="...", path="controller/ci-framework-data/logs/") → 找到 ci_script_008_run.log → get_build_log(uuid="...", log_name="controller/ci-framework-data/logs/ci_script_008_run.log", grep="error|timed out|Error 1", context=2) → 获取包含上下文的确切错误。

定位特定错误

"Show me lines 6478-6484 of the job output"

→ get_build_log(uuid="...", start_line=6478, end_line=6484) → 精确获取这 7 行。

检查实时流水线状态

"Is change 54321 in any pipeline?"

→ get_change_status(change="54321") → 获取包含已运行时间和预计剩余时间的实时作业，或在更改不在流水线中时获取最新的已完成构建集。

比较流水线中的构建结果

"Show me all builds from the latest buildset"

→ 使用 list_builds 获取 buildset_uuid → 使用 get_buildset(uuid="...") → 查看所有同级构建的结果和耗时。

直接粘贴 Zuul URL

"What went wrong with this build?
 https://zuul.example.com/t/tenant/build/abc123def"

→ 使用 get_build_failures(url="https://zuul.example.com/t/tenant/build/abc123def") → 自动提取租户和 UUID。

调试作业为何没有运行

"My project's check pipeline seems broken — jobs aren't triggering"

→ 使用 get_config_errors(project="org/my-project") → 查看配置错误、缺失的引用或仓库访问问题。

检查节点可用性

"Jobs are stuck in queue — are there nodes available?"

→ 使用 list_nodes() → 查看节点状态及按状态汇总 → 使用 list_labels() → 查看可用的节点类型。

检测不稳定的作业

"Is this job flaky? It keeps failing intermittently"

→ 使用 find_flaky_jobs(job_name="my-deploy-job", limit=30) → 查看通过/失败统计、失败率以及 flaky=true/false。

查看项目会运行哪些作业

"What jobs are configured for openstack-operator in the check pipeline?"

→ 使用 get_freeze_jobs(pipeline="check", project="openstack-k8s-operators/openstack-operator") → 查看解析后的作业图及其依赖项。

快速查看日志尾部

"Show me the last 30 lines of the build log"

→ 使用 tail_build_log(uuid="...", lines=30) → 仅查看日志尾部，最大限度减少 token 用量。

继承完成后，我的作业会使用什么 nodeset？

"What nodeset and playbooks will deploy-job actually use?"

→ 使用 get_freeze_job(pipeline="check", project="org/repo", job_name="deploy-job") → 查看完成所有父级继承后的解析结果，包括 nodeset、playbook、变量和超时设置。

开发

git clone https://github.com/imatza-rh/mcp-zuul.git
cd mcp-zuul
uv sync --extra dev

# Run locally
ZUUL_URL=https://softwarefactory-project.io/zuul uv run mcp-zuul

# Run tests
uv run pytest tests/ -v

# Lint and format
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/

# Type check
uv run mypy src/mcp_zuul/

# Build Docker image
docker build -t mcp-zuul .

架构

MCP Client (Claude Code, Cursor, etc.)
    │
    ▼
┌──────────────────────────────────────────────────┐
│  src/mcp_zuul/                                   │
│                                                  │
│  server.py       MCPServer instance               │
│  config.py       env vars, transport, filtering  │
│  auth.py         Kerberos/SPNEGO + OIDC          │
│  errors.py       @handle_errors decorator        │
├──────────────────────────────────────────────────┤
│  tools/          48 tools across 8 submodules    │
│  prompts.py      5 prompt templates              │
│  resources.py    3 zuul:// resources             │
├──────────────────────────────────────────────────┤
│  helpers.py      API client, URL parsing         │
│  formatters.py   token-efficient output          │
│  parsers.py      Ansible/JUnit/log parsing       │
│  classifier.py   failure classification          │
├──────────────────────────────────────────────────┤
│  httpx clients   API (auth) + logs (no auth)     │
└────────┬─────────────────────────┬───────────────┘
         ▼                         ▼
    Zuul REST API           Log file hosts

完整的架构详情请参阅 CLAUDE.md。

收录目录

• PyPI — pip install mcp-zuul
• Glama — 质量：A/A/A
• Conare — 市场收录
• PulseMCP — 服务目录
• LobeHub — 支持安装 Agent 的 MCP 市场
• HiFriendBot — AI 工具目录
• pepy.tech — 下载统计
• Docker — ghcr.io/imatza-rh/mcp-zuul

贡献

欢迎贡献。对于重大变更，请先创建 issue 进行讨论。

# Fork, clone, and install dev dependencies
uv sync --extra dev

# Make changes, then verify
uv run pytest tests/ -v
uv run ruff check src/ tests/
uv run ruff format src/ tests/
uv run mypy src/mcp_zuul/

许可证

Apache-2.0