Skip to content

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

9.6 KB
Raw Blame
"""Documentation tools.

The documentation space (`documents`) is the homelab written down: one markdown
document per Device Inventory row, per canvas, per piece of canvas furniture,
plus a Library tree of free pages and folders. The body is the source of truth —
frontmatter and tags are derived from it — so every write here sends a body and
lets the backend re-derive the rest.

Reading is meant to be cheap: `search_documentation` is the entry point,
`list_documentation` returns summaries with no bodies, and only `read_document`
pays for a full body.
"""

from typing import Any
from urllib.parse import urlencode

from mcp.types import Tool

from .backend_client import backend, safe_id

# Kept in sync with DOCUMENT_KINDS (backend/app/services/doc_tree.py), which is
# itself the DocKind union in frontend/src/documentation/types.ts.
DOC_KINDS = ["device", "node", "design", "page", "folder"]

# Filters `GET /api/v1/documents` understands. Anything else in the args is a
# tool argument the backend has no query parameter for, and is dropped.
_LIST_FILTERS = ("kind", "parent_id", "device_id", "tag")

# Kept in sync with TEMPLATE_IDS (backend/app/services/doc_template.py).
# "device" is the only one that reads the live inventory facts; the rest are
# empty skeletons of headings.
DOC_TEMPLATES = [
    "device",
    "blank",
    "runbook",
    "service",
    "network",
    "incident",
    "procedure",
    "decision",
    "zone",
]

# What the history records for anything written through this server. Not a tool
# argument: an AI client cannot sign its edits as a human's.
_MCP_REASON = "mcp"

DOC_TOOLS = [
    Tool(name="search_documentation", description="Full-text search across every document, returning a snippet per hit. The first thing to call when the question is 'what do we know about X' — cheaper than listing and reading documents. `engine` is 'fts5', or 'like' on a SQLite build without FTS5, where snippets are unhighlighted.", inputSchema={
        "type": "object",
        "required": ["q"],
        "properties": {
            "q": {"type": "string", "description": "Query text. FTS5 syntax (AND, OR, \"quoted phrase\", prefix*) when the engine is fts5."},
            "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 25},
        },
    }),
    Tool(name="list_documentation", description="List documents as summaries — id, kind, title, tags, frontmatter, drift and review dates, never a body. Use it to find what exists; call read_document for the text.", inputSchema={
        "type": "object",
        "properties": {
            "kind": {"type": "string", "enum": DOC_KINDS, "description": "'device'/'node'/'design' describe one thing elsewhere in the app; 'page'/'folder' live in the Library tree."},
            "parent_id": {"type": "string", "description": "Library children of this folder."},
            "device_id": {"type": "string", "description": "The document describing this inventory device."},
            "tag": {"type": "string", "description": "Documents carrying this frontmatter tag."},
        },
    }),
    Tool(name="read_document", description="One document in full: its markdown body, frontmatter, tags, and the facts snapshot it was written against.", inputSchema={
        "type": "object",
        "required": ["id"],
        "properties": {"id": {"type": "string", "description": "Document id. Call search_documentation or list_documentation to discover ids."}},
    }),
    Tool(name="list_document_revisions", description="The edit history of one document, newest first: who caused each revision ('edit' a human in the editor, 'mcp' an AI client, 'restore', 'regenerate', 'scaffold', 'migrate') and how big the body was. Bodies are not included — read_document_revision fetches one.", inputSchema={
        "type": "object",
        "required": ["document_id"],
        "properties": {"document_id": {"type": "string"}},
    }),
    Tool(name="read_document_revision", description="The body a document had at one point in its history. Pair it with read_document to see what an edit changed.", inputSchema={
        "type": "object",
        "required": ["revision_id"],
        "properties": {"revision_id": {"type": "string", "description": "Revision id, from list_document_revisions."}},
    }),
    Tool(name="document_backlinks", description="The documents linking to this one with [[wiki links]], and the line each link sits on. Inverted server-side, so it finds links a document does not know it has received.", inputSchema={
        "type": "object",
        "required": ["document_id"],
        "properties": {"document_id": {"type": "string"}},
    }),
    Tool(name="create_document", description="Write a new document. Send a body to write it outright, or a template_id to scaffold one from headings. A device/node/design document must name the thing it describes; a page or folder may name a parent folder.", inputSchema={
        "type": "object",
        "required": ["title"],
        "properties": {
            "title": {"type": "string"},
            "kind": {"type": "string", "enum": DOC_KINDS, "default": "page"},
            "body": {"type": "string", "description": "Markdown, optionally opening with a `---` frontmatter block. Wins over template_id."},
            "icon": {"type": "string"},
            "parent_id": {"type": "string", "description": "Library folder this page or folder is filed under."},
            "device_id": {"type": "string", "description": "Inventory device this document describes (kind 'device')."},
            "node_id": {"type": "string", "description": "Canvas node this document describes (kind 'node')."},
            "design_id": {"type": "string", "description": "Canvas this document describes (kind 'design')."},
            "template_id": {"type": "string", "enum": DOC_TEMPLATES, "description": "Scaffold the body from this template when no body is sent. 'device' is implied for a device document and is the only one that reads the live facts."},
        },
    }),
    Tool(name="update_document", description="Edit a document. Only the fields sent are applied. Changing the body snapshots the previous one into the history first, tagged as an AI edit, so nothing written here is lost and a human can restore what was there before.", inputSchema={
        "type": "object",
        "required": ["id"],
        "properties": {
            "id": {"type": "string"},
            "body": {"type": "string", "description": "The full replacement body — not a patch. Read the document first and send it back edited, or the rest of it is dropped."},
            "title": {"type": "string", "description": "Renames the document. A `title:` in the body's frontmatter does the same and is the way the UI does it."},
            "icon": {"type": "string"},
            "parent_id": {"type": "string", "description": "Refile a page or folder under another folder."},
            "sort_order": {"type": "integer"},
            "starred": {"type": "boolean"},
            "reviewed": {"type": "boolean", "description": "Records 'I have re-read this and it is still true' at the server's clock."},
            "resync_facts": {"type": "boolean", "description": "Accept the device's current facts as documented, clearing the drift banner without touching the body."},
        },
    }),
    Tool(name="restore_document_revision", description="Put an earlier body back. The body being replaced becomes history too, so a restore is itself undoable.", inputSchema={
        "type": "object",
        "required": ["document_id", "revision_id"],
        "properties": {
            "document_id": {"type": "string"},
            "revision_id": {"type": "string", "description": "From list_document_revisions."},
        },
    }),
]

