Merge branch 'main' into main-sse-disconnect

Author: lcamhoa

README.md

@@ -387,6 +387,8 @@ python server.py
 mcp run server.py
 ```
 
+Note that `mcp run` or `mcp dev` only supports server using FastMCP and not the low-level server variant.
+
 ### Streamable HTTP Transport
 
 > **Note**: Streamable HTTP transport is superseding SSE transport for production deployments.
@@ -694,6 +696,8 @@ if __name__ == "__main__":
     asyncio.run(run())
 ```
 
+Caution: The `mcp run` and `mcp dev` tool doesn't support low-level server.
+
 ### Writing MCP Clients
 
 The SDK provides a high-level client interface for connecting to MCP servers using various [transports](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports):

src/mcp/cli/cli.py

@@ -6,7 +6,10 @@
 import subprocess
 import sys
 from pathlib import Path
-from typing import Annotated
+from typing import Annotated, Any
+
+from mcp.server import FastMCP
+from mcp.server import Server as LowLevelServer
 
 try:
     import typer
@@ -141,17 +144,48 @@ def _import_server(file: Path, server_object: str | None = None):
     module = importlib.util.module_from_spec(spec)
     spec.loader.exec_module(module)
 
+    def _check_server_object(server_object: Any, object_name: str):
+        """Helper function to check that the server object is supported
+
+        Args:
+            server_object: The server object to check.
+
+        Returns:
+            True if it's supported.
+        """
+        if not isinstance(server_object, FastMCP):
+            logger.error(
+                f"The server object {object_name} is of type "
+                f"{type(server_object)} (expecting {FastMCP})."
+            )
+            if isinstance(server_object, LowLevelServer):
+                logger.warning(
+                    "Note that only FastMCP server is supported. Low level "
+                    "Server class is not yet supported."
+                )
+            return False
+        return True
+
     # If no object specified, try common server names
     if not server_object:
         # Look for the most common server object names
         for name in ["mcp", "server", "app"]:
             if hasattr(module, name):
+                if not _check_server_object(getattr(module, name), f"{file}:{name}"):
+                    logger.error(
+                        f"Ignoring object '{file}:{name}' as it's not a valid "
+                        "server object"
+                    )
+                    continue
                 return getattr(module, name)
 
         logger.error(
             f"No server object found in {file}. Please either:\n"
             "1. Use a standard variable name (mcp, server, or app)\n"
-            "2. Specify the object name with file:object syntax",
+            "2. Specify the object name with file:object syntax"
+            "3. If the server creates the FastMCP object within main() "
+            "   or another function, refactor the FastMCP object to be a "
+            "   global variable named mcp, server, or app.",
             extra={"file": str(file)},
         )
         sys.exit(1)
@@ -179,6 +213,9 @@ def _import_server(file: Path, server_object: str | None = None):
         )
         sys.exit(1)
 
+    if not _check_server_object(server, server_object):
+        sys.exit(1)
+
     return server
 
 

src/mcp/client/session.py

@@ -168,7 +168,11 @@ async def send_ping(self) -> types.EmptyResult:
         )
 
     async def send_progress_notification(
-        self, progress_token: str | int, progress: float, total: float | None = None
+        self,
+        progress_token: str | int,
+        progress: float,
+        total: float | None = None,
+        message: str | None = None,
     ) -> None:
         """Send a progress notification."""
         await self.send_notification(
@@ -179,6 +183,7 @@ async def send_progress_notification(
                         progressToken=progress_token,
                         progress=progress,
                         total=total,
+                        message=message,
                     ),
                 ),
             )

src/mcp/client/stdio/__init__.py

@@ -181,6 +181,8 @@ async def stdin_writer():
                 await terminate_windows_process(process)
             else:
                 process.terminate()
+            await read_stream.aclose()
+            await write_stream.aclose()
 
 
 def _get_executable_command(command: str) -> str:

src/mcp/server/fastmcp/server.py

@@ -952,13 +952,14 @@ def request_context(self) -> RequestContext[ServerSessionT, LifespanContextT]:
         return self._request_context
 
     async def report_progress(
-        self, progress: float, total: float | None = None
+        self, progress: float, total: float | None = None, message: str | None = None
     ) -> None:
         """Report progress for the current operation.
 
         Args:
             progress: Current progress value e.g. 24
             total: Optional total value e.g. 100
+            message: Optional message e.g. Starting render...
         """
 
         progress_token = (
@@ -971,7 +972,10 @@ async def report_progress(
             return
 
         await self.request_context.session.send_progress_notification(
-            progress_token=progress_token, progress=progress, total=total
+            progress_token=progress_token,
+            progress=progress,
+            total=total,
+            message=message,
         )
 
     async def read_resource(self, uri: str | AnyUrl) -> Iterable[ReadResourceContents]:

src/mcp/server/lowlevel/server.py

@@ -37,7 +37,8 @@ async def handle_list_resource_templates() -> list[types.ResourceTemplate]:
 3. Define notification handlers if needed:
    @server.progress_notification()
    async def handle_progress(
-       progress_token: str | int, progress: float, total: float | None
+       progress_token: str | int, progress: float, total: float | None,
+       message: str | None
    ) -> None:
        # Implementation
 
@@ -427,13 +428,18 @@ async def handler(req: types.CallToolRequest):
 
     def progress_notification(self):
         def decorator(
-            func: Callable[[str | int, float, float | None], Awaitable[None]],
+            func: Callable[
+                [str | int, float, float | None, str | None], Awaitable[None]
+            ],
         ):
             logger.debug("Registering handler for ProgressNotification")
 
             async def handler(req: types.ProgressNotification):
                 await func(
-                    req.params.progressToken, req.params.progress, req.params.total
+                    req.params.progressToken,
+                    req.params.progress,
+                    req.params.total,
+                    req.params.message,
                 )
 
             self.notification_handlers[types.ProgressNotification] = handler

src/mcp/server/session.py

@@ -282,6 +282,7 @@ async def send_progress_notification(
         progress_token: str | int,
         progress: float,
         total: float | None = None,
+        message: str | None = None,
         related_request_id: str | None = None,
     ) -> None:
         """Send a progress notification."""
@@ -293,6 +294,7 @@ async def send_progress_notification(
                         progressToken=progress_token,
                         progress=progress,
                         total=total,
+                        message=message,
                     ),
                 )
             ),

src/mcp/shared/progress.py

@@ -43,11 +43,11 @@ class ProgressContext(
     total: float | None
     current: float = field(default=0.0, init=False)
 
-    async def progress(self, amount: float) -> None:
+    async def progress(self, amount: float, message: str | None = None) -> None:
         self.current += amount
 
         await self.session.send_progress_notification(
-            self.progress_token, self.current, total=self.total
+            self.progress_token, self.current, total=self.total, message=message
         )
 
 

src/mcp/shared/session.py

@@ -401,7 +401,11 @@ async def _received_notification(self, notification: ReceiveNotificationT) -> No
         """
 
     async def send_progress_notification(
-        self, progress_token: str | int, progress: float, total: float | None = None
+        self,
+        progress_token: str | int,
+        progress: float,
+        total: float | None = None,
+        message: str | None = None,
     ) -> None:
         """
         Sends a progress notification for a request that is currently being

src/mcp/types.py

@@ -337,6 +337,11 @@ class ProgressNotificationParams(NotificationParams):
     total is unknown.
     """
     total: float | None = None
+    """
+    Message related to progress. This should provide relevant human readable 
+    progress information.
+    """
+    message: str | None = None
     """Total number of items to process (or total progress required), if known."""
     model_config = ConfigDict(extra="allow")