fastmcp 2.2.9__py3-none-any.whl → 2.3.0rc1__py3-none-any.whl

fastmcp/server/streamable_http_manager.py

@@ -0,0 +1,241 @@
+"""StreamableHTTP Session Manager for MCP servers."""
+
+# follows https://github.com/modelcontextprotocol/python-sdk/blob/ihrpr/shttp/src/mcp/server/streamable_http_manager.py
+# and can be removed once that spec is finalized
+
+from __future__ import annotations
+
+import contextlib
+import logging
+from collections.abc import AsyncIterator
+from http import HTTPStatus
+from typing import Any
+from uuid import uuid4
+
+import anyio
+from anyio.abc import TaskStatus
+from mcp.server.lowlevel.server import Server as MCPServer
+from mcp.server.streamable_http import (
+    MCP_SESSION_ID_HEADER,
+    EventStore,
+    StreamableHTTPServerTransport,
+)
+from starlette.requests import Request
+from starlette.responses import Response
+from starlette.types import Receive, Scope, Send
+
+logger = logging.getLogger(__name__)
+
+
+class StreamableHTTPSessionManager:
+    """
+    Manages StreamableHTTP sessions with optional resumability via event store.
+
+    This class abstracts away the complexity of session management, event storage,
+    and request handling for StreamableHTTP transports. It handles:
+
+    1. Session tracking for clients
+    2. Resumability via an optional event store
+    3. Connection management and lifecycle
+    4. Request handling and transport setup
+
+    Args:
+        app: The MCP server instance
+        event_store: Optional event store for resumability support.
+                     If provided, enables resumable connections where clients
+                     can reconnect and receive missed events.
+                     If None, sessions are still tracked but not resumable.
+        json_response: Whether to use JSON responses instead of SSE streams
+        stateless: If True, creates a completely fresh transport for each request
+                   with no session tracking or state persistence between requests.
+
+    """
+
+    def __init__(
+        self,
+        app: MCPServer[Any],
+        event_store: EventStore | None = None,
+        json_response: bool = False,
+        stateless: bool = False,
+    ):
+        self.app = app
+        self.event_store = event_store
+        self.json_response = json_response
+        self.stateless = stateless
+
+        # Session tracking (only used if not stateless)
+        self._session_creation_lock = anyio.Lock()
+        self._server_instances: dict[str, StreamableHTTPServerTransport] = {}
+
+        # The task group will be set during lifespan
+        self._task_group = None
+
+    @contextlib.asynccontextmanager
+    async def run(self) -> AsyncIterator[None]:
+        """
+        Run the session manager with proper lifecycle management.
+
+        This creates and manages the task group for all session operations.
+
+        Use this in the lifespan context manager of your Starlette app:
+
+        @contextlib.asynccontextmanager
+        async def lifespan(app: Starlette) -> AsyncIterator[None]:
+            async with session_manager.run():
+                yield
+        """
+        async with anyio.create_task_group() as tg:
+            # Store the task group for later use
+            self._task_group = tg
+            logger.info("StreamableHTTP session manager started")
+            try:
+                yield  # Let the application run
+            finally:
+                logger.info("StreamableHTTP session manager shutting down")
+                # Cancel task group to stop all spawned tasks
+                tg.cancel_scope.cancel()
+                self._task_group = None
+                # Clear any remaining server instances
+                self._server_instances.clear()
+
+    async def handle_request(
+        self,
+        scope: Scope,
+        receive: Receive,
+        send: Send,
+    ) -> None:
+        """
+        Process ASGI request with proper session handling and transport setup.
+
+        Dispatches to the appropriate handler based on stateless mode.
+
+        Args:
+            scope: ASGI scope
+            receive: ASGI receive function
+            send: ASGI send function
+        """
+        if self._task_group is None:
+            raise RuntimeError(
+                "Task group is not initialized. Make sure to use the run()."
+            )
+
+        # Dispatch to the appropriate handler
+        if self.stateless:
+            await self._handle_stateless_request(scope, receive, send)
+        else:
+            await self._handle_stateful_request(scope, receive, send)
+
+    async def _handle_stateless_request(
+        self,
+        scope: Scope,
+        receive: Receive,
+        send: Send,
+    ) -> None:
+        """
+        Process request in stateless mode - creating a new transport for each request.
+
+        Args:
+            scope: ASGI scope
+            receive: ASGI receive function
+            send: ASGI send function
+        """
+        logger.debug("Stateless mode: Creating new transport for this request")
+        # No session ID needed in stateless mode
+        http_transport = StreamableHTTPServerTransport(
+            mcp_session_id=None,  # No session tracking in stateless mode
+            is_json_response_enabled=self.json_response,
+            event_store=None,  # No event store in stateless mode
+        )
+
+        # Start server in a new task
+        async def run_stateless_server(
+            *, task_status: TaskStatus[None] = anyio.TASK_STATUS_IGNORED
+        ):
+            async with http_transport.connect() as streams:
+                read_stream, write_stream = streams
+                task_status.started()
+                await self.app.run(
+                    read_stream,
+                    write_stream,
+                    self.app.create_initialization_options(),
+                    stateless=True,
+                )
+
+        # Assert task group is not None for type checking
+        assert self._task_group is not None
+        # Start the server task
+        await self._task_group.start(run_stateless_server)
+
+        # Handle the HTTP request and return the response
+        await http_transport.handle_request(scope, receive, send)
+
+    async def _handle_stateful_request(
+        self,
+        scope: Scope,
+        receive: Receive,
+        send: Send,
+    ) -> None:
+        """
+        Process request in stateful mode - maintaining session state between requests.
+
+        Args:
+            scope: ASGI scope
+            receive: ASGI receive function
+            send: ASGI send function
+        """
+        request = Request(scope, receive)
+        request_mcp_session_id = request.headers.get(MCP_SESSION_ID_HEADER)
+
+        # Existing session case
+        if (
+            request_mcp_session_id is not None
+            and request_mcp_session_id in self._server_instances
+        ):
+            transport = self._server_instances[request_mcp_session_id]
+            logger.debug("Session already exists, handling request directly")
+            await transport.handle_request(scope, receive, send)
+            return
+
+        if request_mcp_session_id is None:
+            # New session case
+            logger.debug("Creating new transport")
+            async with self._session_creation_lock:
+                new_session_id = uuid4().hex
+                http_transport = StreamableHTTPServerTransport(
+                    mcp_session_id=new_session_id,
+                    is_json_response_enabled=self.json_response,
+                    event_store=self.event_store,  # May be None (no resumability)
+                )
+
+                assert http_transport.mcp_session_id is not None
+                self._server_instances[http_transport.mcp_session_id] = http_transport
+                logger.info(f"Created new transport with session ID: {new_session_id}")
+
+                # Define the server runner
+                async def run_server(
+                    *, task_status: TaskStatus[None] = anyio.TASK_STATUS_IGNORED
+                ) -> None:
+                    async with http_transport.connect() as streams:
+                        read_stream, write_stream = streams
+                        task_status.started()
+                        await self.app.run(
+                            read_stream,
+                            write_stream,
+                            self.app.create_initialization_options(),
+                            stateless=False,  # Stateful mode
+                        )
+
+                # Assert task group is not None for type checking
+                assert self._task_group is not None
+                # Start the server task
+                await self._task_group.start(run_server)
+
+                # Handle the HTTP request and return the response
+                await http_transport.handle_request(scope, receive, send)
+        else:
+            # Invalid session ID
+            response = Response(
+                "Bad Request: No valid session ID provided",
+                status_code=HTTPStatus.BAD_REQUEST,
+            )
+            await response(scope, receive, send)

