albs-mcp

MCPサーバーとCLI for AlmaLinux Build System (ALBS)。

AIコーディングアシスタントにALBSへの直接アクセスを提供します — ビルド失敗の調査、ビルドの作成、パッケージの署名など、すべて自然言語で行えます。

2つの使用方法:

できること

トークンなし（読み取り専用）

• ビルド失敗の調査 — 主なユースケースです。エージェントにビルドIDを与えると、ログから失敗シグネチャ（search_log）をgrepし、正確なファイル、行、診断情報を特定して、その周辺のコンテキストを広げます。行オフセットを推測する必要も、10万行以上のログファイルにトークンを費やす必要もありません。

• ビルド詳細の取得 — すべてのタスク、パッケージ、アーキテクチャ、署名タスクのステータス。

• ビルドの一覧と検索 — 最近のビルドを閲覧し、パッケージ名やステータスでフィルタリング。

• プラットフォームの取得 — すべてのプラットフォームとそのサポートアーキテクチャの動的に取得されるリスト。

• ログのダウンロードと読み取り — 任意のビルドの任意のログファイル: grep（search_log）、下からページング（read_log_tail）、または行範囲の読み取り。読み取りが肥大化することはありません: 各行は500文字に切り詰められ、結果全体は40k文字に制限されます（max_line_chars=0 / max_chars=0で解除）。そのため、1行が数KBのコンパイラフラグになるログでも、巨大なブロブではなく、正確に結合されるページで返されます。読み取り時、ログがまだディスクにない場合は自動的にダウンロードされます。

• 署名ステータスの確認 — ビルドの署名タスクが完了したか失敗したかを確認。

• 製品の一覧 — すべてのリリースターゲット（製品）とそのプラットフォーム、公式/コミュニティフラグ、ID。

• リリースプランの表示 — 既存のリリースのステータス、ソースパッケージ、ターゲットリポジトリ。

JWTトークンあり（認証済み）

• ビルドの作成 — パッケージ、プラットフォーム、ブランチ/タグ/SRPMを指定。単一ビルドで複数プラットフォームをサポート（例: AlmaLinux-8 + AlmaLinux-9）。アーキテクチャは上書きしない限り各プラットフォームの全リストがデフォルト。git.almalinux.org以外のリポジトリ（例: GitHub、GitLab）のカスタムGit URLをサポート。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ファイル（tokenキーを持つPython dict）:

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

トークンがない場合、MCPとCLIの両方が読み取り専用モードで動作します。

実際のトークンをコミットしないでください。 CLI引数ではなく、環境変数または~/.albs/credentialsを使用してください。

セットアップオプション1: MCPサーバー

MCPクライアント設定（例: mcp.jsonまたは同等のもの）に追加:

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

セットアップオプション2: CLI + スキル

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 は調査ワークフロー（get_build_info → get_failed_tasks → 主要なログのダウンロード/読み取りを順に実行）に展開され、ビルド ID によってパラメータ化されます。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 KB のログを grep し、原因をコンテキスト付きで 1 回の呼び出しで返します:

   >>> 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 を要求すると、代わりに 167 KB の gcc コマンド行が返され、呼び出し側の結果サイズ制限を超える可能性があります。search_log は回答を先頭に含む 4 KB を返します。

例: ビルドを作成する

エージェントに依頼します: 「ブランチ 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

環境変数