Merge pull request #3731 from plotly/feature/mcp-tools

MCP Server Part 4: Expose callbacks as tools

Author: KoolADE85

.github/workflows/testing.yml

@@ -105,6 +105,8 @@ jobs:
           echo "DISPLAY=:99" >> $GITHUB_ENV
 
       - name: Run lint
+        env:
+          PYLINT_EXTRA_ARGS: ${{ matrix.python-version == '3.8' && '--ignored-modules=mcp' || '' }}
         run: npm run lint
 
       - name: Run unit tests

.pylintrc

@@ -431,7 +431,7 @@ max-returns=6
 max-statements=50
 
 # Minimum number of public methods for a class (see R0903).
-min-public-methods=2
+min-public-methods=1
 
 
 [IMPORTS]

dash/_callback.py

@@ -82,6 +82,7 @@ def callback(
     optional: Optional[bool] = False,
     hidden: Optional[bool] = None,
     mcp_enabled: bool = True,
+    mcp_expose_docstring: Optional[bool] = None,
     **_kwargs,
 ) -> Callable[..., Any]:
     """
@@ -234,6 +235,7 @@ def callback(
         optional=optional,
         hidden=hidden,
         mcp_enabled=mcp_enabled,
+        mcp_expose_docstring=mcp_expose_docstring,
     )
 
 
@@ -282,6 +284,7 @@ def insert_callback(
     optional=False,
     hidden=None,
     mcp_enabled=True,
+    mcp_expose_docstring=None,
 ):
     if prevent_initial_call is None:
         prevent_initial_call = config_prevent_initial_callbacks
@@ -323,6 +326,7 @@ def insert_callback(
         "allow_dynamic_callbacks": dynamic_creator,
         "no_output": no_output,
         "mcp_enabled": mcp_enabled,
+        "mcp_expose_docstring": mcp_expose_docstring,
     }
     callback_list.append(callback_spec)
 
@@ -658,6 +662,7 @@ def register_callback(
         optional=_kwargs.get("optional", False),
         hidden=_kwargs.get("hidden", None),
         mcp_enabled=_kwargs.get("mcp_enabled", True),
+        mcp_expose_docstring=_kwargs.get("mcp_expose_docstring"),
     )
 
     # pylint: disable=too-many-locals

dash/mcp/primitives/tools/callback_adapter.py

@@ -50,8 +50,17 @@ def __init__(self, callback_output_id: str):
 
     @cached_property
     def as_mcp_tool(self) -> Tool:
-        """Stub — will be implemented in a future PR."""
-        raise NotImplementedError("as_mcp_tool will be implemented in a future PR.")
+        """Transforms the internal Dash callback to a structured MCP tool.
+
+        This tool can be serialized for LLM consumption or used internally for
+        its computed data.
+        """
+        return Tool(
+            name=self.tool_name,
+            description=self._description,
+            inputSchema=self._input_schema,
+            outputSchema=self._output_schema,
+        )
 
     def as_callback_body(self, kwargs: dict[str, Any]) -> CallbackExecutionBody:
         """Transforms the given kwargs to a dict suitable for calling this callback.
@@ -126,7 +135,8 @@ def output_id(self) -> str:
 
     @property
     def tool_name(self) -> str:
-        return get_app().mcp_callback_map._tool_names_map[self._output_id]  # pylint: disable=protected-access
+        # pylint: disable-next=protected-access
+        return get_app().mcp_callback_map._tool_names_map[self._output_id]
 
     @cached_property
     def prevents_initial_call(self) -> bool:
@@ -141,7 +151,7 @@ def prevents_initial_call(self) -> bool:
 
     @cached_property
     def _description(self) -> str:
-        return build_tool_description(self.outputs, self._docstring)
+        return build_tool_description(self)
 
     @cached_property
     def _input_schema(self) -> dict[str, Any]:
@@ -376,7 +386,7 @@ def _expand_output_spec(
     output_id: str,
     cb_info: dict,
     resolved_inputs: list[CallbackInput],
-) -> list[CallbackOutputTarget]:
+) -> CallbackOutputTarget | list[CallbackOutputTarget]:
     """Build the outputs spec, expanding wildcards to concrete IDs.
 
     For wildcard outputs, derives concrete IDs from the resolved inputs.
@@ -408,6 +418,11 @@ def _expand_output_spec(
         else:
             results.append({"id": pid, "property": prop})
 
+    # Mirror the Dash renderer: single-output callbacks send a bare dict,
+    # multi-output callbacks send a list. The framework's output value
+    # matching depends on this shape.
+    if len(results) == 1:
+        return results[0]
     return results
 
 

dash/mcp/primitives/tools/callback_adapter_collection.py

@@ -114,8 +114,7 @@ def get_initial_value(self, id_and_prop: str) -> Any:
         return getattr(layout_component, prop, None)
 
     def as_mcp_tools(self) -> list[Tool]:
-        """Stub — will be implemented in a future PR."""
-        raise NotImplementedError("as_mcp_tools will be implemented in a future PR.")
+        return [cb.as_mcp_tool for cb in self._callbacks if cb.is_valid]
 
     @property
     def tool_names(self) -> set[str]:

dash/mcp/primitives/tools/descriptions/__init__.py

@@ -1,7 +1,33 @@
-"""Stub — real implementation in a later PR."""
+"""Tool-level description generation for MCP tools.
 
+Each source is a ``ToolDescriptionSource`` subclass that can add text
+to the tool's description. All sources are accumulated.
 
