albs-mcp

AlmaLinux Build System(ALBS)용 MCP 서버 및 CLI.

AI 코딩 어시스턴트에게 ALBS에 대한 직접 접근 권한을 부여합니다 — 자연어로 빌드 실패를 조사하고, 빌드를 생성하고, 패키지에 서명할 수 있습니다.

두 가지 사용 방법:

할 수 있는 작업

토큰 없이(읽기 전용)

• 빌드 실패 조사 — 주요 사용 사례. 에이전트에게 빌드 ID를 주면 로그에서 실패 시그니처를 검색하고(search_log), 정확한 파일, 줄, 진단 메시지를 특정한 다음 그 주변의 컨텍스트를 확장합니다. 줄 오프셋을 추측할 필요도 없고 10만 줄이 넘는 로그 파일에 토큰을 낭비할 필요도 없습니다.

• 빌드 상세 정보 가져오기 — 모든 태스크의 상태, 패키지, 아키텍처, 서명 태스크.

• 빌드 목록 및 검색 — 최근 빌드 탐색, 패키지 이름 또는 상태로 필터링.

• 플랫폼 가져오기 — 모든 플랫폼과 지원 아키텍처 목록을 동적으로 가져옴.

• 로그 다운로드 및 읽기 — 모든 빌드의 모든 로그 파일: grep(search_log), 아래에서 위로 페이지 단위 읽기(read_log_tail), 또는 줄 범위 읽기. 어떤 읽기도 폭주하지 않습니다: 각 줄은 500자로, 전체 결과는 40k자로 잘립니다(max_line_chars=0 / max_chars=0으로 해제 가능). 따라서 한 줄이 수 KB의 컴파일러 플래그로 구성된 로그도 하나의 거대한 덩어리 대신 정확히 이어지는 페이지로 반환됩니다. 읽기는 로그가 아직 디스크에 없으면 자동으로 다운로드합니다.

• 서명 상태 확인 — 빌드의 서명 태스크가 완료되었는지 실패했는지 확인.

• 제품 목록 — 모든 릴리스 대상(제품)과 해당 플랫폼, 공식/커뮤니티 플래그, ID.

• 릴리스 계획 보기 — 기존 릴리스의 상태, 소스 패키지, 대상 저장소.

JWT 토큰 포함(인증됨)

• 빌드 생성 — 패키지, 플랫폼, 브랜치/태그/SRPM 지정. 단일 빌드에서 여러 플랫폼 지원(예: AlmaLinux-8 + AlmaLinux-9). 아키텍처는 재정의하지 않으면 각 플랫폼의 전체 목록이 기본값입니다. git.almalinux.org 외부 저장소(예: GitHub, GitLab)용 사용자 지정 Git URL 지원. 모든 mkbuild.py 옵션 지원: 연결된 빌드, mock 정의, 제외 항목, flavor, 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 파일(token 키가 있는 Python dict):

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

토큰이 없으면 MCP와 CLI 모두 읽기 전용 모드로 작동합니다.

실제 토큰을 커밋하지 마세요. CLI 인수가 아닌 환경 변수 또는 ~/.albs/credentials를 사용하세요.

설정 옵션 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단계. AI 도구에 워크플로우 지침 추가:

# 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 또는 이에 상응하는 지침 파일에 복사하세요.

이 스킬은 AI 에이전트에게 동일한 워크플로우(조사 순서, EPEL 처리, 서명)를 MCP 도구 호출 대신 albs 셸 명령을 통해 가르칩니다.

3단계. 확인:

albs --help

CLI는 AI 없이도 독립적으로 작동합니다. 스크립트와 수동 터미널 사용에 유용합니다.

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는 빌드 ID로 매개변수화된 조사 워크플로우(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줄/600KB 로그를 grep하여 원인을 맥락과 함께 한 번의 호출로 반환합니다:

   >>> 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)에서는 이들이 서로 다른 타입이므로, 3.27.0 리베이스는 32비트에서만 깨집니다."

검색 결과가 비어 있었다면, 다음 단계는 read_log_tail을 호출하고, 그다음 그것이 출력하는 ↑ earlier: ... 호출을 사용하여 로그를 한 번에 한 페이지씩 거슬러 올라가는 것입니다. 페이지는 줄 수가 아니라 문자 예산에 따라 크기가 정해집니다 — 이 mock_build의 165줄 또는 같은 빌드 mock_root의 350줄 — 그리고 각 페이지는 이전 페이지가 멈춘 지점에서 정확히 시작하므로 건너뛰는 부분이 없습니다.

3단계가 무엇을 대체하는지 주목하세요. 해당 로그에서 read_log_tail은 make: *** [Makefile:4615: all] Error 2를 반환합니다. 이것은 실제 오류보다 수백 줄 아래에 있는 증상입니다. make -j는 첫 번째 실패 후에도 계속 컴파일하기 때문입니다. 오류에 도달할 만큼 충분한 tail을 요청하면 대신 167KB의 gcc 명령줄이 반환되어 호출자의 결과 크기 제한을 초과할 수 있습니다. search_log는 답이 맨 위에 있는 4KB를 반환합니다.

예제: 빌드 생성

에이전트에게 물어보세요: "c9s 브랜치에서 AlmaLinux-9용 bash를 빌드해 주세요"

에이전트는 다음을 호출합니다:

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가 여러 플랫폼과 함께 지정되면 각 플랫폼에 대해 개별적으로 검증됩니다.

예제: 릴리스 계획 생성

에이전트에게 물어보세요: "AlmaLinux-8에서 빌드 62316에 대한 릴리스 계획을 생성해 주세요."

에이전트는 다음을 수행합니다:

1. get_build_info(62316) — 플랫폼과 빌드에 완료된 작업이 있음을 확인합니다

2. get_products() — 대상을 선택할 수 있도록 제품을 나열합니다(예: AlmaLinux)

3. create_release_plan(build_id=62316, platform="AlmaLinux-8", product="AlmaLinux") — 완료된 빌드 작업을 수집하고 플랫폼/제품 이름을 ID로 변환한 다음 예약된 계획을 생성합니다

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

환경 변수