Add MCP resource providers for layout, components, pages, and clientside callbacks

Author: KoolADE85

dash/mcp/primitives/resources/__init__.py

@@ -0,0 +1,52 @@
+"""MCP resource listing and read handling.
+
+Each resource module exports:
+- ``URI`` — the URI prefix this module handles
+- ``get_resource() -> Resource | None``
+- ``get_template() -> ResourceTemplate | None``
+- ``read_resource(uri) -> ReadResourceResult``
+
+Dispatch is by prefix match: more specific prefixes must come first.
+"""
+
+from __future__ import annotations
+
+from mcp.types import (
+    ListResourcesResult,
+    ListResourceTemplatesResult,
+    ReadResourceResult,
+)
+
+from . import (
+    resource_clientside_callbacks as _clientside,
+    resource_components as _components,
+    resource_layout as _layout,
+    resource_page_layout as _page_layout,
+    resource_pages as _pages,
+)
+
+_RESOURCE_MODULES = [_layout, _components, _pages, _clientside, _page_layout]
+
+
+def list_resources() -> ListResourcesResult:
+    """Build the MCP resources/list response."""
+    resources = [
+        r for mod in _RESOURCE_MODULES for r in [mod.get_resource()] if r is not None
+    ]
+    return ListResourcesResult(resources=resources)
+
+
+def list_resource_templates() -> ListResourceTemplatesResult:
+    """Build the MCP resources/templates/list response."""
+    templates = [
+        t for mod in _RESOURCE_MODULES for t in [mod.get_template()] if t is not None
+    ]
+    return ListResourceTemplatesResult(resourceTemplates=templates)
+
+
+def read_resource(uri: str) -> ReadResourceResult:
+    """Dispatch a resources/read request by URI prefix match."""
+    for mod in _RESOURCE_MODULES:
+        if uri.startswith(mod.URI):
+            return mod.read_resource(uri)
+    raise ValueError(f"Unknown resource URI: {uri}")

dash/mcp/primitives/resources/resource_clientside_callbacks.py

