mcp-nixos

Instructions

Implementation Reference

• mcp_nixos/server.py:868-898 (handler)

  The main handler function that implements the 'home_manager_options_by_prefix' MCP tool. It fetches and parses the Home Manager options HTML documentation, filters options by the given prefix, and formats them as a human-readable list.
  @mcp.tool() async def home_manager_options_by_prefix(option_prefix: str) -> str: """Get Home Manager options matching a specific prefix. Useful for browsing options under a category or finding exact option names. Args: option_prefix: The prefix to match (e.g., 'programs.git' or 'services') Returns: Plain text list of options with the given prefix, including descriptions """ try: options = parse_html_options(HOME_MANAGER_URL, "", option_prefix) if not options: return f"No Home Manager options found with prefix '{option_prefix}'" results = [] results.append(f"Home Manager options with prefix '{option_prefix}' ({len(options)} found):\n") for opt in sorted(options, key=lambda x: x["name"]): results.append(f"• {opt['name']}") if opt["description"]: results.append(f" {opt['description']}") results.append("") return "\n".join(results).strip() except Exception as e: return error(str(e))
• mcp_nixos/server.py:247-336 (helper)

  Key helper function that parses HTML documentation pages (like Home Manager options.xhtml) to extract structured option data (name, description, type). Filters by query string or prefix path. Directly called by the handler with HOME_MANAGER_URL and the option_prefix.
  def parse_html_options(url: str, query: str = "", prefix: str = "", limit: int = 100) -> list[dict[str, str]]: """Parse options from HTML documentation.""" try: resp = requests.get(url, timeout=30) # Increase timeout for large docs resp.raise_for_status() # Use resp.content to let BeautifulSoup handle encoding detection # This prevents encoding errors like "unknown encoding: windows-1252" soup = BeautifulSoup(resp.content, "html.parser") options = [] # Get all dt elements dts = soup.find_all("dt") for dt in dts: # Get option name name = "" if "home-manager" in url: # Home Manager uses anchor IDs like "opt-programs.git.enable" anchor = dt.find("a", id=True) if anchor: anchor_id = anchor.get("id", "") # Remove "opt-" prefix and convert underscores if anchor_id.startswith("opt-"): name = anchor_id[4:] # Remove "opt-" prefix # Convert _name_ placeholders back to <name> name = name.replace("_name_", "<name>") else: # Fallback to text content name_elem = dt.find(string=True, recursive=False) if name_elem: name = name_elem.strip() else: name = dt.get_text(strip=True) else: # Darwin and fallback - use text content name = dt.get_text(strip=True) # Skip if it doesn't look like an option (must contain a dot) # But allow single-word options in some cases if "." not in name and len(name.split()) > 1: continue # Filter by query or prefix if query and query.lower() not in name.lower(): continue if prefix and not (name.startswith(prefix + ".") or name == prefix): continue # Find the corresponding dd element dd = dt.find_next_sibling("dd") if dd: # Extract description (first p tag or direct text) desc_elem = dd.find("p") if desc_elem: description = desc_elem.get_text(strip=True) else: # Get first text node, handle None case text = dd.get_text(strip=True) description = text.split("\n")[0] if text else "" # Extract type info - look for various patterns type_info = "" # Pattern 1: <span class="term">Type: ...</span> type_elem = dd.find("span", class_="term") if type_elem and "Type:" in type_elem.get_text(): type_info = type_elem.get_text(strip=True).replace("Type:", "").strip() # Pattern 2: Look for "Type:" in text elif "Type:" in dd.get_text(): text = dd.get_text() type_start = text.find("Type:") + 5 type_end = text.find("\n", type_start) if type_end == -1: type_end = len(text) type_info = text[type_start:type_end].strip() options.append( { "name": name, "description": description[:200] if len(description) > 200 else description, "type": type_info, } ) if len(options) >= limit: break return options except Exception as exc: raise DocumentParseError(f"Failed to fetch docs: {str(exc)}") from exc
• mcp_nixos/server.py:868-868 (registration)

  The @mcp.tool() decorator registers this function as an MCP tool named 'home_manager_options_by_prefix' in the FastMCP server.
  @mcp.tool()
• mcp_nixos/server.py:173-177 (helper)

  Utility function used by the handler to format error messages in responses.
  def error(msg: str, code: str = "ERROR") -> str: """Format error as plain text.""" # Ensure msg is always a string, even if empty msg = str(msg) if msg is not None else "" return f"Error ({code}): {msg}"
• mcp_nixos/server.py:51-52 (helper)

  Constant URL for the Home Manager options documentation page, passed to parse_html_options by the handler.
  HOME_MANAGER_URL = "https://nix-community.github.io/home-manager/options.xhtml" DARWIN_URL = "https://nix-darwin.github.io/nix-darwin/manual/index.html"