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

fastmcp/utilities/inspect.py

@@ -28,6 +28,7 @@ class ToolInfo:
     tags: list[str] | None = None
     enabled: bool | None = None
     title: str | None = None
+    icons: list[dict[str, Any]] | None = None
     meta: dict[str, Any] | None = None
 
 
@@ -42,6 +43,7 @@ class PromptInfo:
     tags: list[str] | None = None
     enabled: bool | None = None
     title: str | None = None
+    icons: list[dict[str, Any]] | None = None
     meta: dict[str, Any] | None = None
 
 
@@ -58,6 +60,7 @@ class ResourceInfo:
     tags: list[str] | None = None
     enabled: bool | None = None
     title: str | None = None
+    icons: list[dict[str, Any]] | None = None
     meta: dict[str, Any] | None = None
 
 
@@ -75,6 +78,7 @@ class TemplateInfo:
     tags: list[str] | None = None
     enabled: bool | None = None
     title: str | None = None
+    icons: list[dict[str, Any]] | None = None
     meta: dict[str, Any] | None = None
 
 
@@ -85,6 +89,8 @@ class FastMCPInfo:
     name: str
     instructions: str | None
     version: str | None  # The server's own version string (if specified)
+    website_url: str | None
+    icons: list[dict[str, Any]] | None
     fastmcp_version: str  # Version of FastMCP generating this manifest
     mcp_version: str  # Version of MCP protocol library
     server_generation: int  # Server generation: 1 (mcp package) or 2 (fastmcp)
