mcp-nixos

Instructions

Implementation Reference

• mcp_nixos/server.py:1696-1830 (handler)

  The main execution logic for the 'nixhub_find_version' tool. This async function queries NixHub API to find specific package versions, handles errors, formats responses with commit hashes and installation instructions.

  @mcp.tool()
  async def nixhub_find_version(package_name: str, version: str) -> str:
      """Find a specific version of a package in NixHub with smart search.
  
      Automatically searches with increasing limits to find the requested version.
  
      Args:
          package_name: Name of the package to query (e.g., "ruby", "python")
          version: Specific version to find (e.g., "2.6.7", "3.5.9")
  
      Returns:
          Plain text with version info and commit hash if found, or helpful message if not
      """
      # Validate inputs
      if not package_name or not package_name.strip():
          return error("Package name is required")
  
      if not version or not version.strip():
          return error("Version is required")
  
      # Sanitize inputs
      if not re.match(r"^[a-zA-Z0-9\-_.]+$", package_name):
          return error("Invalid package name. Only letters, numbers, hyphens, underscores, and dots are allowed")
  
      # Try with incremental limits
      limits_to_try = [10, 25, 50]
      found_version = None
      all_versions: list[dict[str, Any]] = []
  
      for limit in limits_to_try:
          try:
              # Make request - handle special cases for package names
              nixhub_name = package_name
              # Common package name mappings
              if package_name == "python":
                  nixhub_name = "python3"
              elif package_name == "python2":
                  nixhub_name = "python"
  
              url = f"https://www.nixhub.io/packages/{nixhub_name}?_data=routes%2F_nixhub.packages.%24pkg._index"
              headers = {"Accept": "application/json", "User-Agent": "mcp-nixos/1.0.0"}
  
              resp = requests.get(url, headers=headers, timeout=15)
  
              if resp.status_code == 404:
                  return error(f"Package '{package_name}' not found in NixHub", "NOT_FOUND")
              if resp.status_code >= 500:
                  return error("NixHub service temporarily unavailable", "SERVICE_ERROR")
  
              resp.raise_for_status()
              data = resp.json()
  
              if not isinstance(data, dict):
                  return error("Invalid response format from NixHub")
  
              releases = data.get("releases", [])
  
              # Collect all versions seen
              for release in releases[:limit]:
                  release_version = release.get("version", "")
                  if release_version and release_version not in [v["version"] for v in all_versions]:
                      all_versions.append({"version": release_version, "release": release})
  
                  # Check if this is the version we're looking for
                  if release_version == version:
                      found_version = release
                      break
  
              if found_version:
                  break
  
          except requests.Timeout:
              return error("Request to NixHub timed out", "TIMEOUT")
          except requests.RequestException as e:
              return error(f"Network error accessing NixHub: {str(e)}", "NETWORK_ERROR")
          except Exception as e:
              return error(f"Unexpected error: {str(e)}")
  
      # Format response
      if found_version:
          return _format_nixhub_found_version(package_name, version, found_version)
  
      # Version not found - provide helpful information
      results = []
      results.append(f"✗ {package_name} version {version} not found in NixHub\n")
  
      # Show available versions
      if all_versions:
          results.append(f"Available versions (checked {len(all_versions)} total):")
  
          # Sort versions properly using version comparison
          sorted_versions = sorted(all_versions, key=lambda x: _version_key(x["version"]), reverse=True)
  
          # Find newest and oldest
          newest = sorted_versions[0]["version"]
          oldest = sorted_versions[-1]["version"]
  
          results.append(f"• Newest: {newest}")
          results.append(f"• Oldest: {oldest}")
  
          # Show version range summary
          major_versions = set()
          for v in all_versions:
              parts = v["version"].split(".")
              if parts:
                  major_versions.add(parts[0])
  
          if major_versions:
              results.append(f"• Major versions available: {', '.join(sorted(major_versions, reverse=True))}")
  
          # Check if requested version is older than available
          try:
              requested_parts = version.split(".")
              oldest_parts = oldest.split(".")
  
              if len(requested_parts) >= 2 and len(oldest_parts) >= 2:
                  req_major = int(requested_parts[0])
                  req_minor = int(requested_parts[1])
                  old_major = int(oldest_parts[0])
                  old_minor = int(oldest_parts[1])
  
                  if req_major < old_major or (req_major == old_major and req_minor < old_minor):
                      results.append(f"\nVersion {version} is older than the oldest available ({oldest})")
                      results.append("This version may have been removed after reaching end-of-life.")
          except (ValueError, IndexError):
              pass
  
          results.append("\nAlternatives:")
          results.append("• Use a newer version if possible")
          results.append("• Build from source with a custom derivation")
          results.append("• Use Docker/containers with the specific version")
          results.append("• Find an old nixpkgs commit from before the version was removed")
  
      return "\n".join(results)

