Refactor tool descriptions/schemas to use a base class (just as resources do)

Author: KoolADE85

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

@@ -1,7 +1,7 @@
 """Tool-level description generation for MCP tools.
 
-Each source shares the same signature:
-``(adapter: CallbackAdapter) -> list[str]``
+Each source is a ``ToolDescriptionSource`` subclass that can add text
+to the tool's description. All sources are accumulated.
 
 This is distinct from per-parameter descriptions
 (in ``input_schemas/input_descriptions/``) which populate
@@ -10,25 +10,24 @@
 
 from __future__ import annotations
 
-from __future__ import annotations
-
 from typing import TYPE_CHECKING
 
-from .description_docstring import callback_docstring
-from .description_outputs import output_summary
+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 = [
-    output_summary,
-    callback_docstring,
+_SOURCES: list[type[ToolDescriptionSource]] = [
+    OutputSummaryDescription,
+    DocstringDescription,
 ]
 
 
-def build_tool_description(adapter: CallbackAdapter) -> str:
+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(adapter))
+        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

@@ -4,13 +4,18 @@
 
 from typing import TYPE_CHECKING
 
+from .base import ToolDescriptionSource
+
 if TYPE_CHECKING:
     from dash.mcp.primitives.tools.callback_adapter import CallbackAdapter
 
 
-def callback_docstring(adapter: CallbackAdapter) -> list[str]:
+class DocstringDescription(ToolDescriptionSource):
     """Return the callback's docstring as description lines."""
-    docstring = adapter._docstring
-    if docstring:
-        return ["", docstring.strip()]
-    return []
+
+    @classmethod
+    def describe(cls, callback: CallbackAdapter) -> list[str]:
+        docstring = callback._docstring
+        if docstring:
+            return ["", docstring.strip()]
+        return []

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

@@ -4,54 +4,53 @@
 
 from typing import TYPE_CHECKING
 
+from .base import ToolDescriptionSource
+
 if TYPE_CHECKING:
     from dash.mcp.primitives.tools.callback_adapter import CallbackAdapter
 
 _OUTPUT_SEMANTICS: dict[tuple[str | None, str], str] = {
-    ("Graph", "figure"): "Returns chart/visualization data",
     ("DataTable", "data"): "Returns tabular data",
     ("DataTable", "columns"): "Returns table column definitions",
-    ("Dropdown", "options"): "Returns selection options",
-    ("Dropdown", "value"): "Updates a selection value",
-    ("RadioItems", "options"): "Returns selection options",
-    ("Checklist", "options"): "Returns selection options",
-    ("Store", "data"): "Returns stored data",
+    ("Store", "data"): "Returns data to be remembered client-side",
     ("Download", "data"): "Returns downloadable content",
     ("Markdown", "children"): "Returns formatted text",
     (None, "figure"): "Returns chart/visualization data",
-    (None, "data"): "Returns data",
-    (None, "options"): "Returns selection options",
+    (None, "options"): "Returns available options",
     (None, "columns"): "Returns column definitions",
     (None, "children"): "Returns content",
-    (None, "value"): "Returns a value",
+    (None, "value"): "Returns the current value",
     (None, "style"): "Updates styling",
     (None, "disabled"): "Updates enabled/disabled state",
 }
 
 
-def output_summary(adapter: CallbackAdapter) -> list[str]:
+class OutputSummaryDescription(ToolDescriptionSource):
     """Produce a short summary of what the callback outputs represent."""
