Address review findings on the pre-release machinery

- comment-on-release: pick the previous release by smallest ahead_by
  across all same-major releases instead of trusting list order
  (releases published from drafts keep their draft creation date, so
  list order can hide the true predecessor); check the major line
  before comparing so cross-line candidates cost no API calls; skip
  only candidates whose tag no longer resolves and fail loudly on other
  compare errors; skip drafts; paginate release and comment listings;
  cap the commit range at 250 and skip commenting beyond it; derive
  pre-release wording from the tag as well as the release flag
- RELEASE.md: stable releases must target the v1.x branch (the UI
  defaults to main, which is the v2 rework); the --target commit must
  contain the release tooling and is ignored if the tag already exists;
  release notes need absolute links; yanked versions should point at
  their replacement; bump the Development Status classifier when the
  line changes stage
- README.v2.md: pin install and quickstart commands while v2 is in
  pre-release; point the docs badge and API reference at the v2 docs
  site; fix examples against the v2 API (Icon mime_type/sizes,
  snake_case CallToolResult fields via a re-synced snippet,
  keyword-only max_tokens, elicitation result shape, request context
  fields)
- snippets: fix the resource-read isinstance in the stdio client
  example (TextResourceContents, not TextContent)
- pyproject: drop the leftover "git" keyword

Author: maxisbey

.github/workflows/comment-on-release.yml

@@ -27,33 +27,42 @@ jobs:
           script: |
             const currentTag = process.env.CURRENT_TAG;
 
