albs-mcp

MCP-Server und CLI für AlmaLinux Build System (ALBS).

Gibt KI-Codierungsassistenten direkten Zugriff auf ALBS – Build-Fehler untersuchen, Builds erstellen, Pakete signieren, alles über natürliche Sprache.

Zwei Verwendungsmöglichkeiten:

Was es kann

Ohne Token (nur lesend)

• Build-Fehler untersuchen – der Hauptanwendungsfall. Geben Sie dem Agenten eine Build-ID und er durchsucht die Logs nach den Fehlersignaturen (search_log), lokalisiert die genaue Datei, Zeile und Diagnose und erweitert dann den Kontext darum. Kein Raten bei Zeilenoffsets und kein Verbrennen von Tokens für Logdateien mit über 100.000 Zeilen.

• Build-Details abrufen – Status aller Tasks, Pakete, Architekturen, Signier-Tasks.

• Builds auflisten und durchsuchen – aktuelle Builds durchsuchen, nach Paketname oder Status filtern.

• Plattformen abrufen – dynamisch abgerufene Liste aller Plattformen und ihrer unterstützten Architekturen.

• Logs herunterladen und lesen – jede Logdatei von jedem Build: mit search_log durchsuchen, von unten blättern (read_log_tail) oder einen Zeilenbereich lesen. Kein Lesevorgang kann explodieren: jede Zeile wird auf 500 Zeichen gekürzt und das gesamte Ergebnis auf 40k Zeichen (max_line_chars=0 / max_chars=0 zum Aufheben), sodass ein Log, dessen einzelne Zeilen mehrere KB Compiler-Flags enthalten, in Seiten zurückkommt, die exakt zusammenpassen, statt eines überdimensionierten Blobs. Beim Lesen wird das Log automatisch heruntergeladen, falls es noch nicht auf der Platte ist.

• Signierstatus prüfen – sehen, ob Signier-Tasks für einen Build abgeschlossen oder fehlgeschlagen sind.

• Produkte auflisten – alle Release-Ziele (Produkte) mit ihren Plattformen, offiziell/Community-Flag und IDs.

• Release-Pläne anzeigen – Status, Quellpakete und Ziel-Repositories eines vorhandenen Releases.

Mit einem JWT-Token (authentifiziert)

• Builds erstellen – Pakete, Plattform(en), Branch/Tag/SRPM angeben. Unterstützt mehrere Plattformen in einem einzigen Build (z. B. AlmaLinux-8 + AlmaLinux-9). Architekturen standardmäßig auf die vollständige Liste jeder Plattform, sofern nicht überschrieben. Unterstützt benutzerdefinierte Git-URLs für Repos außerhalb von git.almalinux.org (z. B. GitHub, GitLab). Unterstützt alle mkbuild.py-Optionen: verknüpfte Builds, Mock-Definitionen, Ausschlüsse, Flavors, Secureboot, Module, with/without.

• Builds signieren – Signier-Tasks mit einem gewählten Schlüssel erstellen.

• Signierschlüssel auflisten – verfügbare Schlüssel mit IDs und Plattform-Zuordnungen anzeigen.

• Release-Pläne erstellen – einen geplanten Release-Plan für einen Build erstellen (welche Pakete in welche Repositories gehen), der auf eine gewählte Plattform + Produkt abzielt. Der eigentliche Release wird nie durchgeführt – dies erstellt nur den Plan; Committen/Veröffentlichen ist absichtlich blockiert.

• Builds löschen – aus Sicherheitsgründen absichtlich blockiert.

Log-Typen

ALBS erzeugt mehrere Logdateien pro Build-Task. Die wichtigsten für die Fehlersuche:

Related MCP server: Kerneldev MCP

Installation

pip install git+https://github.com/AlmaLinux/albs-mcp.git

Dies installiert sowohl den MCP-Server (albs-mcp) als auch die CLI (albs).

Authentifizierung

Das JWT-Token wird gelesen aus (in dieser Reihenfolge geprüft):

1. Umgebungsvariable ALBS_JWT_TOKEN

2. Datei ~/.albs/credentials (Python-Dict mit einem token-Schlüssel):

{"token": "eyJ..."}

Ohne Token funktionieren sowohl MCP als auch CLI im Nur-Lese-Modus.

Committen Sie niemals echte Tokens. Verwenden Sie Umgebungsvariablen oder ~/.albs/credentials, nicht CLI-Argumente.

Setup-Option 1: MCP-Server

Fügen Sie zu Ihrer MCP-Client-Konfiguration hinzu (z. B. mcp.json oder Äquivalent):

{
  "mcpServers": {
    "albs": {
      "command": "albs-mcp"
    }
  }
}

Setup-Option 2: CLI + Skill

