fix: MCP spec compliance and transport parity

- Remove invalid 'roots' field from ServerCapabilities per MCP spec 2025-06-18
  Server capabilities should only include: prompts, resources, tools, logging,
  completions, and experimental. roots is a client capability, not server.

- Add missing handlers to streamablehttp transport for feature parity with SSE/RPC:
  * list_resource_templates: Enables resources/templates/list via streamablehttp
  * set_logging_level: Adds logging/setLevel support
  * completion: Provides argument completion suggestions
  This ensures both transports advertise the same capabilities.

- Fix resources/read in streamablehttp to return proper content:
  * Return blob content for binary resources
  * Return text content for text resources
  * Return empty string (not empty list) on errors for correct type signature
  * Fixes empty contents issue reported via MCP inspector

- Update tests to match corrected return type (str/bytes instead of list)

Closes issues found during MCP inspector testing:
  1. Missing elicitation in capabilities (not needed - client capability)
  2. Different capabilities between streamablehttp and SSE (now fixed)
  3. resources/templates/list not working in streamablehttp (now fixed)
  4. resources/read returning empty contents (now fixed)

Signed-off-by: Mihai Criveti <[email protected]>

Author: crivetimihai

mcpgateway/cache/session_registry.py

@@ -1258,7 +1258,6 @@ async def handle_initialize_logic(self, body: Dict[str, Any], session_id: Option
                 tools={"listChanged": True},
                 logging={},
                 completions={},  # Advertise completions capability per MCP spec
-                roots={"listChanged": True},  # Advertise roots capability (roots/list now implemented)
             ),
             serverInfo=Implementation(name=settings.app_name, version=__version__),
             instructions=("MCP Gateway providing federated tools, resources and prompts. Use /admin interface for configuration."),

mcpgateway/transports/streamablehttp_transport.py

@@ -55,6 +55,8 @@
 # First-Party
 from mcpgateway.config import settings
 from mcpgateway.db import SessionLocal
+from mcpgateway.models import LogLevel
+from mcpgateway.services.completion_service import CompletionService
 from mcpgateway.services.logging_service import LoggingService
 from mcpgateway.services.prompt_service import PromptService
 from mcpgateway.services.resource_service import ResourceService
@@ -65,10 +67,11 @@
 logging_service = LoggingService()
 logger = logging_service.get_logger(__name__)
 
-# Initialize ToolService, PromptService and MCP Server
+# Initialize ToolService, PromptService, ResourceService, CompletionService and MCP Server
 tool_service: ToolService = ToolService()
 prompt_service: PromptService = PromptService()
 resource_service: ResourceService = ResourceService()
+completion_service: CompletionService = CompletionService()
 
 mcp_app: Server[Any] = Server("mcp-streamable-http")
 
@@ -555,8 +558,8 @@ async def read_resource(resource_id: str) -> Union[str, bytes]:
         resource_id (str): The ID of the resource to read.
 
     Returns:
-        Union[str, bytes]: The content of the resource, typically as text.
-        Returns an empty list on failure or if no content is found.
+        Union[str, bytes]: The content of the resource as text or binary data.
+        Returns empty string on failure or if no content is found.
 
     Logs exceptions if any errors occur during reading.
 
@@ -574,17 +577,130 @@ async def read_resource(resource_id: str) -> Union[str, bytes]:
                 result = await resource_service.read_resource(db=db, resource_id=resource_id)
             except Exception as e:
                 logger.exception(f"Error reading resource '{resource_id}': {e}")
-                return []
-            if not result or not result.text:
-                logger.warning(f"No content returned by resource: {resource_id}")
-                return []
+                return ""
+
+            # Return blob content if available (binary resources)
+            if result and result.blob:
+                return result.blob
+
+            # Return text content if available (text resources)
+            if result and result.text:
+                return result.text
 
-            return result.text
+            # No content found
+            logger.warning(f"No content returned by resource: {resource_id}")
+            return ""
     except Exception as e:
         logger.exception(f"Error reading resource '{resource_id}': {e}")
+        return ""
+
+
+@mcp_app.list_resource_templates()
+async def list_resource_templates() -> List[types.ResourceTemplate]:
+    """
+    Lists all resource templates available to the MCP Server.
+
+    Returns:
+        List[types.ResourceTemplate]: A list of resource templates with their URIs and metadata.
+
+    Examples:
+        >>> import inspect
+        >>> sig = inspect.signature(list_resource_templates)
+        >>> list(sig.parameters.keys())
+        []
+        >>> sig.return_annotation.__origin__.__name__
+        'list'
+    """
+    try:
+        async with get_db() as db:
+            try:
+                resource_templates = await resource_service.list_resource_templates(db)
+                return resource_templates
+            except Exception as e:
+                logger.exception(f"Error listing resource templates: {e}")
+                return []
+    except Exception as e:
+        logger.exception(f"Error listing resource templates: {e}")
         return []
 
 
