fastmcp 2.12.5__py3-none-any.whl → 2.14.0__py3-none-any.whl

fastmcp/utilities/tests.py

@@ -5,13 +5,14 @@ import logging
 import multiprocessing
 import socket
 import time
-from collections.abc import Callable, Generator
-from contextlib import contextmanager
+from collections.abc import AsyncGenerator, Callable, Generator
+from contextlib import asynccontextmanager, contextmanager, suppress
 from typing import TYPE_CHECKING, Any, Literal
 from urllib.parse import parse_qs, urlparse
 
 import httpx
 import uvicorn
+from pytest import LogCaptureFixture
 
 from fastmcp import settings
 from fastmcp.client.auth.oauth import OAuth
@@ -66,6 +67,7 @@ def _run_server(mcp_server: FastMCP, transport: Literal["sse"], port: int) -> No
             host="127.0.0.1",
             port=port,
             log_level="error",
+            ws="websockets-sansio",
         )
     )
     uvicorn_server.run()
@@ -74,11 +76,11 @@ def _run_server(mcp_server: FastMCP, transport: Literal["sse"], port: int) -> No
 @contextmanager
 def run_server_in_process(
     server_fn: Callable[..., None],
-    *args,
+    *args: Any,
     provide_host_and_port: bool = True,
     host: str = "127.0.0.1",
     port: int | None = None,
-    **kwargs,
+    **kwargs: Any,
 ) -> Generator[str, None, None]:
     """
     Context manager that runs a FastMCP server in a separate process and
@@ -139,8 +141,93 @@ def run_server_in_process(
             raise RuntimeError("Server process failed to terminate even after kill")
 
 
+@asynccontextmanager
+async def run_server_async(
+    server: FastMCP,
+    port: int | None = None,
+    transport: Literal["http", "streamable-http", "sse"] = "http",
+    path: str = "/mcp",
+    host: str = "127.0.0.1",
+) -> AsyncGenerator[str, None]:
+    """
+    Start a FastMCP server as an asyncio task for in-process async testing.
+
+    This is the recommended way to test FastMCP servers. It runs the server
+    as an async task in the same process, eliminating subprocess coordination,
+    sleeps, and cleanup issues.
+
+    Args:
+        server: FastMCP server instance
+        port: Port to bind to (default: find available port)
+        transport: Transport type ("http", "streamable-http", or "sse")
+        path: URL path for the server (default: "/mcp")
+        host: Host to bind to (default: "127.0.0.1")
+
+    Yields:
+        Server URL string
+
+    Example:
+        ```python
+        import pytest
+        from fastmcp import FastMCP, Client
+        from fastmcp.client.transports import StreamableHttpTransport
+        from fastmcp.utilities.tests import run_server_async
+
+        @pytest.fixture
+        async def server():
+            mcp = FastMCP("test")
+
+            @mcp.tool()
+            def greet(name: str) -> str:
+                return f"Hello, {name}!"
+
+            async with run_server_async(mcp) as url:
+                yield url
+
+        async def test_greet(server: str):
+            async with Client(StreamableHttpTransport(server)) as client:
+                result = await client.call_tool("greet", {"name": "World"})
+                assert result.content[0].text == "Hello, World!"
+        ```
+    """
+    import asyncio
+
+    if port is None:
+        port = find_available_port()
+
+    # Wait a tiny bit for the port to be released if it was just used
+    await asyncio.sleep(0.01)
+
+    # Start server as a background task
+    server_task = asyncio.create_task(
+        server.run_http_async(
+            host=host,
+            port=port,
+            transport=transport,
+            path=path,
+            show_banner=False,
+        )
+    )
+
+    # Wait for server lifespan to be ready
+    await server._started.wait()
+
+    # Give uvicorn a moment to bind the port after lifespan is ready
+    await asyncio.sleep(0.1)
+
+    try:
+        yield f"http://{host}:{port}{path}"
+    finally:
+        # Cleanup: cancel the task with timeout to avoid hanging on Windows
+        server_task.cancel()
+        with suppress(asyncio.CancelledError, asyncio.TimeoutError):
+            await asyncio.wait_for(server_task, timeout=2.0)
+
+
 @contextmanager
-def caplog_for_fastmcp(caplog):
+def caplog_for_fastmcp(
+    caplog: LogCaptureFixture,
+) -> Generator[LogCaptureFixture, None, None]:
     """Context manager to capture logs from FastMCP loggers even when propagation is disabled."""
     caplog.clear()
     logger = logging.getLogger("fastmcp")

fastmcp/utilities/types.py

@@ -175,6 +175,63 @@ def find_kwarg_by_type(fn: Callable, kwarg_type: type) -> str | None:
     return None
 
 
+def create_function_without_params(
+    fn: Callable[..., Any], exclude_params: list[str]
+) -> Callable[..., Any]:
+    """
+    Create a new function with the same code but without the specified parameters in annotations.
+
+    This is used to exclude parameters from type adapter processing when they can't be serialized.
+    The excluded parameters are removed from the function's __annotations__ dictionary.
+    """
+    import types
+
+    if inspect.ismethod(fn):
+        actual_func = fn.__func__
+        code = actual_func.__code__  # ty: ignore[unresolved-attribute]
+        globals_dict = actual_func.__globals__  # ty: ignore[unresolved-attribute]
+        name = actual_func.__name__  # ty: ignore[unresolved-attribute]
+        defaults = actual_func.__defaults__  # ty: ignore[unresolved-attribute]
+        closure = actual_func.__closure__  # ty: ignore[unresolved-attribute]
+    else:
+        code = fn.__code__  # ty: ignore[unresolved-attribute]
+        globals_dict = fn.__globals__  # ty: ignore[unresolved-attribute]
+        name = fn.__name__  # ty: ignore[unresolved-attribute]
+        defaults = fn.__defaults__  # ty: ignore[unresolved-attribute]
+        closure = fn.__closure__  # ty: ignore[unresolved-attribute]
+
+    # Create a copy of annotations without the excluded parameters
+    original_annotations = getattr(fn, "__annotations__", {})
+    new_annotations = {
+        k: v for k, v in original_annotations.items() if k not in exclude_params
+    }
+
+    # Create new signature without the excluded parameters
+    sig = inspect.signature(fn)
+    new_params = [
+        param for name, param in sig.parameters.items() if name not in exclude_params
+    ]
+    new_sig = inspect.Signature(new_params, return_annotation=sig.return_annotation)
+
+    new_func = types.FunctionType(
+        code,
+        globals_dict,
+        name,
+        defaults,
+        closure,
+    )
+    new_func.__dict__.update(fn.__dict__)
+    new_func.__module__ = fn.__module__
+    new_func.__qualname__ = getattr(fn, "__qualname__", fn.__name__)  # ty: ignore[unresolved-attribute]
+    new_func.__annotations__ = new_annotations
+    new_func.__signature__ = new_sig  # type: ignore[attr-defined]
+
+    if inspect.ismethod(fn):
+        return types.MethodType(new_func, fn.__self__)
+    else:
+        return new_func
+
+
 class Image:
     """Helper class for returning images from tools."""
 
@@ -190,34 +247,33 @@ class Image:
         if path is not None and data is not None:
             raise ValueError("Only one of path or data can be provided")
 
-        self.path = Path(os.path.expandvars(str(path))).expanduser() if path else None
+        self.path = self._get_expanded_path(path)
         self.data = data
         self._format = format
         self._mime_type = self._get_mime_type()
         self.annotations = annotations
 
+    @staticmethod
+    def _get_expanded_path(path: str | Path | None) -> Path | None:
+        """Expand environment variables and user home in path."""
+        return Path(os.path.expandvars(str(path))).expanduser() if path else None
+
     def _get_mime_type(self) -> str:
         """Get MIME type from format or guess from file extension."""
         if self._format:
             return f"image/{self._format.lower()}"
 
         if self.path:
-            suffix = self.path.suffix.lower()
-            return {
-                ".png": "image/png",
-                ".jpg": "image/jpeg",
-                ".jpeg": "image/jpeg",
-                ".gif": "image/gif",
-                ".webp": "image/webp",
-            }.get(suffix, "application/octet-stream")
+            # Workaround for WEBP in Py3.10
+            mimetypes.add_type("image/webp", ".webp")
+            resp = mimetypes.guess_type(self.path, strict=False)
+            if resp and resp[0] is not None:
+                return resp[0]
+            return "application/octet-stream"
         return "image/png"  # default for raw binary data
 
-    def to_image_content(
-        self,
-        mime_type: str | None = None,
-        annotations: Annotations | None = None,
-    ) -> mcp.types.ImageContent:
-        """Convert to MCP ImageContent."""
+    def _get_data(self) -> str:
+        """Get raw image data as base64-encoded string."""
         if self.path:
             with open(self.path, "rb") as f:
                 data = base64.b64encode(f.read()).decode()
@@ -225,6 +281,15 @@ class Image:
             data = base64.b64encode(self.data).decode()
         else:
             raise ValueError("No image data available")
+        return data
+
+    def to_image_content(
+        self,
+        mime_type: str | None = None,
+        annotations: Annotations | None = None,
+    ) -> mcp.types.ImageContent:
+        """Convert to MCP ImageContent."""
+        data = self._get_data()
 
         return mcp.types.ImageContent(
             type="image",
@@ -233,6 +298,11 @@ class Image:
             annotations=annotations or self.annotations,
         )
 
+    def to_data_uri(self, mime_type: str | None = None) -> str:
+        """Get image as a data URI."""
+        data = self._get_data()
+        return f"data:{mime_type or self._mime_type};base64,{data}"
+
 
 class Audio:
     """Helper class for returning audio from tools."""
@@ -293,7 +363,7 @@ class Audio:
 
 
 class File:
-    """Helper class for returning audio from tools."""
+    """Helper class for returning file data from tools."""
 
     def __init__(
         self,