fastmcp/settings.py

@@ -27,6 +27,16 @@ class Settings(BaseSettings):
 
     test_mode: bool = False
     log_level: LOG_LEVEL = "INFO"
+    tool_attempt_parse_json_args: bool = Field(
+        default=False,
+        description="""
+        Note: this enables a legacy behavior. If True, will attempt to parse
+        stringified JSON lists and objects strings in tool arguments before
+        passing them to the tool. This is an old behavior that can create
+        unexpected type coercion issues, but may be helpful for less powerful
+        LLMs that stringify JSON instead of passing actual lists and objects.
+        Defaults to False.""",
+    )
 
 
 class ServerSettings(BaseSettings):
@@ -51,6 +61,7 @@ class ServerSettings(BaseSettings):
     port: int = 8000
     sse_path: str = "/sse"
     message_path: str = "/messages/"
+    streamable_http_path: str = "/mcp"
     debug: bool = False
 
     # resource settings
@@ -72,6 +83,12 @@ class ServerSettings(BaseSettings):
 
     auth: AuthSettings | None = None
 
+    # StreamableHTTP settings
+    json_response: bool = False
+    stateless_http: bool = (
+        False  # If True, uses true stateless mode (new transport per request)
+    )
+
 
 class ClientSettings(BaseSettings):
     """FastMCP client settings."""