-    outputs = adapter.outputs
-    if not outputs:
-        return ["Dash callback"]
-
-    lines: list[str] = []
-    for out in outputs:
-        comp_id = out["component_id"]
-        prop = out["property"]
-        comp_type = out.get("component_type")
-
-        semantic = _OUTPUT_SEMANTICS.get((comp_type, prop))
-        if semantic is None:
-            semantic = _OUTPUT_SEMANTICS.get((None, prop))
-
-        if semantic is not None:
-            lines.append(f"- {comp_id}.{prop}: {semantic}")
-        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
+
+    @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"]
+            comp_type = out.get("component_type")
+
+            semantic = _OUTPUT_SEMANTICS.get((comp_type, prop))
+            if semantic is None:
+                semantic = _OUTPUT_SEMANTICS.get((None, prop))
+
+            if semantic is not None:
+                lines.append(f"- {comp_id}.{prop}: {semantic}")
+            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,25 +1,26 @@
 """Input schema generation for MCP tool inputSchema fields.
 
-Mirrors ``output_schemas/`` which generates ``outputSchema``.
-
-Each source is tried in priority order. All share the same signature:
-``(param: MCPInput) -> dict | None``.
+Each source is an ``InputSchemaSource`` subclass that can type
+an input parameter. Sources are tried in priority order — first
+non-None wins.
 """
 
 from __future__ import annotations
 
 from typing import Any
 
 from dash.mcp.types import MCPInput
-from .schema_callback_type_annotations import annotation_to_schema
-from .schema_component_proptypes_overrides import get_override_schema
-from .schema_component_proptypes import get_component_prop_schema
+
+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 = [
-    annotation_to_schema,
-    get_override_schema,
-    get_component_prop_schema,
+_SOURCES: list[type[InputSchemaSource]] = [
+    AnnotationSchema,
+    OverrideSchema,
+    ComponentPropSchema,
 ]
 
 
@@ -31,7 +32,7 @@ def get_input_schema(param: MCPInput) -> dict[str, Any]:
     """
     schema: dict[str, Any] = {}
     for source in _SOURCES:
-        result = source(param)
+        result = source.get_schema(param)
         if result is not None:
             schema = result
             break

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

@@ -0,0 +1,20 @@
+"""Base class for input schema sources."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from dash.mcp.types import MCPInput
+
+
+class InputSchemaSource:
+    """A source of JSON Schema that can type an MCP tool input parameter.
+
+    Subclasses implement ``get_schema`` to return a JSON Schema dict
+    for the parameter, or ``None`` if this source cannot determine the
+    type. Sources are tried in priority order — first non-None wins.
+    """
+
+    @classmethod
+    def get_schema(cls, param: MCPInput) -> dict[str, Any] | None:
+        raise NotImplementedError

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

@@ -1,23 +1,22 @@
 """Per-property description generation for MCP tool input parameters.
 
-Each source shares the same signature:
-``(param: MCPInput) -> list[str]``
-
-Sources are tried in order from most generic to most instance-specific.
-All sources that produce lines are combined.
+Each source is an ``InputDescriptionSource`` subclass that can add
+text to a parameter's description. All sources are accumulated.
 """
 
 from __future__ import annotations
 
 from dash.mcp.types import MCPInput
-from .description_component_props import component_props_description
-from .description_docstrings import docstring_prop_description
-from .description_html_labels import label_description
 
-_SOURCES = [
-    docstring_prop_description,
-    label_description,
-    component_props_description,
+from .base import InputDescriptionSource
+from .description_component_props import ComponentPropsDescription
+from .description_docstrings import DocstringPropDescription
+from .description_html_labels import LabelDescription
+
+_SOURCES: list[type[InputDescriptionSource]] = [
+    DocstringPropDescription,
+    LabelDescription,
+    ComponentPropsDescription,
 ]
 
 
@@ -27,5 +26,5 @@ def get_property_description(param: MCPInput) -> str | None:
     if not param.get("required", True):
         lines.append("Input is optional.")
     for source in _SOURCES:
-        lines.extend(source(param))
+        lines.extend(source.describe(param))
     return "\n".join(lines) if lines else None

dash/mcp/primitives/tools/input_schemas/input_descriptions/base.py

@@ -0,0 +1,18 @@
+"""Base class for per-parameter description sources."""
+
+from __future__ import annotations
+
+from dash.mcp.types import MCPInput
+
+
+class InputDescriptionSource:
+    """A source of text that can describe an MCP tool input parameter.
+
+    Subclasses implement ``describe`` to return strings that will be
+    added to the callback parameter's description. All sources
+    are accumulated — every source can add text to the overall description.
+    """
+
+    @classmethod
+    def describe(cls, param: MCPInput) -> list[str]:
+        raise NotImplementedError