Disable docstrings by default in MCP tool descriptions

Author: KoolADE85

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/descriptions/description_docstring.py

@@ -4,18 +4,35 @@
 
 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."""
+    """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
         if docstring:
             return ["", docstring.strip()]
         return []
+
+    @classmethod
+    def _is_exposed(cls, callback: CallbackAdapter) -> bool:
+        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)

tests/unit/mcp/conftest.py

@@ -33,7 +33,11 @@ def _make_app(**kwargs):
         ]
     )
 
-    @app.callback(Output("my-output", "children"), Input("my-input", "children"))
+    @app.callback(
+        Output("my-output", "children"),
+        Input("my-input", "children"),
+        mcp_expose_docstring=True,
+    )
     def update_output(value):
         """Test callback docstring."""
         return f"echo: {value}"

tests/unit/mcp/tools/test_callback_adapter.py

@@ -201,10 +201,48 @@ def test_returns_tool_instance(self, simple_app):
         assert isinstance(tool, Tool)
         assert tool.name == "update"
 
-    def test_description_includes_docstring(self, simple_app):
-        with simple_app.server.test_request_context():
-            tool = app_context.get().mcp_callback_map[0].as_mcp_tool
-        assert "Update output." in tool.description
+    def test_docstring_hidden_by_default(self):
+        """Callback docstrings are not exposed to MCP by default."""
+        app = Dash(__name__)
+        app.layout = html.Div([dcc.Input(id="inp"), html.Div(id="out")])
+
+        @app.callback(Output("out", "children"), Input("inp", "value"))
+        def update(val):
+            """sensitive callback docstring text that must not leak to LLMs"""
+            return val
+
+        app_context.set(app)
+        app.mcp_callback_map = CallbackAdapterCollection(app)
+
+        with app.server.test_request_context():
+            tool = app.mcp_callback_map[0].as_mcp_tool
+        assert (
+            "sensitive callback docstring text that must not leak to LLMs"
+            not in tool.description
+        )
+
+    def test_docstring_exposed_when_opted_in_per_callback(self):
+        app = Dash(__name__)
+        app.layout = html.Div([dcc.Input(id="inp"), html.Div(id="out")])
+
+        @app.callback(
+            Output("out", "children"),
+            Input("inp", "value"),
+            mcp_expose_docstring=True,
+        )
+        def update(val):
+            """intentionally-exposed callback docstring text for the LLM"""
+            return val
+
+        app_context.set(app)
+        app.mcp_callback_map = CallbackAdapterCollection(app)
+
+        with app.server.test_request_context():
+            tool = app.mcp_callback_map[0].as_mcp_tool
+        assert (
+            "intentionally-exposed callback docstring text for the LLM"
+            in tool.description
+        )
 
     def test_description_includes_output_target(self, simple_app):
         with simple_app.server.test_request_context():