refactor: improve execution tool guidance for script execution

This commit refactors MCP app detection and enhances the tool feedback loop to guide
clients toward the correct execution tools.

Key changes:
* Extracted `_use_mcp_app_for_client` from `server.py` into a public
  `use_mcp_app_for_client` utility in `mcp_app.py` for cross-module reuse.
* Added a `_pick_execution_tool` helper in `run_script.py` to dynamically determine
  the right tool (`run_script`, `run_script_interactive`, or
  `run_script_with_confirmation`) based on script flags (readonly,
  needs_confirmation) and client capabilities.
* Updated `validate_script` to explicitly instruct the client on which execution tool
  to use next in its text response.
* Improved the error message in `run_script` to dynamically suggest the appropriate
  confirmation tool if the script requires confirmation but was called incorrectly.
* Updated the middleware tests for adapting to the change from this patch.

Author: Jazzcort

src/linux_mcp_server/mcp_app.py

@@ -1,4 +1,27 @@
+from mcp.types import InitializeRequestParams
+
+from linux_mcp_server.config import CONFIG
+
+
 RUN_SCRIPT_APP_URI = "ui://run_script_readonly_with_mcp_app/run-script-app.html"
 ALLOWED_UI_RESOURCE_URIS = set([RUN_SCRIPT_APP_URI])
 MCP_APP_MIME_TYPE = "text/html;profile=mcp-app"
 MCP_UI_EXTENSION = "io.modelcontextprotocol/ui"
+
+
+def use_mcp_app_for_client(client_params: InitializeRequestParams):
+    # The configuration can overwrite the MCP app support detection, so we have the flexibility to
+    # manually turn the Mcp app feature on/off for developing/testing purposes.
+    if CONFIG.use_mcp_apps is not None:
+        return CONFIG.use_mcp_apps
+
+    # For python-sdk -1.x, count on extensibility of protocol types - while this is being
+    # removed for v2, hopefully extensions will be there properly.
+    capabilities = client_params.capabilities
+    extensions = getattr(capabilities, "extensions", {})
+    mcp_ui_extension = extensions.get(MCP_UI_EXTENSION) or {}
+    mime_types = mcp_ui_extension.get("mimeTypes") or []
+
+    # The configuration can overwrite the MCP app support detection, so we have the flexibility to
+    # manually turn the Mcp app feature on/off for developing/testing purposes.
+    return MCP_APP_MIME_TYPE in mime_types

src/linux_mcp_server/server.py

@@ -15,7 +15,6 @@
 from mcp import ServerSession
 from mcp.types import BlobResourceContents
 from mcp.types import InitializeRequest
-from mcp.types import InitializeRequestParams
 from mcp.types import InitializeResult
 from mcp.types import ReadResourceRequest
 from mcp.types import ReadResourceResult
@@ -28,7 +27,7 @@
 from linux_mcp_server.config import Toolset
 from linux_mcp_server.mcp_app import ALLOWED_UI_RESOURCE_URIS
 from linux_mcp_server.mcp_app import MCP_APP_MIME_TYPE
-from linux_mcp_server.mcp_app import MCP_UI_EXTENSION
+from linux_mcp_server.mcp_app import use_mcp_app_for_client
 
 
 logger = logging.getLogger("linux-mcp-server")
@@ -222,24 +221,6 @@ async def _read_resource_with_meta(req: ReadResourceRequest):
 from linux_mcp_server.tools import *  # noqa: E402, F403
 
 
