Merge branch 'main' into feat/sep-2207

Author: wdawson

.github/workflows/claude-code-review.yml

@@ -14,7 +14,7 @@ on:
 jobs:
   claude:
     if: |
-      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude') && !startsWith(github.event.comment.body, '@claude review')) ||
       (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
       (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
       (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))

.github/workflows/claude.yml

@@ -29,18 +29,31 @@ This document contains critical information about working with this codebase. Fo
    - IMPORTANT: The `tests/client/test_client.py` is the most well designed test file. Follow its patterns.
    - IMPORTANT: Be minimal, and focus on E2E tests: Use the `mcp.client.Client` whenever possible.
    - Coverage: CI requires 100% (`fail_under = 100`, `branch = true`).
-     - Full check: `./scripts/test` (~20s, matches CI exactly)
-     - Targeted check while iterating:
+     - Full check: `./scripts/test` (~23s). Runs coverage + `strict-no-cover` on the
+       default Python. Not identical to CI: CI also runs 3.10–3.14 × {ubuntu, windows},
+       and some branch-coverage quirks only surface on specific matrix entries.
+     - Targeted check while iterating (~4s, deterministic):
 
        ```bash
        uv run --frozen coverage erase
        uv run --frozen coverage run -m pytest tests/path/test_foo.py
        uv run --frozen coverage combine
        uv run --frozen coverage report --include='src/mcp/path/foo.py' --fail-under=0
+       UV_FROZEN=1 uv run --frozen strict-no-cover
        ```
 
        Partial runs can't hit 100% (coverage tracks `tests/` too), so `--fail-under=0`
-       and `--include` scope the report to what you actually changed.
+       and `--include` scope the report. `strict-no-cover` has no false positives on
+       partial runs — if your new test executes a line marked `# pragma: no cover`,
+       even a single-file run catches it.
+   - Coverage pragmas:
+     - `# pragma: no cover` — line is never executed. CI's `strict-no-cover` fails if
+       it IS executed. When your test starts covering such a line, remove the pragma.
+     - `# pragma: lax no cover` — excluded from coverage but not checked by
+       `strict-no-cover`. Use for lines covered on some platforms/versions but not
+       others.
+     - `# pragma: no branch` — excludes branch arcs only. coverage.py misreports the
+       `->exit` arc for nested `async with` on Python 3.11+ (worse on 3.14/Windows).
    - Avoid `anyio.sleep()` with a fixed duration to wait for async operations. Instead:
      - Use `anyio.Event` — set it in the callback/handler, `await event.wait()` in the test
      - For stream messages, use `await stream.receive()` instead of `sleep()` + `receive_nowait()`

CLAUDE.md

@@ -408,16 +408,10 @@ For custom error messages, call `task.fail()` before raising.
 For web applications, use the Streamable HTTP transport:
 
 ```python
-from collections.abc import AsyncIterator
-from contextlib import asynccontextmanager
-
 import uvicorn
-from starlette.applications import Starlette
-from starlette.routing import Mount
 
 from mcp.server import Server
 from mcp.server.experimental.task_context import ServerTaskContext
-from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
 from mcp.types import (
     CallToolResult, CreateTaskResult, TextContent, Tool, ToolExecution, TASK_REQUIRED,
 )
@@ -462,22 +456,8 @@ async def handle_tool(name: str, arguments: dict) -> CallToolResult | CreateTask
     return CallToolResult(content=[TextContent(type="text", text=f"Unknown: {name}")], isError=True)
 
 
-def create_app():
-    session_manager = StreamableHTTPSessionManager(app=server)
-
-    @asynccontextmanager
-    async def lifespan(app: Starlette) -> AsyncIterator[None]:
-        async with session_manager.run():
-            yield
-
-    return Starlette(
-        routes=[Mount("/mcp", app=session_manager.handle_request)],
-        lifespan=lifespan,
-    )
-
-
 if __name__ == "__main__":
-    uvicorn.run(create_app(), host="127.0.0.1", port=8000)
+    uvicorn.run(server.streamable_http_app(), host="127.0.0.1", port=8000)
 ```
 
 ## Testing Task Servers

docs/api.md

@@ -0,0 +1,35 @@
+"""Generate the code reference pages and navigation."""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()
+
+root = Path(__file__).parent.parent.parent
+src = root / "src"
+
+for path in sorted(src.rglob("*.py")):
+    module_path = path.relative_to(src).with_suffix("")
+    doc_path = path.relative_to(src).with_suffix(".md")
+    full_doc_path = Path("api", doc_path)
+
+    parts = tuple(module_path.parts)
+
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+        doc_path = doc_path.with_name("index.md")
+        full_doc_path = full_doc_path.with_name("index.md")
+    elif parts[-1].startswith("_"):
+        continue
+
+    nav[parts] = doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        ident = ".".join(parts)
+        fd.write(f"::: {ident}")
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(root))
+
+with mkdocs_gen_files.open("api/SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())

docs/experimental/tasks-server.md

@@ -64,4 +64,4 @@ npx -y @modelcontextprotocol/inspector
 
 ## API Reference
 
-Full API documentation is available in the [API Reference](api.md).
+Full API documentation is available in the [API Reference](api/mcp/index.md).

docs/hooks/gen_ref_pages.py

@@ -169,6 +169,30 @@ result = await session.list_resources(params=PaginatedRequestParams(cursor="next
 result = await session.list_tools(params=PaginatedRequestParams(cursor="next_page_token"))
 ```
 
+### `ClientSession.get_server_capabilities()` replaced by `initialize_result` property
+
+`ClientSession` now stores the full `InitializeResult` via an `initialize_result` property. This provides access to `server_info`, `capabilities`, `instructions`, and the negotiated `protocol_version` through a single property. The `get_server_capabilities()` method has been removed.
+
+**Before (v1):**
+
+```python
+capabilities = session.get_server_capabilities()
+# server_info, instructions, protocol_version were not stored — had to capture initialize() return value
+```
+
+**After (v2):**
+
+```python
+result = session.initialize_result
+if result is not None:
+    capabilities = result.capabilities
+    server_info = result.server_info
+    instructions = result.instructions
+    version = result.protocol_version
+```
+
+The high-level `Client.initialize_result` returns the same `InitializeResult` but is non-nullable — initialization is guaranteed inside the context manager, so no `None` check is needed. This replaces v1's `Client.server_capabilities`; use `client.initialize_result.capabilities` instead.
+
 ### `McpError` renamed to `MCPError`
 
 The `McpError` exception class has been renamed to `MCPError` for consistent naming with the MCP acronym style used throughout the SDK.
@@ -859,6 +883,6 @@ The lowlevel `Server` also now exposes a `session_manager` property to access th
 
 If you encounter issues during migration:
 
-1. Check the [API Reference](api.md) for updated method signatures
+1. Check the [API Reference](api/mcp/index.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

docs/index.md

@@ -4,14 +4,14 @@ A simple MCP server demonstrating pagination for tools, resources, and prompts u
 
 ## Usage
 
-Start the server using either stdio (default) or SSE transport:
+Start the server using either stdio (default) or Streamable HTTP transport:
 
 ```bash
 # Using stdio transport (default)
 uv run mcp-simple-pagination
 
-# Using SSE transport on custom port
-uv run mcp-simple-pagination --transport sse --port 8000
+# Using Streamable HTTP transport on custom port
+uv run mcp-simple-pagination --transport streamable-http --port 8000
 ```
 
 The server exposes:

docs/migration.md

@@ -10,7 +10,6 @@
 import click
 from mcp import types
 from mcp.server import Server, ServerRequestContext
-from starlette.requests import Request
 
 T = TypeVar("T")
 
@@ -143,10 +142,10 @@ async def handle_get_prompt(ctx: ServerRequestContext, params: types.GetPromptRe
 
 
 @click.command()
-@click.option("--port", default=8000, help="Port to listen on for SSE")
+@click.option("--port", default=8000, help="Port to listen on for HTTP")
 @click.option(
     "--transport",
-    type=click.Choice(["stdio", "sse"]),
+    type=click.Choice(["stdio", "streamable-http"]),
     default="stdio",
     help="Transport type",
 )
@@ -161,30 +160,10 @@ def main(port: int, transport: str) -> int:
         on_get_prompt=handle_get_prompt,
     )
 
-    if transport == "sse":
-        from mcp.server.sse import SseServerTransport
-        from starlette.applications import Starlette
-        from starlette.responses import Response
-        from starlette.routing import Mount, Route
-
-        sse = SseServerTransport("/messages/")
-
-        async def handle_sse(request: Request):
-            async with sse.connect_sse(request.scope, request.receive, request._send) as streams:  # type: ignore[reportPrivateUsage]
-                await app.run(streams[0], streams[1], app.create_initialization_options())
-            return Response()
-
-        starlette_app = Starlette(
-            debug=True,
-            routes=[
-                Route("/sse", endpoint=handle_sse, methods=["GET"]),
-                Mount("/messages/", app=sse.handle_post_message),
-            ],
-        )
-
+    if transport == "streamable-http":
         import uvicorn
 
-        uvicorn.run(starlette_app, host="127.0.0.1", port=port)
+        uvicorn.run(app.streamable_http_app(), host="127.0.0.1", port=port)
     else:
         from mcp.server.stdio import stdio_server