Homelab MCP Server

// src/tools/scout.ts
import { type ScoutInput, ScoutSchema } from "../schemas/scout/index.js";
import type { ServiceContainer } from "../services/container.js";
import { type HelpInput, handleHelpAction } from "../utils/help-handler.js";
import { handleLogsAction } from "./handlers/scout-logs.js";
import { handleScoutSimpleAction } from "./handlers/scout-simple.js";
import { handleZfsAction } from "./handlers/scout-zfs.js";

/**
 * Handle all Scout tool requests - SSH remote operations.
 *
 * Routes incoming requests to specialized handlers based on action type.
 * Validates input against Scout schema before dispatching.
 *
 * @param input - Unvalidated user input to process
 * @param container - Service container with dependencies
 * @returns Formatted response string (markdown or JSON)
 * @throws {Error} When validation fails or action is unknown
 *
 * @example
 * ```typescript
 * const result = await handleScoutTool(
 *   { action: 'peek', target: 'host1:/etc/hosts' },
 *   container
 * );
 * ```
 */
export async function handleScoutTool(
  input: unknown,
  container: ServiceContainer
): Promise<string> {
  // Validate input against Scout schema
  const validated = ScoutSchema.parse(input) as ScoutInput;

  // Route to appropriate handler based on action
  switch (validated.action) {
    case "help":
      return handleHelpAction(validated as HelpInput, ScoutSchema);

    // Simple actions (9) - handled by scout-simple handler
    case "nodes":
    case "peek":
    case "exec":
    case "find":
    case "delta":
    case "emit":
    case "beam":
    case "ps":
    case "df":
      return handleScoutSimpleAction(validated, container);

    // Nested actions with subactions
    case "zfs":
      return handleZfsAction(validated, container);
    case "logs":
      return handleLogsAction(validated, container);
    default:
      // Zod validation should prevent reaching here
      throw new Error(`Unknown action: ${(validated as { action: string }).action}`);
  }
}