style: ruff format and lint; clarify SSE relative endpoint comments and tests

Author: SOURABHMISHRA5221

src/mcp/server/sse.py

@@ -2,16 +2,15 @@
 SSE Server Transport Module
 
 This module implements a Server-Sent Events (SSE) transport layer for MCP servers.
-Fixes the URL path joining issue when using subpaths/proxied servers.
+Endpoints are specified as relative paths. This aligns with common client URL
+construction patterns (for example, `urllib.parse.urljoin`) and works correctly
+when applications are deployed behind proxies or at subpaths.
 
 Example usage:
 ```python
-    # Option 1: Create an SSE transport with absolute path (leading slash)
-    # This treats "/messages/" as absolute within the app
-    sse = SseServerTransport("/messages/")
-
-    # Option 2: Create an SSE transport with relative path (no leading slash)
-    # This treats "messages/" as relative to the root path - RECOMMENDED for proxied servers
+    # Recommended: provide a relative path segment (no scheme/host/query/fragment).
+    # Using "messages/" works well with clients that build absolute URLs using
+    # `urllib.parse.urljoin`, including in proxied/subpath deployments.
     sse = SseServerTransport("messages/")
 
     # Create Starlette routes for SSE and message handling
@@ -36,14 +35,16 @@ async def handle_sse(request):
     uvicorn.run(starlette_app, host="127.0.0.1", port=port)
 ```
 
-Path behavior examples:
-- With root_path="" and endpoint="/messages/": Final path = "/messages/"
-- With root_path="" and endpoint="messages/": Final path = "/messages/"
-- With root_path="/api" and endpoint="/messages/": Final path = "/api/messages/"
-- With root_path="/api" and endpoint="messages/": Final path = "/api/messages/"
+Path behavior examples inside the server (final path emitted to clients):
+- root_path="" and endpoint="messages/"  -> "/messages/"
+- root_path="/api" and endpoint="messages/" -> "/api/messages/"
+
+Note: When clients use `urllib.parse.urljoin(base, path)`, joining a segment that
+starts with "/" replaces the base path. Providing a relative segment like
+`"messages/?id=1"` preserves the base path as intended.
 
-For servers behind proxies or mounted at subpaths, use the relative path format
-(without leading slash) to ensure proper URL joining with urllib.parse.urljoin().
+For servers behind proxies or mounted at subpaths, prefer a relative path without
+leading slash (e.g., "messages/") to ensure correct joining with `urljoin`.
 
 Note: The handle_sse function must return a Response to avoid a "TypeError: 'NoneType'
 object is not callable" error when client disconnects. The example above returns
