fastmcp 2.8.1__py3-none-any.whl → 2.9.1__py3-none-any.whl

fastmcp/cli/cli.py

@@ -1,5 +1,6 @@
 """FastMCP CLI tools."""
 
+import asyncio
 import importlib.metadata
 import importlib.util
 import os
@@ -11,6 +12,7 @@ from typing import Annotated
 
 import dotenv
 import typer
+from pydantic import TypeAdapter
 from rich.console import Console
 from rich.table import Table
 from typer import Context, Exit
@@ -19,6 +21,7 @@ import fastmcp
 from fastmcp.cli import claude
 from fastmcp.cli import run as run_module
 from fastmcp.server.server import FastMCP
+from fastmcp.utilities.inspect import FastMCPInfo, inspect_fastmcp
 from fastmcp.utilities.logging import get_logger
 
 logger = get_logger("cli")
@@ -232,7 +235,7 @@ def run(
         typer.Option(
             "--transport",
             "-t",
-            help="Transport protocol to use (stdio, streamable-http, or sse)",
+            help="Transport protocol to use (stdio, http, or sse)",
         ),
     ] = None,
     host: Annotated[
@@ -435,3 +438,98 @@ def install(
     else:
         logger.error(f"Failed to install {name} in Claude app")
         sys.exit(1)
+
+
+@app.command()
+def inspect(
+    server_spec: str = typer.Argument(
+        ...,
+        help="Python file to inspect, optionally with :object suffix",
+    ),
+    output: Annotated[
+        Path,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Output file path for the JSON report (default: server-info.json)",
+        ),
+    ] = Path("server-info.json"),
+) -> None:
+    """Inspect a FastMCP server and generate a JSON report.
+
+    This command analyzes a FastMCP server (v1.x or v2.x) and generates
+    a comprehensive JSON report containing information about the server's
+    name, instructions, version, tools, prompts, resources, templates,
+    and capabilities.
+
+    Examples:
+        fastmcp inspect server.py
+        fastmcp inspect server.py -o report.json
+        fastmcp inspect server.py:mcp -o analysis.json
+        fastmcp inspect path/to/server.py:app -o /tmp/server-info.json
+    """
+
+    # Parse the server specification
+    file, server_object = run_module.parse_file_path(server_spec)
+
+    logger.debug(
+        "Inspecting server",
+        extra={
+            "file": str(file),
+            "server_object": server_object,
+            "output": str(output),
+        },
+    )
+
+    try:
+        # Import the server
+        server = run_module.import_server(file, server_object)
+
+        # Get server information
+        async def get_info():
+            return await inspect_fastmcp(server)
+
+        try:
+            # Try to use existing event loop if available
+            asyncio.get_running_loop()
+            # If there's already a loop running, we need to run in a thread
+            import concurrent.futures
+
+            with concurrent.futures.ThreadPoolExecutor() as executor:
+                future = executor.submit(asyncio.run, get_info())
+                info = future.result()
+        except RuntimeError:
+            # No running loop, safe to use asyncio.run
+            info = asyncio.run(get_info())
+
+        info_json = TypeAdapter(FastMCPInfo).dump_json(info, indent=2)
+
+        # Ensure output directory exists
+        output.parent.mkdir(parents=True, exist_ok=True)
+
+        # Write JSON report (always pretty-printed)
+        with output.open("w", encoding="utf-8") as f:
+            f.write(info_json.decode("utf-8"))
+
+        logger.info(f"Server inspection complete. Report saved to {output}")
+
+        # Print summary to console
+        console.print(
+            f"[bold green]✓[/bold green] Inspected server: [bold]{info.name}[/bold]"
+        )
+        console.print(f"  Tools: {len(info.tools)}")
+        console.print(f"  Prompts: {len(info.prompts)}")
+        console.print(f"  Resources: {len(info.resources)}")
+        console.print(f"  Templates: {len(info.templates)}")
+        console.print(f"  Report saved to: [cyan]{output}[/cyan]")
+
+    except Exception as e:
+        logger.error(
+            f"Failed to inspect server: {e}",
+            extra={
+                "server_spec": server_spec,
+                "error": str(e),
+            },
+        )
+        console.print(f"[bold red]✗[/bold red] Failed to inspect server: {e}")
+        sys.exit(1)

fastmcp/cli/run.py

@@ -4,14 +4,12 @@ import importlib.util
 import re
 import sys
 from pathlib import Path
-from typing import Any, Literal
+from typing import Any
 
 from fastmcp.utilities.logging import get_logger
 
 logger = get_logger("cli.run")
 
-TransportType = Literal["stdio", "streamable-http", "sse"]
-
 
 def is_url(path: str) -> bool:
     """Check if a string is a URL."""

fastmcp/client/auth/oauth.py

@@ -306,8 +306,7 @@ def OAuth(
     httpx.AsyncClient (or appropriate FastMCP client/transport instance)
 
     Args:
-        mcp_url: Full URL to the MCP endpoint (e.g.,
-        "http://host/mcp/sse")
+        mcp_url: Full URL to the MCP endpoint (e.g. "http://host/mcp/sse/")
         scopes: OAuth scopes to request. Can be a
         space-separated string or a list of strings.
         client_name: Name for this client during registration

fastmcp/client/client.py

@@ -7,6 +7,7 @@ from typing import Any, Generic, Literal, cast, overload
 import anyio
 import httpx
 import mcp.types
+import pydantic_core
 from exceptiongroup import catch
 from mcp import ClientSession
 from pydantic import AnyUrl
@@ -14,10 +15,10 @@ from pydantic import AnyUrl
 import fastmcp
 from fastmcp.client.logging import (
     LogHandler,
-    MessageHandler,
     create_log_callback,
     default_log_handler,
 )
+from fastmcp.client.messages import MessageHandler, MessageHandlerT
 from fastmcp.client.progress import ProgressHandler, default_progress_handler
 from fastmcp.client.roots import (
     RootsHandler,
@@ -142,7 +143,7 @@ class Client(Generic[ClientTransportT]):
         roots: RootsList | RootsHandler | None = None,
         sampling_handler: SamplingHandler | None = None,
         log_handler: LogHandler | None = None,
-        message_handler: MessageHandler | None = None,
+        message_handler: MessageHandlerT | MessageHandler | None = None,
         progress_handler: ProgressHandler | None = None,
         timeout: datetime.timedelta | float | int | None = None,
         init_timeout: datetime.timedelta | float | int | None = None,
@@ -508,13 +509,13 @@ class Client(Generic[ClientTransportT]):
 
     # --- Prompt ---
     async def get_prompt_mcp(
-        self, name: str, arguments: dict[str, str] | None = None
+        self, name: str, arguments: dict[str, Any] | None = None
     ) -> mcp.types.GetPromptResult:
         """Send a prompts/get request and return the complete MCP protocol result.
 
         Args:
             name (str): The name of the prompt to retrieve.
-            arguments (dict[str, str] | None, optional): Arguments to pass to the prompt. Defaults to None.
+            arguments (dict[str, Any] | None, optional): Arguments to pass to the prompt. Defaults to None.
 
         Returns:
             mcp.types.GetPromptResult: The complete response object from the protocol,
@@ -523,17 +524,32 @@ class Client(Generic[ClientTransportT]):
         Raises:
             RuntimeError: If called while the client is not connected.
         """
-        result = await self.session.get_prompt(name=name, arguments=arguments)
+        # Serialize arguments for MCP protocol - convert non-string values to JSON
+        serialized_arguments: dict[str, str] | None = None
+        if arguments:
+            serialized_arguments = {}
+            for key, value in arguments.items():
+                if isinstance(value, str):
+                    serialized_arguments[key] = value
+                else:
+                    # Use pydantic_core.to_json for consistent serialization
+                    serialized_arguments[key] = pydantic_core.to_json(value).decode(
+                        "utf-8"
+                    )
+
+        result = await self.session.get_prompt(
+            name=name, arguments=serialized_arguments
+        )
         return result
 
     async def get_prompt(
-        self, name: str, arguments: dict[str, str] | None = None
+        self, name: str, arguments: dict[str, Any] | None = None
     ) -> mcp.types.GetPromptResult:
         """Retrieve a rendered prompt message list from the server.
 
         Args:
             name (str): The name of the prompt to retrieve.
-            arguments (dict[str, str] | None, optional): Arguments to pass to the prompt. Defaults to None.
+            arguments (dict[str, Any] | None, optional): Arguments to pass to the prompt. Defaults to None.
 
         Returns:
             mcp.types.GetPromptResult: The complete response object from the protocol,

fastmcp/client/logging.py

@@ -1,7 +1,7 @@
 from collections.abc import Awaitable, Callable
 from typing import TypeAlias
 
-from mcp.client.session import LoggingFnT, MessageHandlerFnT
+from mcp.client.session import LoggingFnT
 from mcp.types import LoggingMessageNotificationParams
 
 from fastmcp.utilities.logging import get_logger
@@ -10,7 +10,6 @@ logger = get_logger(__name__)
 
 LogMessage: TypeAlias = LoggingMessageNotificationParams
 LogHandler: TypeAlias = Callable[[LogMessage], Awaitable[None]]
-MessageHandler: TypeAlias = MessageHandlerFnT
 
 
 async def default_log_handler(message: LogMessage) -> None:

fastmcp/client/messages.py

@@ -0,0 +1,126 @@
+from typing import TypeAlias
+
+import mcp.types
+from mcp.client.session import MessageHandlerFnT
+from mcp.shared.session import RequestResponder
+
+Message: TypeAlias = (
+    RequestResponder[mcp.types.ServerRequest, mcp.types.ClientResult]
+    | mcp.types.ServerNotification
+    | Exception
+)
+
+MessageHandlerT: TypeAlias = MessageHandlerFnT
+
+
+class MessageHandler:
+    """
+    This class is used to handle MCP messages sent to the client. It is used to handle all messages,
+    requests, notifications, and exceptions. Users can override any of the hooks
+    """
+
+    async def __call__(
+        self,
+        message: RequestResponder[mcp.types.ServerRequest, mcp.types.ClientResult]
+        | mcp.types.ServerNotification
+        | Exception,
+    ) -> None:
+        return await self.dispatch(message)
+
+    async def dispatch(self, message: Message) -> None:
+        # handle all messages
+        await self.on_message(message)
+
+        match message:
+            # requests
+            case RequestResponder():
+                # handle all requests
+                await self.on_request(message)
+
+                # handle specific requests
+                match message.request.root:
+                    case mcp.types.PingRequest():
+                        await self.on_ping(message.request.root)
+                    case mcp.types.ListRootsRequest():
+                        await self.on_list_roots(message.request.root)
+                    case mcp.types.CreateMessageRequest():
+                        await self.on_create_message(message.request.root)
+
+            # notifications
+            case mcp.types.ServerNotification():
+                # handle all notifications
+                await self.on_notification(message)
+
+                # handle specific notifications
+                match message.root:
+                    case mcp.types.CancelledNotification():
+                        await self.on_cancelled(message.root)
+                    case mcp.types.ProgressNotification():
+                        await self.on_progress(message.root)
+                    case mcp.types.LoggingMessageNotification():
+                        await self.on_logging_message(message.root)
+                    case mcp.types.ToolListChangedNotification():
+                        await self.on_tool_list_changed(message.root)
+                    case mcp.types.ResourceListChangedNotification():
+                        await self.on_resource_list_changed(message.root)
+                    case mcp.types.PromptListChangedNotification():
+                        await self.on_prompt_list_changed(message.root)
+                    case mcp.types.ResourceUpdatedNotification():
+                        await self.on_resource_updated(message.root)
+
+            case Exception():
+                await self.on_exception(message)
+
+    async def on_message(self, message: Message) -> None:
+        pass
+
+    async def on_request(
+        self, message: RequestResponder[mcp.types.ServerRequest, mcp.types.ClientResult]
+    ) -> None:
+        pass
+
+    async def on_ping(self, message: mcp.types.PingRequest) -> None:
+        pass
+
+    async def on_list_roots(self, message: mcp.types.ListRootsRequest) -> None:
+        pass
+
+    async def on_create_message(self, message: mcp.types.CreateMessageRequest) -> None:
+        pass
+
+    async def on_notification(self, message: mcp.types.ServerNotification) -> None:
+        pass
+
+    async def on_exception(self, message: Exception) -> None:
+        pass
+
+    async def on_progress(self, message: mcp.types.ProgressNotification) -> None:
+        pass
+
+    async def on_logging_message(
+        self, message: mcp.types.LoggingMessageNotification
+    ) -> None:
+        pass
+
+    async def on_tool_list_changed(
+        self, message: mcp.types.ToolListChangedNotification
+    ) -> None:
+        pass
+
+    async def on_resource_list_changed(
+        self, message: mcp.types.ResourceListChangedNotification
+    ) -> None:
+        pass
+
+    async def on_prompt_list_changed(
+        self, message: mcp.types.PromptListChangedNotification
+    ) -> None:
+        pass
+
+    async def on_resource_updated(
+        self, message: mcp.types.ResourceUpdatedNotification
+    ) -> None:
+        pass
+
+    async def on_cancelled(self, message: mcp.types.CancelledNotification) -> None:
+        pass

fastmcp/client/transports.py

@@ -9,6 +9,7 @@ import warnings
 from collections.abc import AsyncIterator, Callable
 from pathlib import Path
 from typing import Any, Literal, TypedDict, TypeVar, cast, overload
+from urllib.parse import urlparse, urlunparse
 
 import anyio
 import httpx
@@ -159,6 +160,13 @@ class SSETransport(ClientTransport):
             url = str(url)
         if not isinstance(url, str) or not url.startswith("http"):
             raise ValueError("Invalid HTTP/S URL provided for SSE.")
+
+        # Ensure the URL path ends with a trailing slash to avoid automatic redirects
+        parsed = urlparse(url)
+        if not parsed.path.endswith("/"):
+            parsed = parsed._replace(path=parsed.path + "/")
+            url = urlunparse(parsed)
+
         self.url = url
         self.headers = headers or {}
         self._set_auth(auth)
@@ -227,6 +235,13 @@ class StreamableHttpTransport(ClientTransport):
             url = str(url)
         if not isinstance(url, str) or not url.startswith("http"):
             raise ValueError("Invalid HTTP/S URL provided for Streamable HTTP.")
+
+        # Ensure the URL path ends with a trailing slash to avoid automatic redirects
+        parsed = urlparse(url)
+        if not parsed.path.endswith("/"):
+            parsed = parsed._replace(path=parsed.path + "/")
+            url = urlunparse(parsed)
+
         self.url = url
         self.headers = headers or {}
         self._set_auth(auth)
@@ -721,11 +736,11 @@ class MCPConfigTransport(ClientTransport):
             "mcpServers": {
                 "weather": {
                     "url": "https://weather-api.example.com/mcp",
-                    "transport": "streamable-http"
+                    "transport": "http"
                 },
                 "calendar": {
                     "url": "https://calendar-api.example.com/mcp",
-                    "transport": "streamable-http"
+                    "transport": "http"
                 }
             }
         }

fastmcp/contrib/mcp_mixin/README.md

@@ -1,26 +1,103 @@
+from mcp.types import ToolAnnotations
+
 # MCP Mixin
 
 This module provides the `MCPMixin` base class and associated decorators (`@mcp_tool`, `@mcp_resource`, `@mcp_prompt`).
 
 It allows developers to easily define classes whose methods can be registered as tools, resources, or prompts with a `FastMCP` server instance using the `register_all()`, `register_tools()`, `register_resources()`, or `register_prompts()` methods provided by the mixin.
 
+Includes support for
+Tools:
+* [enable/disable](https://gofastmcp.com/servers/tools#disabling-tools)
+* [annotations](https://gofastmcp.com/servers/tools#annotations-2)
+* [excluded arguments](https://gofastmcp.com/servers/tools#excluding-arguments)
+
+Prompts:
+* [enable/disable](https://gofastmcp.com/servers/prompts#disabling-prompts)
+
+Resources:
+* [enable/disabe](https://gofastmcp.com/servers/resources#disabling-resources)
+  
 ## Usage
 
 Inherit from `MCPMixin` and use the decorators on the methods you want to register.
 
 ```python
+from mcp.types import ToolAnnotations
 from fastmcp import FastMCP
-from fastmcp.contrib.mcp_mixin import MCPMixin, mcp_tool, mcp_resource
+from fastmcp.contrib.mcp_mixin import MCPMixin, mcp_tool, mcp_resource, mcp_prompt
 
 class MyComponent(MCPMixin):
     @mcp_tool(name="my_tool", description="Does something cool.")
     def tool_method(self):
         return "Tool executed!"
 
+    # example of disabled tool
+    @mcp_tool(name="my_tool", description="Does something cool.", enabled=False)
+    def disabled_tool_method(self):
+        # This function can't be called by client because it's disabled
+        return "You'll never get here!"
+
+    # example of excluded parameter tool
+    @mcp_tool(
+        name="my_tool", description="Does something cool.",
+        enabled=False, exclude_args=['delete_everything'],
+    )
+    def excluded_param_tool_method(self, delete_everything=False):
+        # MCP tool calls can't pass the "delete_everything" argument
+        if delete_everything:
+            return "Nothing to delete, I bet you're not a tool :)"
+        return "You might be a tool if..."
+
+    # example tool w/annotations
+    @mcp_tool(
+        name="my_tool", description="Does something cool.",
+        annotations=ToolAnnotations(
+            title="Attn LLM, use this tool first!",
+            readOnlyHint=False,
+            destructiveHint=False,
+            idempotentHint=False,
+        )
+    )
+    def tool_method(self):
+        return "Tool executed!"
+
+    # example tool w/everything
+    @mcp_tool(
+        name="my_tool", description="Does something cool.",
+        enabled=True,
+        exclude_args=['delete_all'],
+        annotations=ToolAnnotations(
+            title="Attn LLM, use this tool first!",
+            readOnlyHint=False,
+            destructiveHint=False,
+            idempotentHint=False,
+        )
+    )
+    def tool_method(self, delete_all=False):
+        if delete_all:
+            return "99 records deleted. I bet you're not a tool :)"
+        return "Tool executed, but you might be a tool!"
+    
     @mcp_resource(uri="component://data")
     def resource_method(self):
         return {"data": "some data"}
 
+    # Disabled resource
+    @mcp_resource(uri="component://data", enabled=False)
+    def resource_method(self):
+        return {"data": "some data"}
+
+    # prompt
+    @mcp_prompt(name="A prompt")
+    def prompt_method(self, name):
+        return f"Whats up {name}?"
+
+    # disabled prompt
+    @mcp_prompt(name="A prompt", enabled=False)
+    def prompt_method(self, name):
+        return f"Whats up {name}?"
+
 mcp_server = FastMCP()
 component = MyComponent()
 
@@ -36,4 +113,4 @@ component.register_all(mcp_server, prefix="my_comp")
 # Or 'my_tool' and 'component://data' are registered (if no prefix used)
 ```
 
-The `prefix` argument in registration methods is optional. If omitted, methods are registered with their original decorated names/URIs. Individual separators (`tools_separator`, `resources_separator`, `prompts_separator`) can also be provided to `register_all` to change the separator for specific types.
+The `prefix` argument in registration methods is optional. If omitted, methods are registered with their original decorated names/URIs. Individual separators (`tools_separator`, `resources_separator`, `prompts_separator`) can also be provided to `register_all` to change the separator for specific types.

fastmcp/contrib/mcp_mixin/mcp_mixin.py

@@ -3,6 +3,8 @@
 from collections.abc import Callable
 from typing import TYPE_CHECKING, Any
 
+from mcp.types import ToolAnnotations
+
 from fastmcp.prompts.prompt import Prompt
 from fastmcp.resources.resource import Resource
 from fastmcp.tools.tool import Tool
@@ -23,6 +25,10 @@ def mcp_tool(
     name: str | None = None,
     description: str | None = None,
     tags: set[str] | None = None,
+    annotations: ToolAnnotations | dict[str, Any] | None = None,
+    exclude_args: list[str] | None = None,
+    serializer: Callable[[Any], str] | None = None,
+    enabled: bool | None = None,
 ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
     """Decorator to mark a method as an MCP tool for later registration."""
 
@@ -31,6 +37,10 @@ def mcp_tool(
             "name": name or func.__name__,
             "description": description,
             "tags": tags,
+            "annotations": annotations,
+            "exclude_args": exclude_args,
+            "serializer": serializer,
+            "enabled": enabled,
         }
         call_args = {k: v for k, v in call_args.items() if v is not None}
         setattr(func, _MCP_REGISTRATION_TOOL_ATTR, call_args)
@@ -46,6 +56,7 @@ def mcp_resource(
     description: str | None = None,
     mime_type: str | None = None,
     tags: set[str] | None = None,
+    enabled: bool | None = None,
 ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
     """Decorator to mark a method as an MCP resource for later registration."""
 
@@ -56,6 +67,7 @@ def mcp_resource(
             "description": description,
             "mime_type": mime_type,
             "tags": tags,
+            "enabled": enabled,
         }
         call_args = {k: v for k, v in call_args.items() if v is not None}
 
@@ -70,6 +82,7 @@ def mcp_prompt(
     name: str | None = None,
     description: str | None = None,
     tags: set[str] | None = None,
+    enabled: bool | None = None,
 ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
     """Decorator to mark a method as an MCP prompt for later registration."""
 
@@ -78,6 +91,7 @@ def mcp_prompt(
             "name": name or func.__name__,
             "description": description,
             "tags": tags,
+            "enabled": enabled,
         }
 
         call_args = {k: v for k, v in call_args.items() if v is not None}