feat: add read-only dnf package manager tools

[Albe83]

Summary

Add read-only MCP tools to query the system package manager (dnf) for troubleshooting workflows on modern RH-like systems.

Assumptions / Constraints

• Target OS: modern RH-like distributions (RHEL/Fedora/CentOS/Alma/Rocky)
• Execution environment: full OS on VM/Bare Metal (not containers)
• Minimum supported dnf version: 4.x
• Read-only operations only (no system modifications)
• Output can be raw dnf output; normalization can be handled by the LLM

Primary Use Cases

1. List installed packages
2. List available packages
3. Get package details (to enable list → detail workflows)
4. List configured repositories and their enabled/disabled state

Non-scope (for now)

• Pagination/volume controls for large outputs
• Structured normalization of output
• Container execution support

Open Questions (non-blocking)

• Exact dnf commands and flags to support (e.g., list/info/repolist)
• Whether to enforce cache-only behaviors or allow repo metadata refresh
• Error reporting format (raw stderr vs. structured)

[Albe83]

Implementation Plan

1. Analysis and design: define supported dnf commands and safe options (e.g. list installed, list available, info <pkg>, repolist), map inputs/flags and raw output; draft a mini-spec for parameters, errors, and readOnlyHint.
2. Tool implementation: create a new module under src/linux_mcp_server/tools/ with required decorators, input sanitization/allowlist, and integration with existing command runner; register the command in src/linux_mcp_server/commands.py and add formatter only if needed (raw passthrough).
3. Tests: add tests under tests/tools/ with 100% patch coverage and autospec=True; cover input validation, command construction, error handling, and readOnlyHint.
4. Final verification: run make verify, fix any lint/type/test issues, and update minimal docs if required.

[Albe83]

Iteration 1 Plan: analysis/design

1. Review existing tool patterns (processes.py, services.py, logs.py) and command registry structure in commands.py to align naming, decorators, and error handling.
2. Define tool surface and parameters (likely 4 tools: list installed, list available, package info, repo list), plus any optional flags.
3. Decide exact dnf command invocations and safe flags (e.g., -C/--cacheonly), balancing read-only constraints vs metadata freshness.
4. Define input validation rules for package identifiers and patterns (e.g., disallow leading -, control chars, whitespace; decide whether glob patterns are allowed).
5. Produce a short mini-spec in the issue (tool names, params, command mapping, error/empty handling, readOnlyHint).

[Albe83]

Iteration 1 Output: mini-spec (analysis/design)

Tool surface

• list_dnf_installed_packages(host: Host | None = None) -> str
• list_dnf_available_packages(host: Host | None = None) -> str
• get_dnf_package_info(package: str, host: Host | None = None) -> str
• list_dnf_repositories(host: Host | None = None) -> str

Command mapping

• Installed packages: dnf list installed
• Available packages: dnf list available
• Package details: dnf info <package>
• Repositories: dnf repolist --all

Input validation

• package must be non-empty, no whitespace or control chars, must not start with -.
• Allow a conservative RPM token charset: letters, digits, ._+:- (no slashes). (Globs like * and ? intentionally excluded for now.)

Output behavior (raw)

• Return stdout as-is on success.
• If stdout empty: return a user-facing message (e.g., "No output returned by dnf.").
• If command fails: return a message that includes stderr (e.g., "Error running dnf: ...").
• For info when no match: return "Package '' not found." (detect common dnf text).

Read-only

• All tools use readOnlyHint=True and disallow_local_execution_in_containers.
• No state changes; only query commands.

Open tradeoffs (deferred)

• Whether to use -C/--cacheonly or -q flags.
• Whether to permit glob patterns in package.
• Pagination/limits for large outputs.

Next iteration proposal (implementation plan)

1. Implement validation helper for package in utils/validation.py.
2. Add new command groups in commands.py for the four dnf commands.
3. Create src/linux_mcp_server/tools/dnf.py with four tools, decorators, and error handling; return raw stdout.
4. Register tool commands in src/linux_mcp_server/commands.py (and tools/__init__.py if required).
5. Add tests under tests/tools/ with full patch coverage (success, empty output, error paths, validation).

[Albe83]

Iteration 2 Completed: implementation

Changes

• Added dnf command groups in commands.py (list installed, list available, info, repolist).
• Added dnf tools module with 4 read-only tools and raw output behavior.
• Added input validation for package identifiers in utils/validation.py.
• Registered new tools in tools/__init__.py.
• Added tests for validation and tool behaviors (success, empty output, error, not-found, invalid input).

Tests

• Not run in this iteration.

[Albe83]

Iteration 2 Test Results