• mcp_nixos/server.py:1697-1707 (schema)

  Input schema defined by function parameters (package_name: str, version: str) and output str as plain text response. Includes detailed docstring with examples.

  async def nixhub_find_version(package_name: str, version: str) -> str:
      """Find a specific version of a package in NixHub with smart search.
  
      Automatically searches with increasing limits to find the requested version.
  
      Args:
          package_name: Name of the package to query (e.g., "ruby", "python")
          version: Specific version to find (e.g., "2.6.7", "3.5.9")
  
      Returns:
          Plain text with version info and commit hash if found, or helpful message if not

• mcp_nixos/server.py:1696-1696 (registration)

  Tool registration via FastMCP @mcp.tool() decorator, which registers the function under the name 'nixhub_find_version'.

  @mcp.tool()

• mcp_nixos/server.py:1492-1534 (helper)

  Helper function used by nixhub_find_version to format successful version findings including commit hashes and usage instructions.

  def _format_nixhub_found_version(package_name: str, version: str, found_version: dict[str, Any]) -> str:
      """Format a found version for display."""
      results = []
      results.append(f"✓ Found {package_name} version {version}\n")
  
      last_updated = found_version.get("last_updated", "")
      if last_updated:
          try:
              from datetime import datetime
  
              dt = datetime.fromisoformat(last_updated.replace("Z", "+00:00"))
              formatted_date = dt.strftime("%Y-%m-%d %H:%M UTC")
              results.append(f"Last updated: {formatted_date}")
          except Exception:
              results.append(f"Last updated: {last_updated}")
  
      platforms_summary = found_version.get("platforms_summary", "")
      if platforms_summary:
          results.append(f"Platforms: {platforms_summary}")
  
      # Show commit hashes
      platforms = found_version.get("platforms", [])
      if platforms:
          results.append("\nNixpkgs commits:")
          seen_commits = set()
  
          for platform in platforms:
              attr_path = platform.get("attribute_path", "")
              commit_hash = platform.get("commit_hash", "")
  
              if commit_hash and commit_hash not in seen_commits:
                  seen_commits.add(commit_hash)
                  if re.match(r"^[a-fA-F0-9]{40}$", commit_hash):
                      results.append(f"• {commit_hash}")
                      if attr_path:
                          results.append(f"  Attribute: {attr_path}")
  
      results.append("\nTo use this version:")
      results.append("1. Pin nixpkgs to one of the commit hashes above")
      results.append("2. Install using the attribute path")
  
      return "\n".join(results)

• mcp_nixos/server.py:1466-1489 (helper)

  Utility function to parse and compare version strings for sorting available versions when target not found.

  def _version_key(version_str: str) -> tuple[int, int, int]:
      """Convert version string to tuple for proper sorting."""
      try:
          parts = version_str.split(".")
          # Handle versions like "3.9.9" or "3.10.0-rc1"
          numeric_parts = []
          for part in parts[:3]:  # Major.Minor.Patch
              # Extract numeric part
              numeric = ""
              for char in part:
                  if char.isdigit():
                      numeric += char
                  else:
                      break
              if numeric:
                  numeric_parts.append(int(numeric))
              else:
                  numeric_parts.append(0)
          # Pad with zeros if needed
          while len(numeric_parts) < 3:
              numeric_parts.append(0)
          return (numeric_parts[0], numeric_parts[1], numeric_parts[2])
      except Exception:
          return (0, 0, 0)