Merge branch 'main' into FastMCP-and-structured-output

Author: SSOBHY2

CONTRIBUTING.md

@@ -2,6 +2,43 @@
 
 Thank you for your interest in contributing to the MCP Python SDK! This document provides guidelines and instructions for contributing.
 
+## Before You Start
+
+We welcome contributions! These guidelines exist to save everyone time, yours included. Following them means your work is more likely to be accepted.
+
+**All pull requests require a corresponding issue.** Unless your change is trivial (typo, docs tweak, broken link), create an issue first. Every merged feature becomes ongoing maintenance, so we need to agree something is worth doing before reviewing code. PRs without a linked issue will be closed.
+
+Having an issue doesn't guarantee acceptance. Wait for maintainer feedback or a `ready for work` label before starting. PRs for issues without buy-in may also be closed.
+
+Use issues to validate your idea before investing time in code. PRs are for execution, not exploration.
+
+### The SDK is Opinionated
+
+Not every contribution will be accepted, even with a working implementation. We prioritize maintainability and consistency over adding capabilities. This is at maintainers' discretion.
+
+### What Needs Discussion
+
+These always require an issue first:
+
+- New public APIs or decorators
+- Architectural changes or refactoring
+- Changes that touch multiple modules
+- Features that might require spec changes (these need a [SEP](https://github.com/modelcontextprotocol/modelcontextprotocol) first)
+
+Bug fixes for clear, reproducible issues are welcome—but still create an issue to track the fix.
+
+### Finding Issues to Work On
+
+| Label | For | Description |
+|-------|-----|-------------|
+| [`good first issue`](https://github.com/modelcontextprotocol/python-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) | Newcomers | Can tackle without deep codebase knowledge |
+| [`help wanted`](https://github.com/modelcontextprotocol/python-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) | Experienced contributors | Maintainers probably won't get to this |
+| [`ready for work`](https://github.com/modelcontextprotocol/python-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22ready+for+work%22) | Maintainers | Triaged and ready for a maintainer to pick up |
+
+Issues labeled `needs confirmation` or `needs maintainer action` are **not** ready for work—wait for maintainer input first.
+
+Before starting, comment on the issue so we can assign it to you. This prevents duplicate effort.
+
 ## Development Setup
 
 1. Make sure you have Python 3.10+ installed
@@ -76,13 +113,29 @@ pre-commit run --all-files
 - Add type hints to all functions
 - Include docstrings for public APIs
 
-## Pull Request Process
+## Pull Requests
+
+By the time you open a PR, the "what" and "why" should already be settled in an issue. This keeps reviews focused on implementation.
+
+### Scope
+
+Small PRs get reviewed fast. Large PRs sit in the queue.
+
+A few dozen lines can be reviewed in minutes. Hundreds of lines across many files takes real effort and things slip through. If your change is big, break it into smaller PRs or get alignment from a maintainer first.
+
+### What Gets Rejected
+
+- **No prior discussion**: Features or significant changes without an approved issue
+- **Scope creep**: Changes that go beyond what was discussed
+- **Misalignment**: Even well-implemented features may be rejected if they don't fit the SDK's direction
+- **Overengineering**: Unnecessary complexity for simple problems
+
+### Checklist
 
 1. Update documentation as needed
 2. Add tests for new functionality
 3. Ensure CI passes
-4. Maintainers will review your code
-5. Address review feedback
+4. Address review feedback
 
 ## Code of Conduct
 

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

@@ -147,9 +147,12 @@ class FastMCP(Generic[LifespanResultT]):
     def __init__(  # noqa: PLR0913
         self,
         name: str | None = None,
+        title: str | None = None,
+        description: str | None = None,
         instructions: str | None = None,
         website_url: str | None = None,
         icons: list[Icon] | None = None,
+        version: str | None = None,
         auth_server_provider: (OAuthAuthorizationServerProvider[Any, Any, Any] | None) = None,
         token_verifier: TokenVerifier | None = None,
         event_store: EventStore | None = None,
@@ -204,9 +207,12 @@ def __init__(  # noqa: PLR0913
 
         self._mcp_server = MCPServer(
             name=name or "FastMCP",
+            title=title,
+            description=description,
             instructions=instructions,
             website_url=website_url,
             icons=icons,
+            version=version,
             # TODO(Marcelo): It seems there's a type mismatch between the lifespan type from an FastMCP and Server.
             # We need to create a Lifespan type that is a generic on the server type, like Starlette does.
             lifespan=(lifespan_wrapper(self, self.settings.lifespan) if self.settings.lifespan else default_lifespan),  # type: ignore
@@ -245,6 +251,14 @@ def __init__(  # noqa: PLR0913
     def name(self) -> str:
         return self._mcp_server.name
 
+    @property
+    def title(self) -> str | None:
+        return self._mcp_server.title
+
+    @property
+    def description(self) -> str | None:
+        return self._mcp_server.description
+
     @property
     def instructions(self) -> str | None:
         return self._mcp_server.instructions
@@ -257,6 +271,10 @@ def website_url(self) -> str | None:
     def icons(self) -> list[Icon] | None:
         return self._mcp_server.icons
 
+    @property
+    def version(self) -> str | None:
+        return self._mcp_server.version
+
     @property
     def session_manager(self) -> StreamableHTTPSessionManager:
         """Get the StreamableHTTP session manager.

src/mcp/server/fastmcp/server.py

@@ -139,6 +139,8 @@ def __init__(
         self,
         name: str,
         version: str | None = None,
+        title: str | None = None,
+        description: str | None = None,
         instructions: str | None = None,
         website_url: str | None = None,
         icons: list[types.Icon] | None = None,
@@ -149,6 +151,8 @@ def __init__(
     ):
         self.name = name
         self.version = version
+        self.title = title
+        self.description = description
         self.instructions = instructions
         self.website_url = website_url
         self.icons = icons
@@ -181,6 +185,8 @@ def pkg_version(package: str) -> str:
         return InitializationOptions(
             server_name=self.name,
             server_version=self.version if self.version else pkg_version("mcp"),
+            title=self.title,
+            description=self.description,
             capabilities=self.get_capabilities(
                 notification_options or NotificationOptions(),
                 experimental_capabilities or {},
@@ -499,7 +505,7 @@ def call_tool(self, *, validate_input: bool = True):
 
         def decorator(
             func: Callable[
-                ...,
+                [str, dict[str, Any]],
                 Awaitable[
                     UnstructuredContent
                     | StructuredContent

src/mcp/server/lowlevel/server.py

@@ -14,6 +14,8 @@
 class InitializationOptions(BaseModel):
     server_name: str
     server_version: str
+    title: str | None = None
+    description: str | None = None
     capabilities: ServerCapabilities
     instructions: str | None = None
     website_url: str | None = None

src/mcp/server/models.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
         )
@@ -176,6 +178,8 @@ async def _received_request(self, responder: RequestResponder[types.ClientReques
                                 capabilities=self._init_options.capabilities,
                                 serverInfo=types.Implementation(
                                     name=self._init_options.server_name,
+                                    title=self._init_options.title,
+                                    description=self._init_options.description,
                                     version=self._init_options.server_version,
                                     websiteUrl=self._init_options.website_url,
                                     icons=self._init_options.icons,
@@ -311,7 +315,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 +356,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 +400,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 +439,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(