-            // Get all releases
-            const { data: releases } = await github.rest.repos.listReleases({
+            // Paginate: with two release lines publishing interleaved, the
+            // previous release on this line can sit far down the list.
+            const releases = await github.paginate(github.rest.repos.listReleases, {
               owner: context.repo.owner,
               repo: context.repo.repo,
               per_page: 100
             });
 
-            // Find current release index
-            const currentIndex = releases.findIndex(r => r.tag_name === currentTag);
-
-            if (currentIndex === -1) {
+            if (!releases.some(r => r.tag_name === currentTag)) {
               console.log('Current release not found in list');
               return null;
             }
 
             const major = tag => (tag.match(/^v?(\d+)/) || [])[1];
 
-            // Releases are sorted by date, but with multiple release lines
-            // (v1.x and the v2 pre-release series) the most recent release may
-            // be on a different branch. Walk older releases until we find one
-            // whose tag is an ancestor of the current tag AND on the same
-            // major line, so the compare never spans branches. For the first
-            // release of a new major line no such release exists, and we skip
-            // commenting rather than compare across the entire new line's
-            // history. per_page=1 because only comparison.status is needed
-            // here; the commits are fetched in the next step.
-            for (const candidate of releases.slice(currentIndex + 1)) {
+            if (major(currentTag) === undefined) {
+              console.log(`Cannot parse a major version from ${currentTag}; skipping comments`);
+              return null;
+            }
+
+            // The list is ordered by release creation date, which does not
+            // reliably reflect tag topology (for example, a release published
+            // from a long-lived draft keeps its draft creation date). Instead
+            // of trusting list order, compare every same-major release and
+            // pick the nearest ancestor of the current tag: the one the
+            // smallest number of commits behind it. The major check runs
+            // first so cross-line candidates cost no API calls; per_page=1
+            // because only status/ahead_by are needed here (the commits are
+            // fetched in the next step). For the first release of a new major
+            // line there is no same-line predecessor, and we skip commenting
+            // rather than compare across the entire new line's history.
+            let best = null;
+            for (const candidate of releases) {
+              if (candidate.tag_name === currentTag || candidate.draft) continue;
+              if (major(candidate.tag_name) !== major(currentTag)) continue;
+
               let comparison;
               try {
                 ({ data: comparison } = await github.rest.repos.compareCommits({
@@ -64,8 +73,14 @@ jobs:
                   per_page: 1
                 }));
               } catch (error) {
-                console.log(`Skipping ${candidate.tag_name}: compare failed (${error.message})`);
-                continue;
+                // Tolerate only candidates whose tag no longer resolves;
+                // anything else (rate limits, server errors) must fail the
+                // job rather than silently produce a wrong comparison base.
+                if (error.status === 404) {
+                  console.log(`Skipping ${candidate.tag_name}: tag does not resolve`);
+                  continue;
+                }
+                throw error;
               }
 
               // 'identical' covers a release re-cut on the same commit; it
@@ -75,17 +90,18 @@ jobs:
                 continue;
               }
 
-              if (major(candidate.tag_name) === undefined || major(candidate.tag_name) !== major(currentTag)) {
-                console.log(`Skipping ${candidate.tag_name}: different release line (${major(candidate.tag_name)} vs ${major(currentTag)})`);
-                continue;
+              if (best === null || comparison.ahead_by < best.aheadBy) {
+                best = { tagName: candidate.tag_name, aheadBy: comparison.ahead_by };
               }
+            }
 
-              console.log(`Found previous release: ${candidate.tag_name}`);
-              return candidate.tag_name;
+            if (best === null) {
+              console.log(`No previous release found for ${currentTag} on its major line (it may be the first); skipping comments`);
+              return null;
             }
 
-            console.log(`No previous release found for ${currentTag} on its major line (it may be the first); skipping comments`);
-            return null;
+            console.log(`Found previous release: ${best.tagName} (${best.aheadBy} commits behind ${currentTag})`);
+            return best.tagName;
 
       - name: Get merged PRs between releases
         id: get_prs
@@ -106,7 +122,10 @@ jobs:
             console.log(`Finding PRs between ${previousTag} and ${currentTag}`);
 
             // Get commits between previous and current release. A single
-            // compare response caps the commit list, so paginate.
+            // compare response caps the commit list, so paginate — but bound
+            // the total: a range this large means a mis-selected base, and
+            // commenting on hundreds of PRs is worse than commenting on none.
+            const MAX_COMMITS = 250;
             const commits = [];
             for (let page = 1; ; page++) {
               const { data: comparison } = await github.rest.repos.compareCommits({
@@ -118,6 +137,10 @@ jobs:
                 page
               });
               commits.push(...comparison.commits);
+              if (commits.length > MAX_COMMITS) {
+                console.log(`Range ${previousTag}...${currentTag} exceeds ${MAX_COMMITS} commits; skipping comments`);
+                return [];
+              }
               if (comparison.commits.length < 100) break;
             }
             console.log(`Found ${commits.length} commits`);
@@ -159,16 +182,22 @@ jobs:
             const prNumbers = JSON.parse(process.env.PR_NUMBERS_JSON);
             const releaseTag = process.env.RELEASE_TAG;
             const releaseUrl = process.env.RELEASE_URL;
-            const releaseKind = process.env.RELEASE_IS_PRERELEASE === 'true' ? 'pre-release' : 'release';
+            // Trust the tag as well as the flag, in case the release manager
+            // forgets to tick the pre-release checkbox.
+            const isPrerelease = process.env.RELEASE_IS_PRERELEASE === 'true' || /\d(a|b|rc)\d/.test(releaseTag);
+            const releaseKind = isPrerelease ? 'pre-release' : 'release';
 
             const comment = `This pull request is included in ${releaseKind} [${releaseTag}](${releaseUrl})`;
 
             let commentedCount = 0;
 
             for (const prNumber of prNumbers) {
               try {
-                // Check if we've already commented on this PR for this release
-                const { data: comments } = await github.rest.issues.listComments({
+                // Check if we've already commented on this PR for this
+                // release. Paginate: comments are returned oldest-first, so
+                // on a busy PR an earlier bot comment is exactly what would
+                // fall off a single page.
+                const comments = await github.paginate(github.rest.issues.listComments, {
                   owner: context.repo.owner,
                   repo: context.repo.repo,
                   issue_number: prNumber,

README.v2.md

@@ -85,7 +85,7 @@
 [python-badge]: https://img.shields.io/pypi/pyversions/mcp.svg
 [python-url]: https://www.python.org/downloads/
 [docs-badge]: https://img.shields.io/badge/docs-python--sdk-blue.svg
-[docs-url]: https://modelcontextprotocol.github.io/python-sdk/
+[docs-url]: https://py.sdk.modelcontextprotocol.io/v2/
 [protocol-badge]: https://img.shields.io/badge/protocol-modelcontextprotocol.io-blue.svg
 [protocol-url]: https://modelcontextprotocol.io
 [spec-badge]: https://img.shields.io/badge/spec-spec.modelcontextprotocol.io-blue.svg
@@ -116,15 +116,17 @@ If you haven't created a uv-managed project yet, create one:
    Then add MCP to your project dependencies:
 
    ```bash
-   uv add "mcp[cli]"
+   uv add "mcp[cli]==2.0.0a1"
    ```
 
 Alternatively, for projects using pip for dependencies:
 
 ```bash
-pip install "mcp[cli]"
+pip install "mcp[cli]==2.0.0a1"
 ```
 
+> While v2 is in pre-release, you must pin the version explicitly: unpinned installs resolve to the latest stable v1.x release, which these docs do not describe. Check the [release history](https://pypi.org/project/mcp/#history) for the newest pre-release. The same applies to ad-hoc commands: use `uv run --with "mcp==2.0.0a1"` rather than `uv run --with mcp`.
+
 ### Running the standalone MCP development tools
 
 To run the mcp command with uv:
@@ -189,7 +191,7 @@ _Full example: [examples/snippets/servers/mcpserver_quickstart.py](https://githu
 You can install this server in [Claude Code](https://docs.claude.com/en/docs/claude-code/mcp) and interact with it right away. First, run the server:
 
 ```bash
-uv run --with mcp examples/snippets/servers/mcpserver_quickstart.py
+uv run --with "mcp==2.0.0a1" examples/snippets/servers/mcpserver_quickstart.py
 ```
 
 Then add it to Claude Code:
@@ -605,8 +607,8 @@ from mcp.server.mcpserver import MCPServer, Icon
 # Create an icon from a file path or URL
 icon = Icon(
     src="icon.png",
-    mimeType="image/png",
-    sizes="64x64"
+    mime_type="image/png",
+    sizes=["64x64"]
 )
 
 # Add icons to server
@@ -926,7 +928,8 @@ The `elicit()` method returns an `ElicitationResult` with:
 
 - `action`: "accept", "decline", or "cancel"
 - `data`: The validated response (only when accepted)
-- `validation_error`: Any validation error message
+
+If the client returns data that doesn't match the schema, `elicit()` raises a `pydantic.ValidationError`.
 
 ### Sampling
 
@@ -1099,7 +1102,7 @@ The session object accessible via `ctx.session` provides advanced control over c
 
 - `ctx.session.client_params` - Client initialization parameters and declared capabilities
 - `await ctx.session.send_log_message(level, data, logger)` - Send log messages with full control
-- `await ctx.session.create_message(messages, max_tokens)` - Request LLM sampling/completion
+- `await ctx.session.create_message(messages, max_tokens=...)` - Request LLM sampling/completion (`max_tokens` is keyword-only)
 - `await ctx.session.send_progress_notification(token, progress, total, message)` - Direct progress updates
 - `await ctx.session.send_resource_updated(uri)` - Notify clients that a specific resource changed
 - `await ctx.session.send_resource_list_changed()` - Notify clients that the resource list changed
@@ -1129,9 +1132,9 @@ The request context accessible via `ctx.request_context` contains request-specif
   - Database connections, configuration objects, shared services
   - Type-safe access to resources defined in your server's lifespan function
 - `ctx.request_context.meta` - Request metadata from the client including:
-  - `progressToken` - Token for progress notifications
+  - `progress_token` - Token for progress notifications
   - Other client-provided metadata
-- `ctx.request_context.request` - The original MCP request object for advanced processing
+- `ctx.request_context.request` - Data the transport attached to this message (for example the HTTP request object on HTTP transports; `None` on stdio)
 - `ctx.request_context.request_id` - Unique identifier for this request
 
 ```python
@@ -2158,7 +2161,7 @@ async def run():
             # Read a resource (greeting resource from mcpserver_quickstart)
             resource_content = await session.read_resource("greeting://World")
             content_block = resource_content.contents[0]
-            if isinstance(content_block, types.TextContent):
+            if isinstance(content_block, types.TextResourceContents):
                 print(f"Resource content: {content_block.text}")
 
             # Call a tool (add tool from mcpserver_quickstart)
@@ -2404,6 +2407,7 @@ For a complete working example, see [`examples/clients/simple-auth-client/`](htt
 
 When calling tools through MCP, the `CallToolResult` object contains the tool's response in a structured format. Understanding how to parse this result is essential for properly handling tool outputs.
 
+<!-- snippet-source examples/snippets/clients/parsing_tool_results.py -->
 ```python
 """examples/snippets/clients/parsing_tool_results.py"""
 
@@ -2415,9 +2419,7 @@ from mcp.client.stdio import stdio_client
 
 async def parse_tool_results():
     """Demonstrates how to parse different types of content in CallToolResult."""
-    server_params = StdioServerParameters(
-        command="python", args=["path/to/mcp_server.py"]
-    )
+    server_params = StdioServerParameters(command="python", args=["path/to/mcp_server.py"])
 
     async with stdio_client(server_params) as (read, write):
         async with ClientSession(read, write) as session:
@@ -2431,9 +2433,9 @@ async def parse_tool_results():
 
             # Example 2: Parsing structured content from JSON tools
             result = await session.call_tool("get_user", {"id": "123"})
-            if hasattr(result, "structuredContent") and result.structuredContent:
+            if hasattr(result, "structured_content") and result.structured_content:
                 # Access structured data directly
-                user_data = result.structuredContent
+                user_data = result.structured_content
                 print(f"User: {user_data.get('name')}, Age: {user_data.get('age')}")
 
             # Example 3: Parsing embedded resources
@@ -2443,18 +2445,18 @@ async def parse_tool_results():
                     resource = content.resource
                     if isinstance(resource, types.TextResourceContents):
                         print(f"Config from {resource.uri}: {resource.text}")
-                    elif isinstance(resource, types.BlobResourceContents):
+                    else:
                         print(f"Binary data from {resource.uri}")
 
             # Example 4: Parsing image content
             result = await session.call_tool("generate_chart", {"data": [1, 2, 3]})
             for content in result.content:
                 if isinstance(content, types.ImageContent):
-                    print(f"Image ({content.mimeType}): {len(content.data)} bytes")
+                    print(f"Image ({content.mime_type}): {len(content.data)} bytes")
 
             # Example 5: Handling errors
             result = await session.call_tool("failing_tool", {})
-            if result.isError:
+            if result.is_error:
                 print("Tool execution failed!")
                 for content in result.content:
                     if isinstance(content, types.TextContent):
@@ -2469,6 +2471,9 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+_Full example: [examples/snippets/clients/parsing_tool_results.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/clients/parsing_tool_results.py)_
+<!-- /snippet-source -->
+
 ### MCP Primitives
 
 The MCP protocol defines three core primitives that servers can implement:
@@ -2493,7 +2498,7 @@ MCP servers declare capabilities during initialization:
 
 ## Documentation
 
-- [API Reference](https://modelcontextprotocol.github.io/python-sdk/api/)
+- [API Reference](https://py.sdk.modelcontextprotocol.io/v2/api/mcp/)
 - [Model Context Protocol documentation](https://modelcontextprotocol.io)
 - [Model Context Protocol specification](https://modelcontextprotocol.io/specification/latest)
 - [Officially supported servers](https://github.com/modelcontextprotocol/servers)

RELEASE.md

@@ -7,8 +7,12 @@
 
 ## Major or Minor Release
 
-Create a GitHub release via UI with the tag being `vX.Y.Z` where `X.Y.Z` is the version,
-and the release title being the same. Then ask someone to review the release.
+Stable releases are cut from the `v1.x` branch. Create a GitHub release via UI
+with the tag being `vX.Y.Z` where `X.Y.Z` is the version and the release title
+being the same, and **set the tag's target to the `v1.x` branch** — the UI
+defaults to `main`, which is the v2 rework, and a v1 tag created there would
+publish the v2 codebase as a stable release. Then ask someone to review the
+release.
 
 The package version will be set automatically from the tag.
 
@@ -22,16 +26,29 @@ for alphas, later `bN`/`rcN` for betas and release candidates.
    passed — check the individual jobs.
 2. Create the release as a pre-release, passing the exact commit verified in
    step 1 as `--target` (otherwise the tag is created from whatever `main`'s
-   HEAD is by then). The pre-release flag keeps GitHub's "Latest" badge and
-   `/releases/latest` pointing at the stable v1.x line:
+   HEAD is by then). The tagged commit determines everything about the
+   release — the workflows that run and the package metadata (readme,
+   classifiers) that gets published — so it must contain the current release
+   tooling, not just pass tests. `--target` is ignored if the tag already
+   exists: when re-creating a release, delete the old tag first and
+   double-check where the new tag points. The pre-release flag keeps GitHub's
+   "Latest" badge and `/releases/latest` pointing at the stable v1.x line:
 
    ```shell
    gh release create v2.0.0aN --prerelease --title v2.0.0aN --target <commit-sha>
    ```
 
 3. Curate the release notes instead of relying on auto-generated ones: what
    changed since the previous pre-release, what is known-incomplete, the
-   install line (`pip install mcp==2.0.0aN`), and a link to the
-   [migration guide](docs/migration.md).
+   install line (`pip install mcp==2.0.0aN`), and a link to the migration
+   guide. Use the absolute URL
+   (`https://github.com/modelcontextprotocol/python-sdk/blob/main/docs/migration.md`)
+   because relative links don't resolve in GitHub release bodies.
 4. If a pre-release turns out to be broken, yank it on PyPI and cut the next
    one. Never delete a release from PyPI — version numbers cannot be reused.
+   Yanking doesn't stop `==` pins from installing the broken version, so set
+   the yank reason (and edit the GitHub release notes) to point at the
+   replacement version.
+5. When the line moves to a new stage (first beta, first release candidate,
+   stable), update the `Development Status` classifier in `pyproject.toml`
+   before tagging — PyPI uploads are immutable.

examples/snippets/clients/stdio_client.py

@@ -59,7 +59,7 @@ async def run():
             # Read a resource (greeting resource from mcpserver_quickstart)
             resource_content = await session.read_resource("greeting://World")
             content_block = resource_content.contents[0]
-            if isinstance(content_block, types.TextContent):
+            if isinstance(content_block, types.TextResourceContents):
                 print(f"Resource content: {content_block.text}")
 
             # Call a tool (add tool from mcpserver_quickstart)

pyproject.toml

@@ -11,7 +11,7 @@ maintainers = [
     { name = "Max Isbey", email = "maxisbey@anthropic.com" },
     { name = "Felix Weinberger", email = "fweinberger@anthropic.com" },
 ]
-keywords = ["git", "mcp", "llm", "automation"]
+keywords = ["mcp", "llm", "automation"]
 license = { text = "MIT" }
 classifiers = [
     "Development Status :: 3 - Alpha",