Merge branch 'main' into fix/prevent-session-hang

Author: newbiehwang

.github/workflows/shared.yml

@@ -56,6 +56,7 @@ jobs:
         run: uv sync ${{ matrix.dep-resolution.install-flags }} --all-extras --python ${{ matrix.python-version }}
 
       - name: Run pytest with coverage
+        shell: bash
         run: |
           uv run --frozen --no-sync coverage run -m pytest
           uv run --frozen --no-sync coverage combine

README.md

@@ -13,6 +13,13 @@
 
 </div>
 
+> [!IMPORTANT]
+> **This is the `main` branch which contains v2 of the SDK (currently in development, pre-alpha).**
+>
+> We anticipate a stable v2 release in Q1 2026. Until then, **v1.x remains the recommended version** for production use. v1.x will continue to receive bug fixes and security updates for at least 6 months after v2 ships to give people time to upgrade.
+>
+> For v1 documentation and code, see the [`v1.x` branch](https://github.com/modelcontextprotocol/python-sdk/tree/v1.x).
+
 <!-- omit in toc -->
 ## Table of Contents
 

docs/migration.md

@@ -0,0 +1,133 @@
+# Migration Guide: v1 to v2
+
+This guide covers the breaking changes introduced in v2 of the MCP Python SDK and how to update your code.
+
+## Overview
+
+Version 2 of the MCP Python SDK introduces several breaking changes to improve the API, align with the MCP specification, and provide better type safety.
+
+## Breaking Changes
+
+### `streamablehttp_client` removed
+
+The deprecated `streamablehttp_client` function has been removed. Use `streamable_http_client` instead.
+
+**Before (v1):**
+
+```python
+from mcp.client.streamable_http import streamablehttp_client
+
+async with streamablehttp_client(
+    url="http://localhost:8000/mcp",
+    headers={"Authorization": "Bearer token"},
+    timeout=30,
+    sse_read_timeout=300,
+    auth=my_auth,
+) as (read_stream, write_stream, get_session_id):
+    ...
+```
+
+**After (v2):**
+
+```python
+import httpx
+from mcp.client.streamable_http import streamable_http_client
+
+# Configure headers, timeout, and auth on the httpx.AsyncClient
+http_client = httpx.AsyncClient(
+    headers={"Authorization": "Bearer token"},
+    timeout=httpx.Timeout(30, read=300),
+    auth=my_auth,
+)
+
+async with http_client:
+    async with streamable_http_client(
+        url="http://localhost:8000/mcp",
+        http_client=http_client,
+    ) as (read_stream, write_stream, get_session_id):
+        ...
+```
+
+### `StreamableHTTPTransport` parameters removed
+
+The `headers`, `timeout`, `sse_read_timeout`, and `auth` parameters have been removed from `StreamableHTTPTransport`. Configure these on the `httpx.AsyncClient` instead (see example above).
+
+### Removed type aliases and classes
+
+The following deprecated type aliases and classes have been removed from `mcp.types`:
+
+| Removed | Replacement |
+|---------|-------------|
+| `Content` | `ContentBlock` |
+| `ResourceReference` | `ResourceTemplateReference` |
+
+**Before (v1):**
+
+```python
+from mcp.types import Content, ResourceReference
+```
+
+**After (v2):**
+
+```python
+from mcp.types import ContentBlock, ResourceTemplateReference
+```
+
+### `args` parameter removed from `ClientSessionGroup.call_tool()`
+
+The deprecated `args` parameter has been removed from `ClientSessionGroup.call_tool()`. Use `arguments` instead.
+
+**Before (v1):**
+
+```python
+result = await session_group.call_tool("my_tool", args={"key": "value"})
+```
+
+**After (v2):**
+
+```python
+result = await session_group.call_tool("my_tool", arguments={"key": "value"})
+```
+
+### `cursor` parameter removed from `ClientSession` list methods
+
+The deprecated `cursor` parameter has been removed from the following `ClientSession` methods:
+
+- `list_resources()`
+- `list_resource_templates()`
+- `list_prompts()`
+- `list_tools()`
+
+Use `params=PaginatedRequestParams(cursor=...)` instead.
+
+**Before (v1):**
+
+```python
+result = await session.list_resources(cursor="next_page_token")
+result = await session.list_tools(cursor="next_page_token")
+```
+
+**After (v2):**
+
+```python
+from mcp.types import PaginatedRequestParams
+
+result = await session.list_resources(params=PaginatedRequestParams(cursor="next_page_token"))
+result = await session.list_tools(params=PaginatedRequestParams(cursor="next_page_token"))
+```
+
+## Deprecations
+
+<!-- Add deprecations below -->
+
+## New Features
+
+<!-- Add new features below -->
+
+## Need Help?
+
+If you encounter issues during migration:
+
+1. Check the [API Reference](api.md) for updated method signatures
+2. Review the [examples](https://github.com/modelcontextprotocol/python-sdk/tree/main/examples) for updated usage patterns
+3. Open an issue on [GitHub](https://github.com/modelcontextprotocol/python-sdk/issues) if you find a bug or need further assistance

mkdocs.yml

@@ -13,6 +13,7 @@ site_url: https://modelcontextprotocol.github.io/python-sdk
 nav:
   - Introduction: index.md
   - Installation: installation.md
+  - Migration Guide: migration.md
   - Documentation:
       - Concepts: concepts.md
       - Low-Level Server: low-level-server.md

src/mcp/client/session.py

@@ -5,7 +5,6 @@
 import anyio.lowlevel
 from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
 from pydantic import AnyUrl, TypeAdapter
-from typing_extensions import deprecated
 
 import mcp.types as types
 from mcp.client.experimental import ExperimentalClientFeatures
@@ -279,112 +278,48 @@ async def set_logging_level(self, level: types.LoggingLevel) -> types.EmptyResul
             types.EmptyResult,
         )
 
-    @overload
-    @deprecated("Use list_resources(params=PaginatedRequestParams(...)) instead")
-    async def list_resources(self, cursor: str | None) -> types.ListResourcesResult: ...
-
-    @overload
-    async def list_resources(self, *, params: types.PaginatedRequestParams | None) -> types.ListResourcesResult: ...
-
-    @overload
-    async def list_resources(self) -> types.ListResourcesResult: ...
-
-    async def list_resources(
-        self,
-        cursor: str | None = None,
-        *,
-        params: types.PaginatedRequestParams | None = None,
-    ) -> types.ListResourcesResult:
+    async def list_resources(self, *, params: types.PaginatedRequestParams | None = None) -> types.ListResourcesResult:
         """Send a resources/list request.
 
         Args:
-            cursor: Simple cursor string for pagination (deprecated, use params instead)
             params: Full pagination parameters including cursor and any future fields
         """
-        if params is not None and cursor is not None:
-            raise ValueError("Cannot specify both cursor and params")
-
-        if params is not None:
-            request_params = params
-        elif cursor is not None:
-            request_params = types.PaginatedRequestParams(cursor=cursor)
-        else:
-            request_params = None
-
         return await self.send_request(
-            types.ClientRequest(types.ListResourcesRequest(params=request_params)),
+            types.ClientRequest(types.ListResourcesRequest(params=params)),
             types.ListResourcesResult,
         )
 
-    @overload
-    @deprecated("Use list_resource_templates(params=PaginatedRequestParams(...)) instead")
-    async def list_resource_templates(self, cursor: str | None) -> types.ListResourceTemplatesResult: ...
-
-    @overload
     async def list_resource_templates(
-        self, *, params: types.PaginatedRequestParams | None
-    ) -> types.ListResourceTemplatesResult: ...
-
-    @overload
-    async def list_resource_templates(self) -> types.ListResourceTemplatesResult: ...
-
-    async def list_resource_templates(
-        self,
-        cursor: str | None = None,
-        *,
-        params: types.PaginatedRequestParams | None = None,
+        self, *, params: types.PaginatedRequestParams | None = None
     ) -> types.ListResourceTemplatesResult:
         """Send a resources/templates/list request.
 
         Args:
-            cursor: Simple cursor string for pagination (deprecated, use params instead)
             params: Full pagination parameters including cursor and any future fields
         """
-        if params is not None and cursor is not None:
-            raise ValueError("Cannot specify both cursor and params")
-
-        if params is not None:
-            request_params = params
-        elif cursor is not None:
-            request_params = types.PaginatedRequestParams(cursor=cursor)
-        else:
-            request_params = None
-
         return await self.send_request(
-            types.ClientRequest(types.ListResourceTemplatesRequest(params=request_params)),
+            types.ClientRequest(types.ListResourceTemplatesRequest(params=params)),
             types.ListResourceTemplatesResult,
         )
 
     async def read_resource(self, uri: AnyUrl) -> types.ReadResourceResult:
         """Send a resources/read request."""
         return await self.send_request(
-            types.ClientRequest(
-                types.ReadResourceRequest(
-                    params=types.ReadResourceRequestParams(uri=uri),
-                )
-            ),
+            types.ClientRequest(types.ReadResourceRequest(params=types.ReadResourceRequestParams(uri=uri))),
             types.ReadResourceResult,
         )
 
     async def subscribe_resource(self, uri: AnyUrl) -> types.EmptyResult:
         """Send a resources/subscribe request."""
         return await self.send_request(  # pragma: no cover
-            types.ClientRequest(
-                types.SubscribeRequest(
-                    params=types.SubscribeRequestParams(uri=uri),
-                )
-            ),
+            types.ClientRequest(types.SubscribeRequest(params=types.SubscribeRequestParams(uri=uri))),
             types.EmptyResult,
         )
 
     async def unsubscribe_resource(self, uri: AnyUrl) -> types.EmptyResult:
         """Send a resources/unsubscribe request."""
         return await self.send_request(  # pragma: no cover
-            types.ClientRequest(
-                types.UnsubscribeRequest(
-                    params=types.UnsubscribeRequestParams(uri=uri),
-                )
-            ),
+            types.ClientRequest(types.UnsubscribeRequest(params=types.UnsubscribeRequestParams(uri=uri))),
             types.EmptyResult,
         )
 
@@ -445,40 +380,14 @@ async def _validate_tool_result(self, name: str, result: types.CallToolResult) -
             except SchemaError as e:  # pragma: no cover
                 raise RuntimeError(f"Invalid schema for tool {name}: {e}")  # pragma: no cover
 
-    @overload
-    @deprecated("Use list_prompts(params=PaginatedRequestParams(...)) instead")
-    async def list_prompts(self, cursor: str | None) -> types.ListPromptsResult: ...
-
-    @overload
-    async def list_prompts(self, *, params: types.PaginatedRequestParams | None) -> types.ListPromptsResult: ...
-
-    @overload
-    async def list_prompts(self) -> types.ListPromptsResult: ...
-
-    async def list_prompts(
-        self,
-        cursor: str | None = None,
-        *,
-        params: types.PaginatedRequestParams | None = None,
-    ) -> types.ListPromptsResult:
+    async def list_prompts(self, *, params: types.PaginatedRequestParams | None = None) -> types.ListPromptsResult:
         """Send a prompts/list request.
 
         Args:
-            cursor: Simple cursor string for pagination (deprecated, use params instead)
             params: Full pagination parameters including cursor and any future fields
         """
-        if params is not None and cursor is not None:
-            raise ValueError("Cannot specify both cursor and params")
-
-        if params is not None:
-            request_params = params
-        elif cursor is not None:
-            request_params = types.PaginatedRequestParams(cursor=cursor)
-        else:
-            request_params = None
-
         return await self.send_request(
-            types.ClientRequest(types.ListPromptsRequest(params=request_params)),
+            types.ClientRequest(types.ListPromptsRequest(params=params)),
             types.ListPromptsResult,
         )
 
@@ -517,40 +426,15 @@ async def complete(
             types.CompleteResult,
         )
 
-    @overload
-    @deprecated("Use list_tools(params=PaginatedRequestParams(...)) instead")
-    async def list_tools(self, cursor: str | None) -> types.ListToolsResult: ...
-
-    @overload
-    async def list_tools(self, *, params: types.PaginatedRequestParams | None) -> types.ListToolsResult: ...
-
-    @overload
-    async def list_tools(self) -> types.ListToolsResult: ...
-
-    async def list_tools(
-        self,
-        cursor: str | None = None,
-        *,
-        params: types.PaginatedRequestParams | None = None,
-    ) -> types.ListToolsResult:
+    async def list_tools(self, *, params: types.PaginatedRequestParams | None = None) -> types.ListToolsResult:
         """Send a tools/list request.
 
         Args:
             cursor: Simple cursor string for pagination (deprecated, use params instead)
             params: Full pagination parameters including cursor and any future fields
         """
-        if params is not None and cursor is not None:
-            raise ValueError("Cannot specify both cursor and params")
-
-        if params is not None:
-            request_params = params
-        elif cursor is not None:
-            request_params = types.PaginatedRequestParams(cursor=cursor)
-        else:
-            request_params = None
-
         result = await self.send_request(
-            types.ClientRequest(types.ListToolsRequest(params=request_params)),
+            types.ClientRequest(types.ListToolsRequest(params=params)),
             types.ListToolsResult,
         )