DOC_TOOL_NAMES = {tool.name for tool in DOC_TOOLS}


async def dispatch_document(name: str, args: dict) -> Any:
    if name == "search_documentation":
        query: dict[str, Any] = {"q": args["q"]}
        if args.get("limit"):
            query["limit"] = args["limit"]
        return await backend.get(f"/api/v1/documents/search?{urlencode(query)}")

    if name == "list_documentation":
        filters = {k: args[k] for k in _LIST_FILTERS if args.get(k)}
        path = "/api/v1/documents"
        if filters:
            path += f"?{urlencode(filters)}"
        return await backend.get(path)

    if name == "read_document":
        return await backend.get(f"/api/v1/documents/{safe_id(args['id'], field='document id')}")

    if name == "list_document_revisions":
        return await backend.get(f"/api/v1/documents/{safe_id(args['document_id'], field='document id')}/revisions")

    if name == "read_document_revision":
        return await backend.get(f"/api/v1/documents/revisions/{safe_id(args['revision_id'], field='revision id')}")

    if name == "document_backlinks":
        return await backend.get(f"/api/v1/documents/{safe_id(args['document_id'], field='document id')}/backlinks")

    if name == "create_document":
        return await backend.post("/api/v1/documents", args)

    if name == "update_document":
        body = {k: v for k, v in args.items() if k not in ("id", "revision_reason")}
        # Every body this server writes is attributed to it, whatever the
        # client asked for. The backend ignores the reason when the body is
        # unchanged, so a starred flag still snapshots nothing.
        body["revision_reason"] = _MCP_REASON
        return await backend.patch(f"/api/v1/documents/{safe_id(args['id'], field='document id')}", body)

    if name == "restore_document_revision":
        path = f"/api/v1/documents/{safe_id(args['document_id'], field='document id')}/revisions/{safe_id(args['revision_id'], field='revision id')}/restore"
        return await backend.post(path, {})

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