Refactor tool result formatters to use a base class (just as resources do)

Author: KoolADE85

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

@@ -1,10 +1,7 @@
 """Tool result formatting for MCP tools/call responses.
 
-Each result formatter shares the same signature:
-``(output: MCPOutput, value: Any) -> list[TextContent | ImageContent]``
-
-Formatters decide for themselves whether they care about a given output.
-The structuredContent is always the full dispatch response.
+Each formatter is a ``ResultFormatter`` subclass that can enrich
+a tool result with additional content. All formatters are accumulated.
 """
 
 from __future__ import annotations
@@ -17,20 +14,21 @@
 from dash.types import CallbackExecutionResponse
 from dash.mcp.primitives.tools.callback_adapter import CallbackAdapter
 
-from .result_dataframe import dataframe_result
-from .result_plotly_figure import plotly_figure_result
+from .base import ResultFormatter
+from .result_dataframe import DataFrameResult
+from .result_plotly_figure import PlotlyFigureResult
 
-_RESULT_FORMATTERS = [
-    plotly_figure_result,
-    dataframe_result,
+_RESULT_FORMATTERS: list[type[ResultFormatter]] = [
+    PlotlyFigureResult,
+    DataFrameResult,
 ]
 
 
 def format_callback_response(
     response: CallbackExecutionResponse,
     callback: CallbackAdapter,
 ) -> CallToolResult:
-    """Format a dispatch response as a CallToolResult.
+    """Format a callback response as a CallToolResult.
 
     The response is always returned as structuredContent. Result
     formatters are called per output property and may add additional
@@ -43,8 +41,8 @@ def format_callback_response(
     resp = response.get("response") or {}
     for callback_output in callback.outputs:
         value = resp.get(callback_output["component_id"], {}).get(callback_output["property"])
-        for result_fn in _RESULT_FORMATTERS:
-            content.extend(result_fn(callback_output, value))
+        for formatter in _RESULT_FORMATTERS:
+            content.extend(formatter.format(callback_output, value))
 
     return CallToolResult(
         content=content,

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

@@ -0,0 +1,24 @@
+"""Base class for result formatters."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.types import ImageContent, TextContent
+
+from dash.mcp.types import MCPOutput
+
+
+class ResultFormatter:
+    """A formatter that can enrich an MCP tool result with additional content.
+
+    Subclasses implement ``format`` to return content items (text, images)
+    for a specific callback output. All formatters are accumulated — every
+    formatter can add content to the overall tool result.
+    """
+
+    @classmethod
+    def format(
+        cls, output: MCPOutput, returned_output_value: Any
+    ) -> list[TextContent | ImageContent]:
+        raise NotImplementedError

dash/mcp/primitives/tools/results/result_dataframe.py

@@ -9,10 +9,12 @@
 
 from typing import Any
 
-from mcp.types import TextContent
+from mcp.types import ImageContent, TextContent
 
 from dash.mcp.types import MCPOutput
 
+from .base import ResultFormatter
+
 MAX_ROWS = 50
 
 _TABULAR_PROPS = {
@@ -45,11 +47,20 @@ def _to_markdown_table(rows: list[dict], max_rows: int = MAX_ROWS) -> str:
     return "\n".join(lines)
 
 
-def dataframe_result(callback_output: MCPOutput, callback_output_value: Any) -> list:
+class DataFrameResult(ResultFormatter):
     """Produce a markdown table for tabular component output values."""
-    key = (callback_output.get("component_type"), callback_output.get("property"))
-    if key not in _TABULAR_PROPS:
-        return []
-    if not isinstance(callback_output_value, list) or not callback_output_value or not isinstance(callback_output_value[0], dict):
-        return []
-    return [TextContent(type="text", text=_to_markdown_table(callback_output_value))]
+
+    @classmethod
+    def format(
+        cls, output: MCPOutput, returned_output_value: Any
+    ) -> list[TextContent | ImageContent]:
+        key = (output.get("component_type"), output.get("property"))
+        if key not in _TABULAR_PROPS:
+            return []
+        if (
+            not isinstance(returned_output_value, list)
+            or not returned_output_value
+            or not isinstance(returned_output_value[0], dict)
+        ):
+            return []
+        return [TextContent(type="text", text=_to_markdown_table(returned_output_value))]

dash/mcp/primitives/tools/results/result_plotly_figure.py

@@ -6,10 +6,12 @@
 import logging
 from typing import Any
 
-from mcp.types import ImageContent
+from mcp.types import ImageContent, TextContent
 
 from dash.mcp.types import MCPOutput
 
+from .base import ResultFormatter
+
 logger = logging.getLogger(__name__)
 
 IMAGE_WIDTH = 700
@@ -35,18 +37,23 @@ def _render_image(figure: Any) -> ImageContent | None:
     return ImageContent(type="image", data=b64, mimeType="image/png")
 
 
-def plotly_figure_result(callback_output: MCPOutput, callback_output_value: Any) -> list:
+class PlotlyFigureResult(ResultFormatter):
     """Produce a rendered PNG for Graph.figure output values."""
-    if callback_output.get("component_type") != "Graph" or callback_output.get("property") != "figure":
-        return []
-    if not isinstance(callback_output_value, dict):
-        return []
-
-    try:
-        import plotly.graph_objects as go
-    except ImportError:
-        return []
 
-    fig = go.Figure(callback_output_value)
-    image = _render_image(fig)
-    return [image] if image is not None else []
+    @classmethod
+    def format(
+        cls, output: MCPOutput, returned_output_value: Any
+    ) -> list[TextContent | ImageContent]:
+        if output.get("component_type") != "Graph" or output.get("property") != "figure":
+            return []
+        if not isinstance(returned_output_value, dict):
+            return []
+
+        try:
+            import plotly.graph_objects as go
+        except ImportError:
+            return []
+
+        fig = go.Figure(returned_output_value)
+        image = _render_image(fig)
+        return [image] if image is not None else []

tests/unit/mcp/tools/results/test_dataframe.py

@@ -2,7 +2,7 @@
 
 from dash.mcp.primitives.tools.results.result_dataframe import (
     MAX_ROWS,
-    dataframe_result,
+    DataFrameResult,
 )
 
 EXPECTED_TABLE = (
@@ -37,26 +37,26 @@
 
 class TestDataframeResult:
     def test_datatable_data_renders_markdown(self):
-        result = dataframe_result(DATATABLE_OUTPUT, SAMPLE_ROWS)
+        result = DataFrameResult.format(DATATABLE_OUTPUT, SAMPLE_ROWS)
         assert len(result) == 1
         assert result[0].text == EXPECTED_TABLE
 
     def test_aggrid_rowdata_renders_markdown(self):
-        result = dataframe_result(AGGRID_OUTPUT, SAMPLE_ROWS)
+        result = DataFrameResult.format(AGGRID_OUTPUT, SAMPLE_ROWS)
         assert len(result) == 1
         assert result[0].text == EXPECTED_TABLE
 
     def test_ignores_non_tabular_props(self):
         non_tabular = {**DATATABLE_OUTPUT, "property": "columns"}
-        assert dataframe_result(non_tabular, SAMPLE_ROWS) == []
+        assert DataFrameResult.format(non_tabular, SAMPLE_ROWS) == []
 
     def test_ignores_empty_or_non_dict_rows(self):
-        assert dataframe_result(DATATABLE_OUTPUT, []) == []
-        assert dataframe_result(DATATABLE_OUTPUT, ["a", "b"]) == []
+        assert DataFrameResult.format(DATATABLE_OUTPUT, []) == []
+        assert DataFrameResult.format(DATATABLE_OUTPUT, ["a", "b"]) == []
 
     def test_truncates_large_tables(self):
         rows = [{"i": n} for n in range(MAX_ROWS + 50)]
-        result = dataframe_result(DATATABLE_OUTPUT, rows)
+        result = DataFrameResult.format(DATATABLE_OUTPUT, rows)
         text = result[0].text
         assert f"| {MAX_ROWS - 1} |" in text
         assert f"| {MAX_ROWS} |" not in text

tests/unit/mcp/tools/results/test_plotly_figure.py

@@ -6,7 +6,7 @@
 import pytest
 
 from dash.mcp.primitives.tools.results.result_plotly_figure import (
-    plotly_figure_result,
+    PlotlyFigureResult,
 )
 
 go = pytest.importorskip("plotly.graph_objects")
@@ -28,15 +28,15 @@ class TestPlotlyFigureResult:
     def test_returns_image_when_kaleido_available(self):
         fig_dict = go.Figure(data=[go.Bar(x=["A", "B"], y=[1, 2])]).to_plotly_json()
         with patch.object(go.Figure, "to_image", return_value=FAKE_PNG):
-            result = plotly_figure_result(GRAPH_FIGURE_OUTPUT, fig_dict)
+            result = PlotlyFigureResult.format(GRAPH_FIGURE_OUTPUT, fig_dict)
         assert len(result) == 1
         assert result[0].type == "image"
         assert result[0].data == FAKE_B64
 
     def test_returns_empty_when_kaleido_unavailable(self):
         fig_dict = go.Figure(data=[go.Bar(x=["A", "B"], y=[1, 2])]).to_plotly_json()
         with patch.object(go.Figure, "to_image", side_effect=ImportError):
-            result = plotly_figure_result(GRAPH_FIGURE_OUTPUT, fig_dict)
+            result = PlotlyFigureResult.format(GRAPH_FIGURE_OUTPUT, fig_dict)
         assert result == []
 
     def test_ignores_non_graph_components(self):
@@ -45,11 +45,11 @@ def test_ignores_non_graph_components(self):
             "component_type": "Div",
             "property": "children",
         }
-        assert plotly_figure_result(output, {}) == []
+        assert PlotlyFigureResult.format(output, {}) == []
 
     def test_ignores_non_figure_props(self):
         output = {**GRAPH_FIGURE_OUTPUT, "property": "clickData"}
-        assert plotly_figure_result(output, {}) == []
+        assert PlotlyFigureResult.format(output, {}) == []
 
     def test_ignores_non_dict_values(self):
-        assert plotly_figure_result(GRAPH_FIGURE_OUTPUT, "not a dict") == []
+        assert PlotlyFigureResult.format(GRAPH_FIGURE_OUTPUT, "not a dict") == []