-def build_tool_description(outputs, docstring=None):  # pylint: disable=unused-argument
-    if docstring:
-        return docstring.strip()
-    return "Dash callback"
+This is distinct from per-parameter descriptions
+(in ``input_schemas/input_descriptions/``) which populate
+``inputSchema.properties.{param}.description``.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .base import ToolDescriptionSource
+from .description_docstring import DocstringDescription
+from .description_outputs import OutputSummaryDescription
+
+if TYPE_CHECKING:
+    from dash.mcp.primitives.tools.callback_adapter import CallbackAdapter
+
+_SOURCES: list[type[ToolDescriptionSource]] = [
+    OutputSummaryDescription,
+    DocstringDescription,
+]
+
+
+def build_tool_description(callback: CallbackAdapter) -> str:
+    """Build a human-readable description for an MCP tool."""
+    lines: list[str] = []
+    for source in _SOURCES:
+        lines.extend(source.describe(callback))
+    return "\n".join(lines) if lines else "Dash callback"

dash/mcp/primitives/tools/descriptions/base.py

@@ -0,0 +1,21 @@
+"""Base class for tool-level description sources."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from dash.mcp.primitives.tools.callback_adapter import CallbackAdapter
+
+
+class ToolDescriptionSource:
+    """A source of text that can describe an MCP tool.
+
+    Subclasses implement ``describe`` to return strings that will be
+    joined into the tool's ``description`` field. All sources are
+    accumulated — every source can add text to the overall description.
+    """
+
+    @classmethod
+    def describe(cls, callback: CallbackAdapter) -> list[str]:
+        raise NotImplementedError

dash/mcp/primitives/tools/descriptions/description_docstring.py

@@ -0,0 +1,39 @@
+"""Callback docstring for tool descriptions."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from dash import get_app
+
+from .base import ToolDescriptionSource
+
+if TYPE_CHECKING:
+    from dash.mcp.primitives.tools.callback_adapter import CallbackAdapter
+
+
+class DocstringDescription(ToolDescriptionSource):
+    """Return the callback's docstring as description lines.
+
+    Gated behind an opt-in flag: docstrings may contain sensitive
+    implementation details that the browser never surfaces to users,
+    so we don't expose them to MCP clients unless the author opts in
+    — either per-callback or app-wide.
+    """
+
+    @classmethod
+    def describe(cls, callback: CallbackAdapter) -> list[str]:
+        if not cls._is_exposed(callback):
+            return []
+        docstring = callback._docstring  # pylint: disable=protected-access
+        if docstring:
+            return ["", docstring.strip()]
+        return []
+
+    @classmethod
+    def _is_exposed(cls, callback: CallbackAdapter) -> bool:
+        # pylint: disable-next=protected-access
+        per_callback = callback._cb_info.get("mcp_expose_docstring")
+        if per_callback is not None:
+            return per_callback
+        return get_app().config.get("mcp_expose_docstrings", False)

dash/mcp/primitives/tools/descriptions/description_outputs.py

@@ -0,0 +1,45 @@
+"""Output summary for tool descriptions."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..prop_roles import iter_prop_roles
+from .base import ToolDescriptionSource
+
+if TYPE_CHECKING:
+    from dash.mcp.primitives.tools.callback_adapter import CallbackAdapter
+
+
+def _describe_output(comp_type: str | None, prop: str) -> str | None:
+    for role in iter_prop_roles():
+        if role.description is not None and role.matches(comp_type, prop):
+            return role.description
+    return None
+
+
+class OutputSummaryDescription(ToolDescriptionSource):
+    """Produce a short summary of what the callback outputs represent."""
+
+    @classmethod
+    def describe(cls, callback: CallbackAdapter) -> list[str]:
+        outputs = callback.outputs
+        if not outputs:
+            return ["Dash callback"]
+
+        lines: list[str] = []
+        for out in outputs:
+            comp_id = out["component_id"]
+            prop = out["property"]
+            description = _describe_output(out.get("component_type"), prop)
+
+            if description is not None:
+                lines.append(f"- {comp_id}.{prop}: {description}")
+            else:
+                lines.append(f"- {comp_id}.{prop}")
+
+        n = len(outputs)
+        if n == 1:
+            return [lines[0].lstrip("- ")]
+        header = f"Returns {n} output{'s' if n > 1 else ''}:"
+        return [header] + lines

dash/mcp/primitives/tools/input_schemas/__init__.py

@@ -1,5 +1,44 @@
-"""Stub — real implementation in a later PR."""
+"""Input schema generation for MCP tool inputSchema fields.
 
+Each source is an ``InputSchemaSource`` subclass that can type
+an input parameter. Sources are tried in priority order — first
+non-None wins.
+"""
 
-def get_input_schema(param):  # pylint: disable=unused-argument
-    return {}
+from __future__ import annotations
+
+from typing import Any
+
+from dash.mcp.types import MCPInput
+
+from .base import InputSchemaSource
+from .schema_callback_type_annotations import AnnotationSchema
+from .schema_component_proptypes_overrides import OverrideSchema
+from .schema_component_proptypes import ComponentPropSchema
+from .input_descriptions import get_property_description
+
+_SOURCES: list[type[InputSchemaSource]] = [
+    AnnotationSchema,
+    OverrideSchema,
+    ComponentPropSchema,
+]
+
+
+def get_input_schema(param: MCPInput) -> dict[str, Any]:
+    """Return the complete JSON Schema for a callback input parameter.
+
+    Type sources provide ``type``/``enum`` (first non-None wins).
+    Description is assembled by ``input_descriptions``.
+    """
+    schema: dict[str, Any] = {}
+    for source in _SOURCES:
+        result = source.get_schema(param)
+        if result is not None:
+            schema = result
+            break
+
+    description = get_property_description(param)
+    if description:
+        schema = {**schema, "description": description}
+
+    return schema