@@ -0,0 +1,95 @@
+"""Clientside callbacks resource."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from mcp.types import (
+    ReadResourceResult,
+    Resource,
+    ResourceTemplate,
+    TextResourceContents,
+)
+
+from dash import get_app
+from dash._utils import clean_property_name, split_callback_id
+
+URI = "dash://clientside-callbacks"
+
+
+def get_resource() -> Resource | None:
+    if not _get_clientside_callbacks():
+        return None
+    return Resource(
+        uri=URI,
+        name="dash_clientside_callbacks",
+        description=(
+            "Actions the user can take manually in the browser "
+            "to affect clientside state. Inputs describe the "
+            "components that can be changed to trigger an effect. "
+            "Outputs describe the components that will change "
+            "in response."
+        ),
+        mimeType="application/json",
+    )
+
+
+def get_template() -> ResourceTemplate | None:
+    return None
+
+
+def read_resource(uri: str = "") -> ReadResourceResult:
+    data = {
+        "description": (
+            "These are actions that the user can take manually in the "
+            "browser to affect the clientside state. Inputs describe "
+            "the components that can be changed to trigger an effect. "
+            "Outputs describe the components that will change in "
+            "response to the effect."
+        ),
+        "callbacks": _get_clientside_callbacks(),
+    }
+    return ReadResourceResult(
+        contents=[
+            TextResourceContents(
+                uri=URI,
+                mimeType="application/json",
+                text=json.dumps(data, default=str),
+            )
+        ]
+    )
+
+
+def _get_clientside_callbacks() -> list[dict[str, Any]]:
+    """Get input/output mappings for clientside callbacks."""
+    app = get_app()
+    callbacks = []
+    callback_map = getattr(app, "callback_map", {})
+
+    for output_id, callback_info in callback_map.items():
+        if "callback" in callback_info:
+            continue
+        normalize_deps = lambda deps: [
+            {
+                "component_id": str(d.get("id", "unknown")),
+                "property": d.get("property", "unknown"),
+            }
+            for d in deps
+        ]
+        parsed = split_callback_id(output_id)
+        if isinstance(parsed, dict):
+            parsed = [parsed]
+        outputs = [
+            {"component_id": p["id"], "property": clean_property_name(p["property"])}
+            for p in parsed
+        ]
+        callbacks.append(
+            {
+                "outputs": outputs,
+                "inputs": normalize_deps(callback_info.get("inputs", [])),
+                "state": normalize_deps(callback_info.get("state", [])),
+            }
+        )
+
+    return callbacks

dash/mcp/primitives/resources/resource_components.py

@@ -0,0 +1,59 @@
+"""Component list resource."""
+
+from __future__ import annotations
+
+import json
+
+from mcp.types import (
+    ReadResourceResult,
+    Resource,
+    ResourceTemplate,
+    TextResourceContents,
+)
+
+from dash import get_app
+from dash.layout import traverse
+
+URI = "dash://components"
+
+
+def get_resource() -> Resource | None:
+    return Resource(
+        uri=URI,
+        name="dash_components",
+        description=(
+            "All components with IDs in the app layout. "
+            "Use get_dash_component with any of these IDs "
+            "to inspect their properties and values. "
+            "See dash://layout for the tree structure showing "
+            "how these components are nested in the page."
+        ),
+        mimeType="application/json",
+    )
+
+
+def get_template() -> ResourceTemplate | None:
+    return None
+
+
+def read_resource(uri: str = "") -> ReadResourceResult:
+    app = get_app()
+    layout = app.get_layout()
+    components = sorted(
+        [
+            {"id": str(comp.id), "type": getattr(comp, "_type", type(comp).__name__)}
+            for comp, _ in traverse(layout)
+            if getattr(comp, "id", None) is not None
+        ],
+        key=lambda c: c["id"],
+    )
+
+    return ReadResourceResult(
+        contents=[
+            TextResourceContents(
+                uri=URI,
+                mimeType="application/json",
+                text=json.dumps(components),
+            )
+        ]
+    )

dash/mcp/primitives/resources/resource_layout.py

@@ -0,0 +1,44 @@
+"""Layout tree resource for the whole app."""
+
+from __future__ import annotations
+
+from mcp.types import (
+    ReadResourceResult,
+    Resource,
+    ResourceTemplate,
+    TextResourceContents,
+)
+
+from dash import get_app
+from dash._utils import to_json
+
+URI = "dash://layout"
+
+
+def get_resource() -> Resource | None:
+    return Resource(
+        uri=URI,
+        name="dash_app_layout",
+        description=(
+            "Full component tree of the Dash app. "
+            "See dash://components for a compact list of component IDs."
+        ),
+        mimeType="application/json",
+    )
+
+
+def get_template() -> ResourceTemplate | None:
+    return None
+
+
+def read_resource(uri: str = "") -> ReadResourceResult:
+    app = get_app()
+    return ReadResourceResult(
+        contents=[
+            TextResourceContents(
+                uri=URI,
+                mimeType="application/json",
+                text=to_json(app.get_layout()),
+            )
+        ]
+    )

dash/mcp/primitives/resources/resource_page_layout.py

@@ -0,0 +1,77 @@
+"""Per-page layout resource template for multi-page apps."""
+
+from __future__ import annotations
+
+from mcp.types import (
+    ReadResourceResult,
+    Resource,
+    ResourceTemplate,
+    TextResourceContents,
+)
+
+from dash._utils import to_json
+
+URI = "dash://page-layout/"
+_URI_TEMPLATE = "dash://page-layout/{path}"
+
+
+def get_resource() -> Resource | None:
+    return None
+
+
+def get_template() -> ResourceTemplate | None:
+    if not _has_pages():
+        return None
+    return ResourceTemplate(
+        uriTemplate=_URI_TEMPLATE,
+        name="dash_page_layout",
+        description="Component tree for a specific page in the app.",
+        mimeType="application/json",
+    )
+
+
+def read_resource(uri: str) -> ReadResourceResult:
+    path = uri[len(URI) :]
+    if not path.startswith("/"):
+        path = "/" + path
+
+    try:
+        from dash._pages import PAGE_REGISTRY
+    except ImportError:
+        raise ValueError("Dash Pages is not available.")
+
+    page_layout = None
+    for _module, page in PAGE_REGISTRY.items():
+        if page.get("path") == path:
+            page_layout = page.get("layout")
+            break
+
+    if page_layout is None:
+        raise ValueError(f"Page not found: {path}")
+
+    if callable(page_layout):
+        page_layout = page_layout()
+
+    if isinstance(page_layout, (list, tuple)):
+        from dash import html
+
+        page_layout = html.Div(list(page_layout))
+
+    return ReadResourceResult(
+        contents=[
+            TextResourceContents(
+                uri=uri,
+                mimeType="application/json",
+                text=to_json(page_layout),
+            )
+        ]
+    )
+
+
+def _has_pages() -> bool:
+    try:
+        from dash._pages import PAGE_REGISTRY
+
+        return bool(PAGE_REGISTRY)
+    except ImportError:
+        return False