Homelab MCP Server

/**
 * Flux tool definition
 *
 * Docker infrastructure management tool for containers, compose, images, and hosts.
 */

import { FluxSchema } from "../../schemas/flux/index.js";
import { handleFluxTool } from "../flux.js";
import type { ToolDefinition } from "../registry.js";

/**
 * Flux tool - Docker infrastructure management
 *
 * Supports: container, compose, docker, and host operations
 */
export const FluxTool: ToolDefinition = {
  name: "flux",
  title: "Flux Tool",
  description: `Docker infrastructure management - container, compose, docker, and host operations

HOW TO USE:
{
  "action": "container",                   // Required: action family
  "subaction": "list",                     // Required: operation within action
  "host": "hostname",                      // Optional: target specific host
  "response_format": "markdown",           // Optional: markdown (default) or json
  "force": true                            // Required for destructive operations (⚠️)
}

Examples:
  • List containers: {"action": "container", "subaction": "list"}
  • Stop container: {"action": "container", "subaction": "stop", "container_id": "container-id"}
  • Docker info: {"action": "docker", "subaction": "info", "host": "myhost"}
  • Help: {"action": "help"}

FLUX OPERATIONS:

Container (14 operations)
  ●  exec       - Execute command in running container
  ●  inspect    - Detailed container information
  ●  list       - List containers across all hosts
  ●  logs       - Container logs with streaming
  ●  pause      - Pause container execution
  ●  pull       - Pull latest image for a container
  ⚠️  recreate   - Recreate a container
  ●  restart    - Restart one or more containers
  ●  resume     - Resume paused container
  ●  search     - Search containers across hosts
  ●  start      - Start stopped containers
  ●  stats      - Container resource usage statistics
  ●  stop       - Stop running containers
  ●  top        - Display running processes in container

Compose (10 operations)
  ●  build      - Build compose project images
  ⚠️  down       - Stop compose project
  ●  list       - List compose projects across all hosts
  ●  logs       - View compose project logs
  ●  pull       - Pull compose project images
  ●  refresh    - Refresh compose project discovery cache
  ⚠️  recreate   - Recreate compose containers
  ●  restart    - Restart compose services
  ●  status     - Show compose project status
  ●  up         - Create and start compose services

Docker (9 operations)
  ⚠️  build      - Build image from Dockerfile
  ●  df         - Show docker disk usage
  ●  images     - List images across all hosts
  ●  info       - Display system-wide information
  ●  networks   - List networks across all hosts
  ●  pull       - Pull a Docker image
  ⚠️  prune      - Remove unused Docker objects
  ⚠️  rmi        - Remove one or more images
  ●  volumes    - List volumes across all hosts

Host (9 operations)
  ✓  doctor     - Run diagnostic checks
  ✓  info       - Host system information
  ●  mounts     - List filesystem mounts
  ●  network    - Network interface details
  ●  ports      - List and filter host/container port mappings
  ●  resources  - CPU, memory, and disk usage
  ●  services   - List systemd services
  ✓  status     - Quick host health check
  ●  uptime     - System uptime and load

Help (1 operation)
  ●  help       - Show available operations

Legend:
  ● State-changing operation
  ⚠️ Destructive operation (requires force: true)
  ✓ Diagnostic/health check`,
  inputSchema: FluxSchema,
  annotations: {
    readOnlyHint: false,
    destructiveHint: true, // Can prune containers, remove images, recreate containers
    idempotentHint: false,
    openWorldHint: true,
  },
  handler: handleFluxTool,
};