albs-mcp

Servidor MCP y CLI para AlmaLinux Build System (ALBS).

Da a los asistentes de codificación con IA acceso directo a ALBS: investigar fallos de compilación, crear compilaciones, firmar paquetes, todo mediante lenguaje natural.

Dos formas de usarlo:

Qué puede hacer

Sin token (solo lectura)

• Investigar fallos de compilación — el caso de uso principal. Dale al agente un ID de compilación y éste busca en los registros las firmas de fallo (search_log), fijando el archivo, la línea y el diagnóstico exactos, y luego amplía el contexto alrededor. Sin adivinar desplazamientos de línea y sin gastar tokens en archivos de registro de más de 100k líneas.

• Obtener detalles de la compilación — estados de todas las tareas, paquetes, arquitecturas, tareas de firma.

• Listar y buscar compilaciones — explorar compilaciones recientes, filtrar por nombre de paquete o estado.

• Obtener plataformas — lista obtenida dinámicamente de todas las plataformas y sus arquitecturas soportadas.

• Descargar y leer registros — cualquier archivo de registro de cualquier compilación: haz grep (search_log), página desde abajo (read_log_tail) o lee un rango de líneas. Ninguna lectura puede explotar: cada línea se recorta a 500 caracteres y el resultado completo a 40k caracteres (max_line_chars=0 / max_chars=0 para levantar), de modo que un registro cuyas líneas individuales llegan a varios KB de flags del compilador vuelve en páginas que se unen exactamente en lugar de un blob sobredimensionado. La lectura descarga automáticamente el registro si aún no está en disco.

• Comprobar estado de firma — ver si las tareas de firma de una compilación se completaron o fallaron.

• Listar productos — todos los objetivos de lanzamiento (productos) con sus plataformas, indicador oficial/comunidad e IDs.

• Ver planes de lanzamiento — estado, paquetes fuente y repositorios objetivo de cualquier lanzamiento existente.

Con token JWT (autenticado)

• Crear compilaciones — especificar paquetes, plataforma(s), rama/etiqueta/SRPM. Soporta múltiples plataformas en una sola compilación (p. ej. AlmaLinux-8 + AlmaLinux-9). Las arquitecturas por defecto son la lista completa de cada plataforma a menos que se sobrescriban. Soporta URLs Git personalizadas para repositorios fuera de git.almalinux.org (p. ej. GitHub, GitLab). Soporta todas las opciones de mkbuild.py: compilaciones enlazadas, definiciones de mock, exclusiones, sabores, secureboot, módulos, con/sin.

• Firmar compilaciones — crear tareas de firma con una clave elegida.

• Listar claves de firma — ver claves disponibles con IDs y asignaciones de plataforma.

• Crear planes de lanzamiento — construir un plan de lanzamiento programado para una compilación (qué paquetes van a qué repositorios) dirigido a una plataforma + producto elegidos. El lanzamiento real nunca se realiza — esto solo crea el plan; la confirmación/publicación está bloqueada intencionalmente.

• Eliminar compilaciones — bloqueado intencionalmente por seguridad.

Tipos de registro

ALBS produce varios archivos de registro por tarea de compilación. Los clave para depurar:

Related MCP server: Kerneldev MCP

Instalación

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

Esto instala tanto el servidor MCP (albs-mcp) como la CLI (albs).

Autenticación

El token JWT se lee de (comprobado en orden):

1. Variable de entorno ALBS_JWT_TOKEN

2. Archivo ~/.albs/credentials (dict de Python con una clave token):

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

Sin token, tanto MCP como CLI funcionan en modo de solo lectura.

Nunca confirmes tokens reales. Usa variables de entorno o ~/.albs/credentials, no argumentos de CLI.

Opción de configuración 1: servidor MCP

Añade a la configuración de tu cliente MCP (p. ej. mcp.json o equivalente):

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

Opción de configuración 2: CLI + Skill

Para configuraciones donde la contaminación del contexto de MCP es una preocupación, o cuando se usan herramientas que no soportan MCP.

Paso 1. Instala el paquete (igual que arriba: te da el comando albs):

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

Paso 2. Añade las instrucciones de flujo de trabajo a tu herramienta de IA:

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

O copia el contenido de skills/albs-cli/SKILL.md en el archivo AGENTS.md de tu proyecto o en un archivo de instrucciones equivalente.

