Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring
TypeScript diagramhomelabhomelab-infrastructure-observabilitynetworkproxmox-veself-hostedzigbeezwavezwave-js
feat(mcp): readOnly/destructive/openWorld annotations on every tool
Tom Vaisbortaa87d032a97f
diff --git a/FEATURES.md b/FEATURES.mdindex 21d7822..682851f 100644--- a/FEATURES.md+++ b/FEATURES.md@@ -277,7 +277,7 @@ Widget snippet lives in the [README](./README.md#gethomepage-widget-read-only-st2. `docker compose up -d mcp` (listens on `:8001`). No Docker? `sudo bash scripts/lxc-mcp-install.sh`.3. Point your client at `http://<your-homelab-ip>:8001/mcp` with header `X-API-Key: <your key>`.-The AI can list nodes/edges/canvas/zones/designs/inventory/scans, add/update/delete nodes, edges and zones, kick off scans, triage and edit inventory entries, and work a rack canvas — create racks, mount and move gear, patch cables. Keep port 8001 firewalled to your LAN. Full setup in the [README](./README.md#mcp-server-ai-integration-optional).+The AI can list nodes/edges/canvas/zones/designs/inventory/scans, add/update/delete nodes, edges and zones, kick off scans, triage and edit inventory entries, and work a rack canvas — create racks, mount and move gear, patch cables. Every tool carries MCP annotations (`readOnlyHint`, `destructiveHint`, `openWorldHint`), so a client can let reads run freely and ask before a delete or a network scan. Keep port 8001 firewalled to your LAN. Full setup in the [README](./README.md#mcp-server-ai-integration-optional).---diff --git a/mcp/app/annotations.py b/mcp/app/annotations.pynew file mode 100644index 0000000..1e87d45--- /dev/null+++ b/mcp/app/annotations.py@@ -0,0 +1,61 @@+"""MCP tool annotations: readOnlyHint / destructiveHint / openWorldHint.++Clients use these hints to decide what an agent may call without asking:+read-only tools can run freely, destructive ones deserve a confirmation, and+open-world ones reach beyond Homelable's own database (a network scan). Every+tool must be classified here: tests/test_annotations.py fails CI for a tool that+is not, and until it is, annotation_for() serves it the most cautious hints+(and logs a warning) rather than stopping the server from starting.+"""+import logging++from mcp.types import Tool, ToolAnnotations++logger = logging.getLogger(__name__)++READ_ONLY = frozenset({+ "get_scan_config", "list_proxmox_children",+ "search_documentation", "list_documentation", "read_document",+ "list_document_revisions", "read_document_revision", "document_backlinks",+ "list_edges", "get_canvas", "list_nodes", "list_node_summaries", "get_node",+ "list_pending_devices", "list_inventory", "list_hidden_devices",+ "list_zones", "list_designs",+ "list_racks", "get_rack", "list_rack_inventory", "list_faceplates",+})++WRITE = frozenset({+ "create_device", "update_device", "bulk_approve_devices", "bulk_hide_devices",+ "bulk_restore_devices",+ "create_document", "update_document", "restore_document_revision",+ "create_node", "update_node", "create_edge", "update_edge",+ "approve_device", "hide_device", "restore_device",+ "create_zone", "add_to_zone", "remove_from_zone", "create_design",+ "create_rack", "update_rack", "mount_device", "mount_accessory", "move_device",+ "patch_cable",+})++DESTRUCTIVE = frozenset({+ "delete_device", "delete_node", "delete_edge", "delete_design", "delete_rack",+ "unmount_device", "unpatch_cable", "set_device_faceplate", "update_scan_config",+})++# Tools that make the backend touch the network (nmap), not just its database.+OPEN_WORLD = frozenset({"trigger_scan", "rescan_device"})+++def annotation_for(name: str) -> ToolAnnotations:+ if name in READ_ONLY:+ return ToolAnnotations(readOnlyHint=True, destructiveHint=False, openWorldHint=False)+ if name in WRITE:+ return ToolAnnotations(readOnlyHint=False, destructiveHint=False, openWorldHint=False)+ if name in DESTRUCTIVE:+ return ToolAnnotations(readOnlyHint=False, destructiveHint=True, openWorldHint=False)+ if name in OPEN_WORLD:+ return ToolAnnotations(readOnlyHint=False, destructiveHint=False, openWorldHint=True)+ logger.warning("MCP tool %r has no annotation class; serving it as destructive and open-world "+ "until it is added to app/annotations.py", name)+ return ToolAnnotations(readOnlyHint=False, destructiveHint=True, openWorldHint=True)+++def annotate(tools: list[Tool]) -> list[Tool]:+ return [tool.model_copy(update={"annotations": annotation_for(tool.name)}) for tool in tools]diff --git a/mcp/app/tools.py b/mcp/app/tools.pyindex 90d2e75..4142bf6 100644--- a/mcp/app/tools.py+++ b/mcp/app/tools.py@@ -3,6 +3,7 @@ from urllib.parse import quotefrom mcp.server import Serverfrom mcp.types import Tool, TextContentfrom .backend_client import backend, safe_id+from .annotations import annotatefrom .devices import DEVICE_TOOL_NAMES, DEVICE_TOOLS, dispatch_devicefrom .documents import DOC_TOOL_NAMES, DOC_TOOLS, dispatch_documentfrom .racks import RACK_TOOL_NAMES, RACK_TOOLS, dispatch_rack@@ -320,7 +321,7 @@ def _build_tools() -> list[Tool]:# The rack canvas, the inventory write routes and the documentation space live# in their own modules — each is big enough to bury the logical-canvas tools# this file is about.-TOOLS = _build_tools() + RACK_TOOLS + DEVICE_TOOLS + DOC_TOOLS+TOOLS = annotate(_build_tools() + RACK_TOOLS + DEVICE_TOOLS + DOC_TOOLS)def register_tools(server: Server):diff --git a/mcp/tests/test_annotations.py b/mcp/tests/test_annotations.pynew file mode 100644index 0000000..8f0837f--- /dev/null+++ b/mcp/tests/test_annotations.py@@ -0,0 +1,88 @@+"""Every MCP tool is classified once and served with annotations, so clients+can tell read-only tools from destructive ones and from network scans."""+import pytest+from mcp.server import Server+from mcp.types import ListToolsRequest++from app.annotations import DESTRUCTIVE, OPEN_WORLD, READ_ONLY, WRITE, annotation_for+from app.tools import TOOLS, register_tools++CLASSES = {"read_only": READ_ONLY, "write": WRITE, "destructive": DESTRUCTIVE, "open_world": OPEN_WORLD}+++def test_every_tool_is_classified_exactly_once():+ names = [t.name for t in TOOLS]+ assert len(names) == len(set(names))+ for name in names:+ hits = [cls for cls, members in CLASSES.items() if name in members]+ assert len(hits) == 1, f"{name}: {hits}"+++def test_classification_lists_no_unknown_tool():+ names = {t.name for t in TOOLS}+ for cls, members in CLASSES.items():+ assert members <= names, f"{cls} lists unknown tools: {sorted(members - names)}"+++def test_every_tool_carries_all_three_hints():+ for tool in TOOLS:+ a = tool.annotations+ assert a is not None, tool.name+ assert a.readOnlyHint is not None and a.destructiveHint is not None and a.openWorldHint is not None+++def test_deletes_are_destructive():+ for tool in TOOLS:+ if tool.name.startswith("delete_"):+ assert tool.annotations.destructiveHint is True, tool.name+ assert tool.annotations.readOnlyHint is False, tool.name+++def test_list_get_read_search_are_read_only():+ for tool in TOOLS:+ if tool.name.startswith(("list_", "get_", "read_", "search_")):+ assert tool.annotations.readOnlyHint is True, tool.name+ assert tool.annotations.openWorldHint is False, tool.name+++def test_scans_are_open_world_and_not_read_only():+ by_name = {t.name: t for t in TOOLS}+ for name in ("trigger_scan", "rescan_device"):+ assert by_name[name].annotations.openWorldHint is True+ assert by_name[name].annotations.readOnlyHint is False+++def test_scan_config_write_is_destructive():+ assert annotation_for("update_scan_config").destructiveHint is True+++def test_destructive_and_open_world_sets_are_pinned_to_explicit_lists():+ # DESTRUCTIVE and OPEN_WORLD are curated allowlists, not derived+ # from naming conventions (unlike READ_ONLY's list_/get_/read_/search_+ # prefixes above) — pin the exact membership so a future edit to either+ # set is a deliberate, reviewed change, not an accidental drift.+ assert DESTRUCTIVE == {+ "delete_device", "delete_node", "delete_edge", "delete_design", "delete_rack",+ "unmount_device", "unpatch_cable", "set_device_faceplate", "update_scan_config",+ }+ assert OPEN_WORLD == {"trigger_scan", "rescan_device"}+++def test_unclassified_tool_gets_the_most_cautious_hints_and_a_warning(caplog):+ # A tool added without a classification must not stop the server from+ # starting (the partition test above is what fails CI); until it is+ # classified, clients are told to treat it as destructive and open-world.+ with caplog.at_level("WARNING", logger="app.annotations"):+ a = annotation_for("brand_new_tool")+ assert (a.readOnlyHint, a.destructiveHint, a.openWorldHint) == (False, True, True)+ assert "brand_new_tool" in caplog.text+++async def test_tools_list_handler_serves_annotations():+ server = Server("annotations-test")+ register_tools(server)+ result = await server.request_handlers[ListToolsRequest](ListToolsRequest(method="tools/list"))+ served = result.root.tools+ assert len(served) == len(TOOLS)+ assert all(t.annotations is not None for t in served)