mcp-zuul: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

MCP server for Zuul CI — 48 tools (40 read-only + 6 write + 1 LogJuicer + 1 console stream), 5 prompts, and 3 resources exposing builds, logs, pipelines, jobs, infrastructure, and live status via the Model Context Protocol. Published on PyPI as mcp-zuul. Supports stdio, SSE, and streamable-http transports.

Commands

# Install dev dependencies
uv sync --extra dev

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

# Tests
uv run pytest tests/ -v                    # all tests
uv run pytest tests/test_tools_builds.py -v  # single test file
uv run pytest tests/ -v -k "test_name"     # single test by name

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

# Type check
uv run mypy src/mcp_zuul/

Architecture

All source lives in src/mcp_zuul/. The package uses hatchling as build backend with src layout.

Module Dependency Flow

__init__.py        →  imports tools, prompts, resources (registers decorators), exports main()
server.py          →  MCPServer instance ("zuul-ci"), lifespan (creates httpx clients), _BearerAuth
tools/             →  Package: 47 @mcp.tool() functions split by domain
  __init__.py      →  Re-exports for backward compat (tests import from mcp_zuul.tools)
  _common.py       →  Shared constants, _check_url_host(), _resolve(), _fetch_job_output(), re-exports from parsers
  _builds.py       →  8 build tools: list_builds, get_build, get_build_failures, diagnose_build, batch_diagnose, diagnose_and_test, etc.
  _console.py      →  1 console stream tool: stream_build_console (optional, requires websockets)
  _logs.py         →  3 log tools: get_build_log, browse_build_logs, tail_build_log
  _status.py       →  7 status/analytics: list_tenants, get_status, get_change_status, find_flaky_jobs, etc.
  _config.py       →  15 config/infra: list_jobs, get_job, get_project, list_nodes, get_freeze_job, etc.
  _write.py        →  6 write ops: enqueue, dequeue, autohold_create, autohold_delete, promote, reenqueue_buildset
  _tests.py        →  1 test results: get_build_test_results + JUnit XML parsing
  _logjuicer.py    →  1 LogJuicer: get_build_anomalies
prompts.py         →  5 @mcp.prompt() templates (debug_build, compare_builds, check_change, tenant_health, diagnose_queue_delay)
resources.py       →  3 @mcp.resource() templates (zuul://{tenant}/build|job|project/...)
helpers.py         →  AppContext dataclass, api() HTTP wrapper, parse_zuul_url(), utility functions
config.py          →  Config dataclass loaded from env vars (ZUUL_URL, MCP_TRANSPORT, ZUUL_ENABLED_TOOLS, etc.)
auth.py            →  Kerberos/SPNEGO authentication (drives OIDC redirect chain)
parsers.py         →  parse_playbooks(), smart_truncate(), extract_inner_recap(), extract_inner_failures(), extract_errors(), grep_log_context()
formatters.py      →  Token-efficient formatters (fmt_build, fmt_buildset, fmt_project, fmt_job_variants, etc.)
errors.py          →  @handle_errors decorator wrapping all tools with uniform error→JSON handling
classifier.py      →  Failure classification (INFRA_FLAKE, REAL_FAILURE, CONFIG_ERROR, UNKNOWN)