Move all hard-coded text into a prop_roles.py file where it can be managed centrally

Author: KoolADE85

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

@@ -4,25 +4,18 @@
 
 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
 
-_OUTPUT_SEMANTICS: dict[tuple[str | None, str], str] = {
-    ("DataTable", "data"): "Returns tabular data",
-    ("DataTable", "columns"): "Returns table column definitions",
-    ("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, "options"): "Returns available options",
-    (None, "columns"): "Returns column definitions",
-    (None, "children"): "Returns content",
-    (None, "value"): "Returns the current value",
-    (None, "style"): "Updates styling",
-    (None, "disabled"): "Updates enabled/disabled state",
-}
+
+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):
@@ -38,14 +31,10 @@ def describe(cls, callback: CallbackAdapter) -> 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))
+            description = _describe_output(out.get("component_type"), prop)
 
-            if semantic is not None:
-                lines.append(f"- {comp_id}.{prop}: {semantic}")
+            if description is not None:
+                lines.append(f"- {comp_id}.{prop}: {description}")
             else:
                 lines.append(f"- {comp_id}.{prop}")
 

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

@@ -1,5 +1,8 @@
-"""A place to manually define Schemas that override component-defined prop types
-where type generation produces insufficient results.
+"""Input schema overrides drawn from the ``PropRole`` registry.
+
+Looks up the parameter's ``(component_type, property)`` in the shared
+registry and returns any attached ``input_schema``. Used when default
+type introspection produces insufficient results.
 """
 
 from __future__ import annotations
@@ -8,67 +11,21 @@
 
 from dash.mcp.types import MCPInput
 
+from ..prop_roles import iter_prop_roles
 from .base import InputSchemaSource
-from .schema_component_proptypes import ComponentPropSchema
-
-_DATE_SCHEMA = {
-    "type": "string",
-    "format": "date",
-    "pattern": r"^\d{4}-\d{2}-\d{2}$",
-}
-
-
-def _compute_dropdown_value_schema(param: MCPInput) -> dict[str, Any] | None:
-    """Dropdown values are an array if `multi=True`; scalar values otherwise."""
-    schema = ComponentPropSchema.get_schema(param)
-    if schema is None:
-        return None
-
-    component = param.get("component")
-    t = schema.get("type")
-    if not isinstance(t, list):
-        return schema
-
-    if getattr(component, "multi", False):
-        items_schema = schema.get("items", {})
-        return (
-            {"type": "array", "items": items_schema}
-            if items_schema
-            else {"type": "array"}
-        )
-
-    scalar_types = [x for x in t if x != "array"]
-    refined = dict(schema)
-    refined["type"] = scalar_types[0] if len(scalar_types) == 1 else scalar_types
-    refined.pop("items", None)
-    return refined
-
-
-_OVERRIDES: dict[tuple[str, str], dict[str, Any] | callable] = {
-    ("DatePickerSingle", "date"): _DATE_SCHEMA,
-    ("DatePickerRange", "start_date"): _DATE_SCHEMA,
-    ("DatePickerRange", "end_date"): _DATE_SCHEMA,
-    ("Graph", "figure"): {
-        "type": "object",
-        "properties": {
-            "data": {"type": "array", "items": {"type": "object"}},
-            "layout": {"type": "object"},
-            "frames": {"type": "array", "items": {"type": "object"}},
-        },
-    },
-    ("Dropdown", "value"): _compute_dropdown_value_schema,
-}
 
 
 class OverrideSchema(InputSchemaSource):
     """Return a schema override, or None to fall through to introspection."""
 
     @classmethod
     def get_schema(cls, param: MCPInput) -> dict[str, Any] | None:
-        key = (param.get("component_type"), param["property"])
-        override = _OVERRIDES.get(key)
-        if override is None:
-            return None
-        if callable(override):
-            return override(param)
-        return dict(override)
+        component_type = param.get("component_type")
+        prop = param["property"]
+        for role in iter_prop_roles():
+            if role.input_schema is None or not role.matches(component_type, prop):
+                continue
+            if callable(role.input_schema):
+                return role.input_schema(param)
+            return dict(role.input_schema)
+        return None

dash/mcp/primitives/tools/prop_roles.py

@@ -0,0 +1,151 @@
+"""Canonical registry of semantic roles for Dash component props.
+
+A ``PropRole`` bundles the set of ``(component_type, property)`` pairs
+that play the same role with the metadata attached to that role:
+an LLM-facing description, an input JSON Schema, etc. Tool descriptions,
+input-schema overrides, and result formatters all consume this registry
+so they can't drift.
+
+Use ``ANY_COMPONENT`` as the component_type sentinel to match any component with
+the given property name.
+
+Declaration order matters: ``iter_prop_roles()`` yields roles in the
+order they're defined in this module, and the first match wins. List
+concrete-match roles before wildcard-match roles that share a prop
+name (e.g. ``MARKDOWN`` before ``CONTENT`` for ``children``).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Iterator, NamedTuple, Union
+
+from typing_extensions import TypeAlias
+
+from dash.mcp.types import MCPInput
+
+PropSchema = Union[
+    Dict[str, Any],
+    Callable[[MCPInput], Dict[str, Any]],
+]
+
+COMPONENT: TypeAlias = Union[str, None]
+ANY_COMPONENT: None = None
+PROP: TypeAlias = str
+
+
+class PropRole(NamedTuple):
+    identifiers: set[tuple[COMPONENT, PROP]]
+    description: str | None = None
+    input_schema: PropSchema | None = None
+
+    def matches(self, component_type: COMPONENT, prop: PROP) -> bool:
+        """True if this role applies to the given ``(component_type, prop)``.
+
+        Matches either a concrete entry or an ``ANY_COMPONENT`` wildcard
+        entry in ``identifiers``. Shared by every consumer so all metadata
+        fields apply uniformly to every identifier in the role.
+        """
+        return (component_type, prop) in self.identifiers or (
+            ANY_COMPONENT,
+            prop,
+        ) in self.identifiers
+
+
+def _compute_dropdown_value_schema(param: MCPInput) -> dict[str, Any]:
+    """Dropdown values are an array if ``multi=True``; scalar otherwise."""
+    _DROPDOWN_SCALAR_TYPE = {
+        "anyOf": [{"type": "string"}, {"type": "number"}, {"type": "boolean"}]
+    }
+    component = param.get("component")
+    if getattr(component, "multi", False):
+        return {"type": "array", "items": _DROPDOWN_SCALAR_TYPE}
+    return _DROPDOWN_SCALAR_TYPE
+
+
+TABULAR = PropRole(
+    identifiers={("DataTable", "data"), ("AgGrid", "rowData")},
+    description="Returns tabular data",
+)
+
+DATE = PropRole(
+    identifiers={
+        ("DatePickerSingle", "date"),
+        ("DatePickerRange", "start_date"),
+        ("DatePickerRange", "end_date"),
+    },
+    input_schema={
+        "type": "string",
+        "format": "date",
+        "pattern": r"^\d{4}-\d{2}-\d{2}$",
+    },
+)
+
+DROPDOWN_VALUE = PropRole(
+    identifiers={("Dropdown", "value")},
+    input_schema=_compute_dropdown_value_schema,
+)
+
+STORE_DATA = PropRole(
+    identifiers={("Store", "data")},
+    description="Returns data to be remembered client-side",
+)
+
+DOWNLOAD = PropRole(
+    identifiers={("Download", "data")},
+    description="Returns downloadable content",
+)
+
+MARKDOWN = PropRole(
+    identifiers={("Markdown", "children")},
+    description="Returns formatted text",
+)
+
+GENERIC_FIGURE = PropRole(
+    identifiers={(ANY_COMPONENT, "figure")},
+    description="Returns chart/visualization data",
+    input_schema={
+        "type": "object",
+        "properties": {
+            "data": {"type": "array", "items": {"type": "object"}},
+            "layout": {"type": "object"},
+            "frames": {"type": "array", "items": {"type": "object"}},
+        },
+    },
+)
+
+GENERIC_CONTENT = PropRole(
+    identifiers={(ANY_COMPONENT, "children")},
+    description="Returns content",
+)
+
+GENERIC_VALUE = PropRole(
+    identifiers={(ANY_COMPONENT, "value")},
+    description="Returns the current value",
+)
+
+GENERIC_OPTIONS = PropRole(
+    identifiers={(ANY_COMPONENT, "options")},
+    description="Returns available options",
+)
+
+GENERIC_COLUMNS = PropRole(
+    identifiers={(ANY_COMPONENT, "columns")},
+    description="Returns column definitions",
+)
+
+GENERIC_STYLE = PropRole(
+    identifiers={(ANY_COMPONENT, "style")},
+    description="Updates styling",
+)
+
+GENERIC_DISABLED = PropRole(
+    identifiers={(ANY_COMPONENT, "disabled")},
+    description="Updates enabled/disabled state",
+)
+
+
+def iter_prop_roles() -> Iterator[PropRole]:
+    """Yield every PropRole defined in this module in declaration order."""
+    for value in globals().values():
+        if isinstance(value, PropRole):
+            yield value

