AsciiDoc-to-Context: Building a Model Context Protocol (MCP) RAG Bridge for Uyuni Doc

This Hackweek project creates a Proof-of-Concept (PoC) MCP Server that exposes the entire Uyuni documentation knowledge base as an agent tool.

We will use the simplest, most performant open-source RAG stack—Pandoc for structured .adoc conversion, LlamaIndex/FAISS for fast semantic retrieval, and FastMCP as the standardized communication wrapper.

This bridge is the essential Knowledge Layer required to augment LLMs (like the Gemini CLI) with accurate, context-limited information from the Uyuni manuals, enabling complex administrative queries.

Description

Motivation

While existing projects provide tools for Action (calling the live Uyuni API) and Diagnosis (analyzing live logs), they critically lack the Knowledge Context necessary for true administrative assistance.

• Action Without Knowledge is Dangerous: An agent that can execute schedulepatchupdate but cannot answer why a specific patch is necessary, how to test it on a staging environment, or what the rollback procedure is, creates more risk than it solves.

• The Problem of "Life Content Management": Uyuni is fundamentally about managing system states and updates across a lifecycle. These are multi-step, complex processes (e.g., setting up channels, defining activation keys, using Spacewalk Configuration Management) that are only defined in the documentation. Without RAG, the agent is forced to guess or hallucinate these procedural details.

• Cost and Latency: The Uyuni documentation is too large to fit into any practical LLM context window. RAG solves this by efficiently retrieving only the 5-10 most relevant, high-quality documentation chunks.

Technical Implementation

The entire system is divided into two distinct open-source phases:

• Document Pre-processing (Pandoc): Uses Pandoc to convert .adoc files to structurally-rich Markdown (.md). This step is critical to enabling structural chunking and avoiding "context poisoning" from noise.

• Semantic Indexing (LlamaIndex): LlamaIndex manages the RAG workflow. It will load the .md files using the MarkdownNodeParser and use an open-source embedding model (BGE-small-en-v1.5) to convert them into vectors.

• Vector Storage (FAISS): The vectors are stored locally in a FAISS index, providing the simplest, fastest, and most PoC-friendly persistence layer. B. Phase 2: Runtime and MCP Exposure (The Bridge)

• MCP Wrapper (FastMCP): Creates the Python web server, handling the MCP-compliant JSON-RPC communication.

• Tool Registration: Registers the tool, getuyunidocs(query: str, top_k: int = 5), allowing external agents to call the RAG service.

• Retrieval Logic: The function loads the FAISS index, performs a semantic search, and returns a context-limited string of the top_k most relevant documentation chunks.

Complex Example Queries & Expected Output

The success of this project is measured by its ability to answer complex, multi-step queries that require the documentation.

"Outline the full procedure for using Content Lifecycle Management to test a security patch on a staging client group before deploying it to production."

"1. Clone the Channel: Use the Uyuni Web UI to clone the Production-Base channel into a new Staging-Test channel. 2. Apply Patch: Apply the security update (e.g., CVE-2023-9999) to the Staging-Test channel only. 3. Link Staging Systems: Modify the Activation Key for your staging systems to subscribe them to the Staging-Test channel. 4. Test & Promote: Once testing confirms the fix, use the Promote feature in Content Lifecycle Management to merge the changes from Staging-Test back into Production-Base."

"I am setting up a Salt-managed Minion but I need to ensure it only accepts packages signed by our custom GPG key. Which config file should I modify and what is the required configuration?"

"You need to modify the Minion Configuration file located at /etc/salt/minion.d/01-uyuni.conf. The required setting is pkg_verify: True. Ensure the custom GPG key is placed in /etc/pki/rpm-gpg/ and referenced in the minion's key configuration." |

"A system is stuck after attempting to remove it from Uyuni. What is the manual, non-API clean-up procedure for a failed minion removal?" "The manual clean-up procedure involves 3 steps: 1. On the client, run zypper remove salt-minion. 2. On the Uyuni Server, delete the system's key from the Salt master key directory (/etc/salt/pki/master/minions/). 3. Run the system refresh command on the Uyuni server: salt-key -D ."

By providing the accurate, documented context for these types of complex queries, the RAG-MCP bridge elevates the Uyuni AI assistant from a simple executor to an indispensable System Administrator Co-pilot.