Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring
TypeScript diagramhomelabhomelab-infrastructure-observabilitynetworkproxmox-veself-hostedzigbeezwavezwave-js
feat(mcp): expose full node schema in create_node/update_node (#174)
Pouzor23a0a47a7fb4
diff --git a/mcp/app/tools.py b/mcp/app/tools.pyindex b9b934c..dbddb27 100644--- a/mcp/app/tools.py+++ b/mcp/app/tools.py@@ -4,87 +4,133 @@ from mcp.types import Tool, TextContentfrom .backend_client import backend+NODE_TYPES = ["isp", "router", "switch", "server", "proxmox", "vm", "lxc", "nas", "iot", "ap", "generic"]++# Shared field schemas mirroring backend NodeBase / NodeUpdate (backend/app/schemas/nodes.py).+# create_node and update_node both expose these so the MCP is symmetric with what the+# backend already validates and stores. _dispatch forwards args verbatim, so any field+# advertised here is accepted by the backend.+_NODE_FIELDS = {+ "label": {"type": "string"},+ "ip": {"type": "string"},+ "hostname": {"type": "string"},+ "mac": {"type": "string", "description": "MAC address."},+ "os": {"type": "string", "description": "Operating system / distribution."},+ "status": {"type": "string", "enum": ["online", "offline", "unknown", "pending"]},+ "check_method": {"type": "string", "description": "Status check method (ping, http, https, ssh, prometheus, tcp)."},+ "check_target": {"type": "string", "description": "Target host/URL used by the status check."},+ "services": {"type": "array", "items": {"type": "object"}, "description": "Running services detected or documented on the node."},+ "notes": {"type": "string", "description": "Free-text notes / documentation for the node."},+ "parent_id": {"type": "string", "description": "ID of the parent node (e.g. Proxmox host for a VM/LXC). Pass null to detach."},+ "container_mode": {"type": "boolean", "description": "Render this node as a container/group that can hold children."},+ "custom_icon": {"type": "string", "description": "Override icon name for the node."},+ "cpu_count": {"type": "integer", "description": "Number of CPU cores/threads."},+ "cpu_model": {"type": "string", "description": "CPU model name."},+ "ram_gb": {"type": "number", "description": "RAM in gigabytes."},+ "disk_gb": {"type": "number", "description": "Disk capacity in gigabytes."},+ "show_hardware": {"type": "boolean", "description": "Display hardware specs on the node card."},+ "properties": {+ "type": "array",+ "description": "Arbitrary key/value metadata shown on the node.",+ "items": {+ "type": "object",+ "required": ["name", "value"],+ "properties": {+ "name": {"type": "string"},+ "value": {"type": "string"},+ },+ },+ },+}+++def _build_tools() -> list[Tool]:+ create_node_props = {+ "type": {"type": "string", "enum": NODE_TYPES},+ **_NODE_FIELDS,+ }+ create_node_props["status"] = {**_NODE_FIELDS["status"], "default": "unknown"}++ update_node_props = {+ "id": {"type": "string"},+ "type": {"type": "string", "enum": NODE_TYPES},+ **_NODE_FIELDS,+ }++ return [+ Tool(name="create_node", description="Add a new node to the homelab canvas", inputSchema={+ "type": "object",+ "required": ["type", "label"],+ "properties": create_node_props,+ }),+ Tool(name="update_node", description="Update an existing node", inputSchema={+ "type": "object",+ "required": ["id"],+ "properties": update_node_props,+ }),+ Tool(name="delete_node", description="Delete a node from the canvas", inputSchema={+ "type": "object",+ "required": ["id"],+ "properties": {"id": {"type": "string"}},+ }),+ Tool(name="create_edge", description="Create a network link between two nodes", inputSchema={+ "type": "object",+ "required": ["source", "target"],+ "properties": {+ "source": {"type": "string"},+ "target": {"type": "string"},+ "type": {"type": "string", "enum": ["ethernet", "wifi", "iot", "vlan", "virtual"], "default": "ethernet"},+ "label": {"type": "string"},+ },+ }),+ Tool(name="delete_edge", description="Delete a network link", inputSchema={+ "type": "object",+ "required": ["id"],+ "properties": {"id": {"type": "string"}},+ }),+ Tool(name="trigger_scan", description="Trigger a network discovery scan", inputSchema={+ "type": "object",+ "properties": {+ "ranges": {"type": "array", "items": {"type": "string"}, "description": "CIDR ranges to scan (uses configured defaults if omitted)"},+ },+ }),+ Tool(name="approve_device", description="Approve a pending discovered device and create a node", inputSchema={+ "type": "object",+ "required": ["id"],+ "properties": {+ "id": {"type": "string"},+ "type": {"type": "string", "enum": NODE_TYPES, "default": "generic"},+ "label": {"type": "string"},+ },+ }),+ Tool(name="hide_device", description="Hide a pending discovered device", inputSchema={+ "type": "object",+ "required": ["id"],+ "properties": {"id": {"type": "string"}},+ }),+ Tool(name="get_canvas", description="Get the full canvas: all nodes and edges in the homelab topology", inputSchema={+ "type": "object",+ "properties": {},+ }),+ Tool(name="list_nodes", description="List all nodes (devices) in the homelab", inputSchema={+ "type": "object",+ "properties": {},+ }),+ Tool(name="list_pending_devices", description="List devices discovered by scan but not yet approved or hidden", inputSchema={+ "type": "object",+ "properties": {},+ }),+ ]+++TOOLS = _build_tools()++def register_tools(server: Server):@server.list_tools()async def list_tools():- return [- Tool(name="create_node", description="Add a new node to the homelab canvas", inputSchema={- "type": "object",- "required": ["type", "label"],- "properties": {- "type": {"type": "string", "enum": ["isp","router","switch","server","proxmox","vm","lxc","nas","iot","ap","generic"]},- "label": {"type": "string"},- "ip": {"type": "string"},- "hostname": {"type": "string"},- "status": {"type": "string", "enum": ["online","offline","unknown","pending"], "default": "unknown"},- },- }),- Tool(name="update_node", description="Update an existing node", inputSchema={- "type": "object",- "required": ["id"],- "properties": {- "id": {"type": "string"},- "label": {"type": "string"},- "ip": {"type": "string"},- "hostname": {"type": "string"},- "status": {"type": "string"},- "parent_id": {"type": "string", "description": "ID of the parent node (e.g. Proxmox host for a VM/LXC). Pass null to detach."},- },- }),- Tool(name="delete_node", description="Delete a node from the canvas", inputSchema={- "type": "object",- "required": ["id"],- "properties": {"id": {"type": "string"}},- }),- Tool(name="create_edge", description="Create a network link between two nodes", inputSchema={- "type": "object",- "required": ["source", "target"],- "properties": {- "source": {"type": "string"},- "target": {"type": "string"},- "type": {"type": "string", "enum": ["ethernet","wifi","iot","vlan","virtual"], "default": "ethernet"},- "label": {"type": "string"},- },- }),- Tool(name="delete_edge", description="Delete a network link", inputSchema={- "type": "object",- "required": ["id"],- "properties": {"id": {"type": "string"}},- }),- Tool(name="trigger_scan", description="Trigger a network discovery scan", inputSchema={- "type": "object",- "properties": {- "ranges": {"type": "array", "items": {"type": "string"}, "description": "CIDR ranges to scan (uses configured defaults if omitted)"},- },- }),- Tool(name="approve_device", description="Approve a pending discovered device and create a node", inputSchema={- "type": "object",- "required": ["id"],- "properties": {- "id": {"type": "string"},- "type": {"type": "string", "enum": ["isp","router","switch","server","proxmox","vm","lxc","nas","iot","ap","generic"], "default": "generic"},- "label": {"type": "string"},- },- }),- Tool(name="hide_device", description="Hide a pending discovered device", inputSchema={- "type": "object",- "required": ["id"],- "properties": {"id": {"type": "string"}},- }),- Tool(name="get_canvas", description="Get the full canvas: all nodes and edges in the homelab topology", inputSchema={- "type": "object",- "properties": {},- }),- Tool(name="list_nodes", description="List all nodes (devices) in the homelab", inputSchema={- "type": "object",- "properties": {},- }),- Tool(name="list_pending_devices", description="List devices discovered by scan but not yet approved or hidden", inputSchema={- "type": "object",- "properties": {},- }),- ]+ return TOOLS@server.call_tool()async def call_tool(name: str, arguments: dict):@@ -94,7 +140,11 @@ def register_tools(server: Server):def _slim_canvas(raw: dict) -> dict:"""Strip React Flow layout/style fields — keep only semantic data for AI use."""- NODE_KEEP = {"id", "type", "label", "ip", "hostname", "status", "services", "description", "parentId"}+ NODE_KEEP = {+ "id", "type", "label", "ip", "hostname", "mac", "os", "status", "services",+ "notes", "description", "properties", "cpu_count", "cpu_model", "ram_gb",+ "disk_gb", "parentId",+ }EDGE_KEEP = {"id", "source", "target", "type", "label"}def slim_node(n: dict) -> dict:diff --git a/mcp/tests/test_tools.py b/mcp/tests/test_tools.pyindex c0b4bcf..be1f7b3 100644--- a/mcp/tests/test_tools.py+++ b/mcp/tests/test_tools.py@@ -1,6 +1,6 @@import pytestfrom unittest.mock import AsyncMock, patch-from app.tools import _dispatch+from app.tools import TOOLS, _dispatch@pytest.fixture@@ -32,6 +32,39 @@ async def test_update_node_parent_id(mock_backend):mock_backend.patch.assert_called_once_with("/api/v1/nodes/42", {"parent_id": "proxmox-1"})+async def test_create_node_full_properties(mock_backend):+ args = {+ "type": "proxmox",+ "label": "pve1",+ "os": "Proxmox VE 8",+ "notes": "Main hypervisor",+ "services": [{"name": "ssh", "port": 22}],+ "cpu_count": 16,+ "cpu_model": "Ryzen 9 5950X",+ "ram_gb": 64,+ "disk_gb": 2000,+ "show_hardware": True,+ "properties": [{"name": "rack", "value": "A1"}],+ }+ await _dispatch("create_node", dict(args))+ # All extra fields forwarded to the backend unchanged.+ mock_backend.post.assert_called_once_with("/api/v1/nodes", args)+++async def test_update_node_properties(mock_backend):+ await _dispatch("update_node", {+ "id": "42",+ "os": "Debian 12",+ "properties": [{"name": "role", "value": "db"}],+ })+ mock_backend.patch.assert_called_once_with("/api/v1/nodes/42", {+ "os": "Debian 12",+ "properties": [{"name": "role", "value": "db"}],+ })++@pytest.mark.anyioasync def test_delete_node(mock_backend):await _dispatch("delete_node", {"id": "42"})@@ -100,6 +133,55 @@ async def test_get_canvas(mock_backend):assert "viewport" not in result+async def test_get_canvas_keeps_documentation_fields(mock_backend):+ mock_backend.get = AsyncMock(return_value={+ "nodes": [+ {+ "id": "n1",+ "type": "proxmox",+ "position": {"x": 0, "y": 0},+ "data": {+ "label": "pve1",+ "os": "Proxmox VE 8",+ "notes": "Main hypervisor",+ "cpu_count": 16,+ "ram_gb": 64,+ "properties": [{"name": "rack", "value": "A1"}],+ },+ }+ ],+ "edges": [],+ })+ result = await _dispatch("get_canvas", {})+ node = result["nodes"][0]+ assert node["os"] == "Proxmox VE 8"+ assert node["notes"] == "Main hypervisor"+ assert node["cpu_count"] == 16+ assert node["ram_gb"] == 64+ assert node["properties"] == [{"name": "rack", "value": "A1"}]+++def _tool_schema(name: str) -> dict:+ tool = next(t for t in TOOLS if t.name == name)+ return tool.inputSchema["properties"]+++def test_create_node_schema_exposes_full_node_fields():+ props = _tool_schema("create_node")+ for field in ("os", "notes", "services", "cpu_count", "ram_gb", "disk_gb", "properties", "mac"):+ assert field in props, f"create_node schema missing {field}"+ # type stays an enum of the canonical node types+ assert "enum" in props["type"]+++def test_update_node_schema_exposes_full_node_fields():+ props = _tool_schema("update_node")+ for field in ("os", "notes", "services", "cpu_count", "ram_gb", "disk_gb", "properties", "mac"):+ assert field in props, f"update_node schema missing {field}"+ assert "id" in props++@pytest.mark.anyioasync def test_list_nodes(mock_backend):mock_backend.get = AsyncMock(return_value=[{"id": "1", "label": "Freebox"}])