@@ -98,8 +99,10 @@ def __init__(self, endpoint: str, security_settings: TransportSecuritySettings |
         messages to the relative path given.
 
         Args:
-            endpoint: A relative path where messages should be posted
-                    (e.g., "/messages/" or "messages/").
+            endpoint: Relative path segment where messages should be posted
+                    (e.g., "messages/"). Avoid scheme/host/query/fragment. When
+                    clients construct absolute URLs using `urllib.parse.urljoin`,
+                    relative segments preserve any existing base path.
             security_settings: Optional security settings for DNS rebinding protection.
 
         Note:
@@ -111,25 +114,24 @@ def __init__(self, endpoint: str, security_settings: TransportSecuritySettings |
             3. Portability: The same endpoint configuration works across different
                environments (development, staging, production)
 
-        The endpoint path handling has been updated to work correctly with urllib.parse.urljoin()
-        when servers are behind proxies or mounted at subpaths.
+        The endpoint path handling preserves the provided relative path and is
+        suitable for deployments under proxies or subpaths.
 
         Raises:
             ValueError: If the endpoint is a full URL instead of a relative path
         """
 
         super().__init__()
 
-        # Validate that endpoint is a relative path and not a full URL
+        # Validate that endpoint is a relative path and not a full URL.
         if "://" in endpoint or endpoint.startswith("//") or "?" in endpoint or "#" in endpoint:
             raise ValueError(
-                f"Given endpoint: {endpoint} is not a relative path (e.g., '/messages/' or 'messages/'), "
-                "expecting a relative path (e.g., '/messages/' or 'messages/')."
+                f"Given endpoint: {endpoint} is not a relative path (e.g., 'messages/'), "
+                "expecting a relative path with no scheme/host/query/fragment."
             )
 
-        # Handle leading slash more intelligently
-        # Remove automatic leading slash enforcement to support proper URL joining
-        # Store the endpoint as-is, allowing both "/messages/" and "messages/" formats
+        # Store the endpoint as provided to retain relative-path semantics and make
+        # client URL construction predictable across deployment topologies.
         self._endpoint = endpoint
         self._read_stream_writers = {}
         self._security = TransportSecurityMiddleware(security_settings)
@@ -139,8 +141,9 @@ def _build_message_path(self, root_path: str) -> str:
         """
         Helper method to properly construct the message path
 
-        This method handles the path construction logic that was causing issues
-        with urllib.parse.urljoin() when servers are proxied or mounted at subpaths.
+        Constructs the message path relative to the app's mount point and the
+        provided `root_path`. The stored endpoint is treated as path-absolute if
+        it starts with "/", otherwise as a relative segment.
 
         Args:
             root_path: The root path from ASGI scope (e.g., "" or "/api_prefix")
@@ -151,10 +154,10 @@ def _build_message_path(self, root_path: str) -> str:
         # Clean up the root path
         clean_root_path = root_path.rstrip("/")
 
-        # If endpoint starts with "/", it's meant to be absolute within the app
-        # If endpoint doesn't start with "/", it's meant to be relative to root_path
+        # If endpoint starts with "/", treat it as path-absolute from the app mount;
+        # otherwise, treat it as relative to `root_path`.
         if self._endpoint.startswith("/"):
-            # Absolute path within the app - just concatenate
+            # Path-absolute within the app mount - just concatenate
             full_path = clean_root_path + self._endpoint
         else:
             # Relative path - ensure proper joining

tests/server/test_sse_security.py

@@ -295,8 +295,21 @@ async def test_sse_security_post_valid_content_type(server_port: int):
 
 @pytest.mark.anyio
 async def test_endpoint_validation_rejects_absolute_urls():
-    """Test that SseServerTransport properly validates endpoint format."""
-    # These should all raise ValueError due to being absolute URLs or having invalid characters
+    """Validate endpoint format: relative path segments only.
+
+    Context on URL joining (urllib.parse.urljoin):
+    - Joining a segment starting with "/" resets to the host root:
+      urljoin("http://host/app/sse", "/messages") -> "http://host/messages"
+    - Joining a relative segment appends relative to the base:
+      urljoin("http://host/hello/world", "messages") -> "http://host/hello/messages"
+      urljoin("http://host/hello/world/", "messages") -> "http://host/hello/world/messages"
+
+    This test ensures the transport accepts relative path segments (e.g., "messages/"),
+    rejects full URLs or paths containing query/fragment components, and stores accepted
+    values verbatim (no normalization). Both leading-slash and non-leading-slash forms
+    are permitted because the server handles construction relative to its mount path.
+    """
+    # Reject: fully-qualified URLs and segments that include query/fragment
     invalid_endpoints = [
         "http://example.com/messages/",
         "https://example.com/messages/",
@@ -309,10 +322,10 @@ async def test_endpoint_validation_rejects_absolute_urls():
         with pytest.raises(ValueError, match="is not a relative path"):
             SseServerTransport(invalid_endpoint)
 
-    # These should all be valid - endpoint is stored as-is (no automatic normalization)
+    # Accept: relative path forms; endpoint is stored as provided (no normalization)
     valid_endpoints_and_expected = [
-        ("/messages/", "/messages/"),  # Absolute path format
-        ("messages/", "messages/"),  # Relative path format
+        ("/messages/", "/messages/"),  # Leading-slash path segment
+        ("messages/", "messages/"),  # Non-leading-slash path segment
         ("/api/v1/messages/", "/api/v1/messages/"),
         ("api/v1/messages/", "api/v1/messages/"),
     ]

tests/shared/test_sse.py

@@ -487,7 +487,7 @@ def test_sse_message_id_coercion():
 @pytest.mark.parametrize(
     "endpoint, expected_result",
     [
-        # These should all be valid - endpoint is stored as-is (no automatic normalization)
+        # Accept: relative path forms; endpoint is stored verbatim (no normalization)
         ("/messages/", "/messages/"),
         ("messages/", "messages/"),
         ("/", "/"),
@@ -500,7 +500,18 @@ def test_sse_message_id_coercion():
     ],
 )
 def test_sse_server_transport_endpoint_validation(endpoint: str, expected_result: str | type[Exception]):
-    """Test that SseServerTransport properly validates and normalizes endpoints."""
+    """Validate relative endpoint semantics and storage.
+
+    Context on URL joining (urllib.parse.urljoin):
+    - Joining a segment starting with "/" resets to the host root:
+      urljoin("http://host/hello/world", "/messages") -> "http://host/messages"
+    - Joining a relative segment appends relative to the base:
+      urljoin("http://host/hello/world", "messages") -> "http://host/hello/messages"
+      urljoin("http://host/hello/world/", "messages/") -> "http://host/hello/world/messages/"
+
+    The transport validates that endpoints are relative path segments (no scheme/host/query/fragment)
+    and stores accepted values exactly as provided.
+    """
     if isinstance(expected_result, type) and issubclass(expected_result, Exception):
         # Test invalid endpoints that should raise an exception
         with pytest.raises(expected_result, match="is not a relative path.*expecting a relative path"):