Add get_dash_component tool and callback tool dispatch pipeline

KoolADE85 · KoolADE85 · commit ece2abf43657 · 2026-04-16T17:20:05.000-06:00
diff --git a/dash/mcp/primitives/tools/__init__.py b/dash/mcp/primitives/tools/__init__.py
@@ -0,0 +1,43 @@
+"""MCP tool listing and call handling.
+
+Each tool module exports:
+- ``get_tool_names() -> set[str]``
+- ``get_tools() -> list[Tool]``
+- ``call_tool(tool_name, arguments) -> CallToolResult``
+
+The __init__ assembles the list and dispatches calls by name.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.types import CallToolResult, ListToolsResult
+
+from dash.mcp.types import ToolNotFoundError
+
+from . import tool_get_dash_component as _get_component
+from . import tools_callbacks as _callbacks
+
+_TOOL_MODULES = [_callbacks, _get_component]
+
+
+def list_tools() -> ListToolsResult:
+    """Build the MCP tools/list response."""
+    tools = []
+    for mod in _TOOL_MODULES:
+        tools.extend(mod.get_tools())
+    return ListToolsResult(tools=tools)
+
+
+def call_tool(tool_name: str, arguments: dict[str, Any]) -> CallToolResult:
+    """Dispatch a tools/call request by tool name."""
+    for mod in _TOOL_MODULES:
+        if tool_name in mod.get_tool_names():
+            result = mod.call_tool(tool_name, arguments)
+            return result
+    raise ToolNotFoundError(
+        f"Tool not found: {tool_name}."
+        " The app's callbacks may have changed."
+        " Please call tools/list to refresh your tool list."
+    )
diff --git a/dash/mcp/primitives/tools/tool_get_dash_component.py b/dash/mcp/primitives/tools/tool_get_dash_component.py
@@ -0,0 +1,123 @@
+"""Built-in tool: get_dash_component."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from mcp.types import CallToolResult, TextContent, Tool
+from pydantic import Field, TypeAdapter
+from typing_extensions import Annotated, NotRequired, TypedDict
+
+from dash import get_app
+from dash._layout_utils import find_component
+from dash.mcp.types import ComponentPropertyInfo, ComponentQueryResult
+
+
+class _ComponentQueryInput(TypedDict):
+    component_id: Annotated[str, Field(description="The component ID to query")]
+    property: NotRequired[
+        Annotated[
+            str,
+            Field(
+                description="The property name to read (e.g. 'options', 'value'). Omit to list all defined properties."
+            ),
+        ]
+    ]
+
+
+_INPUT_SCHEMA = TypeAdapter(_ComponentQueryInput).json_schema()
+_OUTPUT_SCHEMA = TypeAdapter(ComponentQueryResult).json_schema()
+
+NAME = "get_dash_component"
+
+
+def get_tool_names() -> set[str]:
+    return {NAME}
+
+
+def get_tools() -> list[Tool]:
+    return [_build_tool()]
+
+
+def _build_tool() -> Tool:
+    return Tool(
+        name=NAME,
+        description=(
+            "Get a component's properties, values, and tool relationships. "
+            "If property is omitted, returns all defined properties. "
+            "If property is specified, returns only that property. "
+            "See the dash://components resource for available component IDs."
+        ),
+        inputSchema=_INPUT_SCHEMA,
+        outputSchema=_OUTPUT_SCHEMA,
+    )
+
+
+def call_tool(tool_name: str, arguments: dict[str, Any]) -> CallToolResult:
+    comp_id = arguments.get("component_id", "")
+    if not comp_id:
+        raise ValueError("component_id is required")
+
+    prop_filter = arguments.get("property", "")
+    component = find_component(comp_id)
+
+    if component is None:
+        callback_map = get_app().mcp_callback_map
+        rendering_tools = [
+            cb.tool_name
+            for cb in callback_map
+            if any(out["component_id"] == comp_id for out in cb.outputs)
+        ]
+        msg = f"Component '{comp_id}' not found in static layout."
+        if rendering_tools:
+            msg += f" However, the following tools would modify it: {rendering_tools}."
+        msg += " Use the dash://components resource to see statically available component IDs."
+        return CallToolResult(
+            content=[TextContent(type="text", text=msg)],
+            isError=True,
+        )
+
+    callback_map = get_app().mcp_callback_map
+
+    properties: dict[str, ComponentPropertyInfo] = {}
+    for prop_name in getattr(component, "_prop_names", []):
+        if prop_filter and prop_name != prop_filter:
+            continue
+
+        value = callback_map.get_initial_value(f"{comp_id}.{prop_name}")
+        if value is None:
+            value = getattr(component, prop_name, None)
+        if value is None:
+            continue
+
+        modified_by: list[str] = []
+        input_to: list[str] = []
+        id_and_prop = f"{comp_id}.{prop_name}"
+        for cb in callback_map:
+            for out in cb.outputs:
+                if out["id_and_prop"] == id_and_prop:
+                    modified_by.append(cb.tool_name)
+            for inp in cb.inputs:
+                if inp["id_and_prop"] == id_and_prop:
+                    input_to.append(cb.tool_name)
+
+        properties[prop_name] = ComponentPropertyInfo(
+            initial_value=value,
+            modified_by_tool=modified_by,
+            input_to_tool=input_to,
+        )
+
+    labels = callback_map.component_label_map.get(comp_id, [])
+
+    structured: ComponentQueryResult = ComponentQueryResult(
+        component_id=comp_id,
+        component_type=type(component).__name__,
+        label=labels if labels else None,
+        properties=properties,
+    )
+
+    return CallToolResult(
+        content=[TextContent(type="text", text=json.dumps(structured, default=str))],
+        structuredContent=structured,
+    )
diff --git a/dash/mcp/primitives/tools/tools_callbacks.py b/dash/mcp/primitives/tools/tools_callbacks.py
@@ -0,0 +1,47 @@
+"""Dynamic callback tools for MCP.
+
+Handles listing, naming, and executing callback-based tools.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.types import CallToolResult, TextContent, Tool
+
+from dash import get_app
+from dash.mcp.types import CallbackExecutionError, ToolNotFoundError
+
+from .results import format_callback_response
+
+
+def get_tool_names() -> set[str]:
+    return get_app().mcp_callback_map.tool_names
+
+
+def get_tools() -> list[Tool]:
+    """Return one Tool per server-callable callback."""
+    return get_app().mcp_callback_map.as_mcp_tools()
+
+
+def call_tool(tool_name: str, arguments: dict[str, Any]) -> CallToolResult:
+    """Execute a callback tool by name."""
+    from .callback_utils import run_callback
+
+    callback_map = get_app().mcp_callback_map
+    cb = callback_map.find_by_tool_name(tool_name)
+    if cb is None:
+        raise ToolNotFoundError(
+            f"Tool not found: {tool_name}."
+            " The app's callbacks may have changed."
+            " Please call tools/list to refresh your tool list."
+        )
+
+    try:
+        dispatch_response = run_callback(cb, arguments)
+    except CallbackExecutionError as e:
+        return CallToolResult(
+            content=[TextContent(type="text", text=str(e))],
+            isError=True,
+        )
+    return format_callback_response(dispatch_response, cb)
diff --git a/tests/unit/mcp/conftest.py b/tests/unit/mcp/conftest.py
@@ -9,6 +9,7 @@
 if sys.version_info < (3, 10):
     collect_ignore_glob.append("*")
 else:
+    from dash.mcp.primitives.tools import call_tool, list_tools  # pylint: disable=wrong-import-position
     from dash.mcp.primitives.tools.callback_adapter_collection import (  # pylint: disable=wrong-import-position
         CallbackAdapterCollection,
     )
@@ -42,10 +43,10 @@ def update_output(value):
 
 
 def _tools_list(app):
-    """Return tools as Tool objects via as_mcp_tools()."""
+    """Return all tools (callbacks + builtins) as Tool objects."""
     _setup_mcp(app)
     with app.server.test_request_context():
-        return app.mcp_callback_map.as_mcp_tools()
+        return list_tools().tools
 
 
 def _user_tool(tools):
@@ -81,3 +82,10 @@ def _desc_for(tool, param_name=None):
     if param_name is None:
         param_name = next(iter(props))
     return props[param_name].get("description", "")
+
+
+def _call_tool(app, tool_name, arguments=None):
+    """Call a tool via the dispatch pipeline and return the CallToolResult."""
+    _setup_mcp(app)
+    with app.server.test_request_context():
+        return call_tool(tool_name, arguments or {})
diff --git a/tests/unit/mcp/tools/test_tool_get_dash_component.py b/tests/unit/mcp/tools/test_tool_get_dash_component.py
@@ -0,0 +1,117 @@
+"""Tests for the get_dash_component built-in tool."""
+
+from dash import Dash, Input, Output, dcc, html
+
+from tests.unit.mcp.conftest import _call_tool, _make_app, _tools_list
+
+
+class TestGetDashComponent:
+    def test_present_in_tools_list(self):
+        app = _make_app()
+        tool_names = [t.name for t in _tools_list(app)]
+        assert "get_dash_component" in tool_names
+
+    def test_returns_structured_output_with_prop(self):
+        app = Dash(__name__)
+        app.layout = html.Div(
+            [
+                dcc.Dropdown(id="my-dd", options=["a", "b"], value="b"),
+            ]
+        )
+
+        result = _call_tool(
+            app,
+            "get_dash_component",
+            {
+                "component_id": "my-dd",
+                "property": "value",
+            },
+        )
+        sc = result.structuredContent
+        assert sc["component_id"] == "my-dd"
+        assert sc["component_type"] == "Dropdown"
+        assert "value" in sc["properties"]
+        assert sc["properties"]["value"]["initial_value"] == "b"
+        assert "options" not in sc["properties"]
+
+    def test_returns_all_props_without_property(self):
+        app = Dash(__name__)
+        app.layout = html.Div(
+            [
+                dcc.Dropdown(id="my-dd", options=["a", "b"], value="b"),
+            ]
+        )
+
+        result = _call_tool(
+            app,
+            "get_dash_component",
+            {
+                "component_id": "my-dd",
+            },
+        )
+        sc = result.structuredContent
+        assert "options" in sc["properties"]
+        assert "value" in sc["properties"]
+        assert sc["properties"]["value"]["initial_value"] == "b"
+
+    def test_includes_label(self):
+        app = Dash(__name__)
+        app.layout = html.Div(
+            [
+                html.Label("Pick one", htmlFor="my-dd"),
+                dcc.Dropdown(id="my-dd", options=["a", "b"], value="a"),
+            ]
+        )
+
+        @app.callback(Output("my-dd", "value"), Input("my-dd", "options"))
+        def noop(o):
+            return "a"
+
+        result = _call_tool(
+            app,
+            "get_dash_component",
+            {
+                "component_id": "my-dd",
+            },
+        )
+        sc = result.structuredContent
+        assert sc["label"] == ["Pick one"]
+
+    def test_includes_tool_references(self):
+        app = Dash(__name__)
+        app.layout = html.Div(
+            [
+                dcc.Dropdown(id="dd", options=["a", "b"], value="a"),
+                html.Div(id="out"),
+            ]
+        )
+
+        @app.callback(Output("out", "children"), Input("dd", "value"))
+        def update(val):
+            return val
+
+        result = _call_tool(
+            app,
+            "get_dash_component",
+            {
+                "component_id": "dd",
+                "property": "value",
+            },
+        )
+        prop_info = result.structuredContent["properties"]["value"]
+        assert "update" in prop_info["input_to_tool"]
+
+    def test_missing_id_returns_hint(self):
+        app = _make_app()
+        result = _call_tool(
+            app,
+            "get_dash_component",
+            {
+                "component_id": "nonexistent",
+                "property": "value",
+            },
+        )
+        text = result.content[0].text
+        assert "nonexistent" in text
+        assert "not found" in text
+        assert "dash://components" in text
diff --git a/tests/unit/mcp/tools/test_tools_callbacks.py b/tests/unit/mcp/tools/test_tools_callbacks.py
