optimize_mirrors

Instructions

Implementation Reference

• src/arch_ops_server/mirrors.py:399-509 (handler)

  The main handler function for the optimize_mirrors tool. It dispatches to sub-actions: 'status' (list mirrors), 'test' (test mirror speed), 'suggest' (get recommendations), and 'health' (full health check). Uses helper functions list_active_mirrors, test_mirror_speed, suggest_fastest_mirrors, check_mirrorlist_health.

  async def optimize_mirrors(
      action: str = "status",
      country: Optional[str] = None,
      mirror_url: Optional[str] = None,
      limit: int = 10,
      auto_test: bool = False
  ) -> Dict[str, Any]:
      """
      Smart mirror management tool that consolidates 4 mirror operations.
  
      Args:
          action: Operation to perform - "status" (list mirrors), "test" (test speed),
                  "suggest" (get recommendations), or "health" (full health check)
          country: Optional country code for suggestions (e.g., 'US', 'DE')
          mirror_url: Specific mirror URL to test (action="test" only)
          limit: Number of mirrors for suggestions (default 10)
          auto_test: If True, automatically test mirrors after listing (action="status" only)
  
      Returns:
          Dict with results based on action:
          - "status": Current mirror configuration with optional test results
          - "test": Speed test results for specified or all mirrors
          - "suggest": Recommended mirrors from archlinux.org
          - "health": Comprehensive health assessment with issues and recommendations
  
      Examples:
          # Check current mirror configuration
          optimize_mirrors(action="status")
  
          # Test specific mirror
          optimize_mirrors(action="test", mirror_url="https://mirror.example.com")
  
          # Get top 10 fastest mirrors for US
          optimize_mirrors(action="suggest", country="US", limit=10)
  
          # Full health check
          optimize_mirrors(action="health")
  
          # List mirrors and auto-test them
          optimize_mirrors(action="status", auto_test=True)
      """
      logger.info(f"Optimizing mirrors: action={action}, country={country}, auto_test={auto_test}")
  
      try:
          if action == "status":
              # Get current mirror configuration
              result = await list_active_mirrors()
              if "error" in result:
                  return result
  
              response = {
                  "action": "status",
                  "configuration": result
              }
  
              # Optionally run speed tests
              if auto_test:
                  logger.info("Auto-testing mirror speeds...")
                  test_result = await test_mirror_speed()
                  if "error" not in test_result:
                      response["speed_tests"] = test_result
  
              return response
  
          elif action == "test":
              # Test mirror speeds
              return {
                  "action": "test",
                  "results": await test_mirror_speed(mirror_url=mirror_url)
              }
  
          elif action == "suggest":
              # Get mirror suggestions
              return {
                  "action": "suggest",
                  "recommendations": await suggest_fastest_mirrors(country=country, limit=limit)
              }
  
          elif action == "health":
              # Comprehensive health check
              health_result = await check_mirrorlist_health()
  
              if "error" in health_result:
                  return health_result
  
              # Also get current configuration for context
              config_result = await list_active_mirrors()
              if "error" not in config_result:
                  health_result["configuration"] = {
                      "active_count": config_result.get("active_count", 0),
                      "commented_count": config_result.get("commented_count", 0),
                      "active_mirrors": config_result.get("active_mirrors", [])
                  }
  
              return {
                  "action": "health",
                  "assessment": health_result
              }
  
          else:
              return create_error_response(
                  "InvalidAction",
                  f"Invalid action '{action}'. Must be one of: status, test, suggest, health"
              )
  
      except Exception as e:
          logger.error(f"Mirror optimization failed: {e}")
          return create_error_response(
              "OptimizationError",
              f"Failed to optimize mirrors: {str(e)}"
          )

• src/arch_ops_server/server.py:999-1033 (registration)

  Tool registration in the MCP server via @server.list_tools(). Defines the tool name 'optimize_mirrors', description, inputSchema with 5 parameters (action, country, mirror_url, limit, auto_test), and read-only annotations.

  # Mirror Management Tools
  Tool(
      name="optimize_mirrors",
      description="[MIRRORS] Smart mirror management - consolidates 4 mirror operations. Actions: 'status' (list configured mirrors), 'test' (test mirror speeds), 'suggest' (get optimal mirrors from archlinux.org), 'health' (full health check). Examples: optimize_mirrors(action='status', auto_test=True) lists and tests all mirrors; optimize_mirrors(action='suggest', country='US', limit=5) suggests top 5 US mirrors; optimize_mirrors(action='health') checks for issues and gives recommendations.",
      inputSchema={
          "type": "object",
          "properties": {
              "action": {
                  "type": "string",
                  "enum": ["status", "test", "suggest", "health"],
                  "description": "Operation to perform: 'status' (list mirrors), 'test' (test speeds), 'suggest' (get recommendations), 'health' (full check)"
              },
              "country": {
                  "type": "string",
                  "description": "Optional country code for suggestions (e.g., 'US', 'DE') - action='suggest' only"
              },
              "mirror_url": {
                  "type": "string",
                  "description": "Specific mirror URL to test - action='test' only"
              },
              "limit": {
                  "type": "integer",
                  "description": "Number of mirrors for suggestions (default 10)",
                  "default": 10
              },
              "auto_test": {
                  "type": "boolean",
                  "description": "If true, test mirrors after listing - action='status' only",
                  "default": False
              }
          },
          "required": ["action"]
      },
      annotations=ToolAnnotations(readOnlyHint=True)
  ),

• src/arch_ops_server/server.py:1242-1256 (registration)

  Tool invocation handler in @server.call_tool() that dispatches the 'optimize_mirrors' name to the async handler function, extracting arguments and calling optimize_mirrors().

  elif name == "optimize_mirrors":
      action = arguments.get("action")
      country = arguments.get("country")
      mirror_url = arguments.get("mirror_url")
      limit = arguments.get("limit", 10)
      auto_test = arguments.get("auto_test", False)
      
      result = await optimize_mirrors(
          action=action,
          country=country,
          mirror_url=mirror_url,
          limit=limit,
          auto_test=auto_test
      )
      return [TextContent(type="text", text=json.dumps(result, indent=2))]

• src/arch_ops_server/tool_metadata.py:265-273 (schema)

  ToolMetadata definition for optimize_mirrors. Categorized as 'mirrors', platform 'arch', permission 'read', workflow 'optimize'. Related tools: analyze_pacman_conf, check_disk_space.

  "optimize_mirrors": ToolMetadata(
      name="optimize_mirrors",
      category="mirrors",
      platform="arch",
      permission="read",
      workflow="optimize",
      related_tools=["analyze_pacman_conf", "check_disk_space"],
      prerequisite_tools=[]
  ),

• src/arch_ops_server/__init__.py:61-67 (helper)

  Module export of optimize_mirrors from mirrors.py, making it available as a top-level import.

  from .mirrors import (
      list_active_mirrors,
      test_mirror_speed,
      suggest_fastest_mirrors,
      check_mirrorlist_health,
      optimize_mirrors,
  )