mcp-nixos

Instructions

Implementation Reference

• mcp_nixos/server.py:689-739 (handler)

  The core handler function for the 'home_manager_info' tool, decorated with @mcp.tool() for automatic registration. Parses Home Manager HTML documentation to retrieve exact option details or provide suggestions.

  @mcp.tool()
  async def home_manager_info(name: str) -> str:
      """Get detailed information about a specific Home Manager option.
  
      Requires an exact option name match. If not found, suggests similar options.
  
      Args:
          name: The exact option name (e.g., 'programs.git.enable')
  
      Returns:
          Plain text with option details (name, type, description) or error with suggestions
      """
      try:
          # Search more broadly first
          options = parse_html_options(HOME_MANAGER_URL, name, "", 100)
  
          # Look for exact match
          for opt in options:
              if opt["name"] == name:
                  info = []
                  info.append(f"Option: {name}")
                  if opt["type"]:
                      info.append(f"Type: {opt['type']}")
                  if opt["description"]:
                      info.append(f"Description: {opt['description']}")
                  return "\n".join(info)
  
          # If not found, check if there are similar options to suggest
          if options:
              suggestions = []
              for opt in options[:5]:  # Show up to 5 suggestions
                  if name in opt["name"] or opt["name"].startswith(name + "."):
                      suggestions.append(opt["name"])
  
              if suggestions:
                  return error(
                      f"Option '{name}' not found. Did you mean one of these?\n"
                      + "\n".join(f"  • {s}" for s in suggestions)
                      + f"\n\nTip: Use home_manager_options_by_prefix('{name}') to browse all options with this prefix.",
                      "NOT_FOUND",
                  )
  
          return error(
              f"Option '{name}' not found.\n"
              + f"Tip: Use home_manager_options_by_prefix('{name}') to browse available options.",
              "NOT_FOUND",
          )
  
      except Exception as e:
          return error(str(e))

• mcp_nixos/server.py:247-336 (helper)

  Key helper function that parses the Home Manager HTML documentation page using BeautifulSoup to extract option names, types, and descriptions. Called by home_manager_info and related tools.

  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:689-689 (registration)

  The @mcp.tool() decorator registers the home_manager_info function with the FastMCP server.

  @mcp.tool()

• mcp_nixos/server.py:690-700 (schema)

  The function signature and docstring define the tool schema: input 'name' (str), output str.

  async def home_manager_info(name: str) -> str:
      """Get detailed information about a specific Home Manager option.
  
      Requires an exact option name match. If not found, suggests similar options.
  
      Args:
          name: The exact option name (e.g., 'programs.git.enable')
  
      Returns:
          Plain text with option details (name, type, description) or error with suggestions
      """