@@ -83,3 +100,6 @@ class ClientSettings(BaseSettings):
     )
 
     log_level: LOG_LEVEL = Field(default_factory=lambda: Settings().log_level)
+
+
+settings = Settings()

fastmcp/tools/tool.py

@@ -10,7 +10,9 @@ from mcp.types import EmbeddedResource, ImageContent, TextContent, ToolAnnotatio
 from mcp.types import Tool as MCPTool
 from pydantic import BaseModel, BeforeValidator, Field
 
+import fastmcp
 from fastmcp.exceptions import ToolError
+from fastmcp.server.dependencies import get_context
 from fastmcp.utilities.json_schema import prune_params
 from fastmcp.utilities.logging import get_logger
 from fastmcp.utilities.types import (
@@ -21,10 +23,7 @@ from fastmcp.utilities.types import (
 )
 
 if TYPE_CHECKING:
-    from mcp.server.session import ServerSessionT
-    from mcp.shared.context import LifespanContextT
-
-    from fastmcp.server import Context
+    pass
 
 logger = get_logger(__name__)
 
@@ -40,9 +39,6 @@ class Tool(BaseModel):
     name: str = Field(description="Name of the tool")
     description: str = Field(description="Description of what the tool does")
     parameters: dict[str, Any] = Field(description="JSON schema for tool parameters")
-    context_kwarg: str | None = Field(
-        None, description="Name of the kwarg that should receive context"
-    )
     tags: Annotated[set[str], BeforeValidator(_convert_set_defaults)] = Field(
         default_factory=set, description="Tags for the tool"
     )
@@ -59,13 +55,12 @@ class Tool(BaseModel):
         fn: Callable[..., Any],
         name: str | None = None,
         description: str | None = None,
-        context_kwarg: str | None = None,
         tags: set[str] | None = None,
         annotations: ToolAnnotations | None = None,
         serializer: Callable[[Any], str] | None = None,
     ) -> Tool:
         """Create a Tool from a function."""
-        from fastmcp import Context
+        from fastmcp.server.context import Context
 
         # Reject functions with *args or **kwargs
         sig = inspect.signature(fn)
@@ -85,8 +80,7 @@ class Tool(BaseModel):
         type_adapter = get_cached_typeadapter(fn)
         schema = type_adapter.json_schema()
 
-        if context_kwarg is None:
-            context_kwarg = find_kwarg_by_type(fn, kwarg_type=Context)
+        context_kwarg = find_kwarg_by_type(fn, kwarg_type=Context)
         if context_kwarg:
             schema = prune_params(schema, params=[context_kwarg])
 
@@ -95,42 +89,55 @@ class Tool(BaseModel):
             name=func_name,
             description=func_doc,
             parameters=schema,
-            context_kwarg=context_kwarg,
             tags=tags or set(),
             annotations=annotations,
             serializer=serializer,
         )
 
     async def run(
-        self,
-        arguments: dict[str, Any],
-        context: Context[ServerSessionT, LifespanContextT] | None = None,
+        self, arguments: dict[str, Any]
     ) -> list[TextContent | ImageContent | EmbeddedResource]:
         """Run the tool with arguments."""
-        try:
-            injected_args = (
-                {self.context_kwarg: context} if self.context_kwarg is not None else {}
-            )
+        from fastmcp.server.context import Context
 
-            parsed_args = arguments.copy()
+        arguments = arguments.copy()
 
-            # Pre-parse data from JSON in order to handle cases like `["a", "b", "c"]`
-            # being passed in as JSON inside a string rather than an actual list.
-            #
-            # Claude desktop is prone to this - in fact it seems incapable of NOT doing
-            # this. For sub-models, it tends to pass dicts (JSON objects) as JSON strings,
-            # which can be pre-parsed here.
-            for param_name in self.parameters["properties"]:
-                if isinstance(parsed_args.get(param_name, None), str):
+        try:
+            context_kwarg = find_kwarg_by_type(self.fn, kwarg_type=Context)
+            if context_kwarg and context_kwarg not in arguments:
+                arguments[context_kwarg] = get_context()
+
+            if fastmcp.settings.settings.tool_attempt_parse_json_args:
+                # Pre-parse data from JSON in order to handle cases like `["a", "b", "c"]`
+                # being passed in as JSON inside a string rather than an actual list.
+                #
+                # Claude desktop is prone to this - in fact it seems incapable of NOT doing
+                # this. For sub-models, it tends to pass dicts (JSON objects) as JSON strings,
+                # which can be pre-parsed here.
+                signature = inspect.signature(self.fn)
+                for param_name in self.parameters["properties"]:
+                    arg = arguments.get(param_name, None)
+                    # if not in signature, we won't have annotations, so skip logic
+                    if param_name not in signature.parameters:
+                        continue
+                    # if not a string, we won't have a JSON to parse, so skip logic
+                    if not isinstance(arg, str):
+                        continue
+                    # skip if the type is a simple type (int, float, bool)
+                    if signature.parameters[param_name].annotation in (
+                        int,
+                        float,
+                        bool,
+                    ):
+                        continue
                     try:
-                        parsed_args[param_name] = json.loads(parsed_args[param_name])
+                        arguments[param_name] = json.loads(arg)
+
                     except json.JSONDecodeError:
                         pass
 
-            type_adapter = get_cached_typeadapter(
-                self.fn, config=frozenset([("coerce_numbers_to_str", True)])
-            )
-            result = type_adapter.validate_python(parsed_args | injected_args)
+            type_adapter = get_cached_typeadapter(self.fn)
+            result = type_adapter.validate_python(arguments)
             if inspect.isawaitable(result):
                 result = await result
 

fastmcp/tools/tool_manager.py

@@ -3,7 +3,6 @@ from __future__ import annotations as _annotations
 from collections.abc import Callable
 from typing import TYPE_CHECKING, Any
 
-from mcp.shared.context import LifespanContextT
 from mcp.types import EmbeddedResource, ImageContent, TextContent, ToolAnnotations
 
 from fastmcp.exceptions import NotFoundError
@@ -12,9 +11,7 @@ from fastmcp.tools.tool import Tool
 from fastmcp.utilities.logging import get_logger
 
 if TYPE_CHECKING:
-    from mcp.server.session import ServerSessionT
-
-    from fastmcp.server import Context
+    pass
 
 logger = get_logger(__name__)
 
@@ -98,14 +95,11 @@ class ToolManager:
         return tool
 
     async def call_tool(
-        self,
-        key: str,
-        arguments: dict[str, Any],
-        context: Context[ServerSessionT, LifespanContextT] | None = None,
+        self, key: str, arguments: dict[str, Any]
     ) -> list[TextContent | ImageContent | EmbeddedResource]:
         """Call a tool by name with arguments."""
         tool = self.get_tool(key)
         if not tool:
             raise NotFoundError(f"Unknown tool: {key}")
 
-        return await tool.run(arguments, context=context)
+        return await tool.run(arguments)

fastmcp/utilities/cache.py

@@ -0,0 +1,26 @@
+import datetime
+from typing import Any
+
+UTC = datetime.timezone.utc
+
+
+class TimedCache:
+    NOT_FOUND = object()
+
+    def __init__(self, expiration: datetime.timedelta):
+        self.expiration = expiration
+        self.cache: dict[Any, tuple[Any, datetime.datetime]] = {}
+
+    def set(self, key: Any, value: Any) -> None:
+        expires = datetime.datetime.now(UTC) + self.expiration
+        self.cache[key] = (value, expires)
+
+    def get(self, key: Any) -> Any:
+        value = self.cache.get(key)
+        if value is not None and value[1] > datetime.datetime.now(UTC):
+            return value[0]
+        else:
+            return self.NOT_FOUND
+
+    def clear(self) -> None:
+        self.cache.clear()