tests/unit/mcp/tools/test_mcp_input_schemas.py

@@ -111,11 +111,6 @@ def update(val: annotation_type):
         ),
     ),
     ("Input", "n_submit", nullable(NUMBER)),
-    (
-        "Dropdown",
-        "value",
-        nullable(STRING, NUMBER, BOOLEAN, array_of(STRING, NUMBER, BOOLEAN)),
-    ),
     ("Dropdown", "options", nullable({})),
     ("Checklist", "value", nullable(array_of(STRING, NUMBER, BOOLEAN))),
     ("Store", "data", nullable(OBJECT, array_of({}), NUMBER, STRING, BOOLEAN)),
@@ -152,6 +147,13 @@ def test_mcpi001_override_beats_introspection():
     assert "pattern" in schema
 
 
+def test_mcpi013_graph_figure_uses_plotly_schema_override():
+    """Graph.figure matches the FIGURE role's schema override (concrete via wildcard)."""
+    schema = _get_schema("Graph", "figure")
+    assert schema["type"] == "object"
+    assert set(schema["properties"]) == {"data", "layout", "frames"}
+
+
 @pytest.mark.parametrize(
     "component_type,prop,expected",
     INTROSPECTION_CASES,
@@ -268,3 +270,20 @@ def update(val: int, data):
 def test_mcpi010_component_type_maps_to_string():
     """Component annotation type maps to string schema."""
     assert annotation_to_json_schema(Component) == STRING
+
+
+def test_mcpi011_dropdown_value_multi_false_narrows_to_scalar():
+    """Dropdown.value with multi=False narrows to a scalar union."""
+    app = _app_with_callback(dcc.Dropdown(id="dd"))
+    tool = _user_tool(_tools_list(app))
+    assert _schema_for(tool) == {"anyOf": [STRING, NUMBER, BOOLEAN]}
+
+
+def test_mcpi012_dropdown_value_multi_true_narrows_to_array():
+    """Dropdown.value with multi=True narrows to an array of scalars."""
+    app = _app_with_callback(dcc.Dropdown(id="dd", multi=True))
+    tool = _user_tool(_tools_list(app))
+    assert _schema_for(tool) == {
+        "type": "array",
+        "items": {"anyOf": [STRING, NUMBER, BOOLEAN]},
+    }