@@ -104,21 +110,20 @@ async def inspect_fastmcp_v2(mcp: FastMCP[Any]) -> FastMCPInfo:
     Returns:
         FastMCPInfo dataclass containing the extracted information
     """
-    # Get all the components using FastMCP2's direct methods
-    tools_dict = await mcp.get_tools()
-    prompts_dict = await mcp.get_prompts()
-    resources_dict = await mcp.get_resources()
-    templates_dict = await mcp.get_resource_templates()
+    # Get all components via middleware to respect filtering and preserve metadata
+    tools_list = await mcp._list_tools_middleware()
+    prompts_list = await mcp._list_prompts_middleware()
+    resources_list = await mcp._list_resources_middleware()
+    templates_list = await mcp._list_resource_templates_middleware()
 
     # Extract detailed tool information
     tool_infos = []
-    for key, tool in tools_dict.items():
-        # Convert to MCP tool to get input schema
-        mcp_tool = tool.to_mcp_tool(name=key)
+    for tool in tools_list:
+        mcp_tool = tool.to_mcp_tool(name=tool.key)
         tool_infos.append(
             ToolInfo(
-                key=key,
-                name=tool.name or key,
+                key=tool.key,
+                name=tool.name or tool.key,
                 description=tool.description,
                 input_schema=mcp_tool.inputSchema if mcp_tool.inputSchema else {},
                 output_schema=tool.output_schema,
@@ -126,17 +131,20 @@ async def inspect_fastmcp_v2(mcp: FastMCP[Any]) -> FastMCPInfo:
                 tags=list(tool.tags) if tool.tags else None,
                 enabled=tool.enabled,
                 title=tool.title,
+                icons=[icon.model_dump() for icon in tool.icons]
+                if tool.icons
+                else None,
                 meta=tool.meta,
             )
         )
 
     # Extract detailed prompt information
     prompt_infos = []
-    for key, prompt in prompts_dict.items():
+    for prompt in prompts_list:
         prompt_infos.append(
             PromptInfo(
-                key=key,
-                name=prompt.name or key,
+                key=prompt.key,
+                name=prompt.name or prompt.key,
                 description=prompt.description,
                 arguments=[arg.model_dump() for arg in prompt.arguments]
                 if prompt.arguments
@@ -144,17 +152,20 @@ async def inspect_fastmcp_v2(mcp: FastMCP[Any]) -> FastMCPInfo:
                 tags=list(prompt.tags) if prompt.tags else None,
                 enabled=prompt.enabled,
                 title=prompt.title,
+                icons=[icon.model_dump() for icon in prompt.icons]
+                if prompt.icons
+                else None,
                 meta=prompt.meta,
             )
         )
 
     # Extract detailed resource information
     resource_infos = []
-    for key, resource in resources_dict.items():
+    for resource in resources_list:
         resource_infos.append(
             ResourceInfo(
-                key=key,
-                uri=key,  # For v2, key is the URI
+                key=resource.key,
+                uri=resource.key,
                 name=resource.name,
                 description=resource.description,
                 mime_type=resource.mime_type,
@@ -164,17 +175,20 @@ async def inspect_fastmcp_v2(mcp: FastMCP[Any]) -> FastMCPInfo:
                 tags=list(resource.tags) if resource.tags else None,
                 enabled=resource.enabled,
                 title=resource.title,
+                icons=[icon.model_dump() for icon in resource.icons]
+                if resource.icons
+                else None,
                 meta=resource.meta,
             )
         )
 
     # Extract detailed template information
     template_infos = []
-    for key, template in templates_dict.items():
+    for template in templates_list:
         template_infos.append(
             TemplateInfo(
-                key=key,
-                uri_template=key,  # For v2, key is the URI template
+                key=template.key,
+                uri_template=template.key,
                 name=template.name,
                 description=template.description,
                 mime_type=template.mime_type,
@@ -185,6 +199,9 @@ async def inspect_fastmcp_v2(mcp: FastMCP[Any]) -> FastMCPInfo:
                 tags=list(template.tags) if template.tags else None,
                 enabled=template.enabled,
                 title=template.title,
+                icons=[icon.model_dump() for icon in template.icons]
+                if template.icons
+                else None,
                 meta=template.meta,
             )
         )
@@ -197,13 +214,25 @@ async def inspect_fastmcp_v2(mcp: FastMCP[Any]) -> FastMCPInfo:
         "logging": {},
     }
 
+    # Extract server-level icons and website_url
+    server_icons = (
+        [icon.model_dump() for icon in mcp._mcp_server.icons]
+        if hasattr(mcp._mcp_server, "icons") and mcp._mcp_server.icons
+        else None
+    )
+    server_website_url = (
+        mcp._mcp_server.website_url if hasattr(mcp._mcp_server, "website_url") else None
+    )
+
     return FastMCPInfo(
         name=mcp.name,
         instructions=mcp.instructions,
+        version=(mcp.version if hasattr(mcp, "version") else mcp._mcp_server.version),
+        website_url=server_website_url,
+        icons=server_icons,
         fastmcp_version=fastmcp.__version__,
         mcp_version=importlib.metadata.version("mcp"),
         server_generation=2,  # FastMCP v2
-        version=(mcp.version if hasattr(mcp, "version") else mcp._mcp_server.version),
         tools=tool_infos,
         prompts=prompt_infos,
         resources=resource_infos,
@@ -248,6 +277,9 @@ async def inspect_fastmcp_v1(mcp: FastMCP1x) -> FastMCPInfo:
                     tags=None,  # v1 doesn't have tags
                     enabled=None,  # v1 doesn't have enabled field
                     title=None,  # v1 doesn't have title
+                    icons=[icon.model_dump() for icon in mcp_tool.icons]
+                    if hasattr(mcp_tool, "icons") and mcp_tool.icons
+                    else None,
                     meta=None,  # v1 doesn't have meta field
                 )
             )
@@ -269,6 +301,9 @@ async def inspect_fastmcp_v1(mcp: FastMCP1x) -> FastMCPInfo:
                     tags=None,  # v1 doesn't have tags
                     enabled=None,  # v1 doesn't have enabled field
                     title=None,  # v1 doesn't have title
+                    icons=[icon.model_dump() for icon in mcp_prompt.icons]
+                    if hasattr(mcp_prompt, "icons") and mcp_prompt.icons
+                    else None,
                     meta=None,  # v1 doesn't have meta field
                 )
             )
@@ -287,6 +322,9 @@ async def inspect_fastmcp_v1(mcp: FastMCP1x) -> FastMCPInfo:
                     tags=None,  # v1 doesn't have tags
                     enabled=None,  # v1 doesn't have enabled field
                     title=None,  # v1 doesn't have title
+                    icons=[icon.model_dump() for icon in mcp_resource.icons]
+                    if hasattr(mcp_resource, "icons") and mcp_resource.icons
+                    else None,
                     meta=None,  # v1 doesn't have meta field
                 )
             )
@@ -306,6 +344,9 @@ async def inspect_fastmcp_v1(mcp: FastMCP1x) -> FastMCPInfo:
                     tags=None,  # v1 doesn't have tags
                     enabled=None,  # v1 doesn't have enabled field
                     title=None,  # v1 doesn't have title
+                    icons=[icon.model_dump() for icon in mcp_template.icons]
+                    if hasattr(mcp_template, "icons") and mcp_template.icons
+                    else None,
                     meta=None,  # v1 doesn't have meta field
                 )
             )
@@ -318,13 +359,26 @@ async def inspect_fastmcp_v1(mcp: FastMCP1x) -> FastMCPInfo:
             "logging": {},
         }
 
+        # Extract server-level icons and website_url from serverInfo
+        server_info = client.initialize_result.serverInfo
+        server_icons = (
+            [icon.model_dump() for icon in server_info.icons]
+            if hasattr(server_info, "icons") and server_info.icons
+            else None
+        )
+        server_website_url = (
+            server_info.websiteUrl if hasattr(server_info, "websiteUrl") else None
+        )
+
         return FastMCPInfo(
             name=mcp._mcp_server.name,
             instructions=mcp._mcp_server.instructions,
+            version=mcp._mcp_server.version,
+            website_url=server_website_url,
+            icons=server_icons,
             fastmcp_version=fastmcp.__version__,  # Version generating this manifest
             mcp_version=importlib.metadata.version("mcp"),
             server_generation=1,  # MCP v1
-            version=mcp._mcp_server.version,
             tools=tool_infos,
             prompts=prompt_infos,
             resources=resource_infos,
@@ -369,6 +423,8 @@ async def format_fastmcp_info(info: FastMCPInfo) -> bytes:
             "name": info.name,
             "instructions": info.instructions,
             "version": info.version,
+            "website_url": info.website_url,
+            "icons": info.icons,
             "generation": info.server_generation,
             "capabilities": info.capabilities,
         },

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,