fastmcp 2.8.1__py3-none-any.whl → 2.9.0__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
@@ -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/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}

fastmcp/prompts/prompt.py

@@ -3,15 +3,16 @@
 from __future__ import annotations as _annotations
 
 import inspect
+import json
 from abc import ABC, abstractmethod
 from collections.abc import Awaitable, Callable, Sequence
-from typing import TYPE_CHECKING, Any
+from typing import Any
 
 import pydantic_core
 from mcp.types import Prompt as MCPPrompt
 from mcp.types import PromptArgument as MCPPromptArgument
 from mcp.types import PromptMessage, Role, TextContent
-from pydantic import Field, TypeAdapter, validate_call
+from pydantic import Field, TypeAdapter
 
 from fastmcp.exceptions import PromptError
 from fastmcp.server.dependencies import get_context
@@ -25,10 +26,6 @@ from fastmcp.utilities.types import (
     get_cached_typeadapter,
 )
 
-if TYPE_CHECKING:
-    pass
-
-
 logger = get_logger(__name__)
 
 
@@ -155,7 +152,7 @@ class FunctionPrompt(Prompt):
             if param.kind == inspect.Parameter.VAR_KEYWORD:
                 raise ValueError("Functions with **kwargs are not supported as prompts")
 
-        description = description or fn.__doc__
+        description = description or inspect.getdoc(fn)
 
         # if the fn is a callable class, we need to get the __call__ method from here out
         if not inspect.isroutine(fn):
@@ -181,17 +178,43 @@ class FunctionPrompt(Prompt):
         arguments: list[PromptArgument] = []
         if "properties" in parameters:
             for param_name, param in parameters["properties"].items():
+                arg_description = param.get("description")
+
+                # For non-string parameters, append JSON schema info to help users
+                # understand the expected format when passing as strings (MCP requirement)
+                if param_name in sig.parameters:
+                    sig_param = sig.parameters[param_name]
+                    if (
+                        sig_param.annotation != inspect.Parameter.empty
+                        and sig_param.annotation is not str
+                        and param_name != context_kwarg
+                    ):
+                        # Get the JSON schema for this specific parameter type
+                        try:
+                            param_adapter = get_cached_typeadapter(sig_param.annotation)
+                            param_schema = param_adapter.json_schema()
+
+                            # Create compact schema representation
+                            schema_str = json.dumps(param_schema, separators=(",", ":"))
+
+                            # Append schema info to description
+                            schema_note = f"Provide as a JSON string matching the following schema: {schema_str}"
+                            if arg_description:
+                                arg_description = f"{arg_description}\n\n{schema_note}"
+                            else:
+                                arg_description = schema_note
+                        except Exception:
+                            # If schema generation fails, skip enhancement
+                            pass
+
                 arguments.append(
                     PromptArgument(
                         name=param_name,
-                        description=param.get("description"),
+                        description=arg_description,
                         required=param_name in parameters.get("required", []),
                     )
                 )
 
-        # ensure the arguments are properly cast
-        fn = validate_call(fn)
-
         return cls(
             name=func_name,
             description=description,
@@ -201,6 +224,60 @@ class FunctionPrompt(Prompt):
             fn=fn,
         )
 
+    def _convert_string_arguments(self, kwargs: dict[str, Any]) -> dict[str, Any]:
+        """Convert string arguments to expected types based on function signature."""
+        from fastmcp.server.context import Context
+
+        sig = inspect.signature(self.fn)
+        converted_kwargs = {}
+
+        # Find context parameter name if any
+        context_param_name = find_kwarg_by_type(self.fn, kwarg_type=Context)
+
+        for param_name, param_value in kwargs.items():
+            if param_name in sig.parameters:
+                param = sig.parameters[param_name]
+
+                # Skip Context parameters - they're handled separately
+                if param_name == context_param_name:
+                    converted_kwargs[param_name] = param_value
+                    continue
+
+                # If parameter has no annotation or annotation is str, pass as-is
+                if (
+                    param.annotation == inspect.Parameter.empty
+                    or param.annotation is str
+                ):
+                    converted_kwargs[param_name] = param_value
+                # If argument is not a string, pass as-is (already properly typed)
+                elif not isinstance(param_value, str):
+                    converted_kwargs[param_name] = param_value
+                else:
+                    # Try to convert string argument using type adapter
+                    try:
+                        adapter = get_cached_typeadapter(param.annotation)
+                        # Try JSON parsing first for complex types
+                        try:
+                            converted_kwargs[param_name] = adapter.validate_json(
+                                param_value
+                            )
+                        except (ValueError, TypeError, pydantic_core.ValidationError):
+                            # Fallback to direct validation
+                            converted_kwargs[param_name] = adapter.validate_python(
+                                param_value
+                            )
+                    except (ValueError, TypeError, pydantic_core.ValidationError) as e:
+                        # If conversion fails, provide informative error
+                        raise PromptError(
+                            f"Could not convert argument '{param_name}' with value '{param_value}' "
+                            f"to expected type {param.annotation}. Error: {e}"
+                        )
+            else:
+                # Parameter not in function signature, pass as-is
+                converted_kwargs[param_name] = param_value
+
+        return converted_kwargs
+
     async def render(
         self,
         arguments: dict[str, Any] | None = None,
@@ -223,6 +300,9 @@ class FunctionPrompt(Prompt):
             if context_kwarg and context_kwarg not in kwargs:
                 kwargs[context_kwarg] = get_context()
 
+            # Convert string arguments to expected types when needed
+            kwargs = self._convert_string_arguments(kwargs)
+
             # Call function and check if result is a coroutine
             result = self.fn(**kwargs)
             if inspect.iscoroutine(result):