Für Setups, bei denen MCP-Kontextverschmutzung ein Problem ist, oder wenn Sie Tools verwenden, die MCP nicht unterstützen.

Schritt 1. Installieren Sie das Paket (wie oben – gibt Ihnen den albs-Befehl):

pip install git+https://github.com/AlmaLinux/albs-mcp.git

Schritt 2. Fügen Sie die Workflow-Anweisungen zu Ihrem KI-Tool hinzu:

# Copy the skill directory to your tool's skills location, e.g.:
cp -r skills/albs-cli <YOUR_SKILLS_DIR>/albs-cli

Oder kopieren Sie den Inhalt von skills/albs-cli/SKILL.md in die AGENTS.md Ihres Projekts oder eine gleichwertige Anweisungsdatei.

Das Skill lehrt den KI-Agenten dieselben Workflows (Untersuchungsreihenfolge, EPEL-Handhabung, Signieren), aber über albs-Shell-Befehle anstelle von MCP-Tool-Aufrufen.

Schritt 3. Überprüfen:

albs --help

Die CLI funktioniert auch eigenständig – keine KI erforderlich. Nützlich für Skripte und manuelle Terminalnutzung.

CLI-Nutzung

# List platforms
albs platforms

# Investigate a build
albs build-info 52679
albs failed-tasks 52679
# log-search greps for the failure and shows it with context — start here.
# It auto-downloads the log if needed (download-log is optional)
albs log-search 52679 "mock_build.395391.1772974729.log"
# ...or grep for something specific
albs log-search 52679 "mock_build.395391.1772974729.log" -e "Hunk #\d+ FAILED" -A 3
# When the search finds nothing, page the log bottom-up: each page prints the
# exact command for the page above it, so the pages join up with no gaps
albs log-tail 52679 "mock_build.395391.1772974729.log"
albs log-tail 52679 "mock_build.395391.1772974729.log" --before-line 772

# Search builds
albs search --project bash --page 2

# Create a build (requires JWT)
albs create-build AlmaLinux-9 bash --branch c9s
albs create-build AlmaLinux-10 https://example.com/pkg.src.rpm \
    --from-srpm --add-epel-dist --arch x86_64_v2 \
    --flavor EPEL-10 --flavor EPEL-10_altarch

# Build on multiple platforms at once
albs create-build AlmaLinux-8 bash --branch c9s \
    --add-platform AlmaLinux-9

# Build from an external Git repo (e.g. GitHub)
albs create-build AlmaLinux-10 \
    --git-url https://github.com/ykohut/leapp-data.git \
    --branch devel-ng-0.23.0

# Independent tasks (disable the default sequential per-platform task chain,
# so packages build in parallel within each platform)
albs create-build AlmaLinux-9 bash glibc openssl --branch c9s --independent-tasks

# Sign a build (requires JWT)
albs sign-keys
albs sign-build 52679 --key-id 4

# Check whether signing finished
albs sign-status 52679

# List products (release targets) and view an existing release plan
albs products
albs release-plan 39229

# Create a release plan (requires JWT) — never performs the actual release
albs create-release-plan 62316 --platform AlmaLinux-8 --product AlmaLinux
# Release a PARTIAL build (only fully-completed packages):
albs create-release-plan 62316 --platform AlmaLinux-8 --product AlmaLinux \
    --whole-packages-only

# Pass token via flag or env var
albs --token "eyJ..." sign-keys
ALBS_JWT_TOKEN="eyJ..." albs sign-keys

Führen Sie albs --help oder albs <command> --help für die vollständige Nutzung aus.

Tool-Referenz

Nur lesen (ohne Authentifizierung)

Authentifiziert (JWT erforderlich)

Prompts

MCP-Prompts sind benutzeraufgerufene Workflow-Einstiegspunkte. In Clients wie Claude Code erscheinen sie als Slash-Befehle (/mcp__albs__<name>); der Benutzer löst sie aus, nicht der Agent.

Beispiel (Claude Code):

/mcp__albs__investigate_build 52679
/mcp__albs__release_plan 52679

investigate_build erweitert sich zum Untersuchungs-Workflow (get_build_info → get_failed_tasks → Herunterladen/Lesen der wichtigsten Protokolle in der richtigen Reihenfolge), parametrisiert durch die Build-ID. release_plan erweitert sich zum Release-Plan-Workflow (get_build_info → get_products → create_release_plan) und endet ausdrücklich beim Plan – es committet/veröffentlicht nie.

Beispiel: Untersuchung eines fehlgeschlagenen Builds

Fragen Sie den Agenten: „Was ist bei Build 52679 schiefgelaufen?"

Der Agent wird:

1. get_build_info(70368) — erkennt, dass nur die i686-Aufgabe fehlgeschlagen ist; die anderen 7 Architekturen wurden gebaut