-def _use_mcp_app_for_client(client_params: InitializeRequestParams):
-    # The configuration can overwrite the MCP app support detection, so we have the flexibility to
-    # manually turn the Mcp app feature on/off for developing/testing purposes.
-    if CONFIG.use_mcp_apps is not None:
-        return CONFIG.use_mcp_apps
-
-    # For python-sdk -1.x, count on extensibility of protocol types - while this is being
-    # removed for v2, hopefully extensions will be there properly.
-    capabilities = client_params.capabilities
-    extensions = getattr(capabilities, "extensions", {})
-    mcp_ui_extension = extensions.get(MCP_UI_EXTENSION) or {}
-    mime_types = mcp_ui_extension.get("mimeTypes") or []
-
-    # The configuration can overwrite the MCP app support detection, so we have the flexibility to
-    # manually turn the Mcp app feature on/off for developing/testing purposes.
-    return MCP_APP_MIME_TYPE in mime_types
-
-
 class DynamicDiscoveryMiddleware(Middleware):
     async def on_initialize(
         self,
@@ -253,7 +234,7 @@ async def on_initialize(
         # away in the ServerSession object, so we need to modify that based
         # on whether we'll use mcp-apps with the client making the InitializeRequest.
 
-        if _use_mcp_app_for_client(context.message.params):
+        if use_mcp_app_for_client(context.message.params):
             # Getting the ServerSession object is easy for FastMCP 3.x - it's
             # just context.fastcmp_context.session, but the property getter
             # will raise RuntimeError for FastMCP 2.x, so we check _session instead.
@@ -304,7 +285,7 @@ async def on_list_tools(self, context: MiddlewareContext, call_next):
             "FastMCP framework error: client_params should not be None inside on_list_tools"
         )
 
-        if _use_mcp_app_for_client(client_params):
+        if use_mcp_app_for_client(client_params):
             filtered_tools = [t for t in filtered_tools if "mcp_apps_exclude" not in t.tags]
         else:
             filtered_tools = [t for t in filtered_tools if "mcp_apps_only" not in t.tags]

src/linux_mcp_server/tools/run_script.py

@@ -23,6 +23,7 @@
 from linux_mcp_server.gatekeeper import check_run_script
 from linux_mcp_server.gatekeeper import GatekeeperStatus
 from linux_mcp_server.mcp_app import RUN_SCRIPT_APP_URI
+from linux_mcp_server.mcp_app import use_mcp_app_for_client
 from linux_mcp_server.server import mcp
 from linux_mcp_server.utils.decorators import disallow_local_execution_in_containers
 from linux_mcp_server.utils.types import Host
@@ -368,6 +369,16 @@ async def get_execution_state(id: str):
     return {"state": script_detail.state}
 
 
+def _pick_execution_tool(readonly: bool, needs_confirmation: bool, use_mcp_app: bool):
+    if not needs_confirmation and readonly:
+        return "run_script"
+
+    if use_mcp_app:
+        return "run_script_interactive"
+    else:
+        return "run_script_with_confirmation"
+
+
 @mcp.tool(
     tags={"run_script"},
     title="Validate a script",
@@ -409,8 +420,20 @@ async def validate_script(
         script_store.set_script_state(id, "rejected-gatekeeper")
         raise ToolError(gatekeeper_result.description)
 
+    client_params = ctx.session.client_params
+    assert client_params is not None, "FastMCP framework error: client_params should not be None inside tool"
+
+    execution_tool = _pick_execution_tool(
+        readonly, script_details.needs_confirmation, use_mcp_app_for_client(client_params)
+    )
+
     result = ToolResult(
-        content=[TextContent(type="text", text=f"Script passed gatekeeper validation and is stored with ID {id}")],
+        content=[
+            TextContent(
+                type="text",
+                text=f"Script passed gatekeeper validation and is stored with ID {id}. Please use {execution_tool} to execute the validated script.",
+            )
+        ],
         structured_content={
             "token": id,
             "needs_confirmation": script_details.needs_confirmation,
@@ -433,9 +456,17 @@ async def run_script(
 ) -> str:
     script_details = script_store.get_script_details(token)
 
+    client_params = ctx.session.client_params
+    assert client_params is not None, "FastMCP framework error: client_params should not be None inside tool"
+
+    if use_mcp_app_for_client(client_params):
+        confirmation_tool_name = "run_script_interactive"
+    else:
+        confirmation_tool_name = "run_script_with_confirmation"
+
     # Verify that this script doesn't require confirmation
     if script_details.needs_confirmation:
-        raise ToolError("This script requires confirmation. Use run_script_with_confirmation instead of run_script.")
+        raise ToolError(f"This script requires confirmation. Use {confirmation_tool_name} instead of run_script.")
 
     script_store.set_script_state(token, "executing")
     try:

tests/test_middleware.py

@@ -8,35 +8,39 @@
 from mcp.types import InitializeRequestParams
 from mcp.types import Tool
 
+from linux_mcp_server.mcp_app import MCP_APP_MIME_TYPE
+from linux_mcp_server.mcp_app import MCP_UI_EXTENSION
+
 
 # Workaround: with python-3.10, mocker.patch("linux_mcp_server.server.X")
 # doesn't work because it finds the imported server function rather than the module.
 server_module = importlib.import_module("linux_mcp_server.server")
+mcp_app_module = importlib.import_module("linux_mcp_server.mcp_app")
 
 
 class TestUseMcpAppForClient:
     @pytest.mark.parametrize("config_value,expected", [(True, True), (False, False)])
     def test_config_override(self, mocker, config_value, expected):
         # Test CONFIG.use_mcp_apps override
-        mocker.patch.object(server_module, "CONFIG", use_mcp_apps=config_value)
-        result = server_module._use_mcp_app_for_client(mocker.Mock(spec=InitializeRequestParams))
+        mocker.patch.object(mcp_app_module, "CONFIG", use_mcp_apps=config_value)
+        result = server_module.use_mcp_app_for_client(mocker.Mock(spec=InitializeRequestParams))
         assert result is expected
 
     @pytest.mark.parametrize(
         "extensions,expected",
         [
-            ({server_module.MCP_UI_EXTENSION: {"mimeTypes": [server_module.MCP_APP_MIME_TYPE]}}, True),
+            ({MCP_UI_EXTENSION: {"mimeTypes": [MCP_APP_MIME_TYPE]}}, True),
             ({"other-extension": {}}, False),
         ],
     )
     def test_detection(self, mocker, extensions, expected):
         # Test mcp-app detection from client capabilities
-        mocker.patch.object(server_module, "CONFIG", use_mcp_apps=None)
+        mocker.patch.object(mcp_app_module, "CONFIG", use_mcp_apps=None)
         capabilities = mocker.Mock()
         capabilities.extensions = extensions
         params = mocker.Mock(spec=InitializeRequestParams)
         params.capabilities = capabilities
-        result = server_module._use_mcp_app_for_client(params)
+        result = server_module.use_mcp_app_for_client(params)
         assert result is expected
 
 
@@ -56,7 +60,7 @@ def mock_context(self, mocker):
 
     async def test_skips_modification_when_disabled(self, middleware, mock_context, mocker):
         # Test that instructions are not modified when mcp-apps is disabled
-        mocker.patch.object(server_module, "_use_mcp_app_for_client", return_value=False)
+        mocker.patch.object(server_module, "use_mcp_app_for_client", return_value=False)
 
         mock_session = mocker.Mock(spec=ServerSession)
         mock_session._init_options = mocker.Mock()
@@ -69,7 +73,7 @@ async def test_skips_modification_when_disabled(self, middleware, mock_context,
 
     async def test_modifies_instructions_fastmcp_3x(self, middleware, mock_context, mocker):
         # Test instruction modification with FastMCP 3.x
-        mocker.patch.object(server_module, "_use_mcp_app_for_client", return_value=True)
+        mocker.patch.object(server_module, "use_mcp_app_for_client", return_value=True)
 
         mock_session = mocker.Mock(spec=ServerSession)
         mock_session._init_options = mocker.Mock()
@@ -82,7 +86,7 @@ async def test_modifies_instructions_fastmcp_3x(self, middleware, mock_context,
 
     async def test_modifies_instructions_fastmcp_2x(self, middleware, mock_context, mocker):
         # Test instruction modification with FastMCP 2.x via closure extraction
-        mocker.patch.object(server_module, "_use_mcp_app_for_client", return_value=True)
+        mocker.patch.object(server_module, "use_mcp_app_for_client", return_value=True)
         mock_context.fastmcp_context._session = None
 
         mock_session = mocker.Mock(spec=ServerSession)
@@ -104,7 +108,7 @@ async def call_next_func(_ctx):
 
     async def test_handles_extraction_failure(self, middleware, mock_context, mocker):
         # Test graceful handling when session extraction fails
-        mocker.patch.object(server_module, "_use_mcp_app_for_client", return_value=True)
+        mocker.patch.object(server_module, "use_mcp_app_for_client", return_value=True)
         mock_logger = mocker.patch.object(server_module, "logger")
 
         mock_context.fastmcp_context._session = None
@@ -148,7 +152,7 @@ def _make_tool(self, mocker, name: str, tags: set[str] | None = None) -> Tool:
 
     async def test_filters_when_mcp_apps_enabled(self, middleware, mock_context, mocker):
         # Test that hidden_from_model and mcp_apps_exclude are filtered when enabled
-        mocker.patch.object(server_module, "_use_mcp_app_for_client", return_value=True)
+        mocker.patch.object(server_module, "use_mcp_app_for_client", return_value=True)
 
         tools = [
             self._make_tool(mocker, "regular", set()),
@@ -165,7 +169,7 @@ async def test_filters_when_mcp_apps_enabled(self, middleware, mock_context, moc
 
     async def test_filters_when_mcp_apps_disabled(self, middleware, mock_context, mocker):
         # Test that hidden_from_model and mcp_apps_only are filtered when disabled
-        mocker.patch.object(server_module, "_use_mcp_app_for_client", return_value=False)
+        mocker.patch.object(server_module, "use_mcp_app_for_client", return_value=False)
 
         tools = [
             self._make_tool(mocker, "regular", set()),