Merge branch 'main' into fix/1822-decorator-paramspec

Author: Kludex

examples/servers/simple-auth/mcp_simple_auth/py.typed

@@ -126,7 +126,7 @@ plugins:
             group_by_category: false
             # 3 because docs are in pages with an H2 just above them
             heading_level: 3
-          import:
+          inventories:
             - url: https://docs.python.org/3/objects.inv
             - url: https://docs.pydantic.dev/latest/objects.inv
             - url: https://typing-extensions.readthedocs.io/en/latest/objects.inv

mkdocs.yml

@@ -62,9 +62,7 @@
     ToolUseContent,
     UnsubscribeRequest,
 )
-from .types import (
-    Role as SamplingRole,
-)
+from .types import Role as SamplingRole
 
 __all__ = [
     "CallToolRequest",

src/mcp/__init__.py

@@ -206,7 +206,8 @@ def get_server_capabilities(self) -> types.ServerCapabilities | None:
     def experimental(self) -> ExperimentalClientFeatures:
         """Experimental APIs for tasks and other features.
 
-        WARNING: These APIs are experimental and may change without notice.
+        !!! warning
+            These APIs are experimental and may change without notice.
 
         Example:
             status = await session.experimental.get_task(task_id)

src/mcp/client/session.py

@@ -73,11 +73,11 @@ async def handle(self, request: Request) -> Response:
                     ),
                     status_code=400,
                 )
-        if not {"authorization_code", "refresh_token"}.issubset(set(client_metadata.grant_types)):
+        if "authorization_code" not in client_metadata.grant_types:
             return PydanticJSONResponse(
                 content=RegistrationErrorResponse(
                     error="invalid_client_metadata",
-                    error_description="grant_types must be authorization_code and refresh_token",
+                    error_description="grant_types must include 'authorization_code'",
                 ),
                 status_code=400,
             )

src/mcp/server/auth/handlers/register.py

@@ -49,6 +49,7 @@ async def handle_list_prompts(ctx: RequestContext) -> list[types.Prompt]:
 from mcp.server.experimental.session_features import ExperimentalServerSessionFeatures
 from mcp.server.models import InitializationOptions
 from mcp.server.validation import validate_sampling_tools, validate_tool_use_result_messages
+from mcp.shared.exceptions import StatelessModeNotSupported
 from mcp.shared.experimental.tasks.capabilities import check_tasks_capability
 from mcp.shared.experimental.tasks.helpers import RELATED_TASK_METADATA_KEY
 from mcp.shared.message import ServerMessageMetadata, SessionMessage
@@ -93,6 +94,7 @@ def __init__(
         stateless: bool = False,
     ) -> None:
         super().__init__(read_stream, write_stream, types.ClientRequest, types.ClientNotification)
+        self._stateless = stateless
         self._initialization_state = (
             InitializationState.Initialized if stateless else InitializationState.NotInitialized
         )
@@ -311,7 +313,10 @@ async def create_message(
         Raises:
             McpError: If tools are provided but client doesn't support them.
             ValueError: If tool_use or tool_result message structure is invalid.
+            StatelessModeNotSupported: If called in stateless HTTP mode.
         """
+        if self._stateless:
+            raise StatelessModeNotSupported(method="sampling")
         client_caps = self._client_params.capabilities if self._client_params else None
         validate_sampling_tools(client_caps, tools, tool_choice)
         validate_tool_use_result_messages(messages)
@@ -349,6 +354,8 @@ async def create_message(
 
     async def list_roots(self) -> types.ListRootsResult:
         """Send a roots/list request."""
+        if self._stateless:
+            raise StatelessModeNotSupported(method="list_roots")
         return await self.send_request(
             types.ServerRequest(types.ListRootsRequest()),
             types.ListRootsResult,
@@ -391,7 +398,12 @@ async def elicit_form(
 
         Returns:
             The client's response with form data
+
+        Raises:
+            StatelessModeNotSupported: If called in stateless HTTP mode.
         """
+        if self._stateless:
+            raise StatelessModeNotSupported(method="elicitation")
         return await self.send_request(
             types.ServerRequest(
                 types.ElicitRequest(
@@ -425,7 +437,12 @@ async def elicit_url(
 
         Returns:
             The client's response indicating acceptance, decline, or cancellation
+
+        Raises:
+            StatelessModeNotSupported: If called in stateless HTTP mode.
         """
+        if self._stateless:
+            raise StatelessModeNotSupported(method="elicitation")
         return await self.send_request(
             types.ServerRequest(
                 types.ElicitRequest(

src/mcp/server/session.py

@@ -18,6 +18,24 @@ def __init__(self, error: ErrorData):
         self.error = error
 
 
+class StatelessModeNotSupported(RuntimeError):
+    """
+    Raised when attempting to use a method that is not supported in stateless mode.
+
+    Server-to-client requests (sampling, elicitation, list_roots) are not
+    supported in stateless HTTP mode because there is no persistent connection
+    for bidirectional communication.
+    """
+
+    def __init__(self, method: str):
+        super().__init__(
+            f"Cannot use {method} in stateless HTTP mode. "
+            "Stateless mode does not support server-to-client requests. "
+            "Use stateful mode (stateless_http=False) to enable this feature."
+        )
+        self.method = method
+
+
 class UrlElicitationRequiredError(McpError):
     """
     Specialized error for when a tool requires URL mode elicitation(s) before proceeding.

src/mcp/shared/exceptions.py

@@ -1,3 +1,5 @@
+from __future__ import annotations as _annotations
+
 import logging
 from collections.abc import Callable
 from contextlib import AsyncExitStack
@@ -72,14 +74,8 @@ def __init__(
         request_id: RequestId,
         request_meta: RequestParams.Meta | None,
         request: ReceiveRequestT,
-        session: """BaseSession[
-            SendRequestT,
-            SendNotificationT,
-            SendResultT,
-            ReceiveRequestT,
-            ReceiveNotificationT
-        ]""",
-        on_complete: Callable[["RequestResponder[ReceiveRequestT, SendResultT]"], Any],
+        session: BaseSession[SendRequestT, SendNotificationT, SendResultT, ReceiveRequestT, ReceiveNotificationT],
+        on_complete: Callable[[RequestResponder[ReceiveRequestT, SendResultT]], Any],
         message_metadata: MessageMetadata = None,
     ) -> None:
         self.request_id = request_id
@@ -92,7 +88,7 @@ def __init__(
         self._on_complete = on_complete
         self._entered = False  # Track if we're in a context manager
 
-    def __enter__(self) -> "RequestResponder[ReceiveRequestT, SendResultT]":
+    def __enter__(self) -> RequestResponder[ReceiveRequestT, SendResultT]:
         """Enter the context manager, enabling request cancellation tracking."""
         self._entered = True
         self._cancel_scope = anyio.CancelScope()
@@ -179,7 +175,7 @@ class BaseSession(
     _request_id: int
     _in_flight: dict[RequestId, RequestResponder[ReceiveRequestT, SendResultT]]
     _progress_callbacks: dict[RequestId, ProgressFnT]
-    _response_routers: list["ResponseRouter"]
+    _response_routers: list[ResponseRouter]
 
     def __init__(
         self,
@@ -210,7 +206,8 @@ def add_response_router(self, router: ResponseRouter) -> None:
         response stream mechanism. This is used by TaskResultHandler to route
         responses for queued task requests back to their resolvers.
 
-        WARNING: This is an experimental API that may change without notice.
+        !!! warning
+            This is an experimental API that may change without notice.
 
         Args:
             router: A ResponseRouter implementation

src/mcp/shared/session.py

@@ -1,3 +1,5 @@
+from __future__ import annotations as _annotations
+
 from collections.abc import Callable
 from datetime import datetime
 from typing import Annotated, Any, Final, Generic, Literal, TypeAlias, TypeVar
@@ -6,24 +8,6 @@
 from pydantic.networks import AnyUrl, UrlConstraints
 from typing_extensions import deprecated
 
-"""
-Model Context Protocol bindings for Python
-
-These bindings were generated from https://github.com/modelcontextprotocol/specification,
-using Claude, with a prompt something like the following:
-
-Generate idiomatic Python bindings for this schema for MCP, or the "Model Context
-Protocol." The schema is defined in TypeScript, but there's also a JSON Schema version
-for reference.
-
-* For the bindings, let's use Pydantic V2 models.
-* Each model should allow extra fields everywhere, by specifying `model_config =
-  ConfigDict(extra='allow')`. Do this in every case, instead of a custom base class.
-* Union types should be represented with a Pydantic `RootModel`.
-* Define additional model classes instead of using dictionaries. Do this even if they're
-  not separate types in the schema.
-"""
-
 LATEST_PROTOCOL_VERSION = "2025-11-25"
 
 """
@@ -557,7 +541,7 @@ class Task(BaseModel):
     """Current task state."""
 
     statusMessage: str | None = None
-    """  
+    """
     Optional human-readable message describing the current task state.
     This can provide context for any status, including:
     - Reasons for "cancelled" status
@@ -1121,7 +1105,7 @@ class ToolResultContent(BaseModel):
     toolUseId: str
     """The unique identifier that corresponds to the tool call's id field."""
 
-    content: list["ContentBlock"] = []
+    content: list[ContentBlock] = []
     """
     A list of content objects representing the tool result.
     Defaults to empty list if not provided.
@@ -1523,7 +1507,7 @@ class CreateMessageRequestParams(RequestParams):
     stopSequences: list[str] | None = None
     metadata: dict[str, Any] | None = None
     """Optional metadata to pass through to the LLM provider."""
-    tools: list["Tool"] | None = None
+    tools: list[Tool] | None = None
     """
     Tool definitions for the LLM to use during sampling.
     Requires clientCapabilities.sampling.tools to be present.

src/mcp/types.py

@@ -12,19 +12,13 @@
 import tempfile
 import textwrap
 from pathlib import Path
-from typing import TYPE_CHECKING
 
 import anyio
 import pytest
 
 from mcp import ClientSession, StdioServerParameters
 from mcp.client.stdio import _create_platform_compatible_process, stdio_client
-
-# TODO(Marcelo): This doesn't seem to be the right path. We should fix this.
-if TYPE_CHECKING:
-    from ..shared.test_win32_utils import escape_path_for_python
-else:
-    from tests.shared.test_win32_utils import escape_path_for_python
+from tests.shared.test_win32_utils import escape_path_for_python
 
 
 @pytest.mark.anyio