suggest_deployments

Instructions

Implementation Reference

• src/homelab_mcp/tool_handlers/network_handlers.py:47-52 (handler)

  The MCP tool handler for 'suggest_deployments'. Creates a NetworkSiteMap, calls sitemap.suggest_deployments(), and returns the suggestions as a JSON-formatted MCP content response.

  async def handle_suggest_deployments(arguments: dict[str, Any]) -> dict[str, Any]:
      """Handle suggest_deployments tool."""
      sitemap = NetworkSiteMap()
      suggestions = sitemap.suggest_deployments()
      result = json.dumps({"status": "success", "suggestions": suggestions}, indent=2)
      return {"content": [{"type": "text", "text": result}]}

• src/homelab_mcp/tool_schemas/network_tools_schema.py:65-67 (schema)

  Schema definition for 'suggest_deployments' tool. Describes it as suggesting optimal deployment locations based on network topology, with no required input parameters.

  "suggest_deployments": {
      "description": "Suggest optimal deployment locations based on current network topology and device capabilities",
      "inputSchema": {"type": "object", "properties": {}, "required": []},

• src/homelab_mcp/tool_handlers/__init__.py:93-93 (registration)

  Registration of 'suggest_deployments' in the TOOL_HANDLERS registry mapping to handle_suggest_deployments.

  "suggest_deployments": handle_suggest_deployments,

• src/homelab_mcp/sitemap.py:353-437 (helper)

  Core business logic for suggest_deployments. Iterates online devices and categorizes them into load_balancer_candidates, database_candidates, monitoring_targets, and upgrade_recommendations based on CPU cores, memory, and disk usage.

  def suggest_deployments(self) -> dict[str, Any]:
      """Suggest optimal deployment locations based on current network state."""
      devices = self.get_all_devices()
      online_devices = [d for d in devices if d["status"] == "success"]
  
      suggestions: dict[str, list[dict[str, str]]] = {
          "load_balancer_candidates": [],
          "database_candidates": [],
          "monitoring_targets": [],
          "upgrade_recommendations": [],
      }
  
      for device in online_devices:
          hostname = device["hostname"]
  
          # Load balancer candidates (high CPU, good memory)
          # Phase 35 D-10/D-13: skip devices with null cpu_cores or memory_total
          # rather than coercing to 0/"" (which produces false negatives here and
          # false positives in the upgrade_recommendations path below).
          if not _has_threshold_data(device, "cpu_cores", "memory_total"):
              logger.debug(
                  "Skipping device %s in deployment suggestion: missing cpu_cores or memory_total",
                  hostname,
              )
          else:
              cpu_cores = device["cpu_cores"]
              if cpu_cores >= 4:
                  memory_gb = self._parse_memory_gb(str(device["memory_total"]))
                  if memory_gb >= 4:
                      suggestions["load_balancer_candidates"].append(
                          {
                              "hostname": hostname,
                              "reason": f"{cpu_cores} cores, {device['memory_total']} RAM",
                          }
                      )
  
          # Database candidates (good disk space, memory)
          if device.get("disk_use_percent"):
              try:
                  disk_usage = int(device["disk_use_percent"].rstrip("%"))
                  if disk_usage < 50:  # Plenty of disk space
                      memory_total = device.get("memory_total")
                      memory_gb = self._parse_memory_gb(str(memory_total) if memory_total else "")
  
                      if memory_gb >= 8:
                          suggestions["database_candidates"].append(
                              {
                                  "hostname": hostname,
                                  "reason": f"Low disk usage ({device['disk_use_percent']}), {device['memory_total']} RAM",
                              }
                          )
              except (ValueError, AttributeError):
                  logger.debug("Skipping device %s for deployment suggestion: unable to parse disk usage", hostname)
  
          # Monitoring targets (all online devices should be monitored)
          suggestions["monitoring_targets"].append(
              {
                  "hostname": hostname,
                  "connection_ip": device["connection_ip"],
                  "os": device.get("os_info", "Unknown"),
              }
          )
  
          # Upgrade recommendations
          # Phase 35 D-10/D-13: skip devices with null cpu_cores or memory_total;
          # prior behavior coerced None -> 0 and flagged every null-cpu device as a
          # low-resource upgrade candidate (false positive).
          if not _has_threshold_data(device, "cpu_cores", "memory_total"):
              logger.debug(
                  "Skipping device %s in upgrade recommendation: missing cpu_cores or memory_total",
                  hostname,
              )
          else:
              cpu_cores = device["cpu_cores"]
              if cpu_cores <= 2:
                  memory_gb = self._parse_memory_gb(str(device["memory_total"]))
                  if memory_gb <= 4:
                      suggestions["upgrade_recommendations"].append(
                          {
                              "hostname": hostname,
                              "reason": f"Limited resources: {cpu_cores} cores, {device['memory_total']} RAM",
                          }
                      )
  
      return suggestions

• src/homelab_mcp/openapi_app.py:42-42 (registration)

  Listed as a standalone tool (works without external infrastructure) in the OpenAPI REST app.

  "suggest_deployments",