mcp-nixos

Instructions

Implementation Reference

• mcp_nixos/server.py:1111-1142 (handler)

  The main async handler function for the 'darwin_options_by_prefix' tool. It calls parse_html_options with the DARWIN_URL and the given prefix to fetch matching nix-darwin options from HTML docs, formats them as plain text list.

  @mcp.tool()
  async def darwin_options_by_prefix(option_prefix: str) -> str:
      """Get nix-darwin 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., 'system.defaults' or 'services')
  
      Returns:
          Plain text list of options with the given prefix, including descriptions
      """
      try:
          options = parse_html_options(DARWIN_URL, "", option_prefix)
  
          if not options:
              return f"No nix-darwin options found with prefix '{option_prefix}'"
  
          results = []
          results.append(f"nix-darwin 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)

  Shared helper function that parses HTML documentation pages (like nix-darwin manual) to extract configuration options matching a query or prefix. Used by multiple darwin_* tools including darwin_options_by_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:1111-1111 (registration)

  FastMCP decorator that registers the darwin_options_by_prefix function as an MCP tool, auto-generating schema from signature and docstring.

  @mcp.tool()

• mcp_nixos/server.py:1113-1122 (schema)

  Tool docstring defining input schema (option_prefix: str) and output format (plain text list). FastMCP uses this for tool schema generation.

  """Get nix-darwin 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., 'system.defaults' or 'services')
  
  Returns:
      Plain text list of options with the given prefix, including descriptions
  """