• make verify PASSED
• pytest: 456 passed, 1 skipped (root can access restricted paths), 1 warning (vendored module already loaded)

[Albe83]

[Mirror from upstream issue to origin]

Container rebuild + functional test run (dev only, not for PR):

• Rebuilt image as linux-mcp-server:dnf-test2. Build required local-only tweaks to bypass SSL interception during microdnf and uv/pip downloads (disabled SSL verification for UBI repos; added uv/pip insecure host flags). All of those changes were reverted in the working tree after build.
• Replaced the dev container with the new image and ran the server with LINUX_MCP_LOG_LEVEL=DEBUG.
• Needed to run container as root to read the mounted SSH key (/root/.ssh/mcp_container_ed25519). Running as mcp user hit PermissionError.
• Functional checks via MCP streamable-http against host.containers.internal:
  • tools/list returned new DNF tools.
  • list_dnf_installed_packages succeeded.
  • list_dnf_available_packages succeeded.
  • get_dnf_package_info (bash) succeeded.
  • list_dnf_repositories succeeded.

All functional calls returned non-empty output.

[Albe83]

[Mirror from upstream issue to origin]

Docs update:

• Added API docs entry for DNF tools (docs/api/tools/dnf.md) and linked from docs/api/index.md.
• Added usage section for DNF tools in docs/usage.md.
• Added cheatsheet section for DNF tools in docs/cheatsheet.md.
• Added DNF tools file in docs/contributing.md project structure.
• Added DNF feature bullet in README.md.

[Albe83]

[Mirror from upstream issue to origin]

Committed and pushed: feat(dnf): add read-only dnf tools (8174375) on branch feat/dnf-tools.

[Albe83]

[Mirror from upstream issue to origin]

Proposed next additions (from RHEL 9/10 + DNF docs):

High value (read-only):

• dnf_provides: dnf provides <file> to map missing binaries/libs to packages.
• dnf_repo_info: dnf repoinfo <repo_id> for repo metadata and troubleshooting.
• Group tools: dnf group list, dnf group info <group>, optionally dnf group summary.
• Module tools (Application Streams): dnf module list, dnf module list <name>, dnf module provides <pkg>.

These are consistent with RHEL 9/10 docs and common troubleshooting workflows. If approved, I can plan an iteration to add these tools + tests + docs.

[Albe83]

[Mirror from upstream issue to origin]

Plan for next iteration (no implementation yet):

1. Design + validation

• Define tool set and command mappings:
  • dnf_provides -> dnf provides <file>
  • dnf_repo_info -> dnf repoinfo <repo_id>
  • dnf_group_list -> dnf group list
  • dnf_group_info -> dnf group info "<group>"
  • dnf_group_summary -> dnf group summary
  • dnf_module_list -> dnf module list [<name>]
  • dnf_module_provides -> dnf module provides <pkg>
• Add input validation rules (file/path validation for provides; repo_id/group/module name allowlists).

2. Implementation (code)

• Add commands to commands.py.
• Implement new tools in src/linux_mcp_server/tools/dnf.py (readOnlyHint, decorators, raw output, error handling).
• Register tools in tools/__init__.py.

3. Tests

• Unit tests for validation and each tool path (success/empty/error/not found/invalid input).
• Ensure full patch coverage for new code.

4. Docs

• Update docs/api/tools/dnf.md, docs/usage.md, docs/cheatsheet.md with new tools.

5. Verification

• Run make verify.
• (Optional) Container functional run if needed.

If this plan is approved, I will proceed with implementation in the next iteration.

[Albe83]

Iteration 3 Completed: additional DNF tools

Changes

• Added DNF commands and tools for: dnf_provides, get_dnf_repo_info, list_dnf_groups, get_dnf_group_info, get_dnf_group_summary, list_dnf_modules, dnf_module_provides.
• Added validation helpers for repo id, group name, module name (optional), and provides query allowlists.
• Updated DNF documentation in docs/usage.md, docs/cheatsheet.md, and feature bullet in README.md.
• Expanded unit tests for all new validation paths and tool behaviors (success/invalid/not-found).

Tests

• make verify PASSED
• pytest: 518 passed, 1 skipped, 1 warning

[Albe83]

Iteration 3 Update: coverage for new DNF branches

Added tests for error and empty-output branches in the new DNF tools to satisfy full coverage expectations.

Tests

• make verify PASSED
• pytest: 528 passed, 1 skipped, 1 warning

[Albe83]

Functional container tests (iteration 3)

Built and ran the container image with DEBUG logging and streamable HTTP. Validated the new DNF tools end-to-end against host.containers.internal via SSH. All tool calls returned non-empty output and behaved as expected.