Skip to content

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

feat(mcp): readOnly/destructive/openWorld annotations on every tool

Tom Vaisbortaa87d032a97f
diff --git a/FEATURES.md b/FEATURES.md
index 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-st
2. `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.py
new file mode 100644
index 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.py
index 90d2e75..4142bf6 100644
--- a/mcp/app/tools.py
+++ b/mcp/app/tools.py
@@ -3,6 +3,7 @@ from urllib.parse import quote
from mcp.server import Server
from mcp.types import Tool, TextContent
from .backend_client import backend, safe_id
+from .annotations import annotate
from .devices import DEVICE_TOOL_NAMES, DEVICE_TOOLS, dispatch_device
from .documents import DOC_TOOL_NAMES, DOC_TOOLS, dispatch_document
from .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.py
new file mode 100644
index 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)