Skip to content

Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring

8.7 KB
Raw Blame
"""Device Inventory write tools.

The inventory (`device_inventory`) is what a scan finds plus what the user
documents by hand. `tools.py` already reads and triages it; these are the write
routes behind the inventory UI — create, edit, delete, the bulk actions, the
per-device deep rescan and the scan configuration.
"""

from typing import Any

from mcp.types import Tool

from .backend_client import backend, safe_id

# Fields shared by create and update, mirroring InventoryDeviceCreate /
# InventoryDeviceUpdate (backend/app/schemas/scan.py). `_dispatch` forwards args
# verbatim, so anything advertised here is what the backend already validates.
_DEVICE_FIELDS = {
    "ip": {"type": "string"},
    "mac": {"type": "string"},
    "os": {"type": "string"},
    "suggested_type": {"type": "string", "description": "What kind of hardware this is (server, switch, nas, ...). Drives the icon, the filters and the rack faceplate suggestion."},
    "model": {"type": "string"},
    "vendor": {"type": "string"},
    "friendly_name": {"type": "string", "description": "Display name, preferred over the hostname everywhere the device is listed."},
    "device_subtype": {"type": "string"},
    "label": {"type": "string"},
    "type": {"type": "string"},
    "notes": {"type": "string"},
    "services": {"type": "array", "items": {"type": "object"}, "description": "Services running on the device: [{port, protocol, service_name, category}]."},
    # Same shape as a node's: `key` is the identity the backend merges on.
    "properties": {"type": "array", "items": {"type": "object"}, "description": "Key/value metadata: [{key, value, icon, visible}]. `key` is required — keyless properties collapse into one."},
    "cpu_count": {"type": "integer"},
    "cpu_model": {"type": "string"},
    "ram_gb": {"type": "number"},
    "disk_gb": {"type": "number"},
    "show_hardware": {"type": "boolean"},
    "check_method": {"type": "string", "description": "Status check method (ping, http, https, ssh, prometheus, tcp)."},
    "check_target": {"type": "string"},
}

# The front panel the device wears in every rack. Editable from the inventory as
# well as from a rack canvas; sending `rack_faceplate_id` is what models a device.
_RACK_MODEL_FIELDS = {
    "rack_faceplate_id": {"type": "string", "description": "Faceplate the device wears in a rack. Call list_faceplates for ids."},
    "rack_u_height": {"type": "integer"},
    "rack_col_span": {"type": "integer"},
    "rack_color": {"type": "string"},
    "rack_ports": {"type": "array", "items": {"type": "object"}, "description": "Ports on the faceplate: [{id, label, type, x, y}]."},
}

