MCP Server Part 3: Dash App Resources

dash/mcp/primitives/resources/__init__.py

@@ -0,0 +1,48 @@
+"""MCP resource listing and read handling."""
+
+from __future__ import annotations
+
+from mcp.types import (
+    ListResourcesResult,
+    ListResourceTemplatesResult,
+    ReadResourceResult,
+)
+
+from .base import MCPResourceProvider
+from .resource_clientside_callbacks import ClientsideCallbacksResource
+from .resource_components import ComponentsResource
+from .resource_layout import LayoutResource
+from .resource_page_layout import PageLayoutResource
+from .resource_pages import PagesResource
+
+_RESOURCE_PROVIDERS: list[type[MCPResourceProvider]] = [
+    LayoutResource,
+    ComponentsResource,
+    PagesResource,
+    ClientsideCallbacksResource,
+    PageLayoutResource,
+]
+
+
+def list_resources() -> ListResourcesResult:
+    """Build the MCP resources/list response."""
+    resources = [
+        r for p in _RESOURCE_PROVIDERS for r in [p.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 p in _RESOURCE_PROVIDERS for t in [p.get_template()] if t is not None
+    ]
+    return ListResourceTemplatesResult(resourceTemplates=templates)
+
+
+def read_resource(uri: str) -> ReadResourceResult:
+    """Route a resources/read request by URI prefix match."""
+    for p in _RESOURCE_PROVIDERS:
+        if uri.startswith(p.uri):
+            return p.read_resource(uri)
+    raise ValueError(f"Unknown resource URI: {uri}")

dash/mcp/primitives/resources/base.py

@@ -0,0 +1,28 @@
+"""Base class for MCP resource providers."""
+
+from __future__ import annotations
+
+from mcp.types import ReadResourceResult, Resource, ResourceTemplate
+
+
+class MCPResourceProvider:
+    """Base class for MCP resource providers.
+
+    Subclasses must set ``uri`` and implement ``read_resource``.
+    Override ``get_resource`` and/or ``get_template`` to advertise
+    the resource in ``resources/list`` or ``resources/templates/list``.
+    """
+
+    uri: str
+
+    @classmethod
+    def get_resource(cls) -> Resource | None:
+        return None
+
+    @classmethod
+    def get_template(cls) -> ResourceTemplate | None:
+        return None
+
+    @classmethod
+    def read_resource(cls, uri: str) -> ReadResourceResult:
+        raise NotImplementedError

dash/mcp/primitives/resources/resource_clientside_callbacks.py

@@ -0,0 +1,94 @@
+"""Clientside callbacks resource."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from mcp.types import (
+    ReadResourceResult,
+    Resource,
+    TextResourceContents,
+)
+
+from dash import get_app
+from dash._utils import clean_property_name, split_callback_id
+
+from .base import MCPResourceProvider
+
+
+class ClientsideCallbacksResource(MCPResourceProvider):
+    uri = "dash://clientside-callbacks"
+
+    @classmethod
+    def get_resource(cls) -> Resource | None:
+        if not _get_clientside_callbacks():
+            return None
+        return Resource(
+            uri=cls.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",
+        )
+
+    @classmethod
+    def read_resource(cls, 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=cls.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,58 @@
+"""Component list resource."""
+
+from __future__ import annotations
+
+import json
+
+from mcp.types import (
+    ReadResourceResult,
+    Resource,
+    TextResourceContents,
+)
+
+from dash import get_app
+from dash._layout_utils import traverse
+
+from .base import MCPResourceProvider
+
+
+class ComponentsResource(MCPResourceProvider):
+    uri = "dash://components"
+
+    @classmethod
+    def get_resource(cls) -> Resource | None:
+        return Resource(
+            uri=cls.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",
+        )
+
+    @classmethod
+    def read_resource(cls, 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=cls.uri,
+                    mimeType="application/json",
+                    text=json.dumps(components),
+                )
+            ]
+        )

dash/mcp/primitives/resources/resource_layout.py

@@ -0,0 +1,43 @@
+"""Layout tree resource for the whole app."""
+
+from __future__ import annotations
+
+from mcp.types import (
+    ReadResourceResult,
+    Resource,
+    TextResourceContents,
+)
+
+from dash import get_app
+from dash._utils import to_json
+
+from .base import MCPResourceProvider
+
+
+class LayoutResource(MCPResourceProvider):
+    uri = "dash://layout"
+
+    @classmethod
+    def get_resource(cls) -> Resource | None:
+        return Resource(
+            uri=cls.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",
+        )
+
+    @classmethod
+    def read_resource(cls, uri: str = "") -> ReadResourceResult:
+        app = get_app()
+        return ReadResourceResult(
+            contents=[
+                TextResourceContents(
+                    uri=cls.uri,
+                    mimeType="application/json",
+                    text=to_json(app.get_layout()),
+                )
+            ]
+        )

dash/mcp/primitives/resources/resource_page_layout.py

@@ -0,0 +1,64 @@
+"""Per-page layout resource template for multi-page apps."""
+
+from __future__ import annotations
+
+from mcp.types import (
+    ReadResourceResult,
+    ResourceTemplate,
+    TextResourceContents,
+)
+
+from dash._pages import PAGE_REGISTRY
+from dash._utils import to_json
+
+from .base import MCPResourceProvider
+
+_URI_TEMPLATE = "dash://page-layout/{path}"
+
+
+class PageLayoutResource(MCPResourceProvider):
+    uri = "dash://page-layout/"
+
+    @classmethod
+    def get_template(cls) -> ResourceTemplate | None:
+        if not PAGE_REGISTRY:
+            return None
+        return ResourceTemplate(
+            uriTemplate=_URI_TEMPLATE,
+            name="dash_page_layout",
+            description="Component tree for a specific page in the app.",
+            mimeType="application/json",
+        )
+
+    @classmethod
+    def read_resource(cls, uri: str) -> ReadResourceResult:
+        path = uri[len(cls.uri):]
+        if not path.startswith("/"):
+            path = "/" + path
+
+        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),
+                )
+            ]
+        )