albs-mcp

用于 AlmaLinux Build System (ALBS) 的 MCP 服务器和 CLI。

让 AI 编码助手直接访问 ALBS —— 通过自然语言调查构建失败、创建构建、签署软件包。

两种使用方式：

它能做什么

无令牌（只读）

• 调查构建失败 —— 主要用例。给 agent 一个构建 ID，它会 grep 日志以查找失败特征（search_log），精确定位文件、行号和诊断信息，然后扩大上下文。无需猜测行偏移，也不会在超过 10 万行的日志文件上浪费 token。

• 获取构建详情 —— 所有任务、软件包、架构、签名任务的状态。

• 列出和搜索构建 —— 浏览最近的构建，按软件包名称或状态过滤。

• 获取平台 —— 动态获取所有平台及其支持的架构列表。

• 下载和读取日志 —— 任何构建的任何日志文件：用 search_log grep、用 read_log_tail 从底部向上翻页，或读取指定行范围。任何读取都不会失控：每行截断为 500 个字符，整个结果截断为 40k 个字符（可用 max_line_chars=0 / max_chars=0 解除限制），因此单行包含数 KB 编译器标志的日志会以精确拼接的页面返回，而不是一个超大块。如果日志尚未在磁盘上，读取时会自动下载。

• 检查签名状态 —— 查看构建的签名任务是已完成还是失败。

• 列出产品 —— 所有发布目标（产品）及其平台、官方/社区标志和 ID。

• 查看发布计划 —— 任何现有发布的状态、源软件包和目标仓库。

使用 JWT 令牌（已认证）

• 创建构建 —— 指定软件包、平台、分支/标签/SRPM。支持在单个构建中使用多个平台（例如 AlmaLinux-8 + AlmaLinux-9）。除非你覆盖，否则架构默认为每个平台的完整列表。支持 git.almalinux.org 之外仓库的自定义 Git URL（例如 GitHub、GitLab）。支持所有 mkbuild.py 选项：链接构建、mock 定义、排除项、flavors、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 字典）：

{"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 步。 将工作流说明添加到你的 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 或等效说明文件中。

该 skill 教 AI agent 相同的工作流（调查顺序、EPEL 处理、签名），但通过 albs shell 命令而非 MCP 工具调用。

第 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>）的形式出现；由用户触发，而非 agent。

示例（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 搜索，并在一次调用中返回带上下文的失败原因：

   >>> 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 在第一次失败后仍会继续编译。请求足够的尾部内容以 到达错误位置，反而会返回 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

环境变量