fastmcp/utilities/tests.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import copy
+import multiprocessing
+import socket
+import time
+from collections.abc import Callable, Generator
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any, Literal
+
+import uvicorn
+
+from fastmcp.settings import settings
+
+if TYPE_CHECKING:
+    from fastmcp.server.server import FastMCP
+
+
+@contextmanager
+def temporary_settings(**kwargs: Any):
+    """
+    Temporarily override ControlFlow setting values.
+
+    Args:
+        **kwargs: The settings to override, including nested settings.
+
+    Example:
+        Temporarily override a setting:
+        ```python
+        import fastmcp
+        from fastmcp.utilities.tests import temporary_settings
+
+        with temporary_settings(log_level='DEBUG'):
+            assert fastmcp.settings.settings.log_level == 'DEBUG'
+        assert fastmcp.settings.settings.log_level == 'INFO'
+        ```
+    """
+    old_settings = copy.deepcopy(settings.model_dump())
+
+    try:
+        # apply the new settings
+        for attr, value in kwargs.items():
+            if not hasattr(settings, attr):
+                raise AttributeError(f"Setting {attr} does not exist.")
+            setattr(settings, attr, value)
+        yield
+
+    finally:
+        # restore the old settings
+        for attr in kwargs:
+            if hasattr(settings, attr):
+                setattr(settings, attr, old_settings[attr])
+
+
+def _run_server(mcp_server: FastMCP, transport: Literal["sse"], port: int) -> None:
+    # Some Starlette apps are not pickleable, so we need to create them here based on the indicated transport
+    if transport == "sse":
+        app = mcp_server.sse_app()
+    else:
+        raise ValueError(f"Invalid transport: {transport}")
+    uvicorn_server = uvicorn.Server(
+        config=uvicorn.Config(
+            app=app,
+            host="127.0.0.1",
+            port=port,
+            log_level="error",
+        )
+    )
+    uvicorn_server.run()
+
+
+@contextmanager
+def run_server_in_process(
+    server_fn: Callable[[str, int], None],
+) -> Generator[str, None, None]:
+    """
+    Context manager that runs a Starlette app in a separate process and returns the
+    server URL. When the context manager is exited, the server process is killed.
+
+    Args:
+        app: The Starlette app to run.
+
+    Returns:
+        The server URL.
+    """
+    host = "127.0.0.1"
+    with socket.socket() as s:
+        s.bind((host, 0))
+        port = s.getsockname()[1]
+
+    proc = multiprocessing.Process(target=server_fn, args=(host, port), daemon=True)
+    proc.start()
+
+    # Wait for server to be running
+    max_attempts = 100
+    attempt = 0
+    while attempt < max_attempts and proc.is_alive():
+        try:
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                s.connect((host, port))
+                break
+        except ConnectionRefusedError:
+            time.sleep(0.01)
+            attempt += 1
+    else:
+        raise RuntimeError(f"Server failed to start after {max_attempts} attempts")
+
+    yield f"http://{host}:{port}"
+
+    proc.kill()
+    proc.join(timeout=2)
+    if proc.is_alive():
+        raise RuntimeError("Server process failed to terminate")

fastmcp/utilities/types.py

@@ -6,26 +6,23 @@ from collections.abc import Callable
 from functools import lru_cache
 from pathlib import Path
 from types import UnionType
-from typing import Annotated, Any, TypeVar, Union, get_args, get_origin
+from typing import Annotated, TypeVar, Union, get_args, get_origin
 
 from mcp.types import ImageContent
-from pydantic import ConfigDict, TypeAdapter
+from pydantic import TypeAdapter
 
 T = TypeVar("T")
 
 
 @lru_cache(maxsize=5000)
-def get_cached_typeadapter(
-    cls: T, config: frozenset[tuple[str, Any]] | None = None
-) -> TypeAdapter[T]:
+def get_cached_typeadapter(cls: T) -> TypeAdapter[T]:
     """
     TypeAdapters are heavy objects, and in an application context we'd typically
     create them once in a global scope and reuse them as often as possible.
     However, this isn't feasible for user-generated functions. Instead, we use a
     cache to minimize the cost of creating them as much as possible.
     """
-    config_dict = dict(config or {})
-    return TypeAdapter(cls, config=ConfigDict(**config_dict))
+    return TypeAdapter(cls)
 
 
 def issubclass_safe(cls: type, base: type) -> bool:

{fastmcp-2.2.9.dist-info → fastmcp-2.3.0rc1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastmcp
-Version: 2.2.9
+Version: 2.3.0rc1
 Summary: The fast, Pythonic way to build MCP servers.
 Project-URL: Homepage, https://gofastmcp.com
 Project-URL: Repository, https://github.com/jlowin/fastmcp
@@ -19,7 +19,7 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: exceptiongroup>=1.2.2
 Requires-Dist: httpx>=0.28.1
-Requires-Dist: mcp<2.0.0,>=1.7.1
+Requires-Dist: mcp
 Requires-Dist: openapi-pydantic>=0.5.1
 Requires-Dist: python-dotenv>=1.1.0
 Requires-Dist: rich>=13.9.4
@@ -379,6 +379,10 @@ Run tests using pytest:
 ```bash
 pytest
 ```
+or if you want an overview of the code coverage
+```bash
+uv run pytest --cov=src --cov=examples --cov-report=html
+```
 
 ### Static Checks