2. get_failed_tasks(70368) — holt die Protokolldateien, ★ markiert die wichtigen

3. search_log(70368, "mock_build.441500.1785274367.log") — durchsucht das 936-zeilige / 600-KB-Protokoll mit grep und liefert die Ursache mit Kontext in einem Aufruf:

   >>> 826 | usr/lib/common/mech_openssl.c:2766:52: error: passing argument 5 of
             'EVP_PKEY_get_octet_string_param' from incompatible pointer type
       833 | note: expected 'size_t *' {aka 'unsigned int *'} but argument is of
             type 'CK_ULONG *' {aka 'long unsigned int *'}
   >>> 853 | make[1]: *** [Makefile:9851: ...mech_openssl.lo] Error 1

4. search_log(70368, "mock_root.441500.1785274367.log") — keine Treffer: Das Chroot und die Abhängigkeiten waren in Ordnung, also handelt es sich nicht um einen Abhängigkeitsfehler

5. Meldet: „CK_ULONG * ist unsigned long *, während OpenSSL size_t * erwartet; auf ILP32 (i686) sind das verschiedene Typen, daher bricht das 3.27.0-Rebase nur auf 32-Bit."

Wäre die Suche erfolglos geblieben, wäre der nächste Schritt read_log_tail und dann der davon ausgegebene Aufruf ↑ earlier: ..., mit dem das Protokoll Seite für Seite nach oben durchlaufen wird. Die Seiten werden anhand des Zeichenbudgets bemessen, nicht anhand einer Zeilenzahl — 165 Zeilen dieses mock_build oder 350 des mock_root desselben Builds — und jede beginnt genau dort, wo die vorherige aufgehört hat, sodass nichts übersprungen wird.

Beachten Sie, was Schritt 3 ersetzt. read_log_tail liefert für dieses Protokoll make: *** [Makefile:4615: all] Error 2 — das Symptom, Hunderte von Zeilen unterhalb des eigentlichen Fehlers, weil make -j nach dem ersten Fehler weiter kompiliert. Wird genug vom Protokollende angefordert, um den Fehler zu erreichen, liefert das stattdessen 167 KB gcc-Befehlszeilen und kann das Ergebnisgrößenlimit des Aufrufers überschreiten. search_log liefert 4 KB mit der Antwort ganz oben.

Beispiel: Erstellen eines Builds

Fragen Sie den Agenten: „Erstellen Sie bash für AlmaLinux-9 aus dem Branch c9s"

Der Agent wird Folgendes aufrufen:

create_build(packages=["bash"], platform="AlmaLinux-9", branch="c9s")

Für mehrere Plattformen gleichzeitig:

create_build(packages=["bash"], platforms=["AlmaLinux-8", "AlmaLinux-9"], branch="c9s")

Für externe Git-Repos (z. B. GitHub) verwenden Sie git_urls:

create_build(git_urls=["https://github.com/ykohut/leapp-data.git"], platform="AlmaLinux-10", branch="devel-ng-0.23.0")

Standardmäßig entsprechen die Architekturen der vollständigen Liste der jeweiligen Plattform. Wenn arch_list mit mehreren Plattformen angegeben wird, wird sie gegen jede Plattform einzeln validiert.

Beispiel: Erstellen eines Release-Plans

Fragen Sie den Agenten: „Erstellen Sie einen Release-Plan für Build 62316 auf AlmaLinux-8."

Der Agent wird:

1. get_build_info(62316) — bestätigt die Plattform und dass der Build abgeschlossene Aufgaben hat

2. get_products() — listet Produkte auf, damit Sie das Ziel auswählen können (z. B. AlmaLinux)

3. create_release_plan(build_id=62316, platform="AlmaLinux-8", product="AlmaLinux") — sammelt die abgeschlossenen Build-Aufgaben, löst die Plattform-/Produktnamen in IDs auf und erstellt einen geplanten Plan

4. Meldet den Plan (Status, Quellpakete, Ziel-Repositories) und stellt klar, dass nichts veröffentlicht wurde — es handelt sich nur um einen Plan

Die eigentliche Veröffentlichung (Commit/Veröffentlichung des Plans) wird absichtlich nicht durchgeführt. Wird der Agent gebeten, „wirklich zu veröffentlichen", führt das zu commit_release, das blockiert ist und erklärt, dass nur Pläne unterstützt werden.

Tests

pip install -e ".[test]"

# Unit tests (no network, 263 tests)
pytest tests/test_client_unit.py tests/test_server_unit.py tests/test_cli_unit.py -v

# Integration tests (hits real ALBS API, read-only, 30 tests)
pytest tests/test_integration.py -v

# All tests
pytest -v

Umgebungsvariablen