albs-mcp

MCP-сервер и CLI для AlmaLinux Build System (ALBS).

Даёт ИИ-ассистентам для программирования прямой доступ к ALBS — расследование сбоев сборки, создание сборок, подпись пакетов — всё через естественный язык.

Два способа использования:

Что умеет

Без токена (только чтение)

• Расследование сбоев сборки — основной сценарий. Дайте агенту ID сборки, и он просмотрит логи на предмет сигнатур ошибок (search_log), точно определяя файл, строку и диагностику, затем расширяет контекст вокруг них. Никаких догадок о смещениях строк и никакого сжигания токенов на файлы логов размером более 100 000 строк.

• Получение деталей сборки — статусы всех задач, пакетов, архитектур, задач подписи.

• Список и поиск сборок — просмотр последних сборок, фильтрация по имени пакета или статусу.

• Получение платформ — динамически получаемый список всех платформ и поддерживаемых ими архитектур.

• Скачивание и чтение логов — любой файл лога из любой сборки: поиск по нему (search_log), чтение снизу вверх (read_log_tail) или чтение диапазона строк. Ни одно чтение не может «взорваться»: каждая строка обрезается до 500 символов, а весь результат — до 40 000 символов (max_line_chars=0 / max_chars=0 для снятия ограничений), так что лог, отдельные строки которого достигают нескольких КБ флагов компилятора, возвращается страницами, которые точно стыкуются, а не одним раздутым блоком. Чтение автоматически скачивает лог, если его ещё нет на диске.

• Проверка статуса подписи — видеть, завершились ли задачи подписи для сборки или завершились с ошибкой.

• Список продуктов — все цели релиза (продукты) с их платформами, флагом official/community и ID.

• Просмотр планов релиза — статус, исходные пакеты и целевые репозитории любого существующего релиза.

С JWT-токеном (аутентифицированный доступ)

• Создание сборок — указание пакетов, платформы(ы), ветки/тега/SRPM. Поддерживает несколько платформ в одной сборке (например, AlmaLinux-8 + AlmaLinux-9). Архитектуры по умолчанию соответствуют полному списку каждой платформы, если вы не переопределите их. Поддерживает пользовательские Git-URL для репозиториев вне git.almalinux.org (например, GitHub, GitLab). Поддерживает все опции mkbuild.py: связанные сборки, mock-определения, исключения, флейворы, secureboot, модули, with/without.

• Подпись сборок — создание задач подписи с выбранным ключом.

• Список ключей подписи — просмотр доступных ключей с ID и сопоставлениями платформ.

• Создание планов релиза — создание запланированного плана релиза для сборки (какие пакеты идут в какие репозитории) с выбором платформы + продукта. Сам релиз никогда не выполняется — создаётся только план; фиксация/публикация намеренно заблокированы.

• Удаление сборок — намеренно заблокировано для безопасности.

Типы логов

ALBS создаёт несколько файлов логов для каждой задачи сборки. Ключевые для отладки:

Related MCP server: Kerneldev MCP

Установка

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

Эта команда устанавливает и MCP-сервер (albs-mcp), и CLI (albs).

Аутентификация

JWT-токен считывается (проверяется по порядку):

1. Переменная окружения ALBS_JWT_TOKEN

2. Файл ~/.albs/credentials (Python-словарь с ключом token):

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

Без токена и MCP, и CLI работают в режиме только для чтения.

Никогда не коммитьте реальные токены. Используйте переменные окружения или ~/.albs/credentials, а не аргументы CLI.

Вариант настройки 1: MCP-сервер

Добавьте в конфиг вашего MCP-клиента (например, mcp.json или эквивалент):

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

Вариант настройки 2: CLI + Skill

Для случаев, когда загрязнение контекста MCP вызывает беспокойство, или при использовании инструментов, не поддерживающих MCP.

Шаг 1. Установите пакет (как указано выше — даёт вам команду albs):

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

Шаг 2. Добавьте инструкции рабочего процесса в ваш ИИ-инструмент:

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

Или скопируйте содержимое skills/albs-cli/SKILL.md в файл AGENTS.md вашего проекта или эквивалентный файл инструкций.