La skill enseña al agente de IA los mismos flujos de trabajo (orden de investigación, manejo de EPEL, firma) pero mediante comandos de shell albs en lugar de llamadas a herramientas MCP.

Paso 3. Verifica:

albs --help

La CLI también funciona de forma independiente: no se necesita IA. Útil para scripts y uso manual en terminal.

Uso de la CLI

# 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

Ejecuta albs --help o albs <comando> --help para el uso completo.

Referencia de herramientas

Solo lectura (sin autenticación)

Autenticado (requiere JWT)

Prompts

Los prompts de MCP son puntos de entrada de flujo de trabajo invocados por el usuario. En clientes como Claude Code aparecen como comandos de barra (/mcp__albs__<nombre>); los activa el usuario, no el agente.

Ejemplo (Claude Code):

/mcp__albs__investigate_build 52679
/mcp__albs__release_plan 52679

investigate_build se expande en el flujo de trabajo de investigación (get_build_info → get_failed_tasks → descargar/leer los registros clave en orden), parametrizado por el ID de compilación. release_plan se expande en el flujo de trabajo de plan de lanzamiento (get_build_info → get_products → create_release_plan), y se detiene explícitamente en el plan: nunca confirma/publica.

Ejemplo: investigar una compilación fallida

Pregunte al agente: "¿Qué salió mal en la compilación 52679?"

El agente hará:

1. get_build_info(70368) — ve que solo falló la tarea i686; las otras 7 arquitecturas se compilaron

2. get_failed_tasks(70368) — obtiene los archivos de registro, ★ marca los importantes

3. search_log(70368, "mock_build.441500.1785274367.log") — busca en el registro de 936 líneas / 600 KB y devuelve la causa con contexto, en una sola llamada:

   >>> 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") — sin coincidencias: el chroot y las dependencias estaban bien, por lo que no es un fallo de dependencias

5. Informa: "CK_ULONG * es unsigned long * mientras que OpenSSL quiere size_t *; en ILP32 (i686) esos son tipos diferentes, por lo que el rebase 3.27.0 solo se rompe en 32 bits."

Si la búsqueda no hubiera dado resultados, el siguiente paso es read_log_tail y luego la llamada ↑ earlier: ... que imprime, recorriendo el registro hacia arriba una página a la vez. Las páginas se dimensionan según el presupuesto de caracteres, no por número de líneas: 165 líneas de este mock_build, o 350 del mock_root de la misma compilación, y cada una comienza exactamente donde se detuvo la anterior, por lo que no se omite nada.

Observe lo que reemplaza el paso 3. read_log_tail en ese registro devuelve make: *** [Makefile:4615: all] Error 2 — el síntoma, cientos de líneas por debajo del error real, porque make -j sigue compilando después del primer fallo. Pedir suficiente cola para llegar al error devuelve en cambio 167 KB de líneas de comandos de gcc y puede exceder el límite de tamaño de resultado de la persona que llama. search_log devuelve 4 KB con la respuesta al principio.

Ejemplo: crear una compilación

Pregunte al agente: "Compile bash para AlmaLinux-9 desde la rama c9s"

El agente llamará:

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

Para varias plataformas a la vez:

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

Para repositorios Git externos (p. ej., GitHub), use git_urls:

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

Las arquitecturas se establecen por defecto en la lista completa de cada plataforma. Cuando se especifica arch_list con varias plataformas, se valida contra cada plataforma individualmente.

Ejemplo: crear un plan de lanzamiento

Pregunte al agente: "Cree un plan de lanzamiento para la compilación 62316 en AlmaLinux-8."

El agente hará:

1. get_build_info(62316) — confirma la plataforma y que la compilación tiene tareas completadas

2. get_products() — lista los productos para que pueda elegir el destino (p. ej., AlmaLinux)

3. create_release_plan(build_id=62316, platform="AlmaLinux-8", product="AlmaLinux") — recopila las tareas de compilación completadas, resuelve los nombres de plataforma/producto a IDs y crea un plan programado

4. Informa del plan (estado, paquetes fuente, repositorios de destino) y deja claro que no se publicó nada — es solo un plan

El lanzamiento real (confirmar/publicar el plan) no se realiza intencionalmente. Pedir al agente que "libere de verdad" enruta a commit_release, que está bloqueado y explica que solo se admiten planes.

Pruebas

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

Variables de entorno