alt-rdb-mcp

A Go MCP server wrapping the rdb.altlinux.org REST API. It exposes 24 tools (package info, versions across branches, dependencies, build tasks, ACLs, maintainers, CVEs, errata and images) over the Model Context Protocol.

Tools (24)

Packages

Tool	Purpose
package_info	Version and metadata of a source package in one branch
package_versions	Package versions across all branches
package_watch	Whether a newer upstream version exists (watch report)
search_packages	Search packages by a name substring
packages_by_file	Which package provides a file
package_changelog	Recent RPM changelog entries of a package
package_specfile	The RPM .spec file of a package

Dependencies

Tool	Purpose
package_dependencies	Build and runtime dependencies of a package (recursive build depth)
reverse_dependencies	Which packages depend on a given package
backport_helper	Extra packages needed to backport a package into an adjacent branch

Build tasks & ACL

Tool	Purpose
build_task	Info about a gyle build task by ID (state, owner, subtasks)
build_task_diff	Per-arch package plan diff of a build task
package_acl	Who has commit/build rights on a package

Maintainers

Tool	Purpose
maintainer_info	Information about a maintainer
maintainer_packages	A maintainer's packages
maintainer_watch	A maintainer's packages lagging behind upstream
find_maintainer	Search a maintainer by name/nickname

Security (errata / CVE)

Tool	Purpose
package_errata	Errata/CVE for a branch, optionally by package
cve_info	Summary of a CVE/BDU/GHSA
cve_fixes	Where a CVE is fixed (branches/packages/errata)
errata_info	Errata card by id

Images & discovery

Tool	Purpose
image_list	ISO images of an edition/branch
package_in_image	Package version inside an ISO image
list_branches	List all repository branches / package sets

Note: the service is Russian-facing, so tool responses are returned in Russian.

Binary vs source package names

Most RDB endpoints work on source packages, while users name packages the way they see them installed — by their binary name, and the two often differ (bash is built from bash-defaults, openssl from openssl3 in sisyphus but from openssl1.1 in p10). A source-only query for such a name returns nothing, or only long-dead branches, which reads as "no such package".

So package_info, package_versions, package_watch, package_dependencies, reverse_dependencies, package_acl, package_changelog, package_specfile and backport_helper accept either kind of name: when nothing is found, they resolve the binary package to its source package via /api/site/find_source_package?branch=&name=, repeat the query and state the mapping in the answer ("binary package bash is built from source package bash-defaults"), so the model never silently reports the data of a different package. The mapping is per branch, so all distinct sources are reported when they differ across branches.

Build and run

go build -o alt-rdb-mcp .

# stdio transport (default) — for local MCP clients
./alt-rdb-mcp --transport=stdio

# streamable-http — /mcp endpoint
./alt-rdb-mcp --transport=http --addr=:8090

Flags

Flag	Default	Description
--transport	stdio	stdio or http
--addr	:8090	address for the http transport
--rdb-base-url	https://rdb.altlinux.org	base URL of the RDB API

In HTTP mode it also serves GET /healthz (a health-check for quadlet/orchestrator).

Usage with MCP clients

Build the binary and put it on your PATH as alt-rdb-mcp. All examples use the stdio transport (the client spawns the process).

Claude

.mcp.json (project scope) or claude_desktop_config.json:

{
  "mcpServers": {
    "alt-rdb": {
      "command": "alt-rdb-mcp",
      "args": ["--transport=stdio", "--rdb-base-url=https://rdb.altlinux.org"]
    }
  }
}

Codex CLI

~/.codex/config.toml:

[mcp_servers.alt-rdb]
command = "alt-rdb-mcp"
args = ["--transport=stdio"]

opencode

opencode.json:

{
  "mcp": {
    "alt-rdb": {
      "type": "local",
      "command": ["alt-rdb-mcp", "--transport=stdio"],
      "enabled": true
    }
  }
}

Tests

go test ./...

The client tests (internal/rdb/*_test.go) cover URL/parameter construction, JSON parsing, human-readable formatting and the "not found" branches, using httptest servers and JSON fixtures (internal/rdb/testdata/). Particular attention goes to version comparison/sorting (verKey/sortKeyGreater), EVR/epoch formatting, picking the freshest package (selectPackage), handling of 404 → empty, pkghash resolution, binary → source fallback (binsrc.go), edition resolution and base64 spec-file decoding. internal/tools/binsrc_test.go covers the fallback wiring of the tools themselves.

Container (podman/docker)

podman build -t alt-rdb-mcp -f Containerfile .
podman run --rm -p 127.0.0.1:8090:8090 alt-rdb-mcp

The image is multi-stage: build on golang:1.25 (CGO_ENABLED=0, static binary), the final stage is FROM scratch with a CA bundle for HTTPS to rdb.altlinux.org.

Quadlet (rootless systemd)

The alt-rdb-mcp.network and alt-rdb-mcp.container files are for deploying as a rootless service. Copy them into ~/.config/containers/systemd/, then:

systemctl --user daemon-reload
systemctl --user start alt-rdb-mcp

alt-rdb-mcp.network sets Options=mtu=1500 — required, otherwise outbound TCP connections from the container break. The port is published on 127.0.0.1:8090; wiring it to a consumer network is done separately.

Layout

main.go               # CLI + server startup (stdio/http)
internal/rdb/         # RDB client + tests
  http.go             # HTTP GET, 404 → empty, User-Agent, timeouts, helpers
  vercmp.go           # RPM-like version comparison
  packages.go         # package_info, selectPackage, EVR, format_package
  versions.go errata.go vuln.go maintainers.go files.go
  search.go watch.go images.go editions.go
  pkghash.go          # name -> pkghash resolution (via package_versions)
  binsrc.go           # binary -> source package resolution (find_source_package)
  dependencies.go     # build/runtime deps, reverse deps, backport helper
  tasks.go            # build task info + diff
  acl.go branches.go changelog.go specfile.go
internal/tools/       # MCP tools (Input structs + handlers)
Containerfile
alt-rdb-mcp.network alt-rdb-mcp.container