fastmcp 2.12.4__py3-none-any.whl → 2.13.0rc1__py3-none-any.whl

fastmcp/utilities/logging.py

@@ -6,6 +6,7 @@ from typing import Any, Literal, cast
 
 from rich.console import Console
 from rich.logging import RichHandler
+from typing_extensions import override
 
 import fastmcp
 
@@ -19,7 +20,10 @@ def get_logger(name: str) -> logging.Logger:
     Returns:
         a configured logger instance
     """
-    return logging.getLogger(f"fastmcp.{name}")
+    if name.startswith("fastmcp."):
+        return logging.getLogger(name=name)
+
+    return logging.getLogger(name=f"fastmcp.{name}")
 
 
 def configure_logging(
@@ -47,25 +51,48 @@ def configure_logging(
     if logger is None:
         logger = logging.getLogger("fastmcp")
 
-    # Only configure the FastMCP logger namespace
+    formatter = logging.Formatter("%(message)s")
+
+    # Don't propagate to the root logger
+    logger.propagate = False
+    logger.setLevel(level)
+
+    # Configure the handler for normal logs
     handler = RichHandler(
         console=Console(stderr=True),
-        rich_tracebacks=enable_rich_tracebacks,
         **rich_kwargs,
     )
-    formatter = logging.Formatter("%(message)s")
     handler.setFormatter(formatter)
 
-    logger.setLevel(level)
+    # filter to exclude tracebacks
+    handler.addFilter(lambda record: record.exc_info is None)
+
+    # Configure the handler for tracebacks, for tracebacks we use a compressed format:
+    # no path or level name to maximize width available for the traceback
+    # suppress framework frames and limit the number of frames to 3
+
+    import mcp
+    import pydantic
+
+    traceback_handler = RichHandler(
+        console=Console(stderr=True),
+        show_path=False,
+        show_level=False,
+        rich_tracebacks=enable_rich_tracebacks,
+        tracebacks_max_frames=3,
+        tracebacks_suppress=[fastmcp, mcp, pydantic],
+        **rich_kwargs,
+    )
+    traceback_handler.setFormatter(formatter)
+
+    traceback_handler.addFilter(lambda record: record.exc_info is not None)
 
     # Remove any existing handlers to avoid duplicates on reconfiguration
     for hdlr in logger.handlers[:]:
         logger.removeHandler(hdlr)
 
     logger.addHandler(handler)
-
-    # Don't propagate to the root logger
-    logger.propagate = False
+    logger.addHandler(traceback_handler)
 
 
 @contextlib.contextmanager
@@ -118,3 +145,86 @@ def temporary_log_level(
             )
     else:
         yield
+
+
+class _ClampedLogFilter(logging.Filter):
+    min_level: tuple[int, str] | None
+    max_level: tuple[int, str] | None
+
+    def __init__(
+        self,
+        min_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+        | None = None,
+        max_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+        | None = None,
+    ):
+        self.min_level = None
+        self.max_level = None
+
+        if min_level_no := self._level_to_no(level=min_level):
+            self.min_level = (min_level_no, str(min_level))
+        if max_level_no := self._level_to_no(level=max_level):
+            self.max_level = (max_level_no, str(max_level))
+
+        super().__init__()
+
+    def _level_to_no(
+        self, level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] | None
+    ) -> int | None:
+        if level == "DEBUG":
+            return logging.DEBUG
+        elif level == "INFO":
+            return logging.INFO
+        elif level == "WARNING":
+            return logging.WARNING
+        elif level == "ERROR":
+            return logging.ERROR
+        elif level == "CRITICAL":
+            return logging.CRITICAL
+        else:
+            return None
+
+    @override
+    def filter(self, record: logging.LogRecord) -> bool:
+        if self.max_level:
+            max_level_no, max_level_name = self.max_level
+
+            if record.levelno > max_level_no:
+                record.levelno = max_level_no
+                record.levelname = max_level_name
+                return True
+
+        if self.min_level:
+            min_level_no, min_level_name = self.min_level
+            if record.levelno < min_level_no:
+                record.levelno = min_level_no
+                record.levelname = min_level_name
+                return True
+
+        return True
+
+
+def _clamp_logger(
+    logger: logging.Logger,
+    min_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] | None = None,
+    max_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] | None = None,
+) -> None:
+    """Clamp the logger to a minimum and maximum level.
+
+    If min_level is provided, messages logged at a lower level than `min_level` will have their level increased to `min_level`.
+    If max_level is provided, messages logged at a higher level than `max_level` will have their level decreased to `max_level`.
+
+    Args:
+        min_level: The lower bound of the clamp
+        max_level: The upper bound of the clamp
+    """
+    _unclamp_logger(logger=logger)
+
+    logger.addFilter(filter=_ClampedLogFilter(min_level=min_level, max_level=max_level))
+
+
+def _unclamp_logger(logger: logging.Logger) -> None:
+    """Remove all clamped log filters from the logger."""
+    for filter in logger.filters[:]:
+        if isinstance(filter, _ClampedLogFilter):
+            logger.removeFilter(filter)

fastmcp/utilities/mcp_server_config/v1/environments/uv.py

@@ -28,19 +28,19 @@ class UVEnvironment(Environment):
         examples=[["fastmcp>=2.0,<3", "httpx", "pandas>=2.0"]],
     )
 
-    requirements: str | None = Field(
+    requirements: Path | None = Field(
         default=None,
         description="Path to requirements.txt file",
         examples=["requirements.txt", "../requirements/prod.txt"],
     )
 
-    project: str | None = Field(
+    project: Path | None = Field(
         default=None,
         description="Path to project directory containing pyproject.toml",
         examples=[".", "../my-project"],
     )
 
-    editable: list[str] | None = Field(
+    editable: list[Path] | None = Field(
         default=None,
         description="Directories to install in editable mode",
         examples=[[".", "../my-package"], ["/path/to/package"]],
@@ -64,7 +64,7 @@ class UVEnvironment(Environment):
 
         # Add project if specified
         if self.project:
-            args.extend(["--project", str(self.project)])
+            args.extend(["--project", str(self.project.resolve())])
 
         # Add Python version if specified (only if no project, as project has its own Python)
         if self.python and not self.project:
@@ -78,12 +78,12 @@ class UVEnvironment(Environment):
 
         # Add requirements file
         if self.requirements:
-            args.extend(["--with-requirements", str(self.requirements)])
+            args.extend(["--with-requirements", str(self.requirements.resolve())])
 
         # Add editable packages
         if self.editable:
             for editable_path in self.editable:
-                args.extend(["--with-editable", str(editable_path)])
+                args.extend(["--with-editable", str(editable_path.resolve())])
 
         # Add the command
         args.extend(command)

fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py

@@ -291,9 +291,9 @@ class MCPServerConfig(BaseModel):
             environment = UVEnvironment(
                 python=python,
                 dependencies=dependencies,
-                requirements=requirements,
-                project=project,
-                editable=[editable] if editable else None,
+                requirements=Path(requirements) if requirements else None,
+                project=Path(project) if project else None,
+                editable=[Path(editable)] if editable else None,
             )
 
         # Build deployment config if any deployment args provided

fastmcp/utilities/mcp_server_config/v1/schema.json

@@ -250,6 +250,7 @@
         "requirements": {
           "anyOf": [
             {
+              "format": "path",
               "type": "string"
             },
             {
@@ -267,6 +268,7 @@
         "project": {
           "anyOf": [
             {
+              "format": "path",
               "type": "string"
             },
             {
@@ -285,6 +287,7 @@
           "anyOf": [
             {
               "items": {
+                "format": "path",
                 "type": "string"
               },
               "type": "array"

fastmcp/utilities/tests.py

@@ -5,8 +5,8 @@ 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
 from typing import TYPE_CHECKING, Any, Literal
 from urllib.parse import parse_qs, urlparse
 
@@ -66,6 +66,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 +75,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,6 +140,88 @@ 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,
+        )
+    )
+
+    # Give the server a moment to start
+    await asyncio.sleep(0.1)
+
+    try:
+        yield f"http://{host}:{port}{path}"
+    finally:
+        # Cleanup: cancel the task
+        server_task.cancel()
+        try:
+            await server_task
+        except asyncio.CancelledError:
+            pass
+
+
 @contextmanager
 def caplog_for_fastmcp(caplog):
     """Context manager to capture logs from FastMCP loggers even when propagation is disabled."""

fastmcp/utilities/types.py

@@ -293,7 +293,7 @@ class Audio:
 
 
 class File:
-    """Helper class for returning audio from tools."""
+    """Helper class for returning file data from tools."""
 
     def __init__(
         self,