DEVICE_TOOLS = [
    Tool(name="create_device", description="Add hardware to the Device Inventory by hand — a dumb switch, a patch panel, a machine no scan can reach. Merges into the existing entry when the ip or mac is already known.", inputSchema={
        "type": "object",
        "required": ["hostname"],
        "properties": {
            "hostname": {"type": "string", "description": "Host name, or any name when the device has none."},
            "discovery_source": {"type": "string", "enum": ["manual", "rack"], "default": "manual", "description": "'rack' marks a placeholder created for a rack plate; it can never be approved onto a logical canvas."},
            **_DEVICE_FIELDS,
        },
    }),
    Tool(name="update_device", description="Edit an inventory entry: the device facts and its rack faceplate. Only the fields sent are applied. Lifecycle (pending/approved/hidden) is owned by the approve/hide/restore tools.", inputSchema={
        "type": "object",
        "required": ["id"],
        "properties": {
            "id": {"type": "string"},
            "hostname": {"type": "string"},
            **_DEVICE_FIELDS,
            **_RACK_MODEL_FIELDS,
        },
    }),
    Tool(name="delete_device", description="Delete an inventory entry outright. A canvas node drawing it survives with its link cleared; use hide_device instead to keep the entry out of the way without losing it.", inputSchema={
        "type": "object",
        "required": ["id"],
        "properties": {"id": {"type": "string"}},
    }),
    Tool(name="bulk_approve_devices", description="Approve several discovered devices at once, creating a node for each on the target canvas. Devices created from a rack are skipped — they never go on a logical canvas.", inputSchema={
        "type": "object",
        "required": ["device_ids"],
        "properties": {
            "device_ids": {"type": "array", "items": {"type": "string"}},
            "design_id": {"type": "string", "description": "Canvas the nodes land on. Omit for the default (first) canvas."},
        },
    }),
    Tool(name="bulk_hide_devices", description="Hide several pending devices at once, taking them out of the inventory listing.", inputSchema={
        "type": "object",
        "required": ["device_ids"],
        "properties": {"device_ids": {"type": "array", "items": {"type": "string"}}},
    }),
    Tool(name="bulk_restore_devices", description="Un-hide several devices at once, returning them to pending.", inputSchema={
        "type": "object",
        "required": ["device_ids"],
        "properties": {"device_ids": {"type": "array", "items": {"type": "string"}}},
    }),
    Tool(name="rescan_device", description="Deep-rescan one known device to refresh its services. Sweeps every TCP port by default, which is slow; recorded as a scan run like any other.", inputSchema={
        "type": "object",
        "required": ["id"],
        "properties": {
            "id": {"type": "string"},
            "full_ports": {"type": "boolean", "default": True, "description": "Sweep all 65535 TCP ports."},
            "ports": {"type": "string", "description": "Narrow the sweep, e.g. '80,443' or '1-1024'. Wins over full_ports."},
            "http_probe_enabled": {"type": "boolean", "description": "Probe HTTP(S) services for banners and titles."},
            "verify_tls": {"type": "boolean"},
        },
    }),
    Tool(name="list_proxmox_children", description="Inventory entries for the VMs and containers a Proxmox host runs. Empty for anything that is not a host.", inputSchema={
        "type": "object",
        "required": ["id"],
        "properties": {"id": {"type": "string", "description": "Inventory id of the Proxmox host."}},
    }),
    Tool(name="get_scan_config", description="The persisted scan defaults: the ranges swept, and the HTTP probe settings.", inputSchema={
        "type": "object",
        "properties": {},
    }),
    Tool(name="update_scan_config", description="Replace the persisted scan defaults. `ranges` is the full list, not an addition.", inputSchema={
        "type": "object",
        "required": ["ranges"],
        "properties": {
            "ranges": {"type": "array", "items": {"type": "string"}, "description": "CIDR ranges to sweep, e.g. ['192.168.1.0/24']."},
            "http_ranges": {"type": "array", "items": {"type": "string"}, "description": "Port ranges probed for HTTP, e.g. ['80,443', '8000-8100']."},
            "http_probe_enabled": {"type": "boolean"},
            "verify_tls": {"type": "boolean"},
        },
    }),
]

DEVICE_TOOL_NAMES = {tool.name for tool in DEVICE_TOOLS}


async def dispatch_device(name: str, args: dict) -> Any:
    if name == "create_device":
        return await backend.post("/api/v1/scan/pending", args)

    if name == "update_device":
        body = {k: v for k, v in args.items() if k != "id"}
        return await backend.patch(f"/api/v1/scan/pending/{safe_id(args['id'], field='device id')}", body)

    if name == "delete_device":
        return await backend.delete(f"/api/v1/scan/pending/{safe_id(args['id'], field='device id')}")

    if name == "bulk_approve_devices":
        approval: dict[str, Any] = {"device_ids": args["device_ids"]}
        if args.get("design_id"):
            approval["design_id"] = args["design_id"]
        return await backend.post("/api/v1/scan/pending/bulk-approve", approval)

    if name == "bulk_hide_devices":
        return await backend.post("/api/v1/scan/pending/bulk-hide", {"device_ids": args["device_ids"]})

    if name == "bulk_restore_devices":
        return await backend.post("/api/v1/scan/pending/bulk-restore", {"device_ids": args["device_ids"]})

    if name == "rescan_device":
        options = {k: v for k, v in args.items() if k != "id"}
        return await backend.post(f"/api/v1/scan/pending/{safe_id(args['id'], field='device id')}/rescan", options)

    if name == "list_proxmox_children":
        return await backend.get(f"/api/v1/scan/pending/{safe_id(args['id'], field='device id')}/proxmox-children")

    if name == "get_scan_config":
        return await backend.get("/api/v1/scan/config")

    if name == "update_scan_config":
        return await backend.post("/api/v1/scan/config", args)

    raise ValueError(f"Unknown device tool: {name}")