+@mcp_app.set_logging_level()
+async def set_logging_level(level: types.LoggingLevel) -> types.EmptyResult:
+    """
+    Sets the logging level for the MCP Server.
+
+    Args:
+        level (types.LoggingLevel): The desired logging level (debug, info, notice, warning, error, critical, alert, emergency).
+
+    Returns:
+        types.EmptyResult: An empty result indicating success.
+
+    Examples:
+        >>> import inspect
+        >>> sig = inspect.signature(set_logging_level)
+        >>> list(sig.parameters.keys())
+        ['level']
+    """
+    try:
+        # Convert MCP logging level to our LogLevel enum
+        level_map = {
+            "debug": LogLevel.DEBUG,
+            "info": LogLevel.INFO,
+            "notice": LogLevel.INFO,
+            "warning": LogLevel.WARNING,
+            "error": LogLevel.ERROR,
+            "critical": LogLevel.CRITICAL,
+            "alert": LogLevel.CRITICAL,
+            "emergency": LogLevel.CRITICAL,
+        }
+        log_level = level_map.get(level.lower(), LogLevel.INFO)
+        await logging_service.set_level(log_level)
+        return types.EmptyResult()
+    except Exception as e:
+        logger.exception(f"Error setting logging level: {e}")
+        return types.EmptyResult()
+
+
+@mcp_app.completion()
+async def complete(ref: Union[types.PromptReference, types.ResourceReference], argument: types.CompleteRequest) -> types.CompleteResult:
+    """
+    Provides argument completion suggestions for prompts or resources.
+
+    Args:
+        ref (Union[types.PromptReference, types.ResourceReference]): Reference to the prompt or resource.
+        argument (types.CompleteRequest): The completion request with partial argument value.
+
+    Returns:
+        types.CompleteResult: Completion suggestions.
+
+    Examples:
+        >>> import inspect
+        >>> sig = inspect.signature(complete)
+        >>> list(sig.parameters.keys())
+        ['ref', 'argument']
+    """
+    try:
+        async with get_db() as db:
+            try:
+                # Convert types to dict for completion service
+                params = {
+                    "ref": ref.model_dump() if hasattr(ref, "model_dump") else ref,
+                    "argument": argument.model_dump() if hasattr(argument, "model_dump") else argument,
+                }
+                result = await completion_service.handle_completion(db, params)
+
+                # Convert result to CompleteResult
+                if isinstance(result, dict):
+                    return types.CompleteResult(**result)
+                return result
+            except Exception as e:
+                logger.exception(f"Error handling completion: {e}")
+                return types.CompleteResult(completion=types.Completion(values=[], total=0, hasMore=False))
+    except Exception as e:
+        logger.exception(f"Error handling completion: {e}")
+        return types.CompleteResult(completion=types.Completion(values=[], total=0, hasMore=False))
+
+
 class SessionManagerWrapper:
     """
     Wrapper class for managing the lifecycle of a StreamableHTTPSessionManager instance.

tests/unit/mcpgateway/transports/test_streamablehttp_transport.py

@@ -717,6 +717,7 @@ async def test_read_resource_success(monkeypatch):
     mock_db = MagicMock()
     mock_result = MagicMock()
     mock_result.text = "resource content here"
+    mock_result.blob = None  # Explicitly set to None so text is returned
 
     @asynccontextmanager
     async def fake_get_db():
@@ -733,7 +734,7 @@ async def fake_get_db():
 
 @pytest.mark.asyncio
 async def test_read_resource_no_content(monkeypatch, caplog):
-    """Test read_resource returns [] and logs warning if no content."""
+    """Test read_resource returns empty string and logs warning if no content."""
     # Third-Party
     from pydantic import AnyUrl
 
@@ -743,6 +744,7 @@ async def test_read_resource_no_content(monkeypatch, caplog):
     mock_db = MagicMock()
     mock_result = MagicMock()
     mock_result.text = ""
+    mock_result.blob = None
 
     @asynccontextmanager
     async def fake_get_db():
@@ -754,13 +756,13 @@ async def fake_get_db():
     test_uri = AnyUrl("file:///empty.txt")
     with caplog.at_level("WARNING"):
         result = await read_resource(test_uri)
-        assert result == []
+        assert result == ""
         assert "No content returned by resource: file:///empty.txt" in caplog.text
 
 
 @pytest.mark.asyncio
 async def test_read_resource_no_result(monkeypatch, caplog):
-    """Test read_resource returns [] and logs warning if no result."""
+    """Test read_resource returns empty string and logs warning if no result."""
     # Third-Party
     from pydantic import AnyUrl
 
@@ -779,13 +781,13 @@ async def fake_get_db():
     test_uri = AnyUrl("file:///missing.txt")
     with caplog.at_level("WARNING"):
         result = await read_resource(test_uri)
-        assert result == []
+        assert result == ""
         assert "No content returned by resource: file:///missing.txt" in caplog.text
 
 
 @pytest.mark.asyncio
 async def test_read_resource_service_exception(monkeypatch, caplog):
-    """Test read_resource returns [] and logs exception from service."""
+    """Test read_resource returns empty string and logs exception from service."""
     # Third-Party
     from pydantic import AnyUrl
 
@@ -804,13 +806,13 @@ async def fake_get_db():
     test_uri = AnyUrl("file:///error.txt")
     with caplog.at_level("ERROR"):
         result = await read_resource(test_uri)
-        assert result == []
+        assert result == ""
         assert "Error reading resource 'file:///error.txt': service error!" in caplog.text
 
 
 @pytest.mark.asyncio
 async def test_read_resource_outer_exception(monkeypatch, caplog):
-    """Test read_resource returns [] and logs exception from outer try-catch."""
+    """Test read_resource returns empty string and logs exception from outer try-catch."""
     # Standard
     from contextlib import asynccontextmanager
 
@@ -831,7 +833,7 @@ async def failing_get_db():
     test_uri = AnyUrl("file:///db_error.txt")
     with caplog.at_level("ERROR"):
         result = await read_resource(test_uri)
-        assert result == []
+        assert result == ""
         assert "Error reading resource 'file:///db_error.txt': db error!" in caplog.text