home_manager_search
Search Home Manager configuration options by name and description to find specific settings for user environment customization.
Instructions
Search Home Manager configuration options.
Searches through available Home Manager options by name and description.
Args: query: The search query string to match against option names and descriptions limit: Maximum number of results to return (default: 20, max: 100)
Returns: Plain text list of matching options with name, type, and description
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| limit | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- mcp_nixos/server.py:651-687 (handler)Main handler function for the 'home_manager_search' MCP tool. Fetches Home Manager documentation, parses options using BeautifulSoup, filters by query, and formats results as plain text.
async def home_manager_search(query: str, limit: int = 20) -> str: """Search Home Manager configuration options. Searches through available Home Manager options by name and description. Args: query: The search query string to match against option names and descriptions limit: Maximum number of results to return (default: 20, max: 100) Returns: Plain text list of matching options with name, type, and description """ if not 1 <= limit <= 100: return error("Limit must be 1-100") try: options = parse_html_options(HOME_MANAGER_URL, query, "", limit) if not options: return f"No Home Manager options found matching '{query}'" results = [] results.append(f"Found {len(options)} Home Manager options matching '{query}':\n") for opt in options: results.append(f"• {opt['name']}") if opt["type"]: results.append(f" Type: {opt['type']}") 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)Helper function that parses Home Manager (and nix-darwin) HTML documentation to extract option names, types, and descriptions. Used by home_manager_search.
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:651-651 (registration)FastMCP @mcp.tool() decorator registers the home_manager_search function as an MCP tool.
async def home_manager_search(query: str, limit: int = 20) -> str: - mcp_nixos/server.py:652-662 (schema)Input schema defined by function parameters (query: str, limit: int=20) and docstring. Output is str (plain text).
"""Search Home Manager configuration options. Searches through available Home Manager options by name and description. Args: query: The search query string to match against option names and descriptions limit: Maximum number of results to return (default: 20, max: 100) Returns: Plain text list of matching options with name, type, and description """