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"