Skill обучает ИИ-агента тем же рабочим процессам (порядок расследования, обработка EPEL, подпись), но через команды оболочки albs вместо вызовов инструментов MCP.

Шаг 3. Проверка:

albs --help

CLI также работает автономно — ИИ не нужен. Полезно для скриптов и ручного использования в терминале.

Использование 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

Выполните albs --help или albs <command> --help для полной справки.

Справочник инструментов

Только чтение (без аутентификации)

Аутентифицированные (требуется JWT)

Промпты

Промпты MCP — это точки входа в рабочий процесс, вызываемые пользователем. В таких клиентах, как Claude Code, они отображаются как слэш-команды (/mcp__albs__<name>); их запускает пользователь, а не агент.

Пример (Claude Code):

/mcp__albs__investigate_build 52679
/mcp__albs__release_plan 52679

investigate_build разворачивается в рабочий процесс исследования (get_build_info → get_failed_tasks → загрузка/чтение ключевых логов по порядку), параметризованный идентификатором сборки. release_plan разворачивается в рабочий процесс создания плана релиза (get_build_info → get_products → create_release_plan) и явно останавливается на плане — он никогда не коммитит и не публикует.

Пример: исследование упавшей сборки

Спросите агента: «Что пошло не так в сборке 52679?»

Агент выполнит:

1. get_build_info(70368) — видит, что упала только задача i686; остальные 7 архитектур собрались

2. get_failed_tasks(70368) — получает файлы логов, ★ отмечает важные из них

3. search_log(70368, "mock_build.441500.1785274367.log") — просматривает лог из 936 строк / 600 КБ и возвращает причину с контекстом одним вызовом:

   >>> 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") — нет совпадений: chroot и зависимости в порядке, значит, это не сбой зависимостей

5. Сообщает: "CK_ULONG * — это unsigned long *, тогда как OpenSSL ожидает size_t *; на ILP32 (i686) это разные типы, поэтому rebase на 3.27.0 ломается только на 32-битных архитектурах."

Если бы поиск не дал результатов, следующим шагом был бы read_log_tail, а затем вызов ↑ earlier: ..., который он выводит, — так лог просматривается вверх, страница за страницей. Размер страниц задаётся символьным бюджетом, а не числом строк — 165 строк для этого mock_build, или 350 для mock_root той же сборки, — и каждая начинается ровно там, где остановилась предыдущая, так что ничего не пропускается.

Обратите внимание, что именно заменяет шаг 3. read_log_tail для этого лога возвращает make: *** [Makefile:4615: all] Error 2 — симптом, находящийся на сотни строк ниже настоящей ошибки, потому что make -j продолжает компиляцию после первого сбоя. Если запросить достаточно длинный хвост, чтобы добраться до ошибки, вместо этого вернётся 167 КБ команд gcc, что может превысить лимит размера результата вызывающей стороны. search_log возвращает 4 КБ с ответом в начале.

Пример: создание сборки

Спросите агента: «Собери bash для AlmaLinux-9 из ветки c9s»

Агент вызовет:

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

Для нескольких платформ сразу:

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

Для внешних Git-репозиториев (например, GitHub) используйте git_urls:

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

По умолчанию архитектуры соответствуют полному списку каждой платформы. Когда arch_list указан вместе с несколькими платформами, он проверяется отдельно для каждой платформы.

Пример: создание плана релиза

Спросите агента: «Создай план релиза для сборки 62316 на AlmaLinux-8.»

Агент выполнит:

1. get_build_info(62316) — подтверждает платформу и то, что у сборки есть завершённые задачи

2. get_products() — выводит список продуктов, чтобы вы могли выбрать цель (например, AlmaLinux)

3. create_release_plan(build_id=62316, platform="AlmaLinux-8", product="AlmaLinux") — собирает завершённые задачи сборки, преобразует имена платформы и продукта в идентификаторы и создаёт запланированный план

4. Сообщает план (статус, исходные пакеты, целевые репозитории) и поясняет, что ничего не опубликовано — это только план

Сам релиз (коммит/публикация плана) намеренно не выполняется. Если попросить агента «выпустить по-настоящему», запрос направляется на commit_release, который заблокирован и сообщает, что поддерживаются только планы.